Class CommandMode
See Also: Class MouseCallBack, Class ChangeForegroundCallback, Foreground / Background Planes.
class CommandMode
Description:
This base class allows the developer to create a command mode that handles processing user interaction using the mouse in the viewports.
See Also: The Advanced Topics section Command Modes and Mouse Procs. There are methods in 3ds max's Interface class to set and get the current command mode.
Methods:
Prototype:
virtual int Class()=0;
Remarks:
Implemented by the Plug-In.
Returns the Class of the command mode. The class describes the type of command mode this is. If the developer is defining a command mode to be used as part of the sub-object manipulation (Move, Rotate, and Scale) then one of the following pre-defined values should be used:
MOVE_COMMAND
ROTATE_COMMAND
SCALE_COMMAND
USCALE_COMMAND
SQUASH_COMMAND
If one of these other values is appropriate it may be used. If not, the developer is free to define their own (as an int).
VIEWPORT_COMMAND
SELECT_COMMAND
HIERARCHY_COMMAND
CREATE_COMMAND
MODIFY_COMMAND
MOTION_COMMAND
ANIMATION_COMMAND
CAMERA_COMMAND
NULL_COMMAND
DISPLAY_COMMAND
SPOTLIGHT_COMMAND
PICK_COMMAND
Return Value:
The Class of the command mode.
Prototype:
virtual int SuperClass()
Remarks:
Implemented by the Plug-In.
This method can be ignored. The default implementation should be used.
Default Implementation:
{ return 0; }
Prototype:
virtual int ID()=0;
Remarks:
Implemented by the Plug-In.
Returns the ID of the command mode. This value should be the constant CID_USER plus some random value chosen by the developer.
As an example, this method could be implemented as:
{ CID_USER+0x1423; }
In the special case of the developer implementing a custom command mode to be used as part of sub-object manipulation (Move, Rotate or Scale) the value for ID() should be one of the following values:
CID_SUBOBJMOVE
CID_SUBOBJROTATE
CID_SUBOBJSCALE
CID_SUBOBJUSCALE
CID_SUBOBJSQUASH
Note: if two command modes conflict in this ID value, it is not a problem, so the uniqueness is not strictly required. However, this ID() method is often used to check which mode is active, so unless the value for your command mode is identifiable via this ID, you may not be able to recognize if your mode is indeed the active one.
Prototype:
virtual MouseCallBack *MouseProc(int *numPoints)=0;
Remarks:
Implemented by the Plug-In.
This method establishes the number of points required by the command mode and returns a pointer to the mouse callback object that is used to process the user input.
Parameters:
int *numPoints
This is where to store the number of points used by the CommandMode. If the plug-in needs to use an undetermined number of points it can specify a large number for this value. When the mouse proc has finished processing points it returns FALSE to stop the point processing before the number of points specified here have been entered.
Return Value:
A pointer to the mouse callback object that is used to process the user input.
See Also: Class MouseCallBack.
Prototype:
virtual ChangeForegroundCallback *ChangeFGProc()=0;
Remarks:
Implemented by the Plug-In.
Returns a pointer to a callback procedure that flags nodes that belong in the foreground plane. Plug-ins typically use a standard callback object provided by the system that flags all nodes dependent on the plug-in object. This ensures that when the plug-in object changes, any nodes that change as a result will be in the foreground plane, making redraw time faster.
These constants may be specified to use one of the standard callback objects instead of an actual FG proc. For example {return CHANGE_FG_SELECTED;}
CHANGE_FG_SELECTED
Selected nodes are flagged.
CHANGE_FG_ANIMATED
Nodes that are animated are flagged.
Return Value:
A pointer to a callback procedure that flags nodes that belong in the foreground plane.
See Also: For additional information see the Advanced Topics section Foreground / Background Planes.
Prototype:
virtual BOOL ChangeFG( CommandMode *oldMode )=0;
Remarks:
Implemented by the Plug-In.
This method returns TRUE if the command mode needs to change the foreground proc (using ChangeFGProc()) and FALSE if it does not. A command mode that does not involve any redrawing of the viewports can just return FALSE.
Parameters:
CommandMode *oldMode
This is the command mode that is currently in place. This may be used for comparison with a potential new mode. See the sample code below.
Sample Code:
The sample code below checks to see if the command mode is already CHANGE_FG_SELECTED. If it is there is no reason to change to foreground proc to this mode so the method returns FALSE. If a different mode is in place TRUE is returned.
BOOL ChangeFG( CommandMode *oldMode )
{ return (oldMode->ChangeFGProc() != CHANGE_FG_SELECTED); }
ChangeForegroundCallback *ChangeFGProc()
{ return CHANGE_FG_SELECTED; }
Prototype:
virtual void EnterMode()=0;
Remarks:
Implemented by the Plug-In.
This method is called when a command mode becomes active. Usually a developer responds by changing the state of a control to indicate to the user that they have entered the mode. Typically this means pushing in a tool button. When the mode is finished the button should be returned to normal (see ExitMode() below).
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.
Sample Code:
iPick->SetHighlightColor(GREEN_WASH);
iPick->SetCheck(TRUE);
Prototype:
virtual void ExitMode()=0;
Remarks:
Implemented by the Plug-In.
This method is called when the active command mode is replaced by a different mode. Typically a developer implements this method to set the state of the control that invoked the command mode to the 'out' state. See Class ICustButton (specifically the method SetCheck()).
Sample Code:
iPick->SetCheck(FALSE);