Class: TTextToolInteractionTarget

Declaration: TextToolsCore.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible, MToolTarget

Inherited By:

TDocumentTextToolInteractionTarget TSimpleTextToolInteractionTarget

Purpose:

TTextToolInteractionTarget is a tool target that can create and extend text selections from positional information. This is the only type of tool target that TTextView::CreateToolTarget can return today. Tool builders can use a TTextToolInteractionTarget object to create and extend their own MTextSelection objects during tool interaction with a TTextView. In addition to creating client-owned MTextSelection objects from positional information, it is possible to set the one text selection per text representation that is owned by the associated TTextPresenterState object, in the document case.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

The Text Editing Framework classes that are derived from TTextToolInteractionTarget are TDocumentTextToolInteractionTarget and TSimpleTextToolInteractionTarget. The former is for document component-based text, whereas the latter is not document component-based. Derived classes should override ExtendTextSelection, GetTextSelectionColor, and SetTextSelectionColor. They may also provide functions for setting the selection.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTextToolInteractionTarget::~TTextToolInteractionTarget

virtual ~ TTextToolInteractionTarget ()

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: TTextToolInteractionTarget::CreateTextSelection

virtual MTextSelection * CreateTextSelection (const TGPoint & initialPoint, TTextOffset & anchorOffset) const

Interface Category:

API.

Purpose:

Creates a text selection starting at the position represented by initialPoint, and ending at anchorOffset. Called to create the selection. This will typically be used in a tool interactor to create a selection when the mouse button is pressed.

Calling Context:

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

Parameters:

const TGPoint & initialPoint -The initial point for the selection.
TTextOffset & anchorOffset -The offset of the ending point of the selection.

Return Value:

A pointer to the resulting selection object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextToolInteractionTarget::ExtendTextSelection

virtual void ExtendTextSelection (const TGPoint & extendPoint, TTextOffset anchorOffset, MTextSelection & selection) const

Interface Category:

API.

Purpose:

Extends the specified text selection to the extendPoint. Called to extend the selection. This will typically be used in a tool interactor to extend a selection as the mouse is dragged.

Calling Context:

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

Parameters:

const TGPoint & extendPoint -The point to extend the selection to.
TTextOffset anchorOffset -The anchor offset
MTextSelection & selection -The selection to be extended.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextToolInteractionTarget::CopyTextSelection

virtual MTextSelection * CopyTextSelection () const

Interface Category:

API.

Purpose:

Copies the document component's text selection. An Editable Text document component maintains a single model selection in its TTextPresenterState presenter state object.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

A pointer to the copied selection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextToolInteractionTarget::AdoptTextSelection

virtual void AdoptTextSelection (MTextSelection * selection)

Interface Category:

API.

Purpose:

Adopts the specified text selection.

Calling Context:

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

Parameters:

MTextSelection * selection -The selection to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextToolInteractionTarget::GetTextSelectionColor

virtual void GetTextSelectionColor (TColor & color) const

Interface Category:

API.

Purpose:

Retrieves the current text selection color. Called to determine the current color. This should be called during tool interaction prior to changing the color, to save the current color for later restoration.

Calling Context:

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

Parameters:

TColor & color -Receives the selection color.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextToolInteractionTarget::SetTextSelectionColor

virtual void SetTextSelectionColor (const TColor & color)

Interface Category:

API.

Purpose:

Changes the text selection color. Used to change the selection feedback during tool interaction with text. If the tool is a selection tool, the highlight should not be changed. But it may be appropriate for an effector tool to highlight in a different color than the selection color.

Calling Context:

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

Parameters:

const TColor & color -The new color.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the selection color is changed during a tool's interaction, the current highlight color should be saved first, and restored at the end of the tool's interaction with the text.

Member Function: TTextToolInteractionTarget::operator=

TTextToolInteractionTarget & operator =(const TTextToolInteractionTarget &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TTextToolInteractionTarget & -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: TTextToolInteractionTarget::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

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

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: TTextToolInteractionTarget::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

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

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: TTextToolInteractionTarget::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Gets a hash value.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

The numeric value of the hash, a long.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited MCollectible function.

Member Function: TTextToolInteractionTarget::TTextToolInteractionTarget

TTextToolInteractionTarget (TTextView *)
TTextToolInteractionTarget (const TTextToolInteractionTarget & target)
TTextToolInteractionTarget ()

Interface Category:

API.

Purpose:

Constructs a text tool interaction target for use with the specified text view.
Copy constructor.
Default constructor.

Calling Context:

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

Parameters:

TTextView * -The text view the tool will interact with.
const TTextToolInteractionTarget & target -The object to copy.
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.