Contents

NSAppleEventDescriptor

A wrapper for the Apple event descriptor data type.

Declaration

class NSAppleEventDescriptor

Overview

An instance of NSAppleEventDescriptor represents a descriptor—the basic building block for Apple events. This class is a wrapper for the underlying Apple event descriptor data type, AEDesc. Scriptable Cocoa applications frequently work with instances of NSAppleEventDescriptor, but should rarely need to work directly with the AEDesc data structure.

A descriptor is a data structure that stores data and an accompanying four-character code. A descriptor can store a value, or it can store a list of other descriptors (which may also be lists). All the information in an Apple event is stored in descriptors and lists of descriptors, and every Apple event is itself a descriptor list that matches certain criteria.

Descriptors can be used to build arbitrarily complex containers, so that one Apple event can represent a script statement such as tell application "TextEdit" to get word 3 of paragraph 6 of document 3.

In working with Apple event descriptors, it can be useful to understand some of the underlying data types. You’ll find terms such as descriptor, descriptor list, Apple event record, and Apple event defined in Building an Apple Event in Apple Events Programming Guide. You’ll also find information on the four-character codes used to identify information within a descriptor. Apple event data types are defined in Apple Event Manager. The values of many four-character codes used by Apple (and in some cases reused by developers) can be found in AppleScript Terminology and Apple Event Codes.

The most common reason to construct an Apple event with an instance of NSAppleEventDescriptor is to supply information in a return Apple event. The most common situation where you might need to extract information from an Apple event (as an instance of NSAppleEventDescriptor) is when an Apple event handler installed by your application is invoked, as described in “Installing an Apple Event Handler” in How Cocoa Applications Handle Apple Events. In addition, if you execute an AppleScript script using the NSAppleScript class, you get an instance of NSAppleEventDescriptor as the return value, from which you can extract any required information.

When you work with an instance of NSAppleEventDescriptor, you can access the underlying descriptor directly, if necessary, with the aeDesc method. Other methods, including descriptorWithDescriptorType:bytes:length: make it possible to create and initialize instances of NSAppleEventDescriptor without creating temporary instances of NSData.

The designated initializer for NSAppleEventDescriptor is init(aeDescNoCopy:). However, it is unlikely that you will need to create a subclass of NSAppleEventDescriptor.

Cocoa doesn’t currently provide a mechanism for applications to directly send raw Apple events (though compiling and executing an AppleScript script with NSAppleScript may result in Apple events being sent). However, Cocoa applications have full access to the Apple Event Manager C APIs for working with Apple events. So, for example, you might use an instance of NSAppleEventDescriptor to assemble an Apple event and call the Apple Event Manager function AESend(_:_:_:_:_:_:_:) to send it.

If you need to send Apple events, or if you need more information on some of the Apple event concepts described here, see Apple Events Programming Guide and Apple Event Manager.

Topics

Creating and Initializing Descriptors

Getting Information About a Descriptor

Working With List Descriptors

Working With Record Descriptors

Working With Apple Event Descriptors

Supporting Types

Initializers

Instance Properties

Instance Methods

Type Methods

See Also

Apple Event Handling