Class: TInputMethodTextPresentation

Declaration: TextInputMethod.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TTextInputMethodTextPresentation

Purpose:

TInputMethodTextPresentation is an abstract base class that provides a means for input methods to control certain aspects of the presentation (display and editing) of text. TInputMethodTextPresentation itself has very little implementation; it is intended to be derived by developers of text editors (of which the CommonPoint Text Editing framework is one example).

Instantiation:

Abstract class; do not instantiate directly.

Deriving Classes:

The developer of a text editor must derive a class from this class and override the pure virtual functions. This derived class is passed in to the input method by a call to a TTypingConfigurationHandle object's Attach function. CommonPoint provides the TTextInputMethodTextPresentation derived class, for use by the CommonPoint Text Editing framework and text editors derived from that framework.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TInputMethodTextPresentation::~TInputMethodTextPresentation

virtual ~ TInputMethodTextPresentation ()

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.

Member Function: TInputMethodTextPresentation::AddActiveStyles

virtual void AddActiveStyles (const TStyleSet & stylesToAdd, const TTextRange & whereToAdd, const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Sets and displays the specified styles for the specified range of text. There are two possible types of implementations: One is to use the classes TFilteredTextRepresentation and TFilteredText to superpose styles on text being edited without the styles actually being in the text. The other is to put the styles directly in the text being edited.

Calling Context:

Called by the input method to let the editor know that these styles are being added during input. The editor should display the styles to the end user.

Parameters:

const TStyleSet & stylesToAdd -The styles to add.
const TTextRange & whereToAdd -The range of text to which to add the styles.
const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The kind of style to add (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::RemoveActiveStyles

virtual void RemoveActiveStyles (const TStyleSet & stylesToRemove, const TTextRange & whereToRemove, const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Removes the specified styles from the specified range of text.

Calling Context:

Called by the input method when the styles are removed during user input, to notify the editor to change the display accordingly.

Parameters:

const TStyleSet & stylesToRemove -The styles to remove.
const TTextRange & whereToRemove -The range of text for which the styles are to be removed.
const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to remove (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::ReplaceActiveStyles

virtual void ReplaceActiveStyles (const TStyleSet & incomingStyles, const TTextRange & whereToReplace, const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Replaces the current styles on the specified range of text with the specified styles, and updates the display accordingly.

Calling Context:

Called by the input method when the styles are replaced during user input.

Parameters:

const TStyleSet & incomingStyles -The new styles to replace the current ones.
const TTextRange & whereToReplace -The range of text where the new styles should replace the old.
const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to replace (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::RemoveAllActiveStyles

virtual void RemoveAllActiveStyles (const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

This function must remove all traces of input method styles of the specified kind from the display. If the styles were being stored in the actual text instead of a filter, then the TInputMethodTextPresentation derived class must keep track of where they are so they may be removed when this is called.

Calling Context:

Called by the input method when closing the current active area.

Parameters:

const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to remove (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::InsertActiveStyles

virtual void InsertActiveStyles (TTextOffset where, TTextCount howMuch)

Interface Category:

API.

Purpose:

Updates the styles used to represent the active area, in response to the insertion of the number of characters specified by howMuch, starting at the specified text offset.

Calling Context:

Called to alert the presentation to character insertions so that it can keep the active area styles synchronized with the actual text.

Parameters:

TTextOffset where -The location where characters have been inserted.
TTextCount howMuch -The number of inserted characters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

By default, this function does nothing. Derived classes that use filters to manage styles must override it to keep the filter synchronized with the text.

Member Function: TInputMethodTextPresentation::DeleteActiveStyles

virtual void DeleteActiveStyles (const TTextRange & where)

Interface Category:

API.

Purpose:

Updates the styles used to represent the active area, in response to the deletion of characters in the specified range of text.

Calling Context:

Called to alert the presentation to character deletions so that it can keep the active area styles synchronized with the actual text.

Parameters:

const TTextRange & where -The range of deleted text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

By default, this function does nothing. Derived classes that use filters to manage styles must override it to keep the filter synchronized with the text.

Member Function: TInputMethodTextPresentation::FlushInput

virtual void FlushInput ()

Interface Category:

API.

Purpose:

Flushes all pending keystrokes into the text being edited.

Calling Context:

Called by input method behaviors that are installed by the input method, and by any other input method function that needs to ensure all typing has been processed.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::SetSelection

virtual void SetSelection (const TTextArea &)

Interface Category:

API.

Purpose:

Sets the selection in the text being edited to the specified area of text.

Calling Context:

Called by the input method to set the current selection.

Parameters:

const TTextArea & -The area of text to be selected.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::GetSelection

virtual void GetSelection (TTextArea &)

Interface Category:

API.

Purpose:

Gets the current selection in the text being edited.

Calling Context:

Called by the input method to get the current selection.

Parameters:

TTextArea & -Receives the text selection area.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::AdoptBehavior

virtual void AdoptBehavior (MEventTarget * behavior)

Interface Category:

API.

Purpose:

Adopts the specified input method behavior.

Calling Context:

Called to implement the input method's user interface by having the input method behavior adopted. The behavior intercepts keystrokes and mouse clicks, and performs appropriate actions to implement the user interface.

Parameters:

MEventTarget * behavior -The input method behavior to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::OrphanBehavior

virtual void OrphanBehavior (MEventTarget * behavior)

Interface Category:

API.

Purpose:

Orphans the specified input method behavior.

Calling Context:

Called by the input method when the active area closes, or when the input method is removed.

Parameters:

MEventTarget * behavior -The input method behavior to orphan.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::LocalCoordinateToInsertionOffset

virtual void LocalCoordinateToInsertionOffset (const TGPoint & where, TInsertionOffset & offset) const

Interface Category:

API.

Purpose:

Converts the specified local coordinate in the view containing the edited text to an insertion offset in the text being edited.

Calling Context:

Called by the input method to process mouse clicks, and to position user interface elements such as palette windows close to the text being edited.

Parameters:

const TGPoint & where -The local coordinate in the view containing the edited text.
TInsertionOffset & offset -The corresponding insertion offset in the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::InsertionOffsetToLocalCoordinate

virtual void InsertionOffsetToLocalCoordinate (const TInsertionOffset & offset, TGPoint & where) const

Interface Category:

API.

Purpose:

Converts the specified insertion offset in the text being edited to the corresponding local coordinate in the view containing the edited text.

Calling Context:

Called by the input method to process mouse clicks, and to position user interface elements such as palette windows close to the text being edited.

Parameters:

const TInsertionOffset & offset -The insertion offset in the text.
TGPoint & where -The corresponding coordinate in the view containing the edited text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::GlobalCoordinateToInsertionOffset

virtual void GlobalCoordinateToInsertionOffset (const TGPoint & where, TInsertionOffset & offset) const

Interface Category:

API.

Purpose:

Converts the specified global screen coordinate to an insertion offset in the text being edited.

Calling Context:

Called by the input method to process mouse clicks, and to position user interface elements such as palette windows close to the text being edited.

Parameters:

const TGPoint & where -The global screen coordinate.
TInsertionOffset & offset -The corresponding insertion offset in the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::InsertionOffsetToGlobalCoordinate

virtual void InsertionOffsetToGlobalCoordinate (const TInsertionOffset & offset, TGPoint & where) const

Interface Category:

API.

Purpose:

Converts the specified insertion offset in the text being edited to the corresponding global screen coordinate.

Calling Context:

Called by the input method to process mouse clicks, and to position user interface elements such as palette windows close to the text being edited.

Parameters:

const TInsertionOffset & offset -The insertion offset in the text.
TGPoint & where -The corresponding global screen coordinate.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::AdoptAlertWindow

virtual void AdoptAlertWindow (TWindow * alert)

Interface Category:

API.

Purpose:

Adopts and installs the specified alert window.

Calling Context:

Called by the input method to install the alert window.

Parameters:

TWindow * alert -The alert window to install.

Return Value:

None.

Exceptions:

Derived classes may throw TInputMethodCantUseGUIElementException.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::AdoptPaletteWindow

virtual void AdoptPaletteWindow (TWindow * palette)

Interface Category:

API.

Purpose:

Adopts and installs the specified palette window.

Calling Context:

Called by the input method to install the palette window.

Parameters:

TWindow * palette -The palette window to install.

Return Value:

None.

Exceptions:

Derived classes may throw TInputMethodCantUseGUIElementException.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::AdoptMenuWindow

virtual void AdoptMenuWindow (TWindow * menu)

Interface Category:

API.

Purpose:

Adopts and installs the specified menu window.

Calling Context:

Called by the input method to install the menu window.

Parameters:

TWindow * menu -The menu window to install.

Return Value:

None.

Exceptions:

Derived classes may throw TInputMethodCantUseGUIElementException.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::OrphanWindow

virtual TWindow * OrphanWindow (TWindow &)

Interface Category:

API.

Purpose:

Removes the specified window installed using one of the Adopt Window functions (AdoptAlertWindow, AdoptPaletteWindow, or AdoptMenuWindow), and returns ownership of storage to the caller.

Calling Context:

Called when the input method is being deactivated (because the typing configuration is being changed, for example). Not called if the Adopt Window function threw TInputMethodCantUseGUIElementException.

Parameters:

TWindow & -The window to orphan.

Return Value:

A pointer to the window.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::AdoptInputMethodMenuItem

virtual void AdoptInputMethodMenuItem (MMenuItem * adoptMenuItem)

Interface Category:

API.

Purpose:

Adopts the specified input method menu, which should be inserted close to the global typing configuration menu. This menu provides access to all the other functions of the input method, such as bringing up additional tool palettes.

Calling Context:

Called by the input method to install its own menu.

Parameters:

MMenuItem * adoptMenuItem -The menu to be installed.

Return Value:

None.

Exceptions:

Derived classes may throw TInputMethodCantUseGUIElementException.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::OrphanInputMethodMenuItem

virtual MMenuItem * OrphanInputMethodMenuItem (MMenuItem & orphanMenuItem)

Interface Category:

API.

Purpose:

Removes the specified menu installed using AdoptInputMethodMenuItem, and returns ownership of storage to the caller.

Calling Context:

Called when the input method is being deactivated (because the typing configuration is being changed, for example). Not called if AdoptInputMethodMenuItem threw TInputMethodCantUseGUIElementException.

Parameters:

MMenuItem & orphanMenuItem -The menu to be orphaned.

Return Value:

A pointer to the menu.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: TInputMethodTextPresentation::TInputMethodTextPresentation

TInputMethodTextPresentation ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called by the stream-in operators.

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.

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