Class MouseCallBack
See Also: Class CommandMode.
class MouseCallBack : public BaseInterfaceServer
Description:
This class is used to allow a developer to capture the mouse events entered by the user and process them. To create a mouse call back, derive a sub class of this class and implement the proc() method.
Methods:
Prototype:
virtual int proc(HWND hwnd, int msg, int point, int flags, IPoint2 m );
Remarks:
Implemented by the Plug-In.
This method is called when a mouse event takes place to handles its processing.
Parameters:
HWND hwnd
The window handle of the window the user clicked in. This is one of the viewports. An interface to the viewport can be obtained from the system, given this window handle. See Class Interface and review the methods below:
ViewExp *GetViewport( HWND hwnd )
This method gets a viewport interface given the window handle.
void ReleaseViewport( ViewExp *vpt )
When the developer is done with the viewport interface they should call this method to release it.
int msg
This message describes the type of event that occurred. See List of Mouse Callback Messages.
int point
The point number. this is 0 for the first click, 1 for the second, etc.
int flags
These flags describe the state of the mouse buttons. See List of Mouse Callback Flags.
IPoint2 m
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. See Class ViewExp.
Return Value:
TRUE indicates the proc should continue to process points; FALSE means stop processing points. If a plug-in supplied a large number of points in a command mode that uses this mouse proc, FALSE can be returned to abort the processing before all the points have been entered.
Prototype:
virtual int override(int mode)
Remarks:
Implemented by the Plug-In.
This method is used to override the default drag mode. Most plug-in will not need to replace the default implementation of this method. What this does is change the way the messages are sent relative to the mouse clicking.
Normally the messages are sent as follows: When the user clicks down this generates a MOUSE_POINT message. Then the user drags the mouse with the button down and a series of MOUSE_MOVE messages are sent. When they let up on the mouse button a MOUSE_POINT messages is generated. Then as the mouse is moved a series of MOUSE_MOVE messages are sent. Then they click down on the mouse again, but this time a point message is not generated until the button is released. All future points are then only sent after the mouse button has been pressed and released.
Parameters:
int mode
The current drag mode. See below.
Return Value:
One of the following drag modes should be returned:
CLICK_MODE_DEFAULT
Returned to indicate the use of the system mouse mode.
CLICK_DRAG_CLICK
This is the default behavior as described above.
CLICK_MOVE_CLICK
In this mode, the first point is entered by clicking the mouse button down and then letting it up. This generates point 0. In other words, a MOUSE_POINT message is only generated after the user has pressed and released the mouse button.
CLICK_DOWN_POINT
In this mode, point messages are sent on mouse-down only.
Default Implementation:
{ return mode; }
Sample Code:
A sample program that uses the override method is \MAXSDK\SAMPLES\OBJECTS\SPLINE.CPP. It uses CLICK_DOWN_POINT.
Prototype:
virtual BOOL SupportTransformGizmo();
Remarks:
This method is available in release 3.0 and later only.
Implemented by the Plug-In.
This method returns TRUE if the mouse proc supports a transform gizmo; otherwise FALSE.
This method, and DeactivateTransformGizmo() below, are normally implemented by the selection processor and the existing mouse procs. In case a special implementation is done, the following describes what needs to be done:
Since the transform gizmo is dependent on the Command Mode, the MouseCallback itself decides if it supports the use of the transform gizmo. When the node axis (or transform gizmo) is redrawn, the system will ask the command mode's mouse proc if it supports transform gizmos, and if it does, it will draw a gizmo, instead of the regular node axis.
The same things happens with the main selection processor in 3ds max. When the mouse is moved, the selection processor itself asks if the MouseCallback supports transform gizmos, and if it does, it will hit test the gizmo in a MOUSE_FREEMOVE or MOUSE_POINT message. If any of the transform gizmos hit test flags are passed into the mouse procs hit tester, the transform gizmo should be hit tested as well (using Interface::HitTestTransformGizmo())
When hit testing the gizmo, different flags will be passed in: HIT_TRANSFORMGIZMO is passed in on a MOUSE_FREEMOVE message so that the axis is hit tested and it hightlights if it is hit, but it doesn't actually switch the transform mode.
In case of a MOUSE_POINT, the flag will be HIT_SWITCH_GIZMO, and if the axis is hit, the 'hit' transform mode will be pushed on the transform mode stack.
When the mouse is released (MOUSE_POINT (pt==1), or MOUSE_ABORT, then the axis constraint should pop back to the existing one, and DeactivateTransformGizmo() is called. Inside DeactivateTransformGizmo() the normal implementation is to pop the axis mode back. It should also maintain a flag (set it if HitTestTransformGizmo() returns true and the HIT_SWITCH_GIZMO is set, and clear it in DeactivateTransformGizmo(). The flag is needed because you should not call Interface::PopAxisMode() unless the axis mode was previously popped.
Default Implementation:
{ return FALSE; }
Prototype:
virtual void DeactivateTransformGizmo();
Remarks:
This method is available in release 3.0 and later only.
Implemented by the Plug-In.
This method is called to deactivate the transform gizmo. See the note above in SupportTransformGizmo().
Default Implementation:
{}
Prototype:
virtual BOOL SupportAutoGrid();
Remarks:
This method is available in release 3.0 and later only.
Mouse procs wishing to utilize the AutoGrid feature should override this method by returning TRUE and then make the appropriate calls to the ViewExp methods TrackImpliciGrid(), CommitImplicitGrid() and ReleaseImplicitGrid() from the body of their classes proc() method. For sample code see \MAXSDK\SAMPLES\MODIFIERS\SURFWRAP\SURFWRAP.CPP.
Default Implementation:
{return FALSE;}
Prototype:
virtual BOOL TolerateOrthoMode();
Remarks:
This method is available in release 3.0 and later only.
Implemented by the Plug-In.
This method returns TRUE if Ortho Mode makes sense for this creation; FALSE if it doesn't. In general this is only TRUE for splines and such.
Default Implementation:
{return FALSE; }
Prototype:
void setMouseManager(MouseManager *mm)
Remarks:
This method is used internally.
Prototype:
MouseManager *getMouseManager()
Remarks:
This method is used internally.
The following functions are not part of this class but are available for use:
Function:
BOOL GetInMouseAbort();
Remarks:
This global function is available in release 2.0 and later only.
This function is not part of this class but is availalbe for use. It returns TRUE if any mouse proc is currently in the process of aborting a mouse proc; otherwise FALSE.
For instance, a developer may be using the Animatable::MouseCycleCompleted() method to put up a dialog box, but need to not put it up if the mouse proc was aborting. This method provides a way to know if indeed the mouse proc is aborting so the dialog won't be displayed inside MouseCycleCompleted().
Return Value:
TRUE if aborting; otherwise FALSE.
Function:
float GetPerspMouseSpeed();
Remarks:
This global function is not part of class MouseCallBack but is available for use.
Returns the mouse speed value used in perspective viewports. This value corresponds to the value that the user may set using the 3ds max command in the File / Preferences . . . Move / Rotate Transform area.
Function:
void SetPerspMouseSpeed(float speed);
Remarks:
This global function is not part of class MouseCallBack but is available for use.
Sets the mouse speed value used in perspective viewports. This value corresponds to the value that the user may set using the 3ds max command in the File / Preferences . . . Move / Rotate Transform area.
Parameters:
float speed
The value to set.
Function:
void SetMoveModeType(int moveType);
Remarks:
This global function is not part of class MouseCallBack but is available for use.
Sets the mouse move mode. This value corresponds to the value that the user may set using the 3ds max command in the File / Preferences . . . Move / Rotate Transform area.
Parameters:
int moveType
One of the following values:
MOVE_INTERSECTION
MOVE_PROJECTION
Function:
int GetMoveModeType();
Remarks:
This global function is not part of class MouseCallBack but is available for use.
Returns the mouse move mode. This value corresponds to the value that the user may set using the 3ds max command in the File / Preferences . . . Move / Rotate Transform area.
Return Value:
One of the following values:
MOVE_INTERSECTION
MOVE_PROJECTION