Как дескриптор приложений какао события Apple

Scriptable ли Ваше приложение или нет, Какао обеспечивает автоматическую обработку для определенных событий Apple, которые получают все приложения. В этой главе описываются поддержку Какао по умолчанию обработки тех событий Apple и что Ваше приложение должно сделать, чтобы поддерживать или изменить поведение по умолчанию.

Обзор обработки событий Apple

Все приложения Mac, представляющие графический интерфейс пользователя, должны быть в состоянии реагировать на определенные события Apple, отправляющиеся Mac OS. Эти события, иногда называемые требуемыми событиями, включают тех, приложение может получить в запуске ( open application, open documents, print documents, и open contents события), а также другие это получает, уже работая (снова включая open documents и print documents, а также reopen и quit события). Эти события могут также быть отправлены другими приложениями и пользователями, выполняющими сценарии.

Если приложение scriptable, оно может получить дополнительные события, предназначающиеся для scriptable функций, которые оно поддерживает.

Основы обработки событий Apple

Работа приложений с менеджером по корпоративным мероприятиям Apple, чтобы получить и извлечь информацию из событий Apple. Обработка событий Apple обычно следует за этим образцом:

  1. Для событий Apple приложение ожидает получать, оно регистрирует подпрограммы обратного вызова, названные обработчиками событий Apple, с менеджером по корпоративным мероприятиям Apple.

  2. Когда приложение получает событие Apple, оно использует менеджера по корпоративным мероприятиям Apple, чтобы диспетчеризировать событие надлежащему обработчику событий и идентифицировать объект или объекты в приложении, на котором можно выполнить указанную работу. (Подробные данные варьируются в зависимости от среды программирования по использованию.)

Можно читать больше об этом процессе в Руководстве по программированию Событий Apple и Ссылке менеджера по корпоративным мероприятиям Apple. Реализация кода для обработки событий Apple может быть несколько сложной. Однако Какао предоставляет большую встроенную поддержку обработки событий Apple, минимизируя потребность в Вашем рвении непосредственно со структурами данных о событии Apple или менеджером по корпоративным мероприятиям Apple.

Обработка событий Apple в приложении какао

Для каждого приложения Какао Набор Приложения автоматически устанавливает обработчики событий для событий Apple, которые это знает, как обработать, включая отправленных Mac OS. Эти обработчики событий реализуют поведение по умолчанию, описанное в Событиях Apple, Отправленных Mac OS, в некоторых случаях зависящим от кода, реализованного Вашим приложением.

Приложения Nonscriptable

nonscriptable приложение может поддерживать или изменить поведение по умолчанию, предоставленное Набором Приложения обработчики событий Apple этими способами:

nonscriptable приложение может также установить обработчики для других событий Apple. Но если Ваше nonscriptable приложение должно установить много обработчиков, необходимо считать создание его scriptable.

Приложения Scriptable

scriptable приложение может поддерживать или изменить поведение по умолчанию, предоставленное Набором Приложения обработчики событий Apple теми же способами, которыми nonscriptable приложение может (путем реализации или переопределения надлежащих методов, или путем установки заменяющего обработчика событий).

Для других событий Apple scriptable приложение обычно не устанавливает обработчики непосредственно (несмотря на то, что это свободно сделать так), потому что это может использовать механизм команды сценария. Тот механизм, автоматически устанавливающий обработчики на основе информации в sdef файле приложения, получен в итоге в Снимке Сценариев Какао и описан более подробно в Командах Сценария.

События Apple, отправленные Mac OS

Следующие разделы описывают события Apple, которые Ваше приложение, вероятно, получит от Mac OS, ответ, ожидающийся, и поведение по умолчанию, предоставленное Набором Приложения. Ваше приложение может реализовать, или в некоторых случаях переопределить, надлежащие методы, чтобы поддерживать или изменить поведение по умолчанию. (Эти события могут также быть отправлены сценариями или другими приложениями.)

Открытое приложение

open application (или launch) Когда приложение запускается, событие Apple получено. Приложение должно выполнить любые задачи, требуемые, когда пользователь запускает его, не открываясь или распечатывая любые документы.

Вот то, как open application событие обрабатывается в версии 10.4 OS X:

  1. Приложение запускается.

  2. Приложение определяет, должен ли новый, документ без названия быть создан путем вызова делегата приложения applicationShouldOpenUntitledFile: метод. Если делегат приложения не реализует этот метод, новый документ без названия создается. Реализуйте этот метод, если Вы хотите управлять тем поведением (является ли Ваше приложение NSDocument- основанный.)

  3. Если делегат приложения отвечает на applicationOpenUntitledFile:, то сообщение отправляется.

    Иначе:

    • Если приложение NSDocument- основанный, совместно используемое NSDocumentController отправляется это сообщение:

      openUntitledDocumentAndDisplay:error:

      Можно изменить поведение по умолчанию путем переопределения этого метода. Или можно переопределить методы, которые вызывает этот метод (описанный в документации версии 10.4 OS X для NSDocumentController).

    • Оно приложение не основано на документе для документа, который будет создаваться, Ваш делегат приложения, должно реализовать этот метод:

      applicationOpenUntitledFile:

Запускаясь в версии 10.4 OS X, open application Событие Apple может содержать информацию о том, было ли приложение запущено как элемент входа в систему или как сервис элемент. Если так, приложение обычно должно только выполнять действия, подходящие для среды, в которой оно запускается. Например, приложение запустилось как сервис, элемент может не хотеть открывать документ без названия.

Вновь открыться

reopen (или reopen application) Событие Apple получено, когда приложение вновь открывается — например, когда приложение открыто, но не frontmost, и пользователь щелкает по его значку в Прикреплении. Приложение должно выполнить надлежащие задачи — например, оно могло бы создать новый документ, если ни один не открыт.

Вот то, как reopen application событие обрабатывается:

  1. Делегат приложения отправляется это сообщение (если оно реализует метод):

    applicationShouldHandleReopen:hasVisibleWindows:

  2. Если возвращается метод YES, и при отсутствии открытых окон, это пытается создать новый документ без названия таким же образом что касается open application событие.

Можно изменить поведение по умолчанию путем реализации метода делегата приложения.

Открытый

open (или open documents) Когда приложение должно открыть список одного или более документов, событие Apple получено. Например, пользователь, возможно, выбрал файлы документов в Средстве поиска и дважды щелкнул.

Вот то, как open documents событие обрабатывается в версии 10.4 (v10.4) OS X:

  • Если приложение NSDocument- основанный, NSDocumentController отправляется это сообщение, один раз для каждого документа, который будет открыт:

    openDocumentWithContentsOfURL:display:error:

    Для Вашего приложения для настройки открытия документов в ответ на open documents Событие Apple, это может переопределить этот метод. Или это может переопределить методы, которые вызывает этот метод. Эти методы описаны в OS X v10.4 документация для NSDocumentController, который также описывает, как реализация по умолчанию обрабатывает совместимость с предыдущими версиями Mac OS.

  • Если приложение не NSDocument- базируемый:

    1. Делегат приложения отправляется это сообщение, если оно реагирует на него:

      application:openFiles:

    2. Если делегат не реагирует на то сообщение, проверки обработчика, в перечисленном порядке, реагирует ли делегат приложения на одно из следующих сообщений, и если так, отправляет его:

      openTempFile:
      openFiles:
      openFile:

      Для Вашего приложения для открытия документов в ответ на это событие Apple это должно реализовать один из этих методов.

Запускаясь в версии 10.4 OS X, open documents Событие Apple может содержать дополнительный параметр, содержащий искомый текст от поиска Центра внимания, указавшего документы, которые будут открыты. Этот параметр идентифицируется ключевым словом keyAESearchText. Приложение должно приложить разумное усилие для указания случаев искомого текста в каждом открытом документе — например, путем выбора текста и прокрутки первого или основного возникновения в представление. Набор Приложения в настоящее время не обрабатывает этот параметр, но можно обеспечить собственную реализацию путем добавления кода как показанный в Перечислении 10-1 методу, открывающему файлы, такой как application:openFiles:.

Перечисление 10-1  , Извлекающее параметр искомого текста из текущего события Apple

    NSString    *searchString = nil;
    searchString = [[[[NSAppleEventManager sharedAppleEventManager]// 1
        currentAppleEvent]// 2
        paramDescriptorForKeyword:keyAESearchText]// 3
        stringValue];// 4
    // Application-specific code to highlight the searched-for text, if any.// 5

Вот то, что делает этот фрагмент кода:

  1. Это вызывает sharedAppleEventManager метод класса NSAppleEventManager класс для получения экземпляра совместно используемого менеджера.

  2. Это вызывает currentAppleEvent метод NSAppleEventManager объект получить событие Apple, обрабатывающееся на текущем потоке, если таковые имеются, как NSAppleEventDescriptor.

  3. Это вызывает paramDescriptorForKeyword: метод того класса, передавая ключ keyAESearchText (и получающий другой экземпляр NSAppleEventDescriptor).

  4. Это вызывает stringValue метод того класса для получения искомого текста, если таковые имеются, принуждая его к тексту Unicode.

  5. Это выбирает экземпляры указанного текста, если таковые имеются, в документе, как подходящие для приложения (не показанный). Например, это могло бы прокрутить основной экземпляр в представление.

Печать

print (или print documents) Когда приложение должно распечатать список одного или более документов, событие Apple получено.

Вот то, как print событие обрабатывается в версии 10.4 OS X:

  • Если приложение NSDocument- основанный, каждый документ, который будет распечатан, отправляется это сообщение:

    printDocumentWithSettings:showPrintPanel:delegate:didPrintSelector:contextInfo:

    Документы открыты автоматически перед печатью, при необходимости. Если документ открыт только для печати, он закрывается, когда печать завершена.

    Можно изменить поведение по умолчанию путем переопределения методов, которые вызывает этот метод (описанный в OS X v10.4 документация для NSDocumentController).

  • Если приложение не NSDocument- основанный, проверки обработчика, в перечисленном порядке, реагирует ли делегат приложения на одно из следующих сообщений, и если так, отправляют его:

    printFiles:withSettings:showPrintPanels:
    printFiles:
    printFile:

    Для Вашего приложения для печати документов в ответ на это событие Apple это должно реализовать один из этих методов.

Откройте Contents

open contents Событие Apple является доступным запуском в версии 10.4 Mac OS. Это событие Apple отправляется, когда содержание, такое как текст или изображение, отбрасывается на значке приложения — например, когда перетащенное изображение отбрасывается на значке в Прикреплении. Приложение должно использовать содержание надлежащим способом — например, если документ открыт, это могло бы вставить содержание в текущей точке вставки; если никакой документ не открыт, это могло бы открыть новый документ и вставить предоставленный текст или изображение.

Если Ваше приложение предоставляет услугу, которая может принять тип данных в полученном open contents Событие Apple, обработчик по умолчанию будет использовать службу.

Вот то, как open contents событие обрабатывается:

  1. Это вызывает этот метод делегата приложения, чтобы дать приложению шанс установить службы: applicationDidFinishLaunching:

    Это уникально в этом для всех других событий Apple, описанных здесь, applicationDidFinishLaunching: вызывается после того, как описанное поведение обработки событий имеет место.

  2. Это вызывает значение по умолчанию Carbon's open contents Обработчик событий Apple, использующий предоставленную приложением службу. (Поведение углерода описано в «Общих Событиях Apple, Отправленных Mac OS» в Ответе на События Apple в Руководстве по программированию Событий Apple.

Можно изменить поведение по умолчанию путем установки собственного open contents Обработчик событий Apple. Структура события подобна open documents событие. Прямой параметр состоит из списка элементов данных содержания, которые будут открыты. Тип дескриптора для каждого элемента в списке указывает тип содержания ('PICT', 'TIFF', 'utf8', и т.д.).

Выход

quit (или quit application) Когда Ваше приложение завершается, событие Apple получено.

Вот то, как quit событие обрабатывается:

  • Если приложение NSDocument- основанный, поведение зависит от saving параметр, имеющий одно из этих трех значений:

    • NSSaveOptionsNo: Приложение выходит, не отправляя a close обменивайтесь сообщениями к любому документу.

    • NSSaveOptionsYes: Каждый неизмененный документ отправляется a close сообщение; каждый измененный документ отправляется следующее сообщение: saveDocumentWithDelegate:didSaveSelector:contextInfo:

    • NSSaveOptionsAsk: (Это - значение по умолчанию если нет saving параметр предоставляется в конечном счете.), Если существуют измененные открытые документы, NSDocumentController отправляет себе это сообщение:

      reviewUnsavedDocumentsWithAlertTitle:cancellable:delegate:didReviewAllSelector:contextInfo:
  • Если приложение не NSDocument- основанный, делегат приложения отправляется это сообщение (если оно реализовано):

    applicationShouldTerminate:

    Можно изменить поведение по умолчанию путем реализации этого метода.

Константы для обработчиков событий Apple, установленных набором приложения

Таблица 10-1 показывает константы для обработчиков событий Apple, установленных Набором Приложения для обработки событий, отправленных Mac OS. Каждое из этих событий имеет тот же класс событий, kCoreEventClass, который имеет значение 'aevt'. Ваше приложение может использовать эти константы для класса событий и идентификатора события при установке заменяющих обработчиков для изменения стандартного поведения.

Эти константы события Apple определяются в AppleEvents.h, заголовок в AE.framework, подплатформа ApplicationServices.framework. Эти и другие константы описаны в Ссылке менеджера по корпоративным мероприятиям Apple.

Табличный 10-1  Класс событий IDs для событий Apple, отправленных Mac OS

Событие Apple

Идентификатор события

Значение

open application (или launch)

kAEOpenApplication

'oapp'

reopen

kAEReopenApplication

'rapp'

open (или open documents)

kAEOpenDocuments

'odoc'

print (или print documents)

kAEPrintDocuments

'pdoc'

open contents

kAEOpenContents

'ocon'

quit (или quit application)

kAEQuitApplication

'quit'

Установка обработчика событий Apple

Ваше приложение, или scriptable или нет, может установить обработчики событий Apple непосредственно. Это обычно целесообразно в следующих случаях:

Для установки обработчика событий Apple Вы вызываете этот метод NSAppleEventManager класс:

setEventHandler:andSelector:forEventClass:andEventID:

Подпись для нового обработчика должна соответствовать один показанный в Перечислении 10-2.

  Подпись перечисления 10-2 функции обработчика событий

- (void)handleAppleEvent:(NSAppleEventDescriptor *)event withReplyEvent:(NSAppleEventDescriptor *)replyEvent;

Хорошее место для установки обработчиков событий находится в applicationWillFinishLaunching: метод делегата приложения. В той точке Набор Приложения установил свои обработчики стандартного события, поэтому при установке обработчика для одного из тех же событий это заменит версию Набора Приложения.

Установка получить обработчик URL

Перечисление 10-3 показывает, как Вы могли установить обработчик для get URL Событие Apple.

Перечисление 10-3  , Устанавливающее обработчик событий Apple в приложении Какао

NSAppleEventManager *appleEventManager = [NSAppleEventManager sharedAppleEventManager];// 1
[appleEventManager setEventHandler:self andSelector:@selector(handleGetURLEvent:withReplyEvent:) forEventClass:kInternetEventClass andEventID:kAEGetURL];// 2

Вот то, что делает код в Перечислении 10-3:

  1. Это получает ссылку на совместно используемый объект менеджера по корпоративным мероприятиям Apple.

  2. Это вызывает метод того объекта установить новый обработчик, передавая:

    • Ссылка на объект делегата, self, который обработает событие.

    • Селектор для нового get URL обработчик (показанный в Перечислении 10-4).

    • Класс событий, постоянный для события Apple (от заголовка HIServices/InternetConfig.h в платформе Прикладных служб).

    • Идентификатор события, постоянный для события Apple (от заголовка HIServices/InternetConfig.h в платформе Прикладных служб).

    Если обработчик событий уже установлен для указанного класса событий и идентификатора события, это заменяется.

Реализация получить обработчик URL

Перечисление 10-4 обеспечивает шаблон для обработчика событий. Этот код находится в реализации Вашего делегата приложения. После того, как этот обработчик был установлен, он вызывается каждый раз, когда приложение получает a get URL Событие Apple. Событие Apple передается обработчику как экземпляр NSAppleEventDescriptor.

  Реализация перечисления 10-4 получить URL обработчик событий Apple

- (void)handleGetURLEvent:(NSAppleEventDescriptor *)event withReplyEvent:(NSAppleEventDescriptor *)replyEvent
{
    // Extract the URL from the Apple event and handle it here.
}

Подробные данные реализации оставляют Вам, но они требуют методов использования NSAppleEventDescriptor класс для извлечения URL из прямого параметра события Apple, затем выполняя требуемую работу с ним (обычно отображение страницы, на которую ссылаются, в окне). Для подобного примера см. Перечисление 10-1.

Приостановка и возобновление событий Apple и команд сценария

Начиная с версии 10.3 OS X, NSAppleEventManager класс обеспечивает методы для приостановки и возобновления отдельного события Apple. Эти методы полезны для приложений, реагирующих на события Apple, не используя встроенную поддержку сценариев Какао. Для приложений, действительно использующих в своих интересах поддержку сценариев Какао, NSScriptCommand обеспечивает методы для приостановки и возобновления выполнения команды сценария.

Приложение обычно приостанавливает событие Apple (или команда сценария), когда оно выполняет асинхронную работу, так, чтобы приложение больше не получало события Apple от того же сценария, пока оно не завершит обработку текущего события (или команда сценария). Например, предположите, что приложение должно вывести на экран лист как часть получения информации для возврата в событии Apple ответа. Если так, это может приостановить события Apple (или команда сценария) прежде, чем вывести на экран лист, вставить информацию в событие Apple ответа после того, как пользователь отклоняет лист, затем возобновитесь. Эта потребность приостановить и возобновиться может произойти с другими асинхронными операциями (включая тех, которые могут быть открытыми или потребоваться много времени для завершения).

Для приостановки события Apple Вы используете NSAppleEventManager метод suspendCurrentAppleEvent, который возвращает приостановку ID (NSAppleEventManagerSuspensionID) для события Apple, обрабатываемого на текущем потоке. Можно передать эту приостановку ID appleEventForSuspensionID: получить дескриптор события Apple для приостановленного события, или к replyAppleEventForSuspensionID: получить дескриптор для соответствующего события Apple ответа. Для возобновления приостановленного события Apple Вы передаете связанную приостановку ID resumeWithSuspensionID:. В версии 10.4 OS X этот метод может быть вызван в любом потоке.

Для приостановки команды сценария используйте NSScriptCommand метод suspendExecution. Этот метод приостанавливает выполнение команды сценария, если бы получатель выполняется в текущем потоке встроенной поддержкой сценариев Какао (т.е. получатель был бы возвращен [NSScriptCommand currentCommand]). Вы используете resumeExecutionWithResult: возобновлять приостановленную команду сценария. В версии 10.4 OS X этот метод может быть вызван в любом потоке.