<!--
{
  "availability" : [
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSAppleEventDescriptor",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSAppleEventDescriptor"
  },
  "title" : "NSAppleEventDescriptor"
}
-->

# NSAppleEventDescriptor

A wrapper for the Apple event descriptor data type.

```
class NSAppleEventDescriptor
```

## Overview

An instance of [`NSAppleEventDescriptor`](/documentation/Foundation/NSAppleEventDescriptor) represents a descriptor—the basic building block for Apple events. This class is a wrapper for the underlying Apple event descriptor data type, <doc://com.apple.documentation/documentation/coreservices/aedesc>. Scriptable Cocoa applications frequently work with instances of [`NSAppleEventDescriptor`](/documentation/Foundation/NSAppleEventDescriptor), but should rarely need to work directly with the <doc://com.apple.documentation/documentation/coreservices/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.

> Important:
> An instance of `NSAppleEventDescriptor` can represent any kind of descriptor, from a simple value descriptor, to a descriptor list, to a full-fledged Apple event.

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 <doc://com.apple.documentation/documentation/applicationservices/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](http://developer.apple.com/releasenotes/AppleScript/ASTerminology_AppleEventCodes/TermsAndCodes.html).

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](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_handle_AEs/SAppsHandleAEs.html#//apple_ref/doc/uid/20001239). 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`](/documentation/Foundation/NSAppleEventDescriptor/aeDesc) method. Other methods, including [`descriptorWithDescriptorType:bytes:length:`](/documentation/Foundation/NSAppleEventDescriptor/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:)`](/documentation/Foundation/NSAppleEventDescriptor/init(aeDescNoCopy:)-5cioa). 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 <doc://com.apple.documentation/documentation/applicationservices/apple_event_manager>.

## Topics

### Creating and Initializing Descriptors

[`appleEvent(withEventClass:eventID:targetDescriptor:returnID:transactionID:)`](/documentation/Foundation/NSAppleEventDescriptor/appleEvent(withEventClass:eventID:targetDescriptor:returnID:transactionID:))

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

[`init(boolean:)`](/documentation/Foundation/NSAppleEventDescriptor/init(boolean:))

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

[`descriptorWithDescriptorType:bytes:length:`](/documentation/Foundation/NSAppleEventDescriptor/descriptorWithDescriptorType:bytes:length:)

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

[`descriptorWithDescriptorType:data:`](/documentation/Foundation/NSAppleEventDescriptor/descriptorWithDescriptorType:data:)

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

[`init(enumCode:)`](/documentation/Foundation/NSAppleEventDescriptor/init(enumCode:))

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

[`init(int32:)`](/documentation/Foundation/NSAppleEventDescriptor/init(int32:))

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

[`init(string:)`](/documentation/Foundation/NSAppleEventDescriptor/init(string:))

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

[`init(typeCode:)`](/documentation/Foundation/NSAppleEventDescriptor/init(typeCode:))

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

[`list()`](/documentation/Foundation/NSAppleEventDescriptor/list())

Creates and initializes an empty list descriptor.

[`null()`](/documentation/Foundation/NSAppleEventDescriptor/null())

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

[`record()`](/documentation/Foundation/NSAppleEventDescriptor/record())

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

[`init(listDescriptor:)`](/documentation/Foundation/NSAppleEventDescriptor/init(listDescriptor:))

Initializes a newly allocated instance as an empty list descriptor.

[`init(recordDescriptor:)`](/documentation/Foundation/NSAppleEventDescriptor/init(recordDescriptor:))

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

[`init(aeDescNoCopy:)`](/documentation/Foundation/NSAppleEventDescriptor/init(aeDescNoCopy:)-5cioa)

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

[`init(descriptorType:bytes:length:)`](/documentation/Foundation/NSAppleEventDescriptor/init(descriptorType: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).

[`init(descriptorType:data:)`](/documentation/Foundation/NSAppleEventDescriptor/init(descriptorType:data:))

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

[`init(eventClass:eventID:targetDescriptor:returnID:transactionID:)`](/documentation/Foundation/NSAppleEventDescriptor/init(eventClass: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`](/documentation/Foundation/NSAppleEventDescriptor/aeDesc)

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

[`booleanValue`](/documentation/Foundation/NSAppleEventDescriptor/booleanValue)

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

[`coerce(toDescriptorType:)`](/documentation/Foundation/NSAppleEventDescriptor/coerce(toDescriptorType:))

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

[`data`](/documentation/Foundation/NSAppleEventDescriptor/data)

The receiver’s data.

[`descriptorType`](/documentation/Foundation/NSAppleEventDescriptor/descriptorType)

The descriptor type of the receiver.

[`enumCodeValue`](/documentation/Foundation/NSAppleEventDescriptor/enumCodeValue)

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

[`int32Value`](/documentation/Foundation/NSAppleEventDescriptor/int32Value)

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

[`numberOfItems`](/documentation/Foundation/NSAppleEventDescriptor/numberOfItems)

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

[`stringValue`](/documentation/Foundation/NSAppleEventDescriptor/stringValue)

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

[`typeCodeValue`](/documentation/Foundation/NSAppleEventDescriptor/typeCodeValue)

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

### Working With List Descriptors

[`atIndex(_:)`](/documentation/Foundation/NSAppleEventDescriptor/atIndex(_:))

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

[`insert(_:at:)`](/documentation/Foundation/NSAppleEventDescriptor/insert(_:at:))

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

[`remove(at:)`](/documentation/Foundation/NSAppleEventDescriptor/remove(at:))

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

### Working With Record Descriptors

[`forKeyword(_:)`](/documentation/Foundation/NSAppleEventDescriptor/forKeyword(_:))

Returns the receiver’s descriptor for the specified keyword.

[`keywordForDescriptor(at:)`](/documentation/Foundation/NSAppleEventDescriptor/keywordForDescriptor(at:))

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

[`remove(withKeyword:)`](/documentation/Foundation/NSAppleEventDescriptor/remove(withKeyword:))

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

[`setDescriptor(_:forKeyword:)`](/documentation/Foundation/NSAppleEventDescriptor/setDescriptor(_:forKeyword:))

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

### Working With Apple Event Descriptors

[`attributeDescriptor(forKeyword:)`](/documentation/Foundation/NSAppleEventDescriptor/attributeDescriptor(forKeyword:))

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

[`eventClass`](/documentation/Foundation/NSAppleEventDescriptor/eventClass)

The event class for the receiver.

[`eventID`](/documentation/Foundation/NSAppleEventDescriptor/eventID)

The event ID for the receiver.

[`paramDescriptor(forKeyword:)`](/documentation/Foundation/NSAppleEventDescriptor/paramDescriptor(forKeyword:))

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

[`removeParamDescriptor(withKeyword:)`](/documentation/Foundation/NSAppleEventDescriptor/removeParamDescriptor(withKeyword:))

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

[`returnID`](/documentation/Foundation/NSAppleEventDescriptor/returnID)

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

[`setAttribute(_:forKeyword:)`](/documentation/Foundation/NSAppleEventDescriptor/setAttribute(_:forKeyword:))

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

[`setParam(_:forKeyword:)`](/documentation/Foundation/NSAppleEventDescriptor/setParam(_:forKeyword:))

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

[`transactionID`](/documentation/Foundation/NSAppleEventDescriptor/transactionID)

The receiver’s transaction ID, if any.

### Supporting Types

[`NSAppleEventDescriptor.SendOptions`](/documentation/Foundation/NSAppleEventDescriptor/SendOptions)


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)