Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 9 - Recording Apple Events / What to Record

Recording User Actions

Two general guidelines apply to the recording of all user actions:

• Send Apple events that correspond to simple statements in a script rather than compound statements.
• Don't record superfluous actions.

In most cases, if the user performs several related actions, your application should send Apple events for each action rather than saving the actions and creating an event that combines them.

For example, if the user selects some text, cuts it, and then pastes it somewhere else, your application should send itself four events that correspond to these actions:

1. Select the text
2. Cut
3. Set the insertion point
4. Paste

Thus, if the user selects characters 5 through 20 of the frontmost document, chooses the Cut command from the Edit menu, places the insertion point after character 72, and chooses the Paste command, your application should send the following events.

• A Select event (event class kAEMiscStandards, event ID kAESelect) with this direct parameter:

  Keyword	Descriptor type	Data
  keyDirectObject	typeObjectSpecifier	(see indented record)
  keyAEDesiredClass	typeType	cChar
  keyAEContainer	typeObjectSpecifier	(see indented record)
  keyAEDesiredClass	typeType	cDocument
  keyAEContainer	typeNull	No data
  keyAEKeyForm	typeEnumerated	formAbsolutePosition
  keyAEKeyData	typeLongInteger	1
  keyAEKeyForm	typeEnumerated	formRange
  keyAEKeyData	typeRangeDescriptor	(see indented record)
  keyAERangeStart	typeObjectSpecifier	(see indented record)
  keyAEDesiredClass	typeType	cChar
  keyAEContainer	typeCurrentContainer	No data
  keyAEKeyForm	typeEnumerated	formAbsolutePosition
  keyAEKeyData	typeLongInteger	5
  keyAERangeStop	typeObjectSpecifier	(see indented record)
  keyAEDesiredClass	typeType	cChar
  keyAEContainer	typeCurrentContainer	No data
  keyAEKeyForm	typeEnumerated	formAbsolutePosition
  keyAEKeyData	typeLongInteger	20

• A Cut event (event class kAEMiscStandards, event ID kAECut)
• A Select event with this direct parameter:

  Keyword	Descriptor type	Data
  keyDirectObject	typeObjectSpecifier	(see indented record)
  keyAEDesiredClass	typeType	cInsertionLoc
  keyAEContainer	typeObjectSpecifier	(see indented record)
  keyAEDesiredClass	typeType	cChar
  keyAEContainer	typeObjectSpecifier	(see indented record)
  keyAEDesiredClass	typeType	cDocument
  keyAEContainer	typeNull	No data
  keyAEKeyForm	typeEnumerated	formAbsolutePosition
  keyAEKeyData	typeLongInteger	1
  keyAEKeyForm	typeEnumerated	formAbsolutePosition
  keyAEKeyData	typeLongInteger	72
  keyAEKeyForm	typeEnumerated	formRelativePosition
  keyAEKeyData	typeEnumerated	kAEAfter

• A Paste event

Note

The format used for the direct parameters in this example and throughout this chapter does not show the structure of the direct parameters as they exist within the Apple events. Instead, this format shows what you would obtain after calling AEGetKeyDesc repeatedly to extract the nested descriptor records from the Apple events.

When you call AEGetKeyDesc to extract the descriptor record that specifies an application's default container, AEGetKeyDesc returns a descriptor record of type AEDesc with a descriptor type of typeNull and a data handle whose value is 0.

The first Select event in this example sets the application's pSelection property (that is, the current selection) to the objects identified by the object specifier record in the direct parameter--characters 5 through 20. The second Select event places the insertion point after the object identified by the object specifier in the direct parameter--after character 72.

You could also interpret these four actions as a single Move event that simply moves characters 5 through 20 to after character 72. A user could write such a statement in a script, but for recording purposes four separate events correspond more precisely to the user's actions. For example, if the user performed another paste operation after the first four actions, a Move event would not produce the correct results.

It is equally important for a recordable application not to send superfluous events. For example, your application should not send an event every time the user makes a selection. Instead, it should keep track of the most recent selection made. When the user performs some action on the selection, the application should send an event that sets the selection followed by the event that corresponds to the action taken by the user. However, if the user doesn't perform an action on the selection, the application should not send an event.

IMPORTANT

If something is already selected when recording begins, your application should not record that selection. Subsequent user actions should be recorded assuming that there is a selection. By not recording the current selection, you allow the user to record scripts that work, without further modification, much like menu commands that operate on the current selection.

The example just discussed assumes that the application has multiple documents. In such an application, document 1 is always the document in the frontmost window. The examples that follow are simplified, as if they were generated by an application like TeachText that can have only one document open at a time and can therefore locate objects such as characters in the default container. For more complex applications that locate text in cells, documents, and other containers, you must specify additional containers as appropriate.