SDK:Tool Plug-in Events

From Vectorworks Developer
Jump to navigation Jump to search

.SDK|SDK ..SDK:Types|SDK Types ..SDK:Using the SDK|Using the SDK ..VCOM:VCOM (Vectorworks Component Object Model)|VCOM Basics ..VCOM:Class Reference|VCOM Class Reference

Tool Events

Tools receive the following action requests:

kToolInitGlobals

A workspace containing the plug-in has been loaded. This action will not be called again until kToolDisposeGlobals has been called. This is the plug-in’s opportunity to initialize all persistent data.

The message parameters are unused. This action should return 0 if initialization succeeded, otherwise return kToolCouldNotInitialize.

kToolDisposeGlobals

A workspace containing the plug-in has been deselected. The tool should finalize all outstanding actions and free any allocated resources. The message parameters are unused. This routine should always return 0.

kToolDoSetup

This tool has just become active. Activation occurs in two contexts as distinguished by the message1 parameter of the action call. If message1 equals zero then this is a setup that occurs when the user initially selects the tool. If message1 equals kSetupSetdownPauseRestoreFlag then the tool is being restored from a paused state. In either case the mode bar and help text should always be supplied.

This action should return 0 if activation succeeded, otherwise return kToolCouldNotSetUp.

kToolDoSetDown

This tool has just become deactivated. Deactivation occurs in two contexts as distinguished by the message1 parameter. If message1 equals 0 then the user has deselected the tool. If message1 equals kSetupSetdownPauseRestoreFlag then the tool is being paused. In the pause case, the tool will be called again with a kToolDoSetup action with message1 equal to kSetupSetdownPauseRestoreFlag.

This action should always return 0.

kToolGetCursor

Before the user clicks on the document with a tool, VectorWorks indicates the upcoming action by changing the cursor to reflect the mouse position on screen. This action is called by the framework to get the cursor for the tool. The message parameters are unused. This routine should return a value that specifies the resource id of the appropriate cursor to be displayed.

See SDK:Setting Tool Status

kToolDoModeEvent

The user has selected a mode in the mode bar. message1 is the index of the group the user clicked in.

The high word of message2 is the old selection, the low word is the new selection. This action should always return 0.

kToolDoDoubleClick

The user has double-clicked on the tool’s icon in a tool palette. If the tool is a creation tool then it should provide the user with a dialog to specify the new object.

This is currently the only behavior implemented in VectorWorks in response to this action.

Expanding the meaning of this action should be done with care.

In particular, do not use it as an alternative interface to behavior for which VectorWorks provides a standard for access (for example: do not bring up a preference dialog in response to this action. Preferences should be accessed through a mode bar button).

Note that this is not the same as the new kToolDrawingDoubleClick action above.

kToolPointAdded

This action is called when the tool gets a mouse down in the content of the drawing.

This action is also called for a click drag mouse up. The tool may return 0, kToolCancel, kToolCompleted, or kToolSwitchToCursor.

kToolPointRemoved

This action is called whenever the tool framework removes a tool point for any reason. Use this action to clean up any state that becomes stale with the removal of a tool point.

The tool may return 0, kToolCancel, kToolCompleted, or kToolSwitchToCursor.

kToolDraw

This action is called when the tool needs to draw.

The tool framework calls this draw action handling expecting the tool to draw itself.

See SDK:Drawing a Tool.

kToolHandleComplete

This action is called when the tool has signified, through a kToolGetStatus return value, that the tool is complete.

This is where the tool makes changes to the drawing. kToolHandleComplete action handling is the most ikely location for UNDO callbacks. The tool may return 0, kToolCancel, or kToolSwitchToCursor.

kToolGetStatus

This action is called so the tool can return to the system the current state of the tool.

See SDK:Setting Tool Status

kToolMouseMove

This action is called when the mouse moves over the content of the drawing.

If the tool has the tool definition resource screenBasedCursor flag set it gets kToolMouseMove action calls whenever the mouse moves a pixel.

If the tool does not set the screenBasedCursor flag, it gets called whenever the smartcursor snaps to a new point.

kToolDrawingDoubleClick

This action is called whenever the user double-clicks in the content of the drawing window with two or more Tool points.

Tools do not handle this unless they wish to override the default behavior.

The default behavior is to switch to the cursor tool. Most tools that provide an override are multi-segment tools that complete with double-click.

The return value for kToolDrawingDoubleClick is one of kToolCompleted, kHandledDocumentDoubleClick to override the default behavior.

If kToolCompleted is returned the tool’s kToolHandleComplete action handler will be called.

kToolOnCustomBarEvent

The tool has installed a custom bar using the ISDK::CustomBarInstall API.

While the Custom Bar is installed the tool will receive this action. Other APIs are provided to manage the custom databar.

The message1 parameter is a pointer to a CustomBarEventData structure.


kToolOnInitXProperties

A workspace containing the plug-in has been loaded.

This event is called following the kToolInitGlobals action. This action allows the tool to install any additional extended properties using the IExtendedProps::SetToolProperty functions.

The message1 parameter contains the CodeRefID for this tool's definition procedure. This CodeRefID is needed for the IExtendedProps::SetToolProperty function.

Some properties have associated actions.

See Also

Overview | SDK:Tool Plug-in Resources | SDK:Tool Plug-in Main Function | SDK:Tool Plug-in Events