Platforms to show: All Mac Windows Linux Cross-Platform
NSAppleEventDescriptorMBS class
Type | Topic | Plugin | Version | macOS | Windows | Linux | iOS | Targets |
class | Apple Script | MBS MacCocoa Plugin | 11.2 | ✅ Yes | ❌ No | ❌ No | ❌ No | Desktop, Console & Web |
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.
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 Apple Event Manager Reference. 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 make it possible to create and initialize instances of NSAppleEventDescriptor without creating temporary instances of memoryblock.
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 Reference.
This is an abstract class. You can't create an instance, but you can get one from various plugin functions.
- 26 properties
- property aeDesc as Ptr
- property applicationURLValue as String
- property booleanValue as boolean
- property bundleIDValue as String
- property data as Memoryblock
- property dateTimeValue as DateTime
- property dateValue as date
- property description as string
- property descriptorType as string
- property doubleValue as Double
- property enumCodeValue as string
- property eventClass as string
- property eventID as string
- property fileURLValue as String
- property Handle as Integer
- property int16Value as Int16
- property int32Value as Int32
- property isRecordDescriptor as Boolean
- property numberOfItems as Integer
- property processIDValue as Integer
- property returnID as Int16
- property singleValue as single
- property stringValue as string
- property transactionID as Int32
- property typeCodeValue as string
- property UInt32Value as UInt32
- 17 methods
- method attributeDescriptorForKeyword(keyword as string) as NSAppleEventDescriptorMBS
- method coerceToDescriptorType(descriptorType as string) as NSAppleEventDescriptorMBS
- method Constructor Private
- method copy as NSAppleEventDescriptorMBS
- method descriptorAtIndex(index as Integer) as NSAppleEventDescriptorMBS
- method descriptorForKeyword(keyword as string) as NSAppleEventDescriptorMBS
- method insertDescriptor(descriptor as NSAppleEventDescriptorMBS, index as Integer)
- method keywordForDescriptorAtIndex(index as Integer) as string
- method paramDescriptorForKeyword(keyword as string) as NSAppleEventDescriptorMBS
- method print
- method removeDescriptorAtIndex(index as Integer)
- method removeDescriptorWithKeyword(keyword as string)
- method removeParamDescriptorWithKeyword(keyword as string)
- method send(options as Integer, timeoutInSeconds as Double, byref error as NSErrorMBS) as NSAppleEventDescriptorMBS
- method setAttributeDescriptor(descriptor as NSAppleEventDescriptorMBS, keyword as string)
- method setDescriptor(descriptor as NSAppleEventDescriptorMBS, keyword as string)
- method setParamDescriptor(descriptor as NSAppleEventDescriptorMBS, keyword as string)
- 26 shared methods
- shared method appleEventWithEventClass(eventClass as string, eventID as string, targetDescriptor as NSAppleEventDescriptorMBS, returnID as Int16, transactionID as UInt32) as NSAppleEventDescriptorMBS
- shared method currentProcessDescriptor as NSAppleEventDescriptorMBS
- shared method descriptorWithAlias(item as folderitem) as NSAppleEventDescriptorMBS
- shared method descriptorWithApplicationURL(fileURL as string) as NSAppleEventDescriptorMBS
- shared method descriptorWithApplicationURL(item as folderitem) as NSAppleEventDescriptorMBS
- shared method descriptorWithBoolean(value as Boolean) as NSAppleEventDescriptorMBS
- shared method descriptorWithBundleIdentifier(BundleID as String) as NSAppleEventDescriptorMBS
- shared method descriptorWithCurrentProcessSerialNumber as NSAppleEventDescriptorMBS
- shared method descriptorWithDate(value as date) as NSAppleEventDescriptorMBS
- shared method descriptorWithDateTime(value as dateTime) as NSAppleEventDescriptorMBS
- shared method descriptorWithDescriptorType(descriptorType as string, data as memoryblock) as NSAppleEventDescriptorMBS
- shared method descriptorWithDescriptorType(descriptorType as string, data as memoryblock, offset as UInt32, length as UInt32) as NSAppleEventDescriptorMBS
- shared method descriptorWithDouble(value as Double) as NSAppleEventDescriptorMBS
- shared method descriptorWithEnumCode(enumerator as string) as NSAppleEventDescriptorMBS
- shared method descriptorWithFileURL(fileURL as string) as NSAppleEventDescriptorMBS
- shared method descriptorWithFileURL(item as folderitem) as NSAppleEventDescriptorMBS
- shared method descriptorWithInt16(value as Int16) as NSAppleEventDescriptorMBS
- shared method descriptorWithInt32(value as Int32) as NSAppleEventDescriptorMBS
- shared method descriptorWithProcessIdentifier(PID as Integer) as NSAppleEventDescriptorMBS
- shared method descriptorWithSingle(value as single) as NSAppleEventDescriptorMBS
- shared method descriptorWithString(text as string) as NSAppleEventDescriptorMBS
- shared method descriptorWithTypeCode(typeCode as string) as NSAppleEventDescriptorMBS
- shared method descriptorWithUInt32(value as UInt32) as NSAppleEventDescriptorMBS
- shared method listDescriptor as NSAppleEventDescriptorMBS
- shared method nullDescriptor as NSAppleEventDescriptorMBS
- shared method recordDescriptor as NSAppleEventDescriptorMBS
- 13 constants
Constants
Constant | Value | Description |
---|---|---|
kAnyTransactionID | 0 |
Special constant for transaction ID.
no transaction is in use |
kAutoGenerateReturnID | -1 |
Special constant for return ID.
AECreateAppleEvent will generate a session-unique ID internally. |
Send Options
Constant | Value | Description |
---|---|---|
NSAppleEventSendAlwaysInteract | &h30 |
Server should always interact with user where appropriate. |
NSAppleEventSendCanInteract | &h20 |
Server may try to interact with user. |
NSAppleEventSendCanSwitchLayer | &h40 |
Interaction may switch layer. |
NSAppleEventSendDefaultOptions | &h23 |
Default options: WaitForReply with CanInteract. |
NSAppleEventSendDontAnnotate | &h10000 |
Don't automatically add any sandbox or other annotations to the event. |
NSAppleEventSendDontExecute | &h2000 |
Don't execute this event; used for recording. |
NSAppleEventSendDontRecord | &H1000 |
Don't record this event. |
NSAppleEventSendNeverInteract | &h10 |
Server should not interact with user. |
NSAppleEventSendNoReply | 1 |
Sender doesn't want a reply to event. |
NSAppleEventSendQueueReply | 2 |
Sender wants a reply but won't wait. |
NSAppleEventSendWaitForReply | 3 |
Sender wants a reply and will wait. |
This class has no sub classes.
Some methods using this class:
- NSAppleEventManagerMBS.replyAppleEventForSuspensionID(id as NSAppleEventManagerSuspensionIDMBS) as NSAppleEventDescriptorMBS
- NSAppleScriptMBS.DeterminePermissionToAutomateTarget(target as NSAppleEventDescriptorMBS, theAEEventClass as string = "****", theAEEventID as String = "****", askUserIfNeeded as boolean) as Integer
- NSAppleScriptMBS.executeAppleEvent(event as NSAppleEventDescriptorMBS, byref error as dictionary) as NSAppleEventDescriptorMBS
- NSAppleScriptMBS.setValueDescriptorForProperty(propertyName as string, value as NSAppleEventDescriptorMBS) as boolean
- NSAppleScriptMBS.valueDescriptorForProperty(propertyName as string) as NSAppleEventDescriptorMBS
- OSAScriptMBS.executeAppleEvent(event as NSAppleEventDescriptorMBS, byref error as dictionary) as NSAppleEventDescriptorMBS
- OSAScriptMBS.executeHandlerWithName(Name as String, arguments() as String, byref error as dictionary) as NSAppleEventDescriptorMBS
- OSAScriptMBS.richTextFromDescriptor(descriptor as NSAppleEventDescriptorMBS) as NSAttributedStringMBS
- OSAScriptMBS.scriptDataDescriptorWithContentsOfFile(file as FolderItem) as NSAppleEventDescriptorMBS
- OSAScriptMBS.scriptDataDescriptorWithContentsOfURL(URL as String) as NSAppleEventDescriptorMBS
Some properties using for this class:
- OSALanguageInstanceMBS.defaultTarget as NSAppleEventDescriptorMBS
Some events using this class:
- NSAppleEventHandlerMBS.handleAppleEvent(theEvent as NSAppleEventDescriptorMBS, replyEvent as NSAppleEventDescriptorMBS)
Some examples using this class:
- /MacCocoa/AppleScript/DeterminePermissionToAutomateTarget
- /MacCocoa/AppleScript/NSAppleScriptMBS query Mail mailboxes
- /MacCocoa/AppleScript/NSAppleScriptMBS with properties
- /MacCocoa/NSAppleEventHandlerMBS test
- /MacControls/Listbox and TableView Demos/NSOutlineView/Disk Browser
Blog Entries
- MBS Xojo Plugins, version 19.0pr6
- MBS Xojo / Real Studio Plugins, version 16.2pr4
- MBS Xojo / Real Studio Plugins, version 15.5pr1
- MBS Real Studio Plugins, version 12.1pr5
- MBS Real Studio Plugins, version 11.3pr7
- MBS Real Studio Plugins, version 11.2pr11
- MBS Real Studio Plugins, version 11.2pr9
Release notes
- Version 19.0
- Removed descriptorWithFSRef and FSRefValue from NSAppleEventDescriptorMBS in favor of FileURL methods.
The items on this page are in the following plugins: MBS MacCocoa Plugin.
NSAppearanceMBS - NSAppleEventHandlerMBS