Class

# AppleEvent

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

<span class="title-ref">AppleEvent</span> objects can be used to communicate with other macOS applications and the macOS System software. If you are compiling your application for use on other operating systems, be sure to check the global `Boolean</api/data_types/boolean>` constants `TargetWindows</api/compiler_directives/targetwindows>`, `TargetMacOS</api/compiler_directives/targetmacos>`, and `TargetLinux</api/compiler_directives/targetlinux>`. These constants return `True</api/language/true>` if the application is running on the respective operating system.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                                    | Type                                                              | Read-Only | Shared |
|---------------------------------------------------------|-------------------------------------------------------------------|-----------|--------|
| `Ptr<appleevent.ptr>`                                   | `Integer</api/data_types/integer>`                                |           |        |
| `ReplyBoolean<appleevent.replyboolean>`                 | `Boolean</api/data_types/boolean>`                                |           |        |
| `ReplyDescList<appleevent.replydesclist>`               | `AppleEventDescList</api/macos/appleeventdesclist>`               |           |        |
| `ReplyDouble<appleevent.replydouble>`                   | `Double</api/data_types/double>`                                  |           |        |
| `ReplyEnumerated<appleevent.replyenumerated>`           | `String</api/data_types/string>`                                  |           |        |
| `ReplyFolderItem<appleevent.replyfolderitem>`           | `FolderItem</api/files/folderitem>`                               |           |        |
| `ReplyInteger<appleevent.replyinteger>`                 | `Integer</api/data_types/integer>`                                |           |        |
| `ReplyMacType<appleevent.replymactype>`                 | `String</api/data_types/string>`                                  |           |        |
| `ReplyObjectSpecifier<appleevent.replyobjectspecifier>` | `AppleEventObjectSpecifier</api/macos/appleeventobjectspecifier>` |           |        |
| `ReplyPtr<appleevent.replyptr>`                         | `Integer</api/data_types/integer>`                                |           |        |
| `ReplyRecord<appleevent.replyrecord>`                   | `AppleEventRecord</api/macos/appleeventrecord>`                   |           |        |
| `ReplySingle<appleevent.replysingle>`                   | `Single</api/data_types/single>`                                  |           |        |
| `ReplyString<appleevent.replystring>`                   | `String</api/data_types/string>`                                  |           |        |
| `Timeout<appleevent.timeout>`                           | `Integer</api/data_types/integer>`                                |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                    | Parameters                                                                                                                                | Returns                                                           | Shared |
|---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|--------|
| `BooleanParam<appleevent.booleanparam>`                 |                                                                                                                                           | `Boolean</api/data_types/boolean>`                                |        |
| `Constructor<appleevent.constructor0>`                  | EventClass As `String</api/data_types/string>`, EventID As `String</api/data_types/string>`, BundleID As `String</api/data_types/string>` |                                                                   |        |
| `DescListParam<appleevent.desclistparam>`               |                                                                                                                                           | `AppleEventDescList</api/macos/appleeventdesclist>`               |        |
| `DoubleParam<appleevent.doubleparam>`                   |                                                                                                                                           | `Double</api/data_types/double>`                                  |        |
| `EnumeratedParam<appleevent.enumeratedparam>`           |                                                                                                                                           | `String</api/data_types/string>`                                  |        |
| `FolderItemParam<appleevent.folderitemparam>`           |                                                                                                                                           | `FolderItem</api/files/folderitem>`                               |        |
| `IntegerParam<appleevent.integerparam>`                 |                                                                                                                                           | `Integer</api/data_types/integer>`                                |        |
| `LoadFromTemplate<appleevent.loadfromtemplate>`         | Template As `AppleEventTemplate</api/macos/appleeventtemplate>`                                                                           |                                                                   |        |
| `MacTypeParam<appleevent.mactypeparam>`                 |                                                                                                                                           | `String</api/data_types/string>`                                  |        |
| `ObjectSpecifierParam<appleevent.objectspecifierparam>` |                                                                                                                                           | `AppleEventObjectSpecifier</api/macos/appleeventobjectspecifier>` |        |
| `RecordParam<appleevent.recordparam>`                   |                                                                                                                                           | `AppleEventRecord</api/macos/appleeventrecord>`                   |        |
| `Send<appleevent.send>`                                 |                                                                                                                                           | `Boolean</api/data_types/boolean>`                                |        |
| `SetNullParam<appleevent.setnullparam>`                 | ParameterName As `String</api/data_types/string>`                                                                                         |                                                                   |        |
| `SingleParam<appleevent.singleparam>`                   |                                                                                                                                           | `Single</api/data_types/single>`                                  |        |
| `StringParam<appleevent.stringparam>`                   |                                                                                                                                           | `String</api/data_types/string>`                                  |        |

## Property descriptions

<div id="appleevent.ptr">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.Ptr

**Ptr** As `Integer</api/data_types/integer>`

> A Pointer to the underlying <span class="title-ref">AppleEvent</span> data structure, for use with `Declare</api/language/declare>` statements.

<div id="appleevent.replyboolean">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyBoolean

**ReplyBoolean** As `Boolean</api/data_types/boolean>`

> A reply in `Boolean</api/data_types/boolean>` form. `True</api/language/true>` means that the application successfully handled the message.

<div id="appleevent.replydesclist">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyDescList

**ReplyDescList** As `AppleEventDescList</api/macos/appleeventdesclist>`

> A reply in `AppleEventDescriptorList</api/macos/appleeventdesclist>` form.

<div id="appleevent.replydouble">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyDouble

**ReplyDouble** As `Double</api/data_types/double>`

> A reply in `Double</api/data_types/double>` form.

<div id="appleevent.replyenumerated">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyEnumerated

**ReplyEnumerated** As `String</api/data_types/string>`

> A reply in `Enum</api/data_types/enumeration>` form.

<div id="appleevent.replyfolderitem">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyFolderItem

**ReplyFolderItem** As `FolderItem</api/files/folderitem>`

> A reply in `FolderItem</api/files/folderitem>` form.

<div id="appleevent.replyinteger">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyInteger

**ReplyInteger** As `Integer</api/data_types/integer>`

> A reply in `integer</api/data_types/integer>` form.

<div id="appleevent.replymactype">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyMacType

**ReplyMacType** As `String</api/data_types/string>`

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

<div id="appleevent.replyobjectspecifier">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyObjectSpecifier

**ReplyObjectSpecifier** As `AppleEventObjectSpecifier</api/macos/appleeventobjectspecifier>`

> A reply in `AppleEventObjectSpecifier</api/macos/appleeventobjectspecifier>` form.

<div id="appleevent.replyptr">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyPtr

**ReplyPtr** As `Integer</api/data_types/integer>`

> A reply in pointer form to the underlying <span class="title-ref">AppleEvent</span> structures for use with `Declare</api/language/declare>` statements.

<div id="appleevent.replyrecord">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyRecord

**ReplyRecord** As `AppleEventRecord</api/macos/appleeventrecord>`

> A reply in `AppleEventRecord</api/macos/appleeventrecord>` form.

<div id="appleevent.replysingle">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplySingle

**ReplySingle** As `Single</api/data_types/single>`

> A reply in `Single</api/data_types/single>` form.

<div id="appleevent.replystring">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ReplyString

**ReplyString** As `String</api/data_types/string>`

> A reply in `String</api/data_types/string>` form.

<div id="appleevent.timeout">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.Timeout

**Timeout** As `Integer</api/data_types/integer>`

> Timeout time in seconds.

## Method descriptions

<div id="appleevent.booleanparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.BooleanParam

**BooleanParam** As `Boolean</api/data_types/boolean>`

> A `Boolean</api/data_types/boolean>` being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.constructor0">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.Constructor

**Constructor**(EventClass As `String</api/data_types/string>`, EventID As `String</api/data_types/string>`, BundleID As `String</api/data_types/string>`)

> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> `Constructors</api/language/constructor>` are special methods called when you create an object with the `New</api/language/new>` keyword and pass in the parameters above.
>
> </div>
>
> Creates a new <span class="title-ref">AppleEvent</span>.
>
> *EventClass* is the four character <span class="title-ref">AppleEvent</span> class code. *EventID* is the four character <span class="title-ref">AppleEvent</span> ID. *BundleID* identifies the target application for the <span class="title-ref">AppleEvent</span>.
>
> 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.)

<div id="appleevent.desclistparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.DescListParam

**DescListParam** As `AppleEventDescList</api/macos/appleeventdesclist>`

> An `AppleEventDescList</api/macos/appleeventdesclist>` object being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.doubleparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.DoubleParam

**DoubleParam** As `Double</api/data_types/double>`

> A `Double</api/data_types/double>` being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.enumeratedparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.EnumeratedParam

**EnumeratedParam** As `String</api/data_types/string>`

> A four character `String</api/data_types/string>` being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.folderitemparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.FolderItemParam

**FolderItemParam** As `FolderItem</api/files/folderitem>`

> A `FolderItem</api/files/folderitem>` being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.integerparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.IntegerParam

**IntegerParam** As `Integer</api/data_types/integer>`

> An `Integer</api/data_types/integer>` (passed as a `String</api/data_types/string>`) being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.loadfromtemplate">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.LoadFromTemplate

**LoadFromTemplate**(Template As `AppleEventTemplate</api/macos/appleeventtemplate>`)

> Loads an <span class="title-ref">AppleEvent</span> template.

<div id="appleevent.mactypeparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.MacTypeParam

**MacTypeParam** As `String</api/data_types/string>`

> A four character `String</api/data_types/string>` being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.objectspecifierparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.ObjectSpecifierParam

**ObjectSpecifierParam** As `AppleEventObjectSpecifier</api/macos/appleeventobjectspecifier>`

> An `AppleEventObjectSpecifier</api/macos/appleeventobjectspecifier>` being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.recordparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.RecordParam

**RecordParam** As `AppleEventRecord</api/macos/appleeventrecord>`

> An `AppleEventRecord</api/macos/appleeventrecord>` being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.send">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.Send

**Send** As `Boolean</api/data_types/boolean>`

> Sends the <span class="title-ref">AppleEvent</span>. Returns `True</api/language/true>` if the <span class="title-ref">AppleEvent</span> was successfully sent and `False</api/language/false>` if it was not.
>
> `True</api/language/true>` does not mean that the receiving application successfully handled the message. Use the ReplyBoolean property for that.

<div id="appleevent.setnullparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.SetNullParam

**SetNullParam**(ParameterName As `String</api/data_types/string>`)

> Sets the parameter specified by the Keyword to a null.

<div id="appleevent.singleparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.SingleParam

**SingleParam** As `Single</api/data_types/single>`

> A `Single</api/data_types/single>` being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

<div id="appleevent.stringparam">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

AppleEvent.StringParam

**StringParam** As `String</api/data_types/string>`

> A `String</api/data_types/string>` being passed as a parameter in the <span class="title-ref">AppleEvent</span>.

## 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</topics/application_structure/ios/using_a_plist>` file.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### More apple event info

- <https://www.felix-schwarz.org/blog/2018/08/new-apple-event-apis-in-macos-mojave>
- <https://indiestack.com/2018/08/apple-events-usage-description/>
- <https://developer.apple.com/documentation/security/nsappleeventsusagedescription>

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### AppleEvents basics

An <span class="title-ref">AppleEvent</span> is a self-contained block of data which consists in a sequence of key-type-value data (called an <span class="title-ref">AppleEvent</span> 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 <span class="title-ref">AppleEvent</span> as a whole is itself and <span class="title-ref">AppleEvent</span> Descriptor. This flexibility makes the power of AppleEvents but it also has a price: their complexity of use.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Anatomy of an <span class="title-ref">AppleEvent</span>

- 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 <span class="title-ref">AppleEvent</span> 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 <span class="title-ref">AppleEvent</span> which holds the result of the <span class="title-ref">AppleEvent</span>.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### 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](https://developer.apple.com/library/mac/#documentation/AppleScript/Conceptual/AppleScriptLangGuide/introduction/ASLR_intro.html) 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.

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

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

``` xojo
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 <span class="title-ref">AppleEvent</span> 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 <span class="title-ref">AppleEvent</span> terminology) of values instead of a single one. As an example, the following AppleScript command

``` xojo
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:

- `GetIndexedObjectDescriptor</api/macos/getindexedobjectdescriptor>`: you want one object in an array. The key value is the index of the object in the array.
- `GetNamedObjectDescriptor</api/macos/getnamedobjectdescriptor>`: you want to describe an object by its name.
- `GetOrdinalObjectDescriptor</api/macos/getordinalobjectdescriptor>`: you want to get the first, last, middle, any (random) or all object(s).
- `GetRangeObjectDescriptor</api/macos/getrangeobjectdescriptor>`: you want to get a range of objects in an array.
- `GetStringComparisonObjectDescriptor</api/macos/getstringcomparisonobjectdescriptor>`: you want to get an object by comparison with another object descriptor.
- `GetTestObjectDescriptor</api/macos/gettestobjectdescriptor>`: you want to select objects using a test (like an `If...Then...Else</api/language/if...then...else>` statement).
- `GetUniqueIDObjectDescriptor</api/macos/getuniqueidobjectdescriptor>`: you want to get the object given a unique ID that was passed to you earlier by the application (you cannot *guess* the unique ID).
- `GetPropertyObjectDescriptor</api/macos/getpropertyobjectdescriptor>`: you want to access a property of an object.

<div class="note">

<div class="title">

Note

</div>

whenever you want to get an object at the application level, e.g. a window, you should pass `Nil</api/language/nil>` as the *Object* parameter.

</div>

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<span class="title-ref">AppleEvent</span> objects are used to send and receive information between your application and other macOS applications or the Mac OS. To send an <span class="title-ref">AppleEvent</span> from your application to another application, create an <span class="title-ref">AppleEvent</span> with the `AppleEvent constructor</api/macos/appleevent>`, fill in the <span class="title-ref">AppleEvent</span>'s properties with any necessary data, then call the <span class="title-ref">AppleEvent</span>'s `Send<appleevent.send>` function to send it.

<span class="title-ref">AppleEvents</span> can also be received by your application. When an <span class="title-ref">AppleEvent</span> is received, the `DesktopApplication</api/user_interface/desktop/desktopapplication>` object's `HandleAppleEvent<application.handleappleevent>` event is executed and the <span class="title-ref">AppleEvent</span> is passed to the event as a parameter. All intrinsic AppleEvents are first passed to the `DesktopApplication</api/user_interface/desktop/desktopapplication>` object's `HandleAppleEvent<application.handleappleevent>` event handler. If you return `True</api/language/true>` from this event, the default behavior of the <span class="title-ref">AppleEvent</span> will not be executed. For more information on receiving AppleEvents, see the `DesktopApplication</api/user_interface/desktop/desktopapplication>` class.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Replying to an <span class="title-ref">AppleEvent</span>

When an <span class="title-ref">AppleEvent</span> is received (via an <span class="title-ref">AppleEvent</span> handler) the ReplyBoolean, ReplyInteger, and ReplyString properties can be used to automatically send a reply back to the application that sent the <span class="title-ref">AppleEvent</span>. When sending an <span class="title-ref">AppleEvent</span> (via the `Send<appleevent.send>` method) the *Reply*\* properties, such as `ReplyInteger<appleevent.replyinteger>`, can be used to get any reply the target application has sent back once it receives the <span class="title-ref">AppleEvent</span>.

For example, the line:

``` xojo
e.ReplyBoolean = True
```

indicates that the application successfully handled the <span class="title-ref">AppleEvent</span> message.

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

``` xojo
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:

``` xojo
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", FolderItem.PathModes.Native))
list.AppendFolderItem(New FolderItem("My Other Document", FolderItem.PathModes.Native))
a.DescListParam("----") = list
If Not a.Send Then
  MessageBox("The AppleEvent could not be sent.")
End If
```

## Compatibility

|                       |                       |
|-----------------------|-----------------------|
| **Project Types**     | Console, Desktop, Web |
| **Operating Systems** | macOS                 |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; \* `AppleEventDescList</api/macos/appleeventdesclist>`, `AppleEventObjectSpecifier</api/macos/appleeventobjectspecifier>` classes; `DesktopApplication</api/user_interface/desktop/desktopapplication>` object; `If…#Else…#Endif</api/compiler_directives/if...endif>` statement; `TargetLinux</api/compiler_directives/targetlinux>`, `TargetMacOS</api/compiler_directives/targetmacos>`, `TargetWindows</api/compiler_directives/targetwindows>` constants.

- `Advanced Apple Events</topics/macos/advanced_apple_events>`
- [Apple Events Programming Guide](http://developer.apple.com/legacy/mac/library/documentation/AppleScript/Conceptual/AppleEvents/AppleEvents.pdf), a legacy guide on Apple's website.
- [Introduction to AppleScript Language](https://developer.apple.com/library/mac/#documentation/AppleScript/Conceptual/AppleScriptLangGuide/introduction/ASLR_intro.html) on Apple's website.
- For a list of system-defined errors, see file /System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/CarbonCore.framework/Headers/MacErrors.h

</div>