Important: The information in this document is obsolete and should not be used for new development.
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 classcInsertionLoc
and the key formformRelativePosition
. 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 typetypeInsertionLocation
)kAEAfter Just after the specified object (either type typeObjectSpecifier
or typetypeInsertionLocation
)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
orkAEEnd
.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