Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

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:
ConstantCorresponding insertion point
kAEReplaceThe specified object will be replaced if not qualified by one of the other phrases
kAEBeforeJust before the specified object (either type typeObjectSpecifier or type typeInsertionLocation)
kAEAfterJust after the specified object (either type typeObjectSpecifier or type typeInsertionLocation)
kAEBeginningIn the specified container and before all other elements of the same class in that container (type typeInsertionLocation only)
kAEEndIn 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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996