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 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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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.

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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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:
KeywordDescriptor typeData
keyDirectObjecttypeObjectSpecifier(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.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996