---

NSAppleEventDescriptor

Overview

A descriptor is the basic building block for Apple events—every Apple event is a descriptor, where descriptor is a type of data structure. 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.

Cocoa supplies built-in scripting support that converts received Apple events into script commands that operate on application objects. As a result, most Cocoa applications don’t need to work directly with Apple event descriptors. However, those applications that do need to construct Apple events or extract information from them can use NSAppleEventDescriptor. The most common reason to construct an Apple event is to supply information in a return event. In addition, if you execute an AppleScript script using the NSAppleScript class, you get an NSAppleEventDescriptor as the return value, from which you extract the necessary information.

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. 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 Reference.

Tasks

Constructors

• NSAppleEventDescriptor

Creating an Event Descriptor

• descriptorWithBoolean
• descriptorWithEnumCode
• descriptorWithInt32
• descriptorWithString
• descriptorWithTypeCode
• listDescriptor
• nullDescriptor
• recordDescriptor

Getting Information About an Event Descriptor

• data
• descriptorType
• coerceToDescriptorType
• numberOfItems
• booleanValue
• enumCodeValue
• int32Value
• stringValue
• typeCodeValue

Working with List Descriptors

• descriptorAtIndex
• insertDescriptor
• removeDescriptorAtIndex

Working with Record Descriptors

• descriptorForKeyword
• keywordForDescriptorAtIndex
• removeDescriptorWithKeyword
• setDescriptor

Working with Apple Event Descriptors

• attributeDescriptorForKeyword
• setAttributeDescriptor
• eventClass
• eventID
• paramDescriptorForKeyword
• setParamDescriptor
• removeParamDescriptorWithKeyword
• returnID
• transactionID

Static Methods

descriptorWithBoolean

Creates and returns a newly allocated NSAppleEventDescriptor with Apple event type typeBoolean and value specified by boolean.

public static NSAppleEventDescriptor descriptorWithBoolean(boolean boolean)

Availability

• Available in Mac OS X v10.2 and later.

descriptorWithEnumCode

Creates and returns a newly allocated NSAppleEventDescriptor with Apple event type typeEnumerated and value specified by enumerator.

public static NSAppleEventDescriptor descriptorWithEnumCode(int enumerator)

Availability

• Available in Mac OS X v10.2 and later.

descriptorWithInt32

Creates and returns a newly allocated NSAppleEventDescriptor with Apple event type typeSInt32 and value specified by signedInt.

public static NSAppleEventDescriptor descriptorWithInt32(int signedInt)

Availability

• Available in Mac OS X v10.2 and later.

descriptorWithString

Creates and returns a newly allocated NSAppleEventDescriptor with Apple event type typeUnicodeText and value specified by string.

public static NSAppleEventDescriptor descriptorWithString(String string)

Availability

• Available in Mac OS X v10.2 and later.

descriptorWithTypeCode

Creates and returns a newly allocated NSAppleEventDescriptor with Apple event type typeType and value specified by typeCode.

public static NSAppleEventDescriptor descriptorWithTypeCode(int typeCode)

Availability

• Available in Mac OS X v10.2 and later.

listDescriptor

Creates and returns an instance of NSAppleEventDescriptor initialized as an empty list descriptor.

public static NSAppleEventDescriptor listDescriptor()

Discussion

A list descriptor is a descriptor whose data consists of one or more descriptors. You can add items to the list by calling insertDescriptor or remove them with removeDescriptorAtIndex.

nullDescriptor

Creates and returns an instance of NSAppleEventDescriptor with no parameter or attribute values set.

public static NSAppleEventDescriptor nullDescriptor()

Discussion

This method isn’t typically called, as most NSAppleEventDescriptor instance methods can’t be safely called on the returned descriptor.

recordDescriptor

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

public static NSAppleEventDescriptor recordDescriptor()

Discussion

A record descriptor is a descriptor whose data is a set of descriptors keyed by four-character codes. You can add information to the descriptor with methods such as setAttributeDescriptor, setDescriptor, and setParamDescriptor.

Instance Methods

attributeDescriptorForKeyword

Returns an instance of NSAppleEventDescriptor for the attribute specified by keyword.

public NSAppleEventDescriptor attributeDescriptorForKeyword(int keyword)

Discussion

Returns null if any error occurs.

booleanValue

Return the contents of the descriptor, after first coercing it to typeBoolean.

public boolean booleanValue()

Availability

• Available in Mac OS X v10.2 and later.

coerceToDescriptorType

Returns an instance of NSAppleEventDescriptor coerced to the type specified by descType.

public NSAppleEventDescriptor coerceToDescriptorType(int descType)

Discussion

Returns null if the coercion fails.

data

Returns the receiving descriptor’s data as an NSData object.

public NSData data()

Discussion

Returns null if an error occurs.

descriptorAtIndex

Returns an instance of NSAppleEventDescriptor from the position specified by anIndex.

public NSAppleEventDescriptor descriptorAtIndex(int anIndex)

Discussion

NSAppleEventDescriptor indices are one-based. Returns null if an error occurs.

See Also

• insertDescriptor
• removeDescriptorAtIndex

descriptorForKeyword

Returns an instance of NSAppleEventDescriptor for the receiver’s descriptor specified by keyword.

public NSAppleEventDescriptor descriptorForKeyword(int keyword)

Discussion

Returns null if an error occurs.

descriptorType

Returns the descriptor type for the receiving descriptor.

public int descriptorType()

enumCodeValue

Return the contents of the descriptor, after first coercing it to typeEnumerated.

public int enumCodeValue()

Availability

• Available in Mac OS X v10.2 and later.

eventClass

Returns the event class for the receiving descriptor.

public int eventClass()

Discussion

An Apple event is identified by its event class and event ID, a pair of four-character codes stored as 32-bit integers. For example, most events in the Standard suite have the four-character code core (defined as the constant kAECoreSuite in the header AERegistry.h in AE.framework, a subframework of ApplicationServices.framework).

eventID

Returns the event ID for the receiving descriptor.

public int eventID()

Discussion

An Apple event is identified by its event class and event ID, a pair of four-character codes stored as 32-bit integers. For example, the Open Apple event from the Standard suite has the four-character code odoc (defined as the constant kAEOpen in the header AERegistry.h in AE.framework, a subframework of ApplicationServices.framework).

insertDescriptor

Inserts the NSAppleEventDescriptor specified by descriptor at the position specified by anIndex.

public void insertDescriptor(NSAppleEventDescriptor descriptor, int anIndex)

Discussion

NSAppleEventDescriptor indices are one-based. The receiver must be a list descriptor. Currently provides no indication if an error occurs.

See Also

• descriptorAtIndex
• removeDescriptorAtIndex

int32Value

Return the contents of the descriptor, after first coercing it to typeSInt32.

public int int32Value()

Availability

• Available in Mac OS X v10.2 and later.

keywordForDescriptorAtIndex

Returns the keyword for the descriptor at the position specified by anIndex.

public int keywordForDescriptorAtIndex(int anIndex)

Discussion

NSAppleEventDescriptor indices are one-based. Returns the value 0 if an error occurs.

numberOfItems

Returns the number of descriptors in the receiving descriptor list.

public int numberOfItems()

Discussion

Returns the value 0 if an error occurs.

paramDescriptorForKeyword

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

public NSAppleEventDescriptor paramDescriptorForKeyword(int keyword)

Discussion

The receiver must be an Apple event. Returns null if an error occurs.

removeDescriptorAtIndex

Removes the receiver’s descriptor at the position specified by anIndex.

public void removeDescriptorAtIndex(int anIndex)

Discussion

NSAppleEventDescriptor indices are one-based. The receiver must be a list descriptor. Currently provides no indication if an error occurs.

See Also

• descriptorAtIndex
• insertDescriptor

removeDescriptorWithKeyword

Removes the descriptor in the receiver identified by keyword.

public void removeDescriptorWithKeyword(int keyword)

Discussion

The receiver must be an Apple event or Apple event record.

removeParamDescriptorWithKeyword

Removes the receiver’s parameter descriptor identified by keyword.

public void removeParamDescriptorWithKeyword(int keyword)

Discussion

The receiver must be an Apple event or Apple event record.

returnID

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

public int returnID()

Discussion

The receiver must be an Apple event. Returns the value 0 if an error occurs.

setAttributeDescriptor

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

public void setAttributeDescriptor(NSAppleEventDescriptor descriptor, int keyword)

Discussion

The receiver must be an Apple event.

setDescriptor

Adds descriptor to the receiver identified by keyword.

public void setDescriptor(NSAppleEventDescriptor descriptor, int keyword)

Discussion

The receiver must be an Apple event or Apple event record.

setParamDescriptor

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

public void setParamDescriptor(NSAppleEventDescriptor descriptor, int keyword)

Discussion

The receiver must be an Apple event or Apple event record.

stringValue

Return the contents of the descriptor, after first coercing it to typeUnicodeText.

public String stringValue()

Availability

• Available in Mac OS X v10.2 and later.

transactionID

Returns the receiver’s transaction ID, if any.

public int transactionID()

Discussion

For more information on transactions, see the description for NSAppleEventDescriptor.

typeCodeValue

Return the contents of the descriptor, after first coercing it to typeType.

public int typeCodeValue()

Availability

• Available in Mac OS X v10.2 and later.

---