TweetFollow Us on Twitter

aete Resources
Volume Number:11
Issue Number:7
Column Tag:Applescript

Making Sense of ‘aete’ Resources

The inside scoop on building an application’s scripting dictionary.

By Gary McGath, Hooksett, NH

An important step in making an application support Apple Events and scripting is the creation of an ‘aete’ (Apple Event Terminology extension) resource. This resource defines the Apple Events and objects which your application understands, both for scripts and for applications that send you events. Unfortunately, the documentation for this resource is widely scattered; also, it has many “magical” features which are explained only in tech notes and journal articles, and probably others which are unknown outside Apple. This article tries to bring together the most important pieces of information so that the reader can put together an ‘aete’ resource with a minimum of confusion and understand some of its subtleties.

To keep this article from digressing too far, I’m assuming you have a general familiarity with Apple Events. The background you need can be found in Inside Macintosh: Interapplication Communication, chapters 3 through 6. If you’ve never worked with Apple Events, you should learn the basics before there’s any point in trying to create ‘aete’ resources.

Any application that responds to more than the basic four Apple Events, and any scripting addition, should have an ‘aete’ resource. It should have only one of them, and its ID must be the same as the language code specified in the resource. If the target language is English, this means its ID must be 0.

An ‘aete’ resource is organized as a hierarchy of information. It consists of one or more suites, each of which describes a distinct collection of Apple Event information. The hierarchy looks like this:

Suites

Suites are basic to the logical organization of Apple Events. If you’ve worked at all with Apple Events, at minimum you’ve run into the Required Suite and the Core Suite. The Required Suite consists of the four basic events which every application should support (Open Document, Open Application, Print, and Quit). The Core Suite describes a basic set of events which scriptable applications are expected to support. Other commonly used suites are the Text, Table, and Database suites, which respectively provide classes to describe text, two-dimensional arrays of data, and databases (including complex tables). You should try to work within Apple’s standard suites, defining your own only if they prove insufficient.

A suite consists of events, classes, comparison operators, and enumerations. Events and classes are the most important parts of a suite; events tell the world what your application can do, and classes tell what it can do it to.

Enumerations are an adjunct to events and classes; they are a form of data definition in which a parameter or property can take on one of several named values (e.g., “Yes,” “No,” and “Cancel”).

Comparison operators usually defined in ‘aete’ resources when a new data type is defined. In addition, the ‘aete’ resource is identical to the ‘aeut’ resource, which defines the scripting dialect and needs this capability. For everyday purposes, you’ll probably not define one, and they aren’t discussed in this article.

Looking at the ‘aeut’ resource can be useful for studying existing suites. This resource is found in the AppleScript dialect files, in the System Folder:Extensions:Scripting Additions:Dialects folder.

Describing The Resource

This article won’t attempt to describe the byte-by-byte structure of one of the most complicated resource types Apple has devised. Normally, you’ll construct a resource with Rez or SARez, use a resource editor such as Resorcerer, or run a specialized application for ‘aete’ resources such as my own forthcoming EightyRez (plug!). ResEdit is helpless in this situation; an ‘aete’ template is available, but it will choke on any resource large enough to be useful.

The header of an ‘aete’ resource specifies its version, language, and script. The version consists of a major and minor portion (e.g., version 1, revision 2) and is there simply for documentation. The language code must equal the ID of the resource. The script code refers to the way the Script Manager deals with text, not to AppleScript. For ordinary English, both of these should be 0. For other cases, see the discussion of the Script Manager in Inside Macintosh: Text.

Suites (Again)

There are five pieces of information associated with each suite: its ID, name, description, level, and version. The ID is an four-character ID, which are defined by Apple for all the standard suites. If you want to create a suite for your own application, you should give it a type which is the same as the application’s signature.

It’s important to remember that organization of events by suites doesn’t draw any boundary lines in functionality; the Apple Event Manager doesn’t even know about suites. Aside from being a convenience in organizing related events and classes, their only functional significance is that you can import whole suites by name from the ‘aeut’ resource.

You may also want to create a singe suite which puts together pieces of standard suites without completely implementing any of them. In this case, you should give the suite an ID of '****'. If you implement a significant part of a suite, though, you should include it as a separate suite.

The suite ID ‘tpnm’, conventionally called “Type Names,” is magical. If you give a suite this ID, it won’t appear in the Script Editor’s dictionary listing. This is useful for defining classes you want to hide from the user.

The name, description, level, and version of a suite are there simply for informational purposes; if you use a standard suite, the values in your ‘aete’ resource should match those of the suite. Normally the level and version will both be 1.

If a suite is described in the system’s ‘aeut’ resource and you support it completely, all that you have to do is include this basic information about it; you don’t have to list the events and classes which it supports. However, if you support only some of the events and classes in a suite, or if you support extensions to any of them (extra parameters, elements, or properties), then you must itemize them in the suite. If you include any events or classes in a suite, you’re saying that you support only those events and classes.

Events

The two big subdivisions of a suite, as mentioned before, are events and classes. Events correspond to Apple Events, and classes to the objects which they operate on. To use a linguistic metaphor, events are the verbs of your Apple Event vocabulary, and classes are the nouns. An event consists of the following pieces:

Name

Description

Event class

ID

Reply type

Reply description

Reply flags

Direct parameter type

Direct parameter description

Direct parameter flags

Other parameters

The name is what AppleScript uses to refer to an event: examples are “Quit,” “Make,” “Get Class Info,” and “Count.” The event class and ID are four-character codes which identify an Apple Event as corresponding to this entry in the dictionary. Each event should have a unique name, unless you want to define synonyms for an event’s name. (If you do define a synonym, the ID, class, reply, and direct parameter should match precisely.) ID’s should be unique across all suites and classes.

The description is simply a string for documentation, which will be displayed by the Script Editor’s dictionary display; the same applies to other “descriptions” found in various parts of the resource.

The event class generally corresponds to the ID of the suite that the event calls home. This is not necessarily the same as the suite the event is actually found in, since an event from one suite can be included in another suite. For example, the Core (or Standard) suite includes three events from the Required suite; these still have an event class of ‘aevt’, which is the ID of the Required suite, not ‘core’, which is the ID of the Core suite.

The reply type, another of those four-character codes, is the type of the object which will be returned to the event’s sender. In Apple’s Universal Headers, these types are defined in Apple Events.h, and their names all start with “type” (e.g., typeInteger, typeBoolean, typeAlias). Formally, these are of type descType, and they correspond to the descriptorType field of a descriptor record. If the event will not return a reply, the type should be ‘null’. If all you need to return to the sender is an error code, you do not need to specify a reply type other than ‘null’.

There are three reply flags that, when set, respectively designate that the reply is optional, that it is a list, and that it is enumerated. If the reply type is ‘null’, you should always set the Optional flag. If you set the Enumerated flag, this indicates that the reply type is not a standard type, but rather is the ID of an enumeration. You can use this when you want the reply to be one of a set of enumerated values. (Enumerations will be explained further on; for now all you need to know is that they allow a choice of four-character IDs.)

Next we come to the direct parameter. Every event has at least this one parameter (though it may be null). Since it is an object, the parameter looks very much like the reply. The only difference is that there is an extra flag defined which tells whether the event changes the application’s state. This parameter really belongs to the event rather than being a parameter on its own, but was put in with the parameter’s flags because there was room.

In addition to the direct parameter, an event may have one or more additional parameters, which are separate structures in themselves. These parameters can have a name, a keyword, and several flags that the direct parameter doesn’t have. These additional flags mark the parameter as named, masculine, feminine, or plural. The masculine and feminine flags are of interest only in languages with gendered grammar, such as French and German, and even the plural flag is obscure in its purpose.

Parameters do not have to be named, since they can be identified by their position in the event as long as no parameters are left out before them. However, if there is more than one optional parameter, all optional parameters should be named. Also, optional parameters should come after all required parameters, to minimize the chances of confusing AppleScript or the Apple Event Manager with omitted positional parameters.

The keyword of a parameter is the ubiquitous four-character code which is what the application will actually see when it gets the event. Obviously no two parameters of a given event should have the same name or keyword.

You may want to add parameters to an event for your application. For example, you might want to add a parameter to the “save” event to tell your application whether or not to make a backup copy of the document. For maximum compatibility with the rest of the AppleScript world, you should keep the standard parameter definitions unchanged and make your extra parameters optional, with reasonable defaults.

Classes

Classes define the kinds of objects which events can operate on. For various reasons, they’re somewhat more confusing than events. A class has the following pieces:

Name

ID

Description

Properties

Elements

The first three should be familiar by now. AppleScript refers to a class by its name, programs internally refer to it by its four-character ID, and the description is there for documentation. Curiously, a class has no flags, although it could really use a flag word. Instead, there is an odd convention in which a property is used just to provide flags for the class.

A class contains zero or more properties, followed by zero or more elements. The difference between properties and elements has been much discussed in the Apple Event literature, but is worth mentioning here one more time: An element is an item of information which is contained in an object, while a property is something which gives information about an object. Elements can include windows, text, and pictures; properties can include color, font, and size. Some borderline cases are hard to decide; what is most conveniently treated as a property in the usual case may be treated as an object and thus have element-like characteristics. If there can be more than one of something in an object (e.g., the characters in a text object, or pixels in a graphic), it should almost certainly be an element.

A property has the following pieces:

Name

ID

Class

Description

Flags

The name, ID, and description are as usual. The class of a property doesn’t mean the class to which the property belongs, but refers to a different type of “class” entirely. This leads to such interesting linguistic constructions as “the class of the class’s property.”

The class of a property indicates what type of object the property is, but just what this means is ill-defined. Sometimes it will be one of the object classes defined in AERegistry.h, sometimes it will be a descType (like typeInteger), and sometimes it will be unique to the application. What the class actually means is known only to the application itself. If it is a class name, it indicates what kind of object (using the Apple Event object model) is referred to by the property, without saying anything about the object’s physical representation. For example, cGraphicLine (‘glin’) indicates a graphic line, and cPixel ‘cpxl’ indicates a pixel. How they might be stored is up to the application.

When an object is actually passed around by Apple Events, it becomes a parameter or reply of an event, and then its storage format is specified by the type of the event. When a parameter of an Apple Event is of type typeObjectSpecifier (‘obj ’), then the object specifier contains information about the class of the object; this is the link between parameters, whose structure is known to the Apple Event Manager, and objects, whose structure is known only to the application.

As links go, this is a very tenuous one. In particular, there’s no way to specify what kind of object a parameter of type ‘obj ’ refers to. You can’t make an ‘aete’ resource say that a point or a line is acceptable, but a document or a window isn’t. This is a fact we have to live with, and should make up for in the documentation.

Some properties are magical. There is a special property ID, called kAESpecialClassProperties and represented as ‘c@#!’, which tells you that the property really isn’t a property at all, but a place to store flags which describe the class itself. (The ID undoubtedly immortalizes the language some programmer used on discovering that the lack of class flags made this kludge necessary.)

A property with this class is the way that you create a plural synonym for a class (which is something you should do for all classes that may be used in scripts). Having created the singular class, you create another class which has the same ID, a plural version of the name (e.g., “windows” instead of “window”), no elements, and only one property. This property has ID ‘c@#!’ and class ‘type’, and the property has its Plural flag set.

Another magic ID can be useful for eliminating redundant information. If the first property of a class has the ID ‘c@#^’, this signifies that the class inherits properties from another class. In this case its class is the ID of its base class, and the name of the property must be “<Inherited>”, including the angle brackets. Using this trick can make some ‘aete’ resources significantly smaller, if there are a number of bulky classes which are largely similar.

A property can also belong to more than one class. To do this, you must set the Enumerated flag, and set the class to the ID of an enumeration. The enumerated set specifies the classes to which the property can belong. Alternatively, you can use the Wild Card class (‘****’), which says that a property can be of any class.

(This may lead some hackers to wonder: If you use inheritance and enumeration in the same property, do you get multiple inheritance? If anyone is brash enough to try this, let me know if it works.)

If a property can be modified by an event, then the Read/Write flag should be set. If its value is a list (e.g., the styles which are applied to a text item), then the List of Values flag should be set. The Masculine and Feminine flags, once again, don’t apply to English.

The elements of a class are simpler than properties. An element consists of a class, which is a four-character ID, and one or more key forms. The class of an element is the same kind of beast as the class of a property, except that it can’t be enumerated or magical.

The key forms of an element indicate how it can be specified. There are seven standard key forms:

Absolute position ‘indx’

Name ‘name’

Property ID ‘prop’

Range ‘rang’

Relative position ‘rele’

Test ‘test’

Whose ‘whos’

Each of these consists simply of its four-character ID code, as given in the list above. To be useful, an element must have at least one key form; including several is not unusual. A full description of their function would be another article, one dealing with the Apple Event object model, but a partial explanation may help if you haven’t studied this aspect of Apple Events yet. Specification by absolute position locates an element by an ordinal number, for example, “the 7th word.” Specification by name locates it by name, for example, “the window named Untitled5.” Specification by range indicates a range of elements, such as “characters 10 to 20.” The others vary in complication, culminating in the powerful and seldom-supported “whose,” which allows combinations of criteria to be used in specifying an element or set of elements.

Enumerations

Finally, we come to enumerations, which have already been discussed as a way to specify a set of alternatives for the type of an event’s parameters or reply, and for the class of a class’s property. (This is an interseting linguistic constrution as described above. Another way to say this is “the class of a property of a class.”)

An enumeration consists of a four-character ID and one or more enumerators (really two or more, to be at all useful). The ID of an enumeration can be plugged into the type of a parameter or reply, or the class of an element.

The enumerators each consist of a name, a four-character ID, and a description. You use the name of an enumerator in AppleScript to specify which choice or choices you’ve made in an enumerated parameter.

There are two similar terms to keep clear on: enumeration and enumerator. The enumeration is like a list of elements. An enumerator is one of those elements. For example, a hypothetical parameter called “checkbox” may take on the values “checked” or “not checked”. This might be implemented as an enumeration, named “checkbox”, whose enumerators are named “checked” and “not checked.” A script programmer would then write either “checkbox checked” or “checkbox not checked” to indicate the desired initial state of a checkbox; what would actually be passed to the application would be the ID of the enumerator (perhaps ‘chek’ and ‘nchk’, respectively).

Conclusion

Creating an ‘aete’ resource is only one piece of the process of making an application scriptable, though it has quirks enough by itself. Really understanding events and classes requires understanding where they fit in the Apple Event object model. Knowing when standard suites can be adapted for your application is important; doing this will not only save you effort, but make things simpler for anyone scripting the application.

By knowing the fine points of ‘aete’ resources discussed this article, you may be able to make your custom suites more professional-looking and easier to use; having plural versions of classes, correctly set flags, and enumerations where appropriate will make it easier for other applications and scripts to control your application effectively. The result is less effort and more productivity by a method that has worked for humans long before it was applied to software: cooperation and division of labor.

References

Clark, Richard. “Apple Event Objects and You,” develop, Number 10, June 1992.

Eric M. Berdahl, “Better Apple Event Coding Through Objects,” develop, Number 12, December 1992.

Simone, Cal. “Designing a Scripting Implementation,” develop, Number 21, March 1995.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Together 3.6.1 - Store and organize all...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Features Smart storage. With simple drag-and-drop... Read more
Cloud 4.1.1 - File sharing from your men...
Cloud is simple file sharing for the Mac. Drag a file from your Mac to the CloudApp icon in the menubar and we take care of the rest. A link to the file will automatically be copied to your clipboard... Read more
OmniFocus 2.7.1 - GTD task manager with...
OmniFocus helps you manage your tasks the way that you want, freeing you to focus your attention on the things that matter to you most. Capturing tasks and ideas is always a keyboard shortcut away in... Read more
CleanApp 5.1.1 - Application deinstaller...
CleanApp is an application deinstaller and archiver.... Your hard drive gets fuller day by day, but do you know why? CleanApp 5 provides you with insights how to reclaim disk space. There are... Read more
ForkLift 3.0 Beta 2 - Powerful file mana...
ForkLift is a powerful file manager and ferociously fast FTP client clothed in a clean and versatile UI that offers the combination of absolute simplicity and raw power expected from a well-executed... Read more
Sublime Text 3126 - Sophisticated text e...
Sublime Text is a sophisticated text editor for code, markup, and prose. You'll love the slick user interface, extraordinary features, and amazing performance. Features Goto Anything. Use Goto... Read more
1Password 6.3.3 - Powerful password mana...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
WhatsApp 0.2.1880 - Desktop client for W...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more
NeoFinder 6.9.3 - Catalog your external...
NeoFinder (formerly CDFinder) rapidly organizes your data, either on external or internal disks, or any other volumes. It catalogs all your data, so you stay in control of your data archive or disk... Read more
Amadeus Pro 2.3.1 - Multitrack sound rec...
Amadeus Pro lets you use your Mac computer for any audio-related task, such as live audio recording, digitizing tapes and records, converting between a variety of sound formats, etc. Thanks to its... Read more

Our 5 Favorite iMessage Sticker Packs
At long last, iMessage joins the ranks of messaging apps the likes of LINE and Whatsapp, adding an impressive collection of stickers. They’re a great way to add a little something extra to your daily conversations. [Read more] | Read more »
How to get past Vulture Island's tr...
Vulture Island is a colorful and quirky mish-mash of platforming and puzzles. It’s creative and fresh, but sometimes the game can throw a curveball at you, leaving you stuck as to how you should progress. These tips will help you explore smoothly... | Read more »
The new Clash of Kings is just for Weste...
If you’ve played the original Clash of Kings, you’ll probably recognise the city building, alliance forging and strategic battles in Clash of Kings: The West. What sets this version apart is that it’s tailor made for a Western audience and the... | Read more »
Frost - Survival card game (Games)
Frost - Survival card game 1.12.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.12.1 (iTunes) Description: *Warning: the game will work on iPhone 5C and above and iPad Pro / 4. Other devices are not supported* | Read more »
How to build and care for your team in D...
Before you hit the trail and become a dog sledding legend, there’s actually a fair bit of prep work to be done. In Dog Sled Saga, you’re not only racing, you’re also building and caring for a team of furry friends. There’s a lot to consider—... | Read more »
How to win every race in Dog Sled Saga
If I had to guess, I’d say Dog Sled Saga is the most adorable racing game on the App Store right now. It’s a dog sled racing sim full of adorable, loyal puppies. Just look at those fluffy little tails wagging. Behind that cute, pixelated facade is... | Read more »
Let the war games commence in Gunship Ba...
Buzz Lightyear famously said, “This isn’t flying, this is falling – with style!” In the case of Gunship Battle: Second War, though, this really is flying - with style! The flight simulator app from Joycity puts you in control of 20 faithfully... | Read more »
How to get a high score in Fired Up
Fired Up is Noodlecake Games’ high score chasing, firefighting adventure. You take control of a wayward firefighter who propels himself up the side of a highrise with blasts of water. Sound silly? It is. It’s also pretty difficult. You can’t... | Read more »
NBA 2K17 (Games)
NBA 2K17 1.0 Device: iOS iPhone Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: Following the record-breaking launch of NBA 2K16, the NBA 2K franchise continues to stake its claim as the most authentic sports video... | Read more »
Dog Sled Saga (Games)
Dog Sled Saga 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: A game by Dan + Lisa As a rookie musher, foster a dogsledding team whose skills will grow if they're treated right. Week by... | Read more »

Price Scanner via MacPrices.net

Toughbook Celebrates 20 Years of Ruggedized M...
Panasonic System Communications Company of North America, Division of Panasonic Corporation of North America (Panasonic) today celebrates the 20th anniversary of its industry-leading Toughbook mobile... Read more
12-inch 1.1GHz Gray Retina MacBook on sale fo...
B&H Photo has the 2016 12″ 1.1GHz Gray Retina MacBook on sale for $1199.99 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
13-inch 2.5GHz MacBook Pro (Apple refurbished...
Apple has Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros... Read more
Save 30% on Camera Guard’s Secure Protection...
To celebrate the release of macOS Sierra, Miami-based security solutions company, ProtectStar has announced a special 30% discount on Camera Guard Professional for Mac 2016. This innovative security... Read more
DVDFab Special Deal – Get a 1-Year Free Licen...
Beijing, China based specialist in the field of DVD, Blu-ray and video backup solutions, Fengtao Software has launched its Autumn Special Deals 2016, giving a 1-year free license of a randomly picked... Read more
21-inch iMacs on sale for up to $120 off MSRP
B&H Photo has 21″ iMacs on sale for up to $120 off MSRP including free shipping plus NY sales tax only: - 21″ 3.1GHz iMac 4K: $1379 $120 off MSRP - 21″ 2.8GHz iMac: $1199.99 $100 off MSRP - 21″ 1... Read more
13-inch 2.7GHz/256GB Retina MacBook Pro on sa...
Amazon.com has the 13″ 2.7GHz/256GB Retina Apple MacBook Pro on sale for $151 off MSRP including free shipping: - 13″ 2.7GHz/256GB Retina MacBook Pro (sku MF840LL/A): $1348 $151 off MSRP Read more
Apple TVs on sale for up to $50 off MSRP
Best Buy has 32GB and 64GB Apple TVs on sale for $40-$50 off MSRP on their online store. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store... Read more
Apple refurbished 13-inch Retina MacBook Pros...
Apple has Certified Refurbished 13″ Retina MacBook Pros available for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.7GHz... Read more
Duplicate Sweeper Free On Mac App Store For O...
To celebrate the launch of Apple’s latest macOS Sierra, Stafford, United Kingdom based Wide Angle Software has announced that its duplicate file finder software, Duplicate Sweeper, is now available... Read more

Jobs Board

Sr. *Apple* Mac Engineer - Net2Source Inc....
…staffing, training and technology. We have following position open with our client. Sr. Apple Mac Engineer6+ Months CTH Start date : 19th Sept Travelling Job If Read more
*Apple* Retail - Multiple Positions-Norfolk,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Lead *Apple* Solutions Consultant - Apple (...
# Lead Apple Solutions Consultant Job Number: 51829230 Detroit, Michigan, United States Posted: Sep. 19, 2016 Weekly Hours: 40.00 **Job Summary** The Lead ASC is an Read more
US- *Apple* Store Leader Program - Apple (Un...
…Summary Learn and grow as you explore the art of leadership at the Apple Store. You'll master our retail business inside and out through training, hands-on Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.