6. Classes and Enumerated Types
Appscript keywords
For your convenience, appscript represents Apple event type names and application-specific class and enumerator names as instances of the glue's ASConstant subclass. Examples:
# AEM-defined data types:
[TEConstant boolean]
[TEConstant unicodeText]
[TEConstant list]
# Application-defined class names:
[TEConstant document]
[TEConstant window]
[TEConstant disk]
# Application-defined enumerators:
[TEConstant yes]
[TEConstant no]
[TEConstant ask]Occasionally an application dictionary defines a type or enumerator without providing it with a corresponding name name. In these cases, the value will be represented as a raw AEMType or AEMEnum instance instead, e.g.:
[AEMType typeWithCode: 'abcd']
[AEMEnum enumWithCode: 'xyz ']Common AE types
| AE type | appscript name | Foundation/Appscript class |
|---|---|---|
typeNull | null | NSNull |
typeBoolean | boolean | ASBoolean |
typeSInt32 | integer | NSNumber |
typeIEEE64BitFloatingPoint | float | NSNumber |
typeChar * | string | NSString |
typeStyledText * | styledText | NSString |
typeIntlText * | internationalText | NSString |
typeUnicodeText | unicodeText | NSString |
typeAEList | list | NSArray |
typeAERecord | record | NSDictionary |
typeLongDateTime | date | NSDate |
typeAlias | alias | ASAlias |
typeFileURL | fileURL | NSURL |
typeFSRef | fileRef | ASFileRef |
typeFSS * | fileSpecification | ASFileSpec |
typeObjectSpecifier | reference | ASReference ** |
typeInsertionLoc | locationReference | ASReference ** |
typeType | typeClass | ASConstant ** |
typeEnumerated | enumerator | ASConstant ** |
(Note that types marked with '*' are officially deprecated and/or their use discouraged in Mac OS X. They remain supported to ensure backwards compatibility with older applications that may use them.)
(Note that classes marked with '**' are subclassed in application glues to provide application-specific support.)
Type mapping notes
While AE-ObjC type conversions generally work quite seamlessly, it is sometimes useful to know some of the details involved, particularly when troubleshooting code that deals with older or buggy applications.
Numbers
When packing a signed integer, appscript will pack it either as a 32-bit signed integer (most preferred), 64-bit signed integer, or 64-bit float (least preferred), depending on the value's size. When packing a 32-bit unsigned integer, appscript will pack it as a 32-bit signed integer if possible.
Strings
When packing and unpacking NSString instances, appscript uses the NSAppleEventDescriptor class's +descriptorWithString: and -stringValue methods, both of which use AEDescs of typeUnicodeText, coercing other types as needed.
Note that while typeUnicodeText is formally deprecated in Mac OS X 10.4+ in favour of typeUTF8Text and typeUTF16ExternalRepresentation, it is still in common usage so appscript continues to use it to ensure the broadest compatibility with existing scriptable applications.
Filesystem references
The typeAlias AE type represents a filesystem object, and will continue to point to that object even if it's renamed or moved to another location on the same disk. The typeFSRef and typeFileURL types represent a filesystem location. Both can represent existing locations; the typeFileURL type can also be used to specify locations that don't already exist.
FSSpecs are also supported for sake of backwards-compatibility with older Carbon applications that sometimes still use them. They're deprecated in OS X, however, due to lack of proper Unicode and long filename support, and their use is discouraged.
See the aem manual's Packing and Unpacking Data chapter for more information on ASAlias, ASFileRef and ASFileSpec.
Records
The typeAERecord AE type is a struct-like data structure containing zero or more properties. Appscript represents AE records as NSMutableDictionary instances. The keys in this dictionary are usually ASConstant subclass instances representing appscript-style property names, e.g. [TEConstant text], although they may also be AEMType values or strings.
If a dictionary contains a class_ (or 'pcls') key, appscript will pack the remaining items into an AE record, then coerce it to the type specified by this 'class' property. Similarly, when unpacking an record-like AEDesc with a custom type code, appscript will unpack it as a dictionary with the type represented by a class_ entry.
Note that NSAppleEventDescriptor instances cannot be used as dictionary keys, as their -hash and -isEqual: methods compare for object identity only.
Types and enumerators
The typeType and typeEnumerated AE types are unpacked as ASConstant subclass instances when the corresponding terminology is available, otherwise they are unpacked as AEMType and AEMEnum respectively.
Miscellaneous types
The Apple Event Manager defines many other AE types whose names and codes are defined by appscript for completeness. A few of these types are of occasional interest to users, the rest can simply be ignored. In most cases, values of these types will be represented by NSAppleEventDescriptor instances as appscript doesn't automatically convert them.