TweetFollow Us on Twitter

Apple Events in PP
Volume Number:11
Issue Number:6
Column Tag:Applying Apple Technology

Powering Up AppleEvents in PowerPlant

Add an advanced feature to this popular framework

By Jeremy Roschelle

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

One of System 7’s most advanced features is its support for system-level scripting via AppleEvents. The AppleScript programming language can give users the ability to automate tasks, customize the interface, and connect independent applications to perform a task. Although Apple has presented these capabilities as advantages to business users, they are an powerful addition to educational software - what I create. In my present project, “SimCalc,” we decided to add scripting to give students, teachers and curriculum authors the ability to set up mathematical simulations.

Unfortunately, AppleEvents sports System 7’s least comprehensible documentation. Although AppleEvents sounded attractive, dense writing in Inside Mac VI sent me running for cover. With the arrival of better documentation and direct support for the AppleEvents Object Model (AEOM) in the PowerPlant class library, I decided to come out from hiding. After learning many lessons the hard way, SimCalc is now fully scriptable.

This article brings together many bits of necessary information that I discovered along the way. It will guide you through the process of using PowerPlant to make your application “scriptable” - able to respond to AppleEvent commands written in AppleScript or other scripting systems. However, no attempt is made to fully explain the AppleEvent Object Model or the concept of a “recordable” application. For that information, see Inside Mac: InterApplication Communication. AppleEvents and AppleScript are powerful capabilities, and by inheriting the basics from PowerPlant classes, you can easily give your users the power to write scripts that manipulate your application’s objects.

Pieces of the Puzzle

One of the difficulties in getting started with AppleEvents is making several components work smoothly with each other. Here is an overview:

The AppleEvent Object Model (AEOM) defines a generic view of a scriptable application. Every application presents itself to AppleScript as a containment hierarchy. For example, in our SimCalc application, the application contains documents, documents contain pages, and pages contain graphs. Each object in the hierarchy has properties that the user can get and set. Events operate over the objects in the hierarchy, creating and deleting them, and changing their properties.

An application’s “terminology resource” (resource type ‘aete’) presents the application’s AEOM interface to other applications and scripts. It describes your application’s containment hierarchy, along with the actions possible on objects in the hierarchy. The ‘aete’ resource also translates between the English-like AppleScript vocabulary and four-character descriptors that your application can easily respond to. There are descriptors for classes, properties, and event names and parameters.

PowerPlant provides several support classes to handle AppleEvent interaction. The central class is LModelObject, which handles properties, events, and containment relations for one class in the containment hierarchy. By deriving your classes from LModelObject, handling AppleEvents becomes a relatively simple matter of overriding appropriate methods.

ScriptEditor, which is part of the AppleScript kit and included with System 7.5, is helpful for testing your work. It provides tools for reading an applications ‘aete’ terminology dictionary, writing and checking the syntax of scripts against the terminology resource, and compiling and executing the script.

AEOM Conventions and Terms

Awareness of a few conventions and terms will make reading this article easier. The AppleEvent Object Model uses the standard separation of an application into verbs and nouns. Each verb is an “Event” and each noun is a “Class.” For example, the statement “Close Window 1” consists of the “close” event applied to the first object in the “window” class. Events have a “direct object,” which, by convention, is the noun to which the verb is applied (e.g., the window). Events take a list of keyword-specified parameters and can return a value.

A class corresponds to one level in the containment hierarchy. In our application, we have a class for the application, document, page, and graph level, among many others. An AEOM class need not correspond to a C++ implementation class; in particular, you don’t need an AEOM class for every C++ class, just those that will be direct objects of the Events you implement. A class has “Properties” to represent its state. For example, for example a page includes a name and index number as properties. The containment hierarchy is organized by the “Elements” relationship: in our application, the elements of the application class are documents, the elements of the document class are pages, and the elements of the page class are graphs.

PowerPlant uses the “L” prefix to distinguish library classes and we use “SC” to distinguish SimCalc classes.

Organization of the Article

This article divides the task of making your application scriptable into five parts:

1. adding a new class to the model hierarchy

2. adding a property to the class

3. adding a generic undo facility that supports every property.

4. adding an event handler for a standard event

5. adding a custom event

Each of these processes will require changes to the C++ classes derived from the PowerPlant class library, as well as changes to the terminology resource. Each change will be tested using ScriptEditor. Organizing the effort by processes makes it easier to see how AEOM, the terminology resource, PowerPlant, and Script Editor interrelate.

Adding a New Class

In PowerPlant, LApplication, LDocument, and LWindow inherit from LModelObject, which provides the root of the containment hierarchy. The terminology resource that comes with PowerPlant already specifies the “Elements” relationship among these classes, as well as the properties of each class.

In our SimCalc project, our documents are notebooks consisting of a list of pages. We want to support our notion of a page in the AEOM containment hierarchy. This requires changes in both the terminology resource and the SimCalc C++ classes. Specifically, we add the Page class to the terminology resource in two places, define appropriate methods for our SCPage class, and override some LModelObject methods in the containing class, SCDoc.

A good place to start making your application scriptable is with the terminology resource. Resorcerer provides a very good editor for the ‘aete’ resource. We start with the ‘aete’ supplied with PowerPlant, which describes the application, windows, and documents. To this we add information about the existence of the page class, and use the Elements relationship to indicate that documents contain pages.

Information in the terminology resource is organized into suites, with standard suites defined in the AppleEvents Registry, and custom suites defined elsewhere. Since pages are specific to our application, we create a new suite called the SimCalc suite. The name of the suite and its description are arbitrary, but your users will see them when they read your ‘aete’ resource with ScriptEditor’s “Open Dictionary” command. The suite id should be unique (registering it with Apple will maintain uniqueness).

Figure 1: Adding the Page Class to the SimCalc Suite

Adding class to the containment hierarchy involves two operations - creating the class and specifying which container has elements of this type. We’ll add our class to the SimCalc suite. To do this in Resorcerer, position the cursor within the classes box and press the New button. The class name you provide will be used by AppleScript to name the class in English, so choose a short noun. I find it helpful to capitalize the first letter of all English names for debugging: ScriptEditor’s syntax editor will replace statements with the capitalization you provide. Therefore if you type statements into ScriptEditor in lowercase, you can tell if ScriptEditor is recognizing your names by the capitalization.

The class id you choose will be used to identify objects of this class inside your application, and therefore must be unique within your ‘aete’. The description of the class is not functionally important, but will be read by users as they try to understand what the class represents.

In our application documents contain pages. In the terminology resource, the “Elements” relationship is indicated in the containing class. To specify that pages are elements of documents, we edit the definition of the document class, adding the class id of the page class to its elements field. In addition to adding the element, you must specify how the element can be accessed from the container. The most common ways to access a document are by name and index, and our pages also have unique ids, so we added that to the list.

Incidentally, Resorcerer doesn’t know about the ‘ID ’ form code; you have to type it in by hand. Also “absolute position” is a bit misleading, since PowerPlant can use this information to compute a variety of relative references as well. References to the first, last, middle element, as well as reference to an object before or after another object are computed from an absolute position reference.

Figure 2: Specifying that a page is an element in the document

Now we have completed editing the containment hierarchy. To check our work, we can open the terminology resource from ScriptEditor’s Open Dictionary command.

Figure 3: ScriptEditor shows that pages have been added to documents

ScriptEditor parses the information provided, and presents it in readable form. Because we created a class with the name “Page” and made it an element of documents, ScriptEditor can check the syntax of scripts that refer to pages with a variety of reference forms:

tell application "PoweringUp"
 get Page 1 -- by absolute position
 get last Page -- uses absolute position
 get Page "first" -- by name
 get Page after Page "first" -- by relative position
 get Page id 10 -- by id
end tell

Now its time to make the application recognize these references. Fortunately, PowerPlant makes this fairly easy. Each object only needs to know about its “SuperModel” (i.e., the container in which it resides) and any submodels it contains. The SuperModel-SubModel relationship is the same as the “Elements” containment relationship. The containment relationship is different from the Class-SubClass inheritance relationship; AEOM has no good way to express inheritance relationships .

In the SimCalc example, a page needs to know its containing document (its SuperModel), and the document needs to be able to locate pages as SubModels. In addition, the class must override GetModelKind, which is used by PowerPlant to generate an external description of an object. Returning ‘page’ will let PowerPlant know that this particular object is a page.

The external description should be the same as the class id defined in the terminology resource. In our case, the class definition looks like this:

SCPage.h
class SCPage : public LModelObject { 
 public:
 enum   { modelKind = 'page'} ;

 SCPage(SCDoc *inDoc);
 virtual ~SCPage();
 virtual DescType GetModelKind() const;
  
};

The constructor sets up the object’s SuperModel. The SuperModel is the object that contains this class in the containment hierarchy.

SCPage::SCPage
SCPage:SCPage(SCDoc *inDoc) : LModelObject()
{ 
 mSuperModel = inDoc;
 inDoc->AddSubModel(this); // stores the page in the Doc's list
} 

SCPage::~SCPage
SCPage:~SCPage(SCDoc *inDoc) : LModelObject()
{ 
 mSuperModel->RemoveSubModel(this)
 mSuperModel = nil; // prevents removal by LModelObject
} 

The GetModelKind member function overrides the default, and returns the class id.


SCPage::GetModelKind
DescType
SCPage::GetModelKind() const
{ 
 return SCPage::modelKind;
} 

In the SimCalc document class we store each page in a mPageList member variable, which is an LList. To maintain this list, we override the LModelObject::AddSubModel method, which gets called by the SCPage constructor. Now we have ensured that pages refer to the document as its SuperModel, and the document refers to pages as its elements.


SCDoc::AddSubModel
void
SCDoc::AddSubModel(LModelObject *inSubModel)
{ 
 if (SCPage::modelKind == inSubModel->GetModelKind()) { 
 mPageList.InsertItemsAt(1,arrayIndex_Last,&inSubModel);       } 
} 

SCDoc::RemoveSubModel
void
SCDoc::RemoveSubModel(LModelObject *inSubModel)
{ 
 if (SCPage::modelKind == inSubModel->GetModelKind()) { 
 mPageList.Remove(inSubModel);
 } 
} 

While these methods are simple, a subtle C++ gotcha is carefully avoided. In the SCPage constructor, we could have set up the SuperModel-SubModel relationship by passing inDoc in the LModelObject initializer, i.e.,

SCPage:SCPage(SCDoc *inDoc) : LModelObject(inDoc)
{ 
} 

If we did this, the dynamic type check in SCDoc::AddSubModel would return the wrong value. It turns out that GetModelKind would return typeNull instead of scPage. Why?

AddSubModel is called within the LModelObject constructor, and when this constructor is called, the SCPage vtable is not yet constructed, and the object is just an LModelObject. When the SCEleDoc method asks for its type, LModelObject::GetModelKind is called, instead of SCPage::GetModelKind. Gotcha!

The same problem occurs upon deletion. When the LModelObject destructor is called, the vtable has already been deconstructed from an SCPage to a LModelObject, so GetModelKind returns typeNull again. (So in our destructor, we manually break the super-sub model relationship instead.)

We could also try adding items to the LList without checking their type, but this turns out to be a problem, too: PowerPlant will call AddSubModel whenever a property is constructed for an object, so any properties of the document will end up inside mPageList with the pages - not a good thing.

Once we have the super-sub model relationship set up, we use it to enable 
AppleEvents to find pages within the container hierarchy.  The document 
class must be able to count and locate its elements.  The CountSubModels 
method is used to calculate references that use the “middle” and “last” 
forms.


SCDoc::CountSubModels
Int32   
SCDoc::CountSubModels(DescType inModelID) const
{ 
 if (inModelID == SCPage::modelKind) return mPageList.GetCount();
 ThrowOSErr_(errAENotAnElement);
 return 0; // prevent compiler warning
} 

PowerPlant catches exceptions within its AppleEvent handlers and returns an error code, so whenever an operation can’t be completed its best to throw an error.

Next we must take care of an omission in LModelObject. Even though LModelObject defines the CountSubModels method, it doesn’t use it to respond to a CountElements AppleEvent. So we can’t ask for the “number of pages” in AppleScript. Fortunately, its simple to remedy this by overriding HandleAppleEvent to call CountSubModels:


SCDoc::HandleAppleEvent

void  
SCDoc::HandleAppleEvent(  
 const AppleEvent  &inAppleEvent,
 AppleEvent &outAEReply,
 AEDesc &outResult,
 Int32  inAENumber)
{ 
 switch (inAENumber) { 
 case ae_CountElements:
    // note: we should extract the desired kind
    // rather than assuming its SCPage::modelKind
 Int32 count = CountSubModels(SCPage::modelKind);
   OSErr err = AECreateDesc(typeLongInteger,
 (Ptr) &count, 
 sizeof(long), &outResult);
 FailOSErr_(err);
 break;
 default:
 inherited::HandleAppleEvent(inAppleEvent,outAEReply,
 outResult);
 }
}

Since SimCalc defined absolute position, name, and id forms in the terminology resource we need to override the parallel LModelObject member functions for our document type.

The most common way to find an element is by position. For example, in AppleScript you can say:

page 1 of application "PoweringUp"
last page of application "PoweringUp"

When PowerPlant receives an AppleEvent with a position-based object specifier, it calls the containing LModelObject’s GetSubModelByPosition member function. This member function locates the element at the desired location, and returns a “token” containing that element. PowerPlant supplies and manages an appropriate class of tokens, so we don’t need to worry about the details of token implementation.


SCDoc:: GetSubModelByPosition
void  
SCDoc::GetSubModelByPosition( 
 DescType inModelID,
 Int32  inPosition,
 AEDesc &outToken) const
{ 
 if (inModelID == SCPage::modelKind){ 
 SCPage *page;
 if (mPageList->FetchAItemt(inPosition,&page)) { 
 PutInToken(page,outToken); 
 return;
 } 
 ThrowOSErr_(errAENotAnElement);
} 

The second most common way to refer to an element is by name, as in:

page “perfect” of document 1

Overriding the LModelObject::GetSubModelByName member function will handle this. In the method below, pages are found by iterating through the mPageList that contains them.


SCDoc::GetSubModelByName
void    
SCDoc::GetSubModelByName(
 DescType inModelID,
 Str255 inName,
 AEDesc &outToken) const
{ 
 if (inModelID == SCPage::modelKind){ 
 SCPage *page;
 Str255 pageName;
 LListIterator iter(mPageList,iterate_FromStart);

 while (iter.Next(&page)) { 
 page->GetDescriptor(pageName);
 if (EqualString(pageName,inName,false,false)) { 
   PutInToken(page,outToken);
 return;
 } 
 } 
 } 
 ThrowOSErr_(errAENotAnElement);
} 


When referring to an element by unique ID, AEOM allows any type of data be to used as the unique ID (unlike the index and name cases, which use a long and a text string, respectively). Therefore PowerPlant provides the actual descriptor record rather than providing a number or a string as in the prior cases. This adds the extra step of extracting the unique ID from the descriptor record. This is best done using the static methods of the UExtractFromAEDesc class, thereby performing any necessary coercions.


SCDoc::GetSubModelByUniqueID
void    
SCDoc::GetSubModelByUniqueID(
 DescType inModelID,
 const AEDesc  &inKeyData,
 AEDesc &outToken) const
{ 
 long   id,pageID;

 UExtractFromAEDesc::TheInt32(inKeyData,id);

 if (inModelID == SCPage::modelKind){ 
 SCPage *page;
 LListIterator iter(mPageList,iterate_FromStart);

 while (iter.Next(&page)) { 
 pageID = page->GetID();
 if (pageID == id) { 
   PutInToken(page,outToken);
 return;
 } 
 } 
 } 
 ThrowOSErr_(errAENotAnElement);
} 

Finally, we have to override the GetPositionOfSubModel method, which is used to compute relative references (i.e., page after page 3).


SCDoc::GetPositionOfSubModel
Int32   
SCDoc::GetPositionOfSubModel(
 DescType inModelID,
 const LModelObject *inSubModel) const
{ 
 if (inModelID == SCPage::modelKind) { 
 return mPageList.FetchIndexOf(&inSubModel);
 } 
 
 ThrowOSErr_(errAENotAnElement);
 return 0; // prevent compiler warning
}

In our actual SimCalc application, the containment hierarchy has additional levels: Pages contain graphs, for example. Because the implementation of the page-graph Elements relationship is exactly the same as the document-page, we’ll skip the details. The important thing to notice is that no matter how deeply nested the AppleScript container syntax gets, you only need to implement the Elements relationship between each class and its immediate SuperModel. PowerPlant and AEOM do the rest for you.

At this point, we have a working containment hierarchy for pages. However, because the page class has no properties, and responds to no events, the demo is pretty dull. We’ll fix that in the next two sections, first adding properties, and then event handling.

Adding Properties to the Class

In the AEOM, a property is a state variable of an object in the container hierarchy. Scripts change the state of the application by changing properties of objects. An application describes its classes’ properties in the terminology resource. Inside, the application handles properties via the PowerPlant LModelProperty class property. To add a property to a class, you have to edit the terminology resource and override two LModelObject methods.

The resource template has a slot for a list of properties within each class. For the page in SimCalc, we defined properties for the name, index, and id of each page. The name can be set by the user, but the index and id are read-only. The string you provide for the property name is used to refer to the property in AppleScript, and will be translated to the value in the code field when received by your application. The class field is the type of the variable. AppleScript will coerce user-supplied input into this type. The AppleEvent Registry defines many standard property names and types. You should use the most appropriate type.

A couple of warnings are due: be careful not to re-use an existing property code with a different property name (i.e., giving the ‘pnam’ property the name “descriptor” instead of “name”). This will mostly likely confuse AppleScript. Also, I’ve found that AppleScript sometimes caches an applications ‘aete’ resource. After you edit an ‘aete’, you may need to restart your Macintosh to get AppleScript to notice the changes.

Figure 4: ScriptEditor shows the properties of the Page Class

Implementing properties in an object derived from LModelObject is easy - you just override SetAEProperty and GetAEProperty. Explaining how it works is a bit more difficult, because PowerPlant does a lot of work behind the scenes to make properties easy to support. After presenting the two overridden functions, I’ll explain the gist of how it works.

GetAEProperty dispatches on the property id, and places the value of the desired property into a AppleEvent descriptor record. The property ids for pIndex and pName are defined in AERegistry.h, and our header file defines pUID to be ‘ID ’. Its no accident that these identities are the same as those that appear in terminology resource. AppleScript uses the terminology resource to translate English names for properties.

Figure 5: Adding properties to the terminology resource


SCPage::GetAEProperty
void    
SCPage::GetAEProperty(  
 DescType inProperty,
 const AEDesc  &inRequestedType,
 AEDesc &outPropertyDesc) const
{ 
 long   id, index;
 Str255 name;
 
 switch (inProperty) { 
 case pIndex:
 index = GetIndex(); 
 FailOSErr_(AECreateDesc(typeLongInteger, (Ptr) &index,
 sizeof(long), &outPropertyDesc));
 break;
 case pUID:
 id = GetID();
 FailOSErr_(AECreateDesc(typeLongInteger, (Ptr) &id,
 sizeof(long), &outPropertyDesc));
 break;
 case pName:
 GetDescriptor(name);
 FailOSErr_(AECreateDesc(typeChar, &(name[1]),
 name[0], &outPropertyDesc));
 break;
 } 
} 

Setting a property is very similar to getting a property; the main difference is that instead of putting a value into a a descriptor record, you take one out. This can be done directly by calls to the AppleEvent manager, or through PowerPlant. There is a big advantage to using PowerPlant’s methods: they will coerce data into the right type for you, and throw an exception if coercion fails. This exception will be trapped within PowerPlant’s basic AppleEvent handlers, so the exception will be transparent to you. But PowerPlant will give the user an appropriate error message. PowerPlant defines extraction methods in UExtractFromAEDesc via a pseudo-template mechanism that makes it easy for you to add extraction methods for any additional types you need.


SCPage::SetAEProperty
void    
SCPage::SetAEProperty(  
 DescType inProperty,
 const AEDesc  &inValue,
 AEDesc &outAEReply)
{ 
 Str255 name;
 
 switch (inProperty) {    
 case pName:
 UExtractFromAEDesc::ThePString(inValue,name);
 CopyPStr(name,mName);
 break;
 default:
 inherited::SetAEProperty(inProperty,inValue,outAEReply);
 } 
} 
 

As you can see, adding properties to an LModelObject is not hard. You can test that the property works in ScriptEditor. Some example lines are:

tell application “PoweringUp”
 copy name of page 1 to oldName
 copy oldName & “er” to newName
 set name of page 1 to newName
 get index of page newName
end tell

Here’s the story on how this works. AppleScript sets and gets properties by applying the standard set data and get data events to property tokens. Consider the execution of the line:

copy name of page 1 to oldName

PowerPlant handles properties by re-using standard AppleEvent handling. The routine for handling any AppleEvent is to first get a token representing the object (the noun), and then send it the event (the verb). Rather than defining a second token type for properties, PowerPlant treats properties as a class of LModelObject. During the execution of an AppleEvent that refers to a property, PowerPlant creates an LModelProperty on the fly, destroying it at the end of event processing. This LModelProperty has the target object as its SuperModel and has an mPropertyID member variable to represent the identity of the property. When the property receives a set or get data event, it calls its SuperModel’s SetAEProperty and GetAEProperty methods, specifying its property id.

Supporting Undo for All Properties

Supporting AppleEvents seems to be a lot of work for most simple tasks. But it actually can make my most dreaded task, supporting Undo, easier.

Think about it: Most of the application’s changes to state are changes to the value of properties. There is a standard form for naming these properties, the property id, and standard methods for getting and setting them. The only problem is that the property data may come in a variety of forms, and we need to be able to store them all - an anathema to C++ strong typing. This is where AppleEvents shines by providing a dynamically typed descriptor record that can store any sort of property value.

In SimCalc, we support property undo with a subclass of LModelProperty. When handling an incoming set property event, this subclass calls GetAEProperty just before it calls SetAEProperty. It stores the previous value and a duplicate of the new value in a task, along with the target LModelObject and the id of the property. Using these entities, the task can easily respond to undo and redo. As a finishing touch we parse the ‘aete’ resource for the English name of the property and incorporate this into the undo menu item in the edit menu. This provides totally automatic handling of undo for property values we might ever define, without any additional work.

Our special form of property overrides only one method, to post a SCSetPropertyAction whenever the user tries to set the value of a property.


SCModelProperty::HandleSetData
void  
SCModelProperty::HandleSetData(
 const AppleEvent  &inAppleEvent,
 AppleEvent &outAEReply)
{ 
 SCApp::PostAction(new SCSetPropertyAction(GetSuperModel(),
 mPropertyID, 
 inAppleEvent));
} 

The interesting work is done in the SCSetPropertyAction, which is derived from LSemanticAction. The constructor gets the old value, and saves it along with the copy of the new value, in member variables mNewData and mOldData. These member variables are StAEDescriptors; they hold AppleEvent descriptor records, and automatically dispose of those descriptors when upon destruction.

SCSetPropertyAction::SCSetPropertyAction

SCSetPropertyAction::SCSetPropertyAction(
 LModelObject    *inObject,
 DescType inPropID,
 const AppleEvent&inAE)
 :  LSemanticAction(200,3), mObject(inObject), mPropID(inPropID)
 
{ 
    // get old data from object itself
 StAEDescriptor  reply;
 mObject->GetAEProperty(mPropID, reply.mDesc, mOldData.mDesc);
 
 mNewData.GetParamDesc(inAE, keyAEData, typeWildCard);
 
 UAppleEventsMgr::CheckForMissedParams(inAE);
} 

Now the redo and undo methods are nearly trivial, and work regardless of the C type that stores the property value:


SCSetPropertyAction::RedoSelf
void 
SCSetPropertyAction::RedoSelf()
{ 
 StAEDescriptor  result;  // will dispose result on deletion
 mObject->SetAEProperty(mPropID,mNewData.mDesc,result.mDesc);
} 


SCSetPropertyAction::UndoSelf
void 
SCSetPropertyAction::UndoSelf()
{ 
 StAEDescriptor  result;// will dispose result on deletion
 mObject->SetAEProperty(mPropID,mOldData.mDesc,result.mDesc);
} 

The final step is to force our object to use SCModelProperty instead of LModelProperty by overriding GetModelProperty.


SCPage::GetModelProperty
LModelProperty*  
SCPage::GetModelProperty(DescType inProperty)
{ 
 return new SCModelProperty(inProperty,this);
} 

Adding Event Handling for a Standard Event

According to the AEOM, you should represent most of your application’s state as properties of classes. Many user commands therefore translate into setting a property. Some commands, however, are best thought of as verbs that operate on a noun, changing the state of the application in a way that cannot be reflected in a single property. In this case, you probably need to define and handle an event.

Consider the act of changing pages. When the user clicks the “next page” or “previous page” button, the application changes the entire contents of the screen. I think of this most naturally as sending the document a change page event, with the name or number of the desired page as a parameter. However, AEOM has its own way of thinking about things; and Apple discourages users from inventing events where a standard one will do. In this case, changing a page can also be represented by sending the page a “select” event. In AppleScript you type:

tell application "PoweringUP" 
 select page 43
end tell

At first, this convention of using sending “select” to a page rather than “change page” to a document seems arbitrary. But it turns out to have important implications. Apple’s preferred methods factor the verb from the designation of the noun, whereas the “change page” method incorporates the noun as a parameter of the verb. The practical difference is that the “select” method can operate over an arbitrary expression that designates a page object, such as:

select (page after page 4)
select (page before page id 104)
select last page
select (make new page at end)

The standard terminology resource supplied with PowerPlant already contains the select event. Therefore to add event handling for select, we need only modify code internal to the application. In particular, we should override the LModelObject method that handles AppleEvents, which strangely enough is called HandleAppleEvent.


SCPage::HandleAppleEvent
void    
SCPage::HandleAppleEvent( 
 const AppleEvent&inAppleEvent,
 AppleEvent &outAEReply,
 AEDesc &outResult,
 Int32  inAENumber)
{  
 switch (inAENumber) { 
 case ae_Select:
 ((SCDoc *)GetSuperModel())->SetSelection(this);
 break;
 default:
 inherited::HandleAppleEvent( inAppleEvent,
 outAEReply,
 outResult,
 inAENumber);
 break;
 } 
} 

Handling an event with no parameters is just a matter of dispatching on the AppleEvent number. SimCalc internally prefers to treat changing the page as a responsibility of the document, so we call the ChangePage method of the page’s SuperModel, (which will be its document; we set it up that way in the constructor).

There is one subtle mystery with the parameters to this function. Can you find it? In the terminology resource, an event is identified by its class id and its event id, but here an event is identified by a number which has no correspondence to either of those ids. The translation between these two forms of event identity was initially a deep mystery to me.

It turns out that the mapping is represented in an ‘aedt’ resource. There is one ‘aedt’ for each suite, and each item in the ‘aedt’ contains a suite id, an event id, and a long integer. PowerPlant uses this resource to translate incoming events ids to a long integer, which is then passed to your object’s HandleAppleEvent method. It is also important to understand that the class id for an event is not the id of a class! Rather “class id” in this context means a class of events contained in a suite. For example the class id for standard events like close is ‘core’ and appears in the ‘coRe’ suite.

Defining New Events

The previous example covered handling an event already defined within the terminology resource. Adding a completely new event is possible, and combines parts of the processes described in preceding sections. In short, to add an event you:

1. add the event to an appropriate suite of the terminology resource

2. add a mapping from suite and event id to a number in an ‘aedt’ resource

3. add a case to the switch statement in HandleAppleEvent that:

a. extracts descriptor records for each parameter in the event

b. extracts C++ values from the descriptor records

c. calls a member function that does the work

d. creates a descriptor record containing any return value

To illustrate, we will add a “sort” event to the document, allowing it to sort the pages into alphabetical order.

First, we need to edit the terminology resource, adding the new event to the PoweringUp suite. We’ll use ‘P Up’, our application’s signature, as the class id, and ‘sort’ as the event id. These two bits of information also need to be added to an ‘aedt’ resource along with a unique long integer that will signify this event within the application. The event name supplies the English verb that will create this event from within AppleScript, but the description is purely informational. The reply type for our event is a null, since we don’t return anything.

The direct object comes right after the verb in AppleScript syntax; it is the first parameter of the event. If the direct object has object specifier as its type, PowerPlant will call that object with the HandleAppleEvent message. You can think of this translating to C++ syntax as:

(direct object)->EventName(parameter1,parameter2,....);

The direct object for the sort command will be the document.

In this case we want one additional parameter which describes the sort direction. We could use a Boolean to represent the sort order, but to make things nicer, let’s use an enumeration. Then the user can type “ascending” or “descending” rather than remember which direction “true” implies.

To indicate that this will be an enumerated parameter, we turn on that option and use the id of the enumeration, which we will define as ‘Esrt’. Then in the enumeration section of the suite, we create an enumeration of this type, and specify each option as an enumerator. Each enumerator has a name that can be typed in AppleScript, and a corresponding id code that will be sent in the event.

Figure 6: The terminology for the Sort event

Figure 7: The terminology for the sort direction enumeration.

To finish off the parameter description we need to provide a parameter name and keyword. The name will become part of the AppleScript syntax of the event. Since we specified “in direction” as the name, we will be able to say:

sort in direction ascending
sort in direction descending

Figure 8: ScriptEditor shows the terminology for the Sort event.

Figure 9: The aedt resource maps class and id to a number

Inside the application, the work if fairly easy. We will retrieve the parameter with the ‘srtD’ keyword. To SCDoc:HandleAppleEvent, we add a case statement that triggers on the long integer we set in the ‘aedt’ resource, 10000.


SCDoc::HandleAppleEvent
void    
SCDoc::HandleAppleEvent(
 const AppleEvent&inAppleEvent,
 AppleEvent &outAEReply,
 AEDesc &outResult,
 Int32  inAENumber)
{ 
 switch (inAENumber) { 
 case ae_CountElements:
 HandleCountEvent(inAppleEvent, outAEReply, outResult);
 break;
 case ae_Sort:
 { 
 StAEDescriptor  desc;
 OSType direction = kSortAscending;
 desc.GetOptionalParamDesc( inAppleEvent,
 keySortDirection,
 typeEnumeration);
 if (desc.mDesc.dataHandle != nil) {  // check for parameter
 UExtractFromAEDesc::TheEnum(desc.mDesc,direction);
 } 
 DoSort(direction == kSortAscending);
 break;
 } 
 default:
 inherited::HandleAppleEvent( inAppleEvent,
 outAEReply,
 outResult,
 inAENumber);
 break;
 } 
} 

In the this routine’s sort case, we first get the descriptor for the sort parameter. PowerPlant provides a handy routine for this: GetOptionalParamDesc. Since this parameter is optional, it may not exist. If it does exist, the dataHandle of the descriptor will not be nil. Then we can use UExtractFromAEDesc::TheEnum to extract the enum from the descriptor. Then we dispatch to our member function that does the work.

Conclusion

Good AppleEvent support is the distinguishing mark of a System 7-savvy application. By building on the classes provided within PowerPlant, supporting AppleEvents becomes a simple, incremental process.

First, you characterize your application as an AEOM containment hierarchy, consisting of classes linked by the Elements relationship. This is accomplished by specifying the classes and the Elements relationship in the terminology resource, deriving your class from LModelObject, and overriding a few key methods. Second, you add support for setting and getting the value of the properties of your classes. This is achieved by editing the ‘aete’ to specify English property names and corresponding internal property ids. Then you override the GetAEProperty and SetAEProperty methods appropriately. Third, you add support for additional events that your class responds to. Again this requires editing the ‘aete’, as well as the ‘aedt’. Then you add a clause to your objects’ HandleAppleEvent method.

As an natural extension to this methodology, you could handle Create, Delete, and Move events for any object in your hierarchy. An abstraction that builds on LList can support these events uniformly for any container in your hierarchy, including general Undo handling. By supporting Create, Delete and Move, along with the events already supported within PowerPlant, you will be well on your way to handling the whole AppleEvents Core Suite.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Capto 1.2.9 - $29.99
Capto (was Voila) is an easy-to-use app that takes capturing, recording, video and image editing to the next level. With an intelligent file manager and quick sharing options, Capto is perfect for... Read more
Opera 51.0.2830.40 - High-performance We...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
GarageSale 7.0.13 - Create outstanding e...
GarageSale is a slick, full-featured client application for the eBay online auction system. Create and manage your auctions with ease. With GarageSale, you can create, edit, track, and manage... Read more
1Password 6.8.7 - 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
Evernote 7.0.1 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
MacUpdate Desktop 6.2.0 - $20.00
MacUpdate Desktop brings seamless 1-click app installs and version updates to your Mac. With a free MacUpdate account and MacUpdate Desktop 6, Mac users can now install almost any Mac app on... Read more
HoudahSpot 4.3.5 - Advanced file-search...
HoudahSpot is a versatile desktop search tool. Use HoudahSpot to locate hard-to-find files and keep frequently used files within reach. HoudahSpot will immediately feel familiar. It works just the... Read more
EtreCheck 4.0.4 - For troubleshooting yo...
EtreCheck is an app that displays the important details of your system configuration and allow you to copy that information to the Clipboard. It is meant to be used with Apple Support Communities to... Read more
WhatsApp 0.2.8361 - 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
iClock 4.2 - Customize your menubar cloc...
iClock is a menu-bar replacement for Apple's default clock but with 100x features. Have your Apple or Google calendar in the menubar. Have the day, date, and time in different fonts and colors in the... Read more

Latest Forum Discussions

See All

The best games like Florence
Florence is a great little game about relationships that we absolutely adored. The only problem with it is it's over a little too soon. If you want some other games with some emotional range like Florence, check out these suggestions: [Read more] | Read more »
Angry Birds Champions adds cash prizes t...
Collaborating with developer Rovio Entertainment, GSN Games has released a twist on the Angry Birds formula. Angry Birds Champions features the same bird-flinging gameplay, but now you can catapult Red and co for cash. | Read more »
Around the Empire: What have you missed...
148Apps is part of a family. A big family of sites that make sure you're always up to date with all the portable gaming news. Just like a real family, I guess. I don't know, my mum never told me anything about Candy Crush to be fair. [Read more] | Read more »
The Battle of Polytopia Guide - Tips for...
The addition of multiplayer to The Battle of Polytopia has catapulted the game from a fun enough time waster to a fully-fledged 4X experience on your phone. We've been playing quite a few matches over the past week or so, and we've put together a... | Read more »
All the best games on sale for iPhone an...
Hi there, and welcome to our round up of all the best games that are on sale for iOS at the moment. It's not a vintage week in terms of numbers, but I'm pretty sure that every single one of these is worth picking up if you haven't already played... | Read more »
Disc Drivin' 2 Guide - Tips for the...
We're all still playing quite a bit of Disc Drivin' 2 over here at 148Apps, and we've gotten pretty good at it. Now that we've spent some more time with the game and unlocked more powerups, check out some of these more advanced tips: | Read more »
Alto's Odyssey Guide - How to Tackl...
Alto’s Odyssey is a completely stunning and serene runner, but it can also be a bit tricky. Check out these to try and keep your cool while playing this endless runner: Don’t focus too much on tasks [Read more] | Read more »
Here's everything you need to know...
Alto's Odyssey is a really, really good game. If you don't believe me, you should definitely check out our review by clicking this link right here. It takes the ideas from the original Alto's Adventure, then subtly builds on them, creating... | Read more »
Alto's Odyssey (Games)
Alto's Odyssey 1.0.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: Just beyond the horizon sits a majestic desert, vast and unexplored. Join Alto and his friends and set off on an endless... | Read more »
Vainglory 5v5: Everything you need to kn...
Vainglory just got bigger. [Read more] | Read more »

Price Scanner via MacPrices.net

Apple AirPods in stock today for $159, free s...
Adorama reports stock of Apple AirPods today for $159 including free shipping, plus pay no sales tax outside of NY & NJ. See our Apple AirPod Price Tracker for the latest prices and stock status... Read more
Saturday Sale: Amazon offers 12″ 1.3GHz MacBo...
Amazon has Silver and Gold 2017 12″ 1.3GHz Retina MacBooks on sale for $250 off MSRP. Shipping is free: – 12″ 1.3GHz Silver MacBook: $1349.99 $250 off MSRP – 12″ 1.3GHz Gold MacBook: $1349.99 $250... Read more
Use your Apple Education discount and save up...
Purchase a new Mac using Apple’s Education discount, and take up to $400 off MSRP. All teachers, students, and staff of any educational institution with a .edu email address qualify for the discount... Read more
Apple Canada offers 2017 21″ and 27″ iMacs fo...
 Canadian shoppers can save up to $470 on the purchase of a 2017 current-generation 21″ or 27″ iMac with Certified Refurbished models at Apple Canada. Apple’s refurbished prices are the lowest... Read more
9″ iPads available online at Walmart for $50...
Walmart has 9.7″ Apple iPads on sale for $50 off MSRP for a limited time. Sale prices are for online orders only, in-store prices may vary: – 9″ 32GB iPad: $279.99 $50 off – 9″ 128GB iPad: $379.99 $... Read more
15″ Apple MacBook Pros, Certified Refurbished...
Save $360-$420 on the purchase of a 2017 15″ MacBook Pro with Certified Refurbished models at Apple. Apple’s refurbished prices are the lowest available for each model from any reseller. An standard... Read more
Amazon restocks MacBook Pros with models avai...
Amazon has restocked 15″ and 13″ Apple MacBook Pros with models on sale for up to $251 off MSRP. Shipping is free. Note that stock of some Macs may come and go (and some sell out quickly), so check... Read more
Lowest price of the year: 15″ 2.8GHz Apple Ma...
Amazon has the 2017 Space Gray 15″ 2.8GHz MacBook Pro on sale today for $251 off MSRP. Shipping is free: – 15″ 2.8GHz Touch Bar MacBook Pro Space Gray (MPTR2LL/A): $2148, $251 off MSRP Their price is... Read more
Apple restocks full line of Certified Refurbi...
Apple has restocked a full line of Apple Certified Refurbished 2017 13″ MacBook Pros for $200-$300 off MSRP. A standard Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
Lowest sale price available for 13″ 1.8GHz Ma...
Focus Camera has the 2017 13″ 1.8GHz/128GB Apple MacBook Air on sale today for $829 including free shipping. Their price is $170 off MSRP, and it’s the lowest price available for a current 13″... Read more

Jobs Board

*Apple* Media Products Commerce Engineering...
# Apple Media Products Commerce Engineering Manager Job Number: 56207285 Santa Clara Valley, California, United States Posted: 26-Jan-2018 Weekly Hours: 40.00 **Job Read more
Digital Platforms Lead, Today at *Apple* -...
# Digital Platforms Lead, Today at Apple Job Number: 56178747 Santa Clara Valley, California, United States Posted: 23-Feb-2018 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.