Legacy Document

Inside Macintosh: Text /

Chapter 7 - Text Services Manager / Text Services Manager Reference

Apple Event Handlers Supplied by Client Applications

Creating and Updating an Active Input Area

The text service component uses the Update Active Input Area Apple event to request that your client application create and update an active input area, and accept confirmed text. For details on active input areas, see "Inline Input" on page 7-11.

Update Active Input Area--Creating and Updating an Active Input Area (Continued)
Event class	kTextServiceClass
Event ID	kUpdateActiveInputArea
Requested action	Update a range of text. Specify any necessary highlighting with offsets in the optional keyAEHiliteRange parameter.
Required parameters
Keyword:	keyAETSMDocumentRefcon
Descriptor type:	typeLongInteger
Data:	A TSM document specifier (reference constant) supplied by the application in a prior call to the NewTSMDocument function (see page 7-50). This value is associated with the TSM document whose active input area is to be updated.
Keyword:	keyAEServerInstance
Descriptor type:	typeComponentInstance
Data:	A component instance value created by a prior call to the Component Manager OpenComponent function. This value identifies the text service component.
Keyword:	keyAETheData
Descriptor type:	typeChar
Data:	Text data that has been processed in some way by a text service component.
Keyword:	keyAEScriptTag
Descriptor type:	typeIntlWritingCode
Data:	The script code and language code associated with the text returned in the keyAETheData parameter. The information is passed in a script-language record, as defined on page 7-42.
Required parameters
Keyword:	keyAEFixLength
Descriptor type:	typeLongInteger
Data:	The length of the confirmed text in the active inline area. If the value of keyAEFixLength is -1, the text contained in the keyAETheData parameter is to completely replace the current selection in the application window. In this case, there is to be no active input area, the text is all considered to be confirmed, and is to be made part of the body text of the client application. If the value is 0, an active input area is in process, but there is no completely confirmed text being sent. If the value is greater than 0, the text specified in the keyAETheData parameter up to the indicated offset is confirmed data and should be consumed by the application. The Text Services Manager considers any text beyond the offset specified by the keyAEFixLength parameter to be inside the active input area with the starting point of the active input area at that offset. This is illustrated in Figure 7-11.

Figure 7-11 Updating text in an active input area

Update Active Input Area--Creating and Updating an Active Input Area (continued) (Continued)
Optional parameters
Keyword:	keyAEHiliteRange
Descriptor type:	typeTextRangeArray
Data:	An array that specifies the ranges of text to be highlighted in the active input area. It also specifies caret position. There are 5 types of highlighting:
	Constant	Applies to
	kCaretPosition	The caret position only
	kRawText	All of the unconverted text
	kSelectedRawText	Part of the unconverted text
	kConvertedText	All of the converted text
	kSelectedConvertedText	Part of the converted text
	For instance, the input method may have the application highlight all raw text with a gray underline; but if it needs to further highlight a selection within that raw text, it may specify a different underline for the selected raw text. The text range array is an array of text-range records, each of which has this form: TYPE TextRange = RECORD fStart: LongInt; fEnd: LongInt; fHiliteStyle: Integer; END; For the text-range record whose highlight style is kCaretPosition, both fStart and fEnd are the same and denote the position of the caret. Negative values for a text range mean that the specified range only adds to, rather than replaces, any current highlighting for the specified type of text.
Optional parameters
Keyword:	keyAEUpdateRange
Descriptor type:	typeTextRangeArray
Data:	An array of text-range records that indicates the update range of the active input area (in many circumstances, not all of the active input area needs updating). Update Active Input Area always uses the text-range records in the text range array in pairs. The first record (0) specifies a range of old text (text in the inline buffer) to be updated; the second record (1) specifies the range of text in keyAETheData that is to replace that old text. In general, the record n (n >= 0, n is an even number) specifies the range of old text to be updated and the record n + 1 specifies the range of new text to replace the corresponding old text. (The fHiliteStyle field is ignored.)
Keyword:	keyAEPinRange
Descriptor type:	typeTextRange
Data:	A text range record that specifies a start offset and and an end offset that should be scrolled into view if the text specified by these offsets is not already in view. (The fHiliteStyle field is ignored.)
Keyword:	keyAEClauseOffsets
Descriptor type:	typeOffsetArray
Data:	An offset array (defined by the OffsetArray data type) that specifies offsets of word or clause boundaries of the new text. Offsets are from the start of the active input area. Applications can use this information for word selection or other purposes. TYPE OffsetArray = RECORD fNumOfOffsets: Integer; fOffset: ARRAY[0..0] of LongInt; END; The numOfOffsets field contains an integer that specifies the number of offsets in the offset array. The fOffset field is an array of long integers with the number of entries specified in the numOfOffsets field.
Return parameter
Keyword:	keyErrorNumber
Descriptor type:	typeShortInteger
Data:	Any errors that the application needs to return to the text service component. The application must pass Memory Manager, TextEdit, or other errors that it receives through to the component; otherwise, it should pass 0 (noErr).

The text range array data structure used in the keyAEHiliteRange
and keyAEUpadateRange parameters described above is defined by the TextRangeArray data type:

TYPE TextRangeArray = 
   RECORD
      fNumOfRanges:  Integer;
      fRange:        ARRAY[0..0] of TextRange;
   END;

The fNumOfRanges field contains an integer that indicates how many text ranges this array holds. The fRange field contains a series of text-range records. (If the array consists of more than one text-range record, the size of the array must be calculated as fNumOfRanges * SizeOf(fRange).)

For sample code that handles the Update Active Input Area Apple event, see Listing 7-7 on page 7-26.