Class

AppleEvent

Description

AppleEvent objects can be used to communicate with other Macintosh applications and the Macintosh System software. If you are compiling your application for use on other operating systems, be sure to check the global Boolean constants TargetWindows, TargetMacOS, and TargetLinux. These constants return True if the application is running on the respective operating system.

Methods

Name

Parameters

Returns

Shared

Constructor

EventClass As String, EventID As String, BundleID As String

LoadFromTemplate

Template As AppleEventTemplate

Send

Boolean

SetNullParam

ParameterName As String

Property descriptions

AppleEvent.BooleanParam

BooleanParam As Boolean

A Boolean being passed as a parameter in the AppleEvent.

AppleEvent.DescListParam

DescListParam As AppleEventDescList

An AppleEventDescList object being passed as a parameter in the AppleEvent.

AppleEvent.DoubleParam

DoubleParam As Double

A Double being passed as a parameter in the AppleEvent.

AppleEvent.EnumeratedParam

EnumeratedParam As String

A four character String being passed as a parameter in the AppleEvent.

AppleEvent.FolderItemParam

FolderItemParam As FolderItem

A FolderItem being passed as a parameter in the AppleEvent.

AppleEvent.IntegerParam

IntegerParam As Integer

An Integer (passed as a String) being passed as a parameter in the AppleEvent.

AppleEvent.MacTypeParam

MacTypeParam As String

A four character String being passed as a parameter in the AppleEvent.

AppleEvent.ObjectSpecifierParam

ObjectSpecifierParam As AppleEventObjectSpecifier

An AppleEventObjectSpecifier being passed as a parameter in the AppleEvent.

AppleEvent.Ptr

Ptr As Integer

A Pointer to the underlying AppleEvent data structure, for use with Declare statements.

AppleEvent.RecordParam

RecordParam As AppleEventRecord

An AppleEventRecord being passed as a parameter in the AppleEvent.

AppleEvent.ReplyBoolean

ReplyBoolean As Boolean

A reply in Boolean form. True means that the application successfully handled the message.

AppleEvent.ReplyDescList

ReplyDescList As AppleEventDescList

A reply in AppleEventDescriptorList form.

AppleEvent.ReplyDouble

ReplyDouble As Double

A reply in Double form.

AppleEvent.ReplyEnumerated

ReplyEnumerated As String

A reply in Enum form.

AppleEvent.ReplyFolderItem

ReplyFolderItem As FolderItem

A reply in FolderItem form.

AppleEvent.ReplyInteger

ReplyInteger As Integer

A reply in integer form.

AppleEvent.ReplyMacType

ReplyMacType As String

A reply in the form of a four-character MacType.

AppleEvent.ReplyObjectSpecifier

ReplyObjectSpecifier As AppleEventObjectSpecifier

A reply in AppleEventObjectSpecifier form.

AppleEvent.ReplyPtr

ReplyPtr As Integer

A reply in pointer form to the underlying AppleEvent structures for use with Declare statements.

AppleEvent.ReplyRecord

ReplyRecord As AppleEventRecord

A reply in AppleEventRecord form.

AppleEvent.ReplySingle

ReplySingle As Single

A reply in Single form.

AppleEvent.ReplyString

ReplyString As String

A reply in String form.

AppleEvent.SingleParam

SingleParam As Single

A Single being passed as a parameter in the AppleEvent.

AppleEvent.StringParam

StringParam As String

A String being passed as a parameter in the AppleEvent.

AppleEvent.Timeout

Timeout As Integer

Timeout time in seconds.

Method descriptions

AppleEvent.Constructor

Constructor(EventClass As String, EventID As String, BundleID As String)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a new AppleEvent.

EventClass is the four character AppleEvent class code. EventID is the four character AppleEvent ID. BundleID identifies the target application for the AppleEvent.

Use this constructor instead of the deprecated NewAppleEvent function. (Note that the BundleID parameter of this constructor is not the same as the OSType parameter of the deprecated NewAppleEvent function, even though both are Strings.)

AppleEvent.LoadFromTemplate

LoadFromTemplate(Template As AppleEventTemplate)

Loads an AppleEvent template.

AppleEvent.Send

Send As Boolean

Sends the AppleEvent. Returns True if the AppleEvent was successfully sent and False if it was not.

True does not mean that the receiving application successfully handled the message. Use the ReplyBoolean property for that.

AppleEvent.SetNullParam

SetNullParam(ParameterName As String)

Sets the parameter specified by the Keyword to a null.

Notes

In order to use AppleEvents on newer versions of macOS (Mojave and later) you will need to include the NSAppleEventsUsageDescription key in your plist file.

AppleEvents basics

An AppleEvent is a self-contained block of data which consists in a sequence of key-type-value data (called an AppleEvent Descriptor, or AEDesc per Apple's terminology). Each descriptor can contain other descriptors as an ordered array or as a mixture of keyed data. The AppleEvent as a whole is itself and AppleEvent Descriptor. This flexibility makes the power of AppleEvents but it also has a price: their complexity of use.

Anatomy of an AppleEvent

  • A command, composed of an event class and an event ID (both a four-character code).

  • Some so called attributes, notably the target, i.e. the application to which the AppleEvent should be sent. The target can be any already running application, either on the local or a distant computer.

  • Some parameters, each being identified by a four-character code. Internally, each parameter also stores its type, its size and its data. You should use the appropriate xxxParam() properties to get or set parameters of a given type. The special parameter '----' is called the direct parameter.

  • An automatically generated reply AppleEvent which holds the result of the AppleEvent.

Applescript

AppleScript is a way of using AppleEvents very easily through a sort of natural speaking language. The text script is first compiled as a sequence of AppleEvents, then it can be executed any number of times with different parameters. AppleScript was part of the Apple's Open Scripting Architecture (OSA). OSA allows everyone to develop a full programming language based on AppleEvents but, as of now, only AppleScript survived as an OSA language.

See Introduction to AppleScript Language on Apple's website.

The mandatory AppleEvents

Per Apple's programming rules, every application interacting with the user should support the following AppleEvents:

  • aevt/oapp: sent to the application when it is opened ('oapp' stands for Open APPlication).

  • aevt/odoc: sent to the application when one or more documents are to be opened ('odoc' stands for Open DOCument)

  • aevt/quit: sent to quit the application.

  • aevt/pdoc: sent to the application to print a document ('pdoc' stands for Print DOCument). Mandatory only if printing is sensible in the context of your application.

  • aevt/rapp: sent to application when user reopens the application, either by double-clicking again on the icon, or clicking on the icon in the dock ('rapp' stands for Reopen APPlication).

Object descriptors

AppleEvents are sort of object oriented as they give instructions on what to do on a given object (a button, a window...). However, they are intimately linked to AppleScript which is supposed to be a very simple and natural language, hence the use of common words (before, after, first, last, any...) which are sometimes difficult to implement in another programming language. This is why there are 9 different Get...ObjectDescriptor methods.

Use the "dot notation" to access an object and any of its property, e.g.

Var s As String
s = Window1.ContainerControl1.Control1.Value

In AppleScript, you would use "of" instead, like in:

set s to Text of Control1 of ContainerControl1 of Window1

("of Application" is usually omitted)

Describing an object

According to the context, there may be different ways of describing an object: the frontmost window, the next row, the first word... However, the application you sent an AppleEvent to should reply by giving you a better description of the object, such as its unique ID. In such a case, you should use the object descriptor that the application sent to you.

Also, the flexibility of AppleEvents allows a function to return any kind of data. Most notably, you can get an array (i.e. a list in AppleEvent terminology) of values instead of a single one. As an example, the following AppleScript command

tell application "Finder" to get name of windows
 --this is interpreted as "give me the name of every opened window"

may legally return nothing or an empty list if there is no window opened, a string or a list with only one string item if there is 1 window opened, or a list of strings when there are more than one window opened.

Getting an object descriptor

As said before, there are 9 different Get...ObjectDescriptor functions corresponding to the different ways to obtain a reference to an object. Choose the one which suits best your needs:

Note: whenever you want to get an object at the application level, e.g. a window, you should pass Nil as the Object parameter.

AppleEvent objects are used to send and receive information between your application and other Macintosh applications or the Mac OS. To send an AppleEvent from your application to another application, create an AppleEvent with the AppleEvent constructor, fill in the AppleEvent's properties with any necessary data, then call the AppleEvent's Send function to send it.

AppleEvents can also be received by your application. When an AppleEvent is received, the DesktopApplication object's HandleAppleEvent event is executed and the AppleEvent is passed to the event as a parameter. All intrinsic AppleEvents are first passed to the DesktopApplication object's HandleAppleEvent event handler. If you return True from this event, the default behavior of the AppleEvent will not be executed. For more information on receiving AppleEvents, see the DesktopApplication class.

Replying to an AppleEvent

When an AppleEvent is received (via an AppleEvent handler) the ReplyBoolean, ReplyInteger, and ReplyString properties can be used to automatically send a reply back to the application that sent the AppleEvent. When sending an AppleEvent (via the Send method) the Reply* properties, such as ReplyInteger, can be used to get any reply the target application has sent back once it receives the AppleEvent.

For example, the line:

e.ReplyBoolean = True

indicates that the application successfully handled the AppleEvent message.

To determine whether the other application successfully handled a message, use code such as:

Var ae As AppleEvent
Var s As String

If ae.Send Then ' AE successfully sent
  If ae.ReplyBoolean Then
    s = "Yes (handled)"
  Else
    s = "Yes (unhandled)"
  End If
Else
  s = "No"
End If

Sample code

In this code, the TextEdit application (which must be running for this code to work) is instructed to open two documents ("My Document" and "My Other Document") that are located in the default folder:

Var a As AppleEvent
Var list As AppleEventDescList

a = New AppleEvent("aevt", "odoc", "com.apple.textedit")
list = New AppleEventDescList
list.AppendFolderItem(New FolderItem("My Document"))
list.AppendFolderItem(New FolderItem("My Other Document"))
a.DescListParam("----") = list
If Not a.Send Then
  MessageBox("The AppleEvent could not be sent.")
End If

Compatibility

All project types on all supported operating systems.

See also

Object parent class; * AppleEventDescList, AppleEventObjectSpecifier classes; DesktopApplication object; If…#Else…#Endif statement; TargetLinux, TargetMacOS, TargetWindows constants.