Class: MToolHandler

Declaration: CursorTools.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

MGUIToolHandler TCanvasView TTextView

Purpose:

MToolHandler is a mixin class that is used to provide other classes with cursor tools support. It is typically mixed into view classes that will support tools.

Instantiation:

MMouseEventHandler is a mixin class and cannot be instantiated.

Deriving Classes:

Typically, MToolTarget is mixed into view classes that will support cursor tools. AdoptAndDo, DoBegin, DoIncrement, and AdoptAndDoEnd must all be implemented. CreateToolTarget, CreateToolInteractor, or both should be implemented.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: MToolHandler::~MToolHandler

virtual ~ MToolHandler ()

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: MToolHandler::CreateToolTarget

virtual MToolTarget * CreateToolTarget (const TTypeDescription &, const TGPoint &) const

Interface Category:

API.

Purpose:

Creates a target at the specified location for the specified type of tool to work on.

Calling Context:

Called by TSimpleMouseTool::MouseDown to obtain a target to use when creating the interactor.

Parameters:

const TTypeDescription & -The tool type required.
const TGPoint & -The position to start interaction.

Return Value:

Returns created tool target.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Override CreateToolTarget to create targets for tools to work on.

Member Function: MToolHandler::CreateToolInteractor

virtual TToolInteractor * CreateToolInteractor (const TGPoint &, const TToken & hint) const

Interface Category:

API.

Purpose:

The Tools framework calls CreateToolInteractor when a delegating tool wants to work on a view. A delegating tool is one that has unspecified behavior across applications and is target-type neutral, such as the arrow tool.

Calling Context:

Called by the Cursor Tools Framework when a delegating tool's MouseDown function creates a tool interactor.

Parameters:

const TGPoint & -The position to start.
const TToken & hint -The tool type.

Return Value:

Returns created interactor.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Override CreateToolInteractor to create interactors for the tool framework to start. Your application is provided with a hint of the tool type that is, essentially, a way of describing the graphic. You provide the implementation for interactor.

Member Function: MToolHandler::AdoptAndDo

virtual void AdoptAndDo (TToolCommandBinding *)

Interface Category:

API.

Purpose:

Adopts a tool command binding and does the command.

Calling Context:

Called to adopt a tool command binding and do the command. Called by TToolInteractor.

Parameters:

TToolCommandBinding * -The tool command binding to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MToolHandler::DoBegin

virtual void DoBegin (TToolCommandBinding &)

Interface Category:

API.

Purpose:

Performs the initial segment of an incremental command.

Calling Context:

Called to start an interactor. Called by TToolInteractor.

Parameters:

TToolCommandBinding & -The tool command binding.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MToolHandler::DoIncrement

virtual void DoIncrement (TToolCommandBinding &)

Interface Category:

API.

Purpose:

Performs the intermediate segment of an incremental command.

Calling Context:

Called to executes the command created by the tool against a document. Called by TToolInteractor.

Parameters:

TToolCommandBinding & -The tool command to be executed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Deriving classes must implement this member function.

Member Function: MToolHandler::AdoptAndDoEnd

virtual void AdoptAndDoEnd (TToolCommandBinding *)

Interface Category:

API.

Purpose:

Adopts the specified tool command binding and performs the final segment of an incremental command.

Calling Context:

Called to adopt the specified tool command binding and stop the interactor. Called by TToolInteractor.

Parameters:

TToolCommandBinding * -The tool command binding to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MToolHandler::SupportsFeedback

virtual bool SupportsFeedback () const

Interface Category:

API.

Purpose:

Checks if this object supports graphic feedback.

Calling Context:

Called to determine if this object supports graphic feedback. Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if a feedback graphic is supported.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MToolHandler::AdoptFeedbackGraphic

virtual void AdoptFeedbackGraphic (MGraphic *, const TGArea & total, const TGArea & changed)

Interface Category:

API.

Purpose:

Adopts the specified graphic for interactor feedback.

Calling Context:

Called to adopt the specified graphic for interactor feedback. Call this function directly.

Parameters:

MGraphic * -The graphic to adopt.
const TGArea & total -The size of the area used by the graphic.
const TGArea & changed -The change indicator for the graphic.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MToolHandler::OrphanFeedbackGraphic

virtual MGraphic * OrphanFeedbackGraphic (bool repair =true)

Interface Category:

API.

Purpose:

Removes the current graphic used for interactor feedback.

Calling Context:

Called to orphans the graphic currently used for interactor feedback. Call this function directly.

Parameters:

bool repair =true -Set to true if the area of the feedback graphic needs to be refreshed.

Return Value:

Returns a reference to the orphaned graphic.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You may wish to use the sprite frame to achieve better drawing performance.

Member Function: MToolHandler::MToolHandler

MToolHandler ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called to create an instance of MToolHandler.

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.