Important: The information in this document is obsolete and should not be used for new development.
Recording User Actions
Two general guidelines apply to the recording of all user 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.
- Send Apple events that correspond to simple statements in a script rather than compound statements.
- Don't record superfluous actions.
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:
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.
- Select the text
- Cut
- Set the insertion point
- Paste
- A Select event (event class
kAEMiscStandards
, event IDkAESelect
) 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 IDkAECut
)- 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
The first Select event in this example sets the application's
- 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 typeAEDesc
with a descriptor type oftypeNull
and a data handle whose value is 0.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.
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.
- 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.