Simple mouse tools
A simple cursor tool (TSimpleMouseTool) works on a target of a specified type. Figure 22 shows that TSimpleMouseTool derives from TTool and mixes in MMouseEventHandler. TSimpleMouseTool creates and launches an interactor that creates and binds a command to the target. The target must be of the specified type. For example the interactor for creating (drawing) a canvas graphic binds the command for drawing with the MCanvasSelection for the representation to which the graphic will be added.
GrafEdit provides the concrete classes shown in Figure 22. You can use these classes as is, or you can derive from TSimpleMouseTool to create your own simple mouse tool.
When the canvas view delegates positional event handling to the cursor tools framework, it identifies itself as the tool handler (MToolHandler) to be called back for target creation. The Cursor tools framework handles positional events by determining whether there is a cursor tool bound to the device that produced the event. If so, and if the tool starts interaction on the given event (for example, the mouse tools start on a mouse-down event), the Cursor Tools framework calls the canvas view to create the type of target that the tool requires.
Tool negotiation
virtual MToolTarget* TCanvasView::CreateToolTarget( const TTypeDescription&,
The CreateToolTarget function identifies the required target type (TTypeDescription) and the position at which the tool wants to start working (TGPoint). If the canvas view returns a non-Nil target, the tool and the target are introduced and the tool creates and starts its interactor.
const TGPoint& ) ;
The TTypeDescription parameter is a token text string that specifies a target tool type. The canvas view supports only tools that work on canvas selections (MCanvasSelection); therefore, MCanvasSelection is passed to the CreateToolTarget function in the TTypeDescription parameter. Derived classes of TCanvasView can extend this, however.
TCanvasView implements CreateToolTarget to create and return an MCanvasSelection by creating a reference to a new selection that selects the canvas graphic at the position of the tool, if any. If there is no canvas graphic at the position of the tool, CreateToolTarget returns Nil.
Figure 23
GrafEdit provides the TStandardArrowTool concrete classes shown in Figure 23. (Eventually other concrete classes will be provided.) You can use these classes as is, or you can derive from TDelegatingMouseTool to create your own delegating tool. The Mars sample application uses the Arrow tool (TStandardArrowTool) to select, rotate, translate, and scale a canvas graphic.
As with simple tools, the Cursor Tools framework detects when a delegating tool is bound to the device of an event and starts on the event. The Cursor Tools framework calls on the canvas view to create the tool interactor, passes the position of the event (TGPoint), and provides a hint to identify the tool type (TToken).
To allow canvas graphics to define their own custom interactions, the canvas view depends on canvas graphics to help it create tool interactors. To do this, the canvas view enumerates canvas graphics from front to back looking for a graphic that coincides with the tool position. When a graphic is found, the canvas view asks this graphic to create an interactor by calling the graphic's TCanvasGraphic::CreateInteractor. When no graphic is found or when the hit graphic returns Nil for its tool interactor, the canvas view creates a TCanvasSelectionInteractor as the default interactor.
The canvas view does not use the TCanvasView::Hit function because this function does not take selection graphics into account. Normally, hit detection identifies a hit graphic in the representation. Because selections are temporary, they are not part of the representation. To create an interactor, however, selection graphics are taken into account because these graphics often represent new interaction potential. For example, in the Mars sample application, when a graphic is selected, a selection box appears. The selection box permits scaling, rotating, and translating the graphics in the selection.
The concrete canvas graphic classes provided in GrafEdit do not create tool interactors; they all return Nil. The TSRTBoxFeedbacker class creates a TCanvasGraphicScalingInteractor, TCanvasGraphicRotatingInteractor, or a TCanvasGraphicTranslatingInteractor depending on where the tool position hits the feedback graphic. As a result, the only canvas graphic that GrafEdit provides to support graphic-specific interaction is the feedback graphic.
To customize graphic-specific interaction, create custom canvas graphic derived classes and override TCanvasGraphic::CreateToolInteractor.
Tool target creation
Delegating mouse tools
A delegating mouse cursor tool (TDelegatingMouseCursorTool) delegates interaction creation to the application. For example, the Arrow tool has such differing behavior in different applications and in different areas of the same application that it cannot provide a single interactor for all cases. In the Mars sample application, the arrow tool selects canvas graphics and lets you perform scale, rotate, and translate operations on the selected graphics. 
Tool negotiation
The TToken parameter is a token text string that specifies a delegating tool type. Currently, the only standard delegating tool is the Arrow tool (TStandardArrowTool), which provides the token "Arrow." virtual TToolInteractor* TCanvasView::CreateToolInteractor( const TGPoint&,
TToken& hint );
Tool interactor creation
Simple or delegating mouse tool?
To decide whether you need to create a simple cursor tool or a delegating cursor tool, ask yourself "What controls the interaction, the tool or its target?" If the answer is "The tool," you want a simple cursor tool. If the answer is "The target," you want a delegating tool.
[Contents]
[Previous]
[Next]
Click the icon to mail questions or corrections about this material to Taligent personnel.
Generated with WebMaker