Command Modes and Mouse Procs

3DS Max Plug-In SDK

Overview

In addition to any user interface that a plug-in may provide in the command panel via rollup pages, a plug-in may want to process mouse interaction in any of the viewports. Command modes allow the plug-in developer to define custom user / mouse interaction procedures. The system uses command modes as well. Examples are the viewport manipulation commands such as zoom and arc-rotate. Move, rotate and scale are implemented as command modes as well.

This section discusses command modes and the methods used to work with them.

Methods

In MAX, there is always a current command mode. This is the instance of the class CommandMode that is currently at the top of the system's command stack. Command modes can either be pushed on the stack or replace the item on the top of the stack.

There are methods in MAX's Interface class to set and get the current command mode as well as getting the size of the command stack and finding a particular mode by index. See the methods:

virtual void PushCommandMode(CommandMode *m)=0;

virtual void SetCommandMode(CommandMode *m)=0;

virtual void PopCommandMode()=0;

virtual CommandMode* GetCommandMode()=0;

virtual void SetStdCommandMode(int cid)=0;

virtual void PushStdCommandMode(int cid)=0;

virtual void RemoveMode(CommandMode *m)=0;

virtual void DeleteMode(CommandMode *m)=0;

virtual int GetCommandStackSize();

virtual GetCommandStackEntry(int entry)

Viewport manipulation commands, for instance, are always pushed on the stack so that if the user right clicks while in a viewport mode, the viewport command mode is popped off the stack, restoring the previous command mode in effect before the viewport command was engaged.

A command mode provides the system with two major things:

$image\bullet.gif$ A callback procedure which flags nodes that belong in the foreground plane.

$image\bullet.gif$ A mouse proc which handles mouse input in the viewports.

For the first item, plug-ins typically use a standard callback object provided by the system that flags all nodes dependent on the plug-in object. So when the plug-in object changes, any nodes that change as a result will be in the foreground plane, making redraw time faster. For more details see the section Foreground / Background Planes.

The mouse proc is the object that allows plug-ins to process viewport mouse input. The MouseCallback class is a pure virtual class with a method named proc(). This method is called when a mouse event takes place. It gets passed several parameters:

$image\bullet.gif$ The window handle of the window the user clicked in. This will be one of the viewports. An interface to the viewport can be obtained from the system, given this window handle.

$image\bullet.gif$ A message parameter. This describes the type of event such as mouse down, mouse up, mouse move, etc.

$image\bullet.gif$ The point number. this is 0 for the first click, 1 for the second, etc.

$image\bullet.gif$ Flags. These specify the state of the Shift, Ctrl, and Alt keys.

$image\bullet.gif$ The 2D screen point that the user clicked on. Methods in the viewport interface allow this point to be converted into a world space ray or a 3D view space point. A world space ray can be intersected with the active construction plane which results in a point on the active construction plane.

The mouse proc can specify how many points it wants for its specific task. For instance, the move transform needs two points. The first point represents the point where the user clicked down and the second point represents where the user released the mouse. A mouse proc can specify that it needs a large number of points and then return an abort code when it has completed its operation. For instance, the mouse proc that handles the creation of a spline expects to get some arbitrary number of points. When the user completes the spline, the mouse proc signals the system that its operation is completed.

In addition to providing the system with a foreground callback and a mouse proc, a command mode also has some other methods.

When a command mode becomes active its EnterMode() method is called. Usually it would respond by changing the state of a control somewhere to reflect to the user that they were in that mode. Typically this means pushing in a tool button. When the mode is finished the button should be returned to normal. The user may have activated the mode by pushing in the tool button, in which case it is redundant for the command mode to also set the button's state to 'in', however the mode could have been entered by right clicking while in a viewport manipulation mode in which case, the tool button would have been in the 'out' state. Note: A developer should use the standard color GREEN_WASH for check buttons that instigate a command mode. While the command mode is active the button should be displayed in GREEN_WASH. See Class ICustButton (specifically the method SetHighlightColor()) for more details.

When the active mode is replaced by a different mode, its ExitMode() method is called. Typically, the command mode would respond by setting its corresponding tool button to the 'out' state.

Command modes are identified by a class ID and an ID. The class ID is usually chosen from a pre-defined set of class IDs although developers may create their own. These define the 'type' of mode. The ID is the mode's unique ID.

There are two other methods a developer may find useful. These methods allow a plug-in to receive notification when the command mode has been changed by the user. These methods of class Interface are:

virtual void RegisterCommandModeChangedCallback(

CommandModeChangedCallback *cb)=0;

Register a callback object that will get called when the user changes the command mode. See Class CommandModeChangedCallback.

virtual void UnRegisterCommandModeChangedCallback(

CommandModeChangedCallback *cb)=0;

Un-registers the command mode change callback object.

Display of Messages in Command Modes

Developers cannot put up a message box using the Windows MessageBox() API while in the middle of a mouse operation inside a command mode. For example, if the user is dragging the mouse, it will cause problems to put up a message box. The prompt line may be used if a message needs to be sent to the user while in this state. This is done using the methods of class Interface. See Class Interface to review these methods.

Summary

Command modes allow the plug-in developer to process mouse interaction in any of the viewports. A command mode provides the system with a foreground callback and a mouse proc. See the section Object Creation Methods for a discussion of how command modes participate in custom object creation procedures.

previous page start next page