Typing interactors

1. Use the typing configuration mechanism to convert keystrokes to text. This should include support for using an input method. Typing configurations are described in Chapter 7, "Text input."
   
2. Propagate the typing styles to input text. Generally, these are the styles applied to the character preceding the insertion offset.
   
3. Use the font substitution mechanism to style missing glyphs in input text before inserting the text into the text component. This mechanism is described in "Font substitution" on page 75.
   

The class TTypingConfigurationHandle provides the ChooseConfiguration function you use to determine what typing configuration to use to process text input. ChooseConfiguration has two implementations--one chooses a configuration based on a TLanguageStyle and the other chooses a configuration based on the script to which a particular set of characters belongs.

To select a configuration based on a language style:

1. Get the typing styles for the insertion offset at which the text will be input. Your interactor should use the current selection to determine the typing styles.
   
2. Query the set of typing styles for a TLanguageStyle.
   
3. If the set contains a language style, call TTypingConfigurationHandle::ChooseConfiguration, passing a pointer to the language style.
   

Processing typing input

The Text Editing framework provides concrete implementations of this class that are used by the classes derived from TTypingInteractor:

TDocumentTypingInteractor uses a TDocumentTextTypingStore to process typing input, while TSimpleTypingInteractor uses a TSimpleTextTypingStore. Both classes use TTypingCommand to perform the actual modifications to the text representation underlying the text component.

The following is a simplified version of the process used by editable text components to handle input text:

1. The view creates a typing interactor when it is activated; the interactor creates and maintains a typing store.
   
2. When the view receives the initial key-down event, it starts the TTypingInteractor or TDocumentTypingInteractor. The typing interactor controls the interaction from this point. When the interactor receives the first key event, it does the following:
   
   1. Ensures an appropriate typing configuration is active.
      
   2. Maps the key event to text, using the virtual keyboard in the current typing configuration.
      
   3. Invokes the typing configuration, which handles the next phase of the typing interaction.
      
3. The typing configuration accesses the typing store to insert newly input text, performing the following:
   
   1. Retrieves the text from the typing store, locking the text store first.
      
   2. Calls typing store functions to process the typing input.
      
4. The typing store object actually creates and issues the typing command. From here, the interactor handles typing input incrementally until the interactor is stopped--for example, if a selection interactor is created or the view is deactivated. The incremental typing process is roughly as follows:
   
   1. The interactor receives a key-down event and maps the key event to text using the typing configuration's virtual keyboard.
      
   2. The interactor invokes the typing configuration to process subsequent typing. The typing configuration handles the interaction with the typing store and activates any text modifiers or input methods.
      
   3. When the typing configuration has produced text that is ready to be inserted into the text representation object, it calls typing store functions that ensure that the typing command is executed. The typing command is an incremental command, inserting one or more characters into the text representation object on each iteration.
      

Supporting input methods

The abstract protocol for supporting an input method within a text editor is provided by the Input Method framework class TInputMethodTextPresentation. A text editor must provide an implementation of this class and pass it to the input method via the typing configuration handle.

This section describes the Text Editing framework implementation of TInputMethodTextPresentation and related classes. For a more general description of TInputMethodTextPresentation, see "Input Method framework" on page 186.

The input method presentation provides visual feedback to the end user while typing occurs by applying styles to the input text. These styles are superposed on the text; they are not really part of the text being editing. These styles can be managed by applying the styles directly to the text and then removing them before the typing interaction is completed, or by using a filter that specifies the styles to apply to the text and maintains the styles independently from the text object itself. The Text Editing framework provides classes that filter the text, as shown in this figure:

TTextInputMethodTextPresentation implements the abstract protocol in TInputMethodTextPresentation, using the text component's typing interactor to handle typing input and using the component's view to access text selections and manage the styles on text input with an input method.

TTextView uses these classes to manage text while it is being processed by an input method:

• TFilteredText wraps the text instance underlying a text representation and encapsulates the styles to be applied to the interim text being entered with an input method. These styles must be of a kind that is independent of the underlying characters--for example, paragraph styles cannot be applied. TFilteredText also specifies the range of text to which the filter applies. This range is automatically extended or collapsed as the text is edited.

Functions that access the text delegate to the underlying text instance, and then return a text instance with the filter styles attached as if they were really applied to the text.

• TFilteredTextRepresentation wraps the text representation instance for the component and uses TFilteredText to apply the filter styles to the encapsulated text. TFilteredTextRepresentation allows write operations on the text, delegating these calls to the encapsulated MTextRepresentation. The filter is not adjusted automatically when the character data in a TFilteredTextRepresentation is edited; this must be done separately.

See "Input Method framework" on page 186 for more information on TInputMethodTextPresentation and on input methods in general.