Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 9 - Recording Apple Events / What to Record

Recording Insertion Points

The insertion point and a selection are synonymous in the Macintosh Operating System. However, scripting languages need a way of specifying a zero-width selection. Sometimes the best way to specify an insertion location is in relation to another object; for example, "after word 5." This section describes recommended methods of specifying an insertion point in a recordable event.

The insertion point can be specified in Apple events by either an insertion location descriptor record (typeInsertionLocation) or an object specifier record (typeObjectSpecifier) that specifies the class cInsertionLoc and the key form formRelativePosition. The Move, Clone, and Create events accept an insertion location descriptor record; other events, including Select and Set Data, require an object specifier record.

Five constants can be used to describe an insertion point in relation to an object or container:

Constant	Corresponding insertion point
kAEReplace	The specified object will be replaced if not qualified by one of the other phrases
kAEBefore	Just before the specified object (either type typeObjectSpecifier or type typeInsertionLocation)
kAEAfter	Just after the specified object (either type typeObjectSpecifier or type typeInsertionLocation)
kAEBeginning	In the specified container and before all other elements of the same class in that container (type typeInsertionLocation only)
kAEEnd	In the specified container and after all other elements of the same class in that container

For more information about the way AppleScript uses insertion location descriptor records, see "Defining Terminology for Use by the AppleScript Component," which begins on page 8-3, and the Apple Event Registry: Standard Suites. The rest of this section provides examples of object specifier records used to specify insertion points.

Users usually insert objects after some other object. So, unless the insertion point is clearly at the beginning or end of a container or identifies an object to be replaced, use the constant kAEAfter to record the location.

For example, if the user places the insertion point after character 2, your application should send 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	typeNull	No data
keyAEKeyForm	typeEnumerated	formAbsolutePosition
keyAEKeyData	typeLongInteger	2
keyAEKeyForm	typeEnumerated	formRelativePosition
keyAEKeyData	typeEnumerated	kAEAfter

If the selection is not 0 characters wide, the user is replacing the selection with another object, so you can specify the location simply as the object specifier record for the object to be replaced.

If the user clicks the white space after a paragraph somewhere in the middle of the document, defining the insertion point becomes more complex because different applications deal with this situation in different ways. Some place the insertion point at the end of the current paragraph, while others place the insertion point at the beginning of the next paragraph. Depending on the way your application handles this situation, you should use an object specifier record that specifies either kAEBeginning or kAEEnd.

Remember that the Select event requires an object specifier record. Thus, if you want to place the insertion point at the beginning of a paragraph, use an object specifier record that specifies a location just before the first item of the paragraph, rather than an insertion location descriptor record.

For example, a Select event with this direct parameter places the insertion point just before the first item of paragraph 3:

Keyword	Descriptor type	Data
keyDirectObject	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cInsertionLoc
keyAEContainer	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cItem
keyAEContainer	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cParagraph
keyAEContainer	typeNull	No data
keyAEKeyForm	typeEnumerated	formAbsolutePosition
keyAEKeyData	typeLongInteger	3
keyAEKeyForm	typeType	formAbsolutePosition
keyAEKeyData	typeLongInteger	1
keyAEKeyForm	typeEnumerated	formRelativePosition
keyAEKeyData	typeEnumerated	kAEPrevious

If the user clicks the left edge of the first line in a paragraph, thus setting the insertion point before the beginning of the paragraph, you should use a similar strategy. However, this is the only situation in which you should use kAEPrevious.

When the insertion point is at the end of a document record, use an object specifier record that specifies the location after the last item in the document.

For example, a Select event with this direct parameter places the insertion point just after the last item in a document:

Keyword	Descriptor type	Data
keyDirectObject	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cInsertionLoc
keyAEContainer	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cItem
keyAEContainer	typeNull	No data
keyAEKeyForm	typeEnumerated	formAbsolutePosition
keyAEKeyData	typeLongInteger	-1
keyAEKeyForm	typeEnumerated	formRelativePosition
keyAEKeyData	typeEnumerated	kAENext

A Select event with this direct parameter places the insertion point just after the last item in paragraph 3:

Keyword	Descriptor type	Data
keyDirectObject	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cInsertionLoc
keyAEContainer	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cParagraph
keyAEContainer	typeNull	No data
keyAEKeyForm	typeEnumerated	formAbsolutePosition
keyAEKeyData	typeLongInteger	3
keyAEKeyForm	typeEnumerated	formRelativePosition
keyAEKeyData	typeEnumerated	kAENext