---

Two Approaches to Creating an Apple Event

How do you put together the data structures described in this chapter to create an Apple event? The Apple Event Manager provides functions that lend themselves to two main approaches, which you can combine as needed:

• You can create an Apple event with one call, passing all the information needed for a complete Apple event.

  Related functions allow you to create a complex descriptor, attribute, or parameter and add it to an existing Apple event in one step.

• You can create an Apple event sequentially, by first creating a potentially incomplete event, then adding information to it with subsequent calls.

  With this approach, you build descriptors into more complex data structures from the bottom up.

In either case, your application relies on the Apple Event Manager to construct Apple event data structures based on the arguments you pass.

In this section:

Creating an Apple Event in One Step
Creating an Apple Event Sequentially
The Completed Apple Event

Creating an Apple Event in One Step

You can call the AEBuildAppleEventfunction to create an Apple event in one step. To do so, you pass event class, event ID, and other information that is used to create the Apple event’s attributes. The AEBuildAppleEvent function includes parameters for specifying the target address—you don’t have to separately create an address descriptor. You may need to prepare data you’ll pass to AEBuildAppleEvent—for example, you may need to create aliases to files you will insert into the Apple event as a descriptor list.

In addition, you provide a specially formatted string, similar to the string you might pass to a printf function, along with parameters that specify the data that corresponds to items in the format string. As a result, AEBuildAppleEvent can also create the parameters for your Apple event, resulting in a full-fledged Apple event.

The Apple Event Manager also provides the AEBuildDesc function as a one-step mechanism for adding potentially complex descriptors to an existing Apple event, and the AEBuildParameters function for adding parameters or attributes.

The one-step functions are most useful in situations where your application knows in advance all the information needed to create an Apple event or other data structure. They also make it easier to do parameterized substitution of values. For an example of this approach, see “Creating an Apple Event With AEBuildAppleEvent.”

Creating an Apple Event Sequentially

You can create the basic structure for an Apple event by calling the AECreateAppleEvent function. You pass information specifying event class, event ID, target address, return ID, and transaction ID; the function creates an Apple event containing the corresponding attributes. However, before you can call AECreateAppleEvent, you have to create a target address descriptor to pass to it, using a function such as AECreateDesc.

After calling AECreateAppleEvent, the resulting Apple event contains attributes for the event but no parameters. To add parameters to the event, you can use the AEBuildDesc and AEBuildParameters functions described in the previous section, or you can continue to work sequentially. For example, if the direct object of the event you are creating is a list of file aliases, you could create it sequentially by performing the following steps:

1. Call AECreateDesc once for each file alias to create a descriptor for it.

2. Call AECreateList to create a descriptor list.

3. Call AEPutDesc once for each descriptor to add it to the descriptor list.

4. Call AEPutParamDesc to add the descriptor list to the Apple event as a parameter.

This sequential approach is most useful for creating simple Apple events, or in situations where your application must factor the creation of an Apple event across several layers of code—for example, where you create an event, then pass it to various subsystems to add data to it.

For an example of how to create an Apple event step by step, see “Creating an Apple Event With AECreateAppleEvent.”

The Completed Apple Event

Figure 2-8 shows the main data structures of a complete Apple event, containing a list of keyword-specified descriptors that specify the attributes and parameters of an open documents Apple event. Although this is an event sent to your application by the Mac OS, events you create have a similar structure.

The figure includes attributes for the event class, event ID, and target address. It also shows the direct parameter—a keyword-specified descriptor with the keyword keyDirectObject. The entire figure corresponds to the open documents event shown in Figure 2-7.

---