Scripted Mouse Tools

Scripted Mouse Tools are used to perform a set of actions based on mouse clicks in the 3ds Max viewports. Tools are useful for scripted object creation plug-ins, as described in Scripted Plug-ins.

tool foo
(
local b
on mousePoint clickno do
if clickno == 1 then b = box pos:worldPoint else #stop
on mouseMove clickno do b.pos = worldPoint
)

startTool foo

The syntax for tools is similar to that for utility definition constructs. They have local variables, functions, and event handlers, but tools have no user-interface items.

A tool is created using the tool definition construct in MAXScript. The top-level syntax is as follows:

tool <tool_name> [ prompt:<string> ] [ numPoints:<number> ]( <tool_body> )

where <tool_name> is the name of an automatically created variable to hold the value that represents the tool. The scope of this variable is the current MAXScript scope. This value is also returned as a result of the tool declaration. The class of this value is MouseTool .

The optional prompt: keyword argument specifies the prompt string displayed in the 3ds Max Prompt Line while the tool is executing.

The optional numPoints: keyword argument specifies the maximum number of points (mouse clicks) the tool will use. If the tool is still executing when you reach the numPoints number of mouse clicks, the tool will stop and return a value of #stop .

<tool_body> is enclosed in the required parentheses and is a sequence of clauses that define the functions and event handlers that process mouse clicks. These clauses are defined in detail in Mouse Tool Clauses.

The following method invokes a tool:

startTool <tool_name> [prompt:<string>] [snap:#3D|#2D] [numPoints:<number>]

where <tool_name> is the tool name used in a tool definition.

The optional prompt: keyword argument specifies the prompt string displayed in the 3ds Max Prompt Line while the tool is executing. If specified, this string overrides the prompt string specified in the tool definition.

The optional snap: keyword argument specifies the upper limit on snapping. Specifying a snap parameter does not turn on snap, only the user can turn it on in the interface. When 2.5D or 3D snapping is turned on by the user, the snap parameter restricts snapping to the specified level.

The optional numPoints: keyword argument specifies the maximum number of points (mouse clicks) the tool will use. If specified, this value overrides the number of points specified in the tool definition.

The return value from startTool() will be either #stop if a called change handler returns the value #stop or the numPoints value is reached, or #abort if the user aborts the tool using a right-click or presses the ESC key.

A currently executing tool can also be aborted using the following method:

stopTool <tool_name>

where:

<tool_name> is the tool name used in a tool definition.

This method would typically be called in a callback function or change handler (see Change Handlers and Callbacks), or in a timer event handler in a rollout (see Timer).