Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Important: The information in this document is obsolete and should not be used for new development.
Recording the Selection of Text Objects
When your application needs to record a selection that the user has made by dragging through a range of text, it should send itself a Select event that selects a range of characters. For example, a Select event with this direct parameter selects characters 80 through 764:
Keyword Descriptor type Data keyDirectObject typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cChar keyAEContainer typeNull No data 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 80 keyAERangeStop typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cChar keyAEContainer typeCurrentContainer No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 764 It is sufficient to record such a text selection as a range of characters. However, recording selections in other units can make the corresponding scripts easier to read. If you decide to record text selections in other units, keep these guidelines in mind:
The rest of this section provides examples of how to apply these guidelines.
- Use the largest whole unit that completely describes the selection.
- Do not mix units.
- Use units appropriate to the method of selection.
- Use logical units rather than units that vary with reformatting.
- Don't try to guess the user's intentions.
If you do record text selections in units other than characters, record each selection in terms of the largest whole unit that completely describes the selection. For example, suppose the user selects characters 115 through 170 by dragging. Further, suppose the selected characters are exactly the same as words 33 through 50 and also the same as paragraph 2. In this case your application should send itself a Select event with this direct parameter:
Keyword Descriptor type Data keyDirectObject typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cParagraph keyAEContainer typeNull No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 2 However, if the selected characters don't match a larger unit exactly--for example, if paragraph 2 is larger than the selection or the selection is a portion of two paragraphs-- use the largest unit available, in this case words.
For example, a Select event with this direct parameter selects word 33 through word 45:
Keyword Descriptor type Data keyDirectObject typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cText keyAEContainer typeNull No data keyAEKeyForm typeEnumerated formRange keyAEKeyData typeRangeDescriptor (see indented record) keyAERangeStart typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cWord keyAEContainer typeCurrentContainer No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 33 keyAERangeStop typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cWord keyAEContainer typeCurrentContainer No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 45 Do not mix units. You should not send Apple events that define selections like character 2 of word 3 of line 5 of paragraph 2 in document "MyDocument." Instead, define selections as simply as possible; for example, character 45 in the document "MyDocument."
When the user selects text by double-clicking it, your application should send a Select event that specifies words. For example, your application should send a Select event with this direct parameter when the user double-clicks word 5:
Keyword Descriptor type Data keyDirectObject typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cWord keyAEContainer typeNull No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 5 If the user double-clicks word 5 and then extends the selection through word 9, your application should send a Select event with this direct parameter:
Keyword Descriptor type Data keyDirectObject typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cText keyAEContainer typeNull No data keyAEKeyForm typeEnumerated formRange keyAEKeyData typeRangeDescriptor (see indented record) keyAERangeStart typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cWord keyAEContainer typeCurrentContainer No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 5 keyAERangeStop typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cWord keyAEContainer typeCurrentContainer No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 9 If your application supports selection of a paragraph, for example by clicking the left margin, triple-clicking, or some other action, your application should send a Select event that selects the paragraph. For example, a Select event with this direct parameter selects paragraph 2:
Keyword Descriptor type Data keyDirectObject typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cParagraph keyAEContainer typeNull No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 2 If your application supports the selection of other units (for instance, cells, rows, and columns in a spreadsheet; embedded graphics in a word processor; or buttons) and if users can select a range of such units, your application should record using those units when appropriate. For example, a Select event with this direct parameter selects row 5 through row 23:
Keyword Descriptor type Data keyDirectObject typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cRow keyAEContainer typeNull No data keyAEKeyForm typeEnumerated formRange keyAEKeyData typeRangeDescriptor (see indented record) keyAERangeStart typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cRow keyAEContainer typeCurrentContainer No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 5 keyAERangeStop typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cRow keyAEContainer typeCurrentContainer No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 23 A Select event with this direct parameter selects the second
'PICT'image:
Keyword Descriptor type Data keyDirectObject typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cPICT keyAEContainer typeNull No data keyAEKeyForm typeEnumerated formAbsolutePosition keyAEKeyData typeLongInteger 2
When the user chooses a Select All command, your application should send a Select event with this direct parameter to select the contents of the document:
Keyword Descriptor type Data keyDirectObject typeObjectSpecifier (see indented record) keyAEDesiredClass typeType cProperty keyAEContainer typeNull No data keyAEKeyForm typeEnumerated formPropertyID keyAEKeyData typeLongInteger pContents Units that vary with reformatting, such as lines and pages in a text document, are not as useful as logical units that describe the data more precisely. Whenever possible, use logical units such as character, word, paragraph, section, and so on.
Don't try to guess the user's intentions. For example, if a selection can be described as either "word 14" or as "the third bold word in paragraph 3," use the simpler description. If you guess the user's intentions, you will be wrong often enough to cause the user to distrust the recording process.