Class: TTypingConfigurationHandle

Declaration: TypingConfiguration.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TTypingConfiguration

Inherited By:

None.

Purpose:

Concrete handle class that permits lightweight access to real typing configurations (TEditableTypingConfiguration or derived classes).

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Not typically derived. If so, must guarantee that the handle always references a valid TEditableTypingConfiguration or derived class.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TTypingConfigurationHandle::TTypingConfigurationHandle

TTypingConfigurationHandle ()
TTypingConfigurationHandle (const TLocalizableName & name)

Interface Category:

API.

Purpose:

Default constructor. Constructs a handle that can be used with the current system configuration.
Constructs a handle that will reference the configuration specified by name.

Calling Context:

Called by the stream-in operators and directly by clients.
Called directly by clients.

Parameters:

Takes no parameters.
const TLocalizableName & name -The name of the actual typing configuration.

Return Value:

None.

Exceptions:

Throws TTypingConfiguration::kConfigurationUnavailable if a configuration cannot be found.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::MapKeyEventToText

virtual void MapKeyEventToText (TKeyEvent & event, TText & text) const

Interface Category:

API.

Purpose:

Generates the text result from a key event that is appropriate to the current typing configuration.

Calling Context:

Can be called directly by clients. Also called internally by the typing interaction state.

Parameters:

TKeyEvent & event -A key event.
TText & text -The resulting text for the key event.

Return Value:

Returned in the text parameter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::GetTypingConfiguration

virtual const TEditableTypingConfiguration * GetTypingConfiguration () const

Interface Category:

API.

Purpose:

Returns a pointer to the actual typing configuration currently referenced by this handle.

Calling Context:

Called internally by the typing interaction state. Can also be called by clients who need to used the actual configuration directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to the configuration referenced by this handle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::SetLocalizableName

virtual void SetLocalizableName (const TLocalizableName & name)

Interface Category:

API.

Purpose:

Sets the localizable name of the handle and changes the configuration referenced by this handle.

Calling Context:

Called directly by clients.

Parameters:

const TLocalizableName & name -The name of the new configuration.

Return Value:

None.

Exceptions:

Throws TTypingConfiguration::kConfigurationUnavailable if a configuration for name is not available.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::GetKeyboard

virtual void GetKeyboard(TVirtualKeyboardHandle& keyboard) const

Interface Category:

API.

Purpose:

Returns a handle to the keyboard for the configuration currently referenced by this handle.

Calling Context:

Called directly by clients who need the keyboard.

Parameters:

const TVirtualKeyboardHandle & name -Filled in with the keyboard for this configuration.

Return Value:

In parameter keyboard.

Exceptions:

Throws TTypingConfiguration::kConfigurationUnavailable if a configuration is not available.

Concurrency:

Not multithread safe.

Other Considerations:

To get the current keyboard, call GetSystemTypingConfiguration and then call GetKeyboard on the configuration that is returned. .

Member Function: TTypingConfigurationHandle::GetSystemTypingConfiguration

static void GetSystemTypingConfiguration (TTypingConfigurationHandle & configuration)

Interface Category:

API.

Purpose:

Returns the global typing configuration for the system.

Calling Context:

Called directly by clients.

Parameters:

TTypingConfigurationHandle & configuration -Returns the current configuration for the system.

Return Value:

Returned in the handle parameter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::SetSystemTypingConfiguration

static void SetSystemTypingConfiguration (TTypingConfigurationHandle & configuration)

Interface Category:

API.

Purpose:

Sets the global configuration for the system.

Calling Context:

Called directly by clients.

Parameters:

TTypingConfigurationHandle & configuration -The configuration to be set.

Return Value:

None.

Exceptions:

Throws TTypingConfiguration::kConfigurationUnavailable if a configuration is not available.

Concurrency:

Not multithread safe.

Other Considerations:

Has global side effects.

Member Function: TTypingConfigurationHandle::operator=

TTypingConfigurationHandle & operator =(const TTypingConfigurationHandle & copy)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TTypingConfigurationHandle & copy -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::operator<<=

virtual TStream & operator <<= (TStream & fromStream)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::operator>>=

virtual TStream & operator >>=(TStream & toStream) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::HasTextModifiers

virtual bool HasTextModifiers () const

Interface Category:

API.

Purpose:

Indicates whether or not there are text modifiers associated with the configuration referred to by this handle.

Calling Context:

Typically called by the typing interactor as an optimization to avoid a call to TypeText if there are no modifiers present.

Parameters:

Takes no parameters.

Return Value:

Returns true if the configuration has one or more text modifiers.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::GetInputMethod

virtual TTextInputMethod * GetInputMethod () const

Interface Category:

API.

Purpose:

Returns a pointer to the text input member function associated with the typing configuration currently referenced by this handle.

Calling Context:

Called directly by clients and within the typing configuration to get access to the configuration's input member function.

Parameters:

Takes no parameters.

Return Value:

A pointer to the text input member function associated with the typing configuration currently referenced by this handle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::ChooseConfiguration

virtual bool ChooseConfiguration (const TLanguageStyle & language)
virtual bool ChooseConfiguration (const TText & text, const TTextRange & range)

Interface Category:

API.

Purpose:

Allows the handle to pick an appropriate configuration based on language.
Allows the handle to pick an appropriate configuration based on the Unicode values of the text.

Calling Context:

Called by the typing interaction state when typing is about to begin. Can be called directly by other clients who want to pick a configuration appropriate to the language.
Called by the typing interaction state when typing is about to begin and language information is not available.

Parameters:

const TLanguageStyle & language -The language for which a configuration is sought.
const TText & text -Text for which a matching configuration is sought.
const TTextRange & range -The range of text to be used.

Return Value:

Returns true if the configuration has changed. Clients can then call GetLocalizableName to identify the new configuration.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Several configurations can share a common language. The choice of configuration for a specific language will be managed by preferences.

Member Function: TTypingConfigurationHandle::Modify

virtual bool Modify (const TText & currentText, const TTextRange & newRange, const TText & newText, TText & replacementText, TTextRange & replacementRange)

Interface Category:

API.

Purpose:

Given the current text, the new text to be added to the current text, and the newRange indicating where the new text is to be added, this function generates the replacement text by invoking each modifier in the typing configuration's chain of modifiers. The modified text is returned in the replacementText parameter. This function also generates the replacement range, which indicates the range of text in currentText that is to be replaced by the modified text. This function is intended for non-interactive processing of text, and does not require that a typing store be attached to the configuration.

Calling Context:

Called by TypeText to invoke the text modifiers on text to be added. Can be used directly on a TText derived class.

Parameters:

const TText & currentText -The current text.
const TTextRange & newRange -The range indicating where new text is to be added, including any backspaces. Note: newRange.GetCount is defined to be the number of deletions, and newRange.GetEnd is defined to be the insertion point relative to currentText.
const TText & newText -The new text to be added to currentText.
TText & replacementText -The modified text, after invoking the modifiers on the new text.
TTextRange & replacementRange -The range of text in currentText that is to be replaced.

Return Value:

Returns true if the configuration actually generated a modified replacementText.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::TypeEnd

virtual void TypeEnd ()

Interface Category:

API.

Purpose:

Calls TypeEnd on the typing configuration's attached typing store so that the input member function can complete processing of the typing transaction.

Calling Context:

Call at the end of the typing transaction to allow the input member function to complete processing.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::TypeText

virtual void TypeText (const TTextRange & newRange, const TText & newText)

Interface Category:

API.

Purpose:

Replaces the specified range in the typing store with the newText after it is processed by the typing configuration. First calls Modify to produce a modified text result. This result and a replacementRange (also produced by Modify) are then passed to the input member function by a call to TypeText on the typing configuration's attached typing store.

Calling Context:

Called for interactive typing.

Parameters:

const TTextRange & newRange -The range indicating where the new text is to be added.
const TText & newText -The new text to be added.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through, except if it catches TTypingStoreChangedException, it calls TypeEnd before passing the exception through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::Detach

virtual void Detach ()

Interface Category:

API.

Purpose:

Detaches from the typing store and input member function presentation that were associated with the typing configuration by a call to Attach.

Calling Context:

Should be called by the text editor at the end of a typing session (for example, inside the typing interactor destructor).

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::Attach

virtual void Attach (TTypingStore * theStore, TInputMethodTextPresentation * presentation)

Interface Category:

API.

Purpose:

Associates the specified typing store and input member function presentation with the typing configuration so that the configuration can get at the typing callbacks.

Calling Context:

Should be called by the text editor at the beginning of a typing session (for example., inside the constructor for the typing interactor). The client still owns the storage.

Parameters:

TTypingStore * theStore -The typing store.
TInputMethodTextPresentation * presentation -The input member function presentation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::GetAvailableConfigurations

static void GetAvailableConfigurations (TCollectionOf < TTypingConfigurationHandle > & list)

Interface Category:

API.

Purpose:

Returns a list of TTypingConfigrationHandles for all the configurations in the system.

Calling Context:

Typically called by a menu manager or other clients who want to display the list of available configurations.

Parameters:

TCollectionOf < TTypingConfigurationHandle > & list -The list of TTypingConfigrationHandles for all the configurations in the system.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::GetLanguage

virtual TLanguageStyle GetLanguage () const

Interface Category:

API.

Purpose:

Returns the language style for the typing configuration associated with this handle.

Calling Context:

Called directly by clients to get the configuration's language.

Parameters:

Takes no parameters.

Return Value:

The language style for the typing configuration associated with this handle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::MapKeyToText

virtual void MapKeyToText (TVirtualKeyCode :: EVirtualKey key, const TModifierKeys & modifiers, TText & text) const

Interface Category:

API.

Purpose:

Generates the text result that is appropriate to the current typing configuration based on the specified virtual key and the state of the modifier keys (shift, caps lock, etc.).

Calling Context:

Can be called directly by clients. Also called internally by the typing interaction state.

Parameters:

TVirtualKeyCode :: EVirtualKey key -The virtual key.
const TModifierKeys & modifiers -Represents the state of the modifier keys (shift, caps lock, etc.) when the key stroke was generated.
TText & text -The resulting text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTypingConfigurationHandle::~TTypingConfigurationHandle

virtual ~ TTypingConfigurationHandle ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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