Class

NSAppleEventDescriptor

A wrapper for the Apple event descriptor data type.

Declaration

@interface NSAppleEventDescriptor : NSObject

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 initWithAEDescNoCopy:. 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

+ appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:

Creates a descriptor that represents an Apple event, initialized according to the specified information.

+ descriptorWithBoolean:

Creates a descriptor initialized with type typeBoolean that stores the specified Boolean value.

+ descriptorWithDescriptorType:bytes:length:

Creates a descriptor initialized with the specified event type that stores the specified data (from a series of bytes).

+ descriptorWithDescriptorType:data:

Creates a descriptor initialized with the specified event type that stores the specified data (from an instance of NSData).

+ descriptorWithEnumCode:

Creates a descriptor initialized with type typeEnumerated that stores the specified enumerator data type value.

+ descriptorWithInt32:

Creates a descriptor initialized with Apple event type typeSInt32 that stores the specified integer value.

+ descriptorWithString:

Creates a descriptor initialized with type typeUnicodeText that stores the text from the specified string.

+ descriptorWithTypeCode:

Creates a descriptor initialized with type typeType that stores the specified type value.

+ listDescriptor

Creates and initializes an empty list descriptor.

+ nullDescriptor

Creates and initializes a descriptor with no parameter or attribute values set.

+ recordDescriptor

Creates and initializes a descriptor for an Apple event record whose data has yet to be set.

- initListDescriptor

Initializes a newly allocated instance as an empty list descriptor.

- initRecordDescriptor

Initializes a newly allocated instance as a descriptor that is an Apple event record.

- initWithAEDescNoCopy:

Initializes a newly allocated instance as a descriptor for the specified Carbon AEDesc structure.

- initWithDescriptorType:bytes:length:

Initializes a newly allocated instance as a descriptor with the specified descriptor type and data (from an arbitrary sequence of bytes and a length count).

- initWithDescriptorType:data:

Initializes a newly allocated instance as a descriptor with the specified descriptor type and data (from an instance of NSData).

- initWithEventClass:eventID:targetDescriptor:returnID:transactionID:

Initializes a newly allocated instance as a descriptor for an Apple event, initialized with the specified values.

Getting Information About a Descriptor

aeDesc

The AEDesc structure encapsulated by the receiver, if it has one.

booleanValue

The contents of the receiver as a Boolean value, coercing (to typeBoolean) if necessary.

- coerceToDescriptorType:

Returns a descriptor obtained by coercing the receiver to the specified type.

data

The receiver’s data.

descriptorType

The descriptor type of the receiver.

enumCodeValue

The contents of the receiver as an enumeration type, coercing to typeEnumerated if necessary.

int32Value

The contents of the receiver as an integer, coercing (to typeSInt32) if necessary.

numberOfItems

The number of descriptors in the receiver’s descriptor list.

stringValue

The contents of the receiver as a Unicode text string, coercing to typeUnicodeText if necessary.

typeCodeValue

The contents of the receiver as a type, coercing to typeType if necessary.

Working With List Descriptors

- descriptorAtIndex:

Returns the descriptor at the specified (one-based) position in the receiving descriptor list.

- insertDescriptor:atIndex:

Inserts a descriptor at the specified (one-based) position in the receiving descriptor list, replacing the existing descriptor, if any, at that position.

- removeDescriptorAtIndex:

Removes the descriptor at the specified (one-based) position in the receiving descriptor list.

Working With Record Descriptors

- descriptorForKeyword:

Returns the receiver’s descriptor for the specified keyword.

- keywordForDescriptorAtIndex:

Returns the keyword for the descriptor at the specified (one-based) position in the receiver.

- removeDescriptorWithKeyword:

Removes the receiver’s descriptor identified by the specified keyword.

- setDescriptor:forKeyword:

Adds a descriptor, identified by a keyword, to the receiver.

Working With Apple Event Descriptors

- attributeDescriptorForKeyword:

Returns a descriptor for the receiver’s Apple event attribute identified by the specified keyword.

eventClass

The event class for the receiver.

eventID

The event ID for the receiver.

- paramDescriptorForKeyword:

Returns a descriptor for the receiver’s Apple event parameter identified by the specified keyword.

- removeParamDescriptorWithKeyword:

Removes the receiver’s parameter descriptor identified by the specified keyword.

returnID

The receiver’s return ID (the ID for a reply Apple event).

- setAttributeDescriptor:forKeyword:

Adds a descriptor to the receiver as an attribute identified by the specified keyword.

- setParamDescriptor:forKeyword:

Adds a descriptor to the receiver as an Apple event parameter identified by the specified keyword.

transactionID

The receiver’s transaction ID, if any.

Supporting Types

Relationships

Inherits From

See Also

Apple Event Handling

NSAppleEventManager

A mechanism for registering handler routines for specific types of Apple events and dispatching events to those handlers.