Legacy Document

Inside Macintosh: Text /

Chapter 2 - TextEdit / TextEdit Reference

Routines / Additional TextEdit Features

TEFeatureFlag

The TEFeatureFlag function turns a specified feature on or off or returns the current status of that feature. Features supported are automatic scrolling, text buffering, outline highlighting, inline input, and text services.

FUNCTION TEFeatureFlag (feature: Integer; action: Integer;
                        hTE: TEHandle): Integer;

feature

The feature for which the action is to be performed.

action

A selector stipulating that the feature, specified by the feature parameter, is to be turned on or off, or that the current status of the feature is to be returned.

hTE

A handle to the edit record for which the action should be performed.

DESCRIPTION

You can use the TEFeatureFlag function to check the status of additional TextEdit features--automatic scrolling, outline highlighting, and text buffering--and to enable or disable the feature. You can also use this function to disable inline input in a particular edit record and to enable several features that have been provided so that inline input works correctly with TextEdit.

To identify a feature, you specify one of the following constants as the value of the feature parameter.

Constant	Value	Description
teFAutoScroll	0	Automatic scrolling
teFTextBuffering	1	Text buffering
teFOutlineHilite	2	Outline highlighting
teFInlineInput	3	Inline input
teFUseTextServices	4	Use inline input service

You specify the action to be performed on a feature through the following constants.

Constant	Value	Description
teBitClear	0	Disables the specified feature
teBitSet	1	Enables the specified feature
teBitTest	-1	Returns the current setting of the specified feature

If teBitTest returns teBitSet, the feature is enabled; if it returns teBitClear, it is disabled.

You can use the TEFeatureFlag function to turn automatic scrolling on and off as an alternative to calling TEAutoView. The effect is the same.

The teFOutlineHilite selector specifies outline highlighting as the feature for which an action is to be performed. If a highlighted region exists in an edit record and the window is inactive, then the highlighted region is outlined or framed.

In the case that outline highlighting is enabled and the current selection range is an insertion point, the caret is then drawn in a gray pattern so that it appears dimmed. To do the framing and caret dimming, TextEdit temporarily replaces the current address in the highHook and caretHook fields of the edit record, redraws the caret or the highlighted region, and then immediately restores the hooks to their previous addresses.

The teFTextBuffering selector enables or disables text buffering for performance improvements of 2-byte scripts. This is a global buffer, as opposed to the TEKey procedure's internal 2-byte buffer, and it is used across all active edit records. When using text buffering, take the following precautions:

• Exercise care when you enable the text-buffering capability in more than one active record; otherwise, the bytes that are buffered from one edit record may appear in another edit record.
• Ensure that buffering is not turned off in the middle of processing a 2-byte character. To guarantee the integrity of your record, it is important that you wait for an idle event before you disable buffering or enable buffering in a second edit record.
• When text buffering is enabled, ensure that TEIdle is called before any pause of more than a few ticks--for example, before the Event Manager procedure WaitNextEvent. A possibility of a long delay before characters appear on the screen exists, especially in non-Roman systems. If you do not call TEIdle, the characters can end up in the edit record of another application. For more information, see "TEIdle" on page 2-79.

If text buffering is enabled on a non-Roman script system and the keyboard has changed, TextEdit flushes the text of the current script from the buffer before bringing characters of the new script into the buffer.

If your application follows the guidelines for inline input available from Macintosh Developer Technical Support, then you should set the useTextEditServices flag in the Size resource in your application. This allows inline input to work with your application. Inline input is a keyboard input method (often used for double-byte script systems) in which conversion from a phonetic to an ideographic representation of a character takes place at the current line position where the text is intended to appear. This allows the user to type text directly in the line as opposed to a special conversion window. If inline input is installed and the useTextEditServices flag in the Size resource is set, inline input sets TextEdit's teFUseTextServices feature bit whenever an edit record is created. TextEdit does not use this bit.

Inline input checks the teFUseTextServices bit during text editing to determine if an inline session should begin. If you want to disable inline input for a particular edit record, your application can clear this bit after the edit record is created. You can also clear this bit to disable inline input temporarily and then restore it, but the edit record must always be deactivated before the state of the bit is changed.

IMPORTANT

You must deactivate an edit record (using TEDeactivate) before changing the state of the feature bits or any fields in the edit record.

In the future, other text services may use this same mechanism. If you follow the guidelines specified here, your application should also work with future text services. When an inline edit session begins, inline input also sets the teFInlineInput bit to provide the following features so that inline input works correctly with TextEdit:

• disabling font and keyboard synchronization
• forcing a multiple-line selection to be highlighted line by line using a separate rectangle for each line rather than using a minimum number of rectangles for optimization
• highlighting a line only to the edge of the text rather than beyond the text to the edge of the view rectangle

IMPORTANT

The teFInlineInput bit is cleared by inline input when an inline session ends. Use the teFInlineInput constant in the feature parameter of TEFeatureFlag to include these features in your application even when inline input is not installed. Be careful about changing the state of this bit if the teFUseTextServices bit is set. Again, the edit record should always be deactivated before you change the state of the teFInlineInput bit. If you clear the teFUseTextServices bit and you set the teFInlineInput bit, inline input is disabled, but your application retains the features listed above.

To test for the availability of these features, you can call the Gestalt function with the gestaltTextEditVersion selector. A result of gestaltTE4 or greater returned in the response parameter indicates that outline highlighting and text buffering are available. A result of gestaltTE5 or greater returned in the response parameter indicates that the two inline input features are available.

The inline input features are also available on version 6.0.7 systems with non-Roman script systems installed. However, there is no Gestalt constant that indicates this availability.

SEE ALSO

For a description of the WaitNextEvent function, see the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials.