Class: TTypingInteractor

Declaration: TextInteractorsCore.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TInteractor, MKeyEventHandler

Inherited By:

TSimpleTypingInteractor TDocumentTypingInteractor

Purpose:

TTypingInteractor, derived from TInteractor and MKeyEventHandler, is used by the Text Editing Framework to handle typing input from the keyboard. It contains a TTypingConfigurationHandle for access to typing configurations. It also contains other data to access information about the current context, for example, pointers to the view and to the typing queue it uses.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

The Text Editing Framework classes derived from TTypingInteractor are TDocumentTypingInteractor and TSimpleTypingInteractor. The former is for model-based text, whereas the latter is not model-based. A derived typing interactor class must be paired with a derived text view class. You must override HandleCreateTypingInteractor in your derived text view class to return your derived typing interactor. TTypingInteractor is not intended to be directly derived. See the documentation of TSimpleTypingInteractor and TDocumentTypingInteractor for more information on how to specialize the typing interaction with simple text views and document text views respectively.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TTypingInteractor::TTypingInteractor

TTypingInteractor (TTextView * view)
TTypingInteractor ()
TTypingInteractor (const TTypingInteractor &)

Interface Category:

API.

Purpose:

Constructs an interactor to process typing events for the specified view.
Default constructor. This constructor is protected.
Copy constructor. This constructor is protected.

Calling Context:

Called to construct an interactor for a particular view.
Called by the stream-in operators.
Called to copy an object.

Parameters:

TTextView * view -The view to construct this interactor for.
Takes no parameters.
const TTypingInteractor & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::~TTypingInteractor

virtual ~ TTypingInteractor ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Typically not called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::KeyDown

virtual bool KeyDown (TKeyDownEvent &)

Interface Category:

API.

Purpose:

An overridden MKeyEventHandler function. If this is the first key event of the interactor, this function chooses the typing configuration. For each key event it then calls MapKey to convert the key event into text data and passes the text to the ProcessText function.

Calling Context:

Typically not called directly by clients. Called by the input system.

Parameters:

TKeyDownEvent & -The key event to process.

Return Value:

Returns true if the key event is handled and processed correctly.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited MKeyEventHandler function.

Member Function: TTypingInteractor::ProcessText

virtual void ProcessText (const TText & text, TTextCount numberOfDeletes)

Interface Category:

API.

Purpose:

Distributes text to the appropriate functions, after it has been converted from a key stroke, based on the current phase of this interactor. This function calls other functions of this interactor (TypeBegin, TypeIncrement, and BufferText). Typically not called directly by clients. Called directly from the typing task of the framework.

Parameters:

const TText & text -The text representing the key event.
TTextCount numberOfDeletes -The number of backspaces represented by the key event, if the key event was a backspace.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::TypeBegin

virtual void TypeBegin (const TText & text, TTextCount numberOfDeletes)

Interface Category:

API.

Purpose:

Processes the first keystroke of this interactor. If the first range of the current selection is smaller than numberOfDeletes, it resets the phase to the increment phase, and returns. Otherwise, it calls InvokeTypingConfiguration.

Calling Context:

Called by the ProcessText function when typing input begins.

Parameters:

const TText & text -The text representing the key event.
TTextCount numberOfDeletes -The number of backspaces represented by the key event, if the key event was a backspace.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::TypeIncrement

virtual void TypeIncrement (const TText & text, TTextCount numberOfDeletes)

Interface Category:

API.

Purpose:

Processes the incremental keystrokes of this interactor. Calls InvokeTypingConfiguration. Called by the ProcessText function, if there is no typing buffer, to incrementally process the text of converted key events. If there is a typing buffer, BufferText will be called instead.

Calling Context:

Typically not called directly by clients.

Parameters:

const TText & text -The text representing the key event.
TTextCount numberOfDeletes -The number of backspaces represented by the key event, if the key event was a backspace.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::TypeEnd

virtual void TypeEnd ()

Interface Category:

API.

Purpose:

Processes the final keystrokes, if there are any, and stops the interactor. If buffering is enabled, it calls FlushBuffer. Otherwise, if the current phase is the increment phase, it calls the TypeEnd function of the typing configuration. Finally, it re-initializes the interactor. Called when typing input ends.

Calling Context:

Typically not called directly by clients. Called by various places in the view. For example, when the view receives a mouse down, it stops the typing interactor and starts a mouse interactor.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::BufferText

virtual void BufferText (const TText & textToInsert, TTextCount backspaces)

Interface Category:

API.

Purpose:

Buffers key event text and delete counts. Used to support type-ahead, and to improve performance. Called by the ProcessText function to incrementally buffer the text of converted key events.

Calling Context:

Typically not called directly by clients.

Parameters:

const TText & textToInsert -The text representing the key event.
TTextCount backspaces -The number of backspaces represented by the key event, if the key event was a backspace.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::FlushBuffer

virtual void FlushBuffer ()

Interface Category:

API.

Purpose:

Processes and flushes the buffer items; calls TypeIncrement for each text item saved in the buffer. Called by TypeEnd when typing input ends.

Calling Context:

Typically not called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::GetTypingConfiguration

virtual void GetTypingConfiguration (TTypingConfigurationHandle & typingConfig)

Interface Category:

API.

Purpose:

Returns the handle of the typing configuration this interactor uses to process text.

Calling Context:

Called to access the typing configuration used by this interactor. Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

TTypingConfigurationHandle & typingConfig -Receives the handle of the typing configuration this interactor uses.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTypingInteractor::MapKeyEvent

virtual bool MapKeyEvent (TKeyDownEvent & event, TText & newText, TTextCount & numberOfDeletes)

Interface Category:

API.

Purpose:

Calls MapKey to set newText and numberOfDeletes, based on the event's virtual key code and modifier keys. MapKey first checks if the virtual key event was a backward delete. If so, sets numberOfDeletes to 1. If not, sets numberOfDeletes to 0, and then maps the key event to a text object, and adds a language style to the text object if we're in the beginning phase of the typing interactor.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

TKeyDownEvent & event -The key event to process.
TText & newText -Receives the text representing the key event.
TTextCount & numberOfDeletes -The number of backspaces represented by the key event. This is set to 1 if the key event mapped to the backward delete virtual key code, otherwise it is set to 0.

Return Value:

Returns true if the key event was mapped successfully.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTypingInteractor::InvokeTypingConfiguration

virtual void InvokeTypingConfiguration (const TText & newText, TTextCount numberOfDeletes)

Interface Category:

API.

Purpose:

Invokes the typing configuration's TypeText function to delete numberOfDeletes characters and insert the new text.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

const TText & newText -The text to insert.
TTextCount numberOfDeletes -The number of deletes to do.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTypingInteractor::ChooseTypingConfiguration

virtual void ChooseTypingConfiguration ()

Interface Category:

API.

Purpose:

Sets the typing configuration to be used by this interactor to process text, based on the language style.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTypingInteractor::GetTextView

const TTextView * GetTextView () const
TTextView * GetTextView ()

Interface Category:

API.

Purpose:

Accessor function for getting a pointer to the text view associated with this interactor.
Accessor function for getting a pointer to the text view associated with this interactor.

Calling Context:

May be called directly by clients. May be called from other classes.
May be called directly by clients. May be called from other classes.

Parameters:

Takes no parameters.
Takes no parameters.

Return Value:

A pointer to the text view associated with this interactor.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTypingInteractor::SetCurrentPhase

void SetCurrentPhase (TTypingInteractor :: EPhase phase)

Interface Category:

API.

Purpose:

Sets the interactor's phase of typing.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

TTypingInteractor :: EPhase phase -The new phase.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTypingInteractor::DetachTypingCallbacks

void DetachTypingCallbacks ()

Interface Category:

API.

Purpose:

Remove typing configuration knowledge about text store and presentation.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::AttachTypingCallbacks

void AttachTypingCallbacks (TTypingStore *, TInputMethodTextPresentation *)

Interface Category:

API.

Purpose:

Establish typing configuration knowledge about text store and presentation.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

TTypingStore * -Pointer to typing store object to alias.
TInputMethodTextPresentation * -Pointer to input method presentation to alias.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::MapKey

virtual bool MapKey (TVirtualKeyCode :: EVirtualKey key, const TModifierKeys & modifiers, TText & newText, TTextCount & numberOfDeletes)

Interface Category:

API.

Purpose:

First checks if the virtual key was a backward delete. If so, sets numberOfDeletes to 1. If not, sets numberOfDeletes to 0, and then maps the key to a text object, and adds a language style to the text object if we're in the beginning phase of the typing interactor.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

TVirtualKeyCode :: EVirtualKey key -The virtual key code.
const TModifierKeys & modifiers -The modifier keys.
TText & newText -Receives the text representing the key event.
TTextCount & numberOfDeletes -The number of backspaces represented by the key event. This is set to 1 if the key event mapped to the backward delete virtual key code, otherwise it is set to 0.

Return Value:

Returns true if the key was mapped successfully.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingInteractor::GetCurrentPhase

TTypingInteractor :: EPhase GetCurrentPhase () const

Interface Category:

API.

Purpose:

Gets the interactor's phase of typing.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

Takes no parameters.

Return Value:

The new phase.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Click the icon to mail questions or corrections about this material to Taligent personnel.