Class SimpleManipulator
See Also: Class Manipulator, Class ISimpleManipulator, Class PolyShape, Class GizmoShape, Class ReferenceTarget, Class IParamBlock2, Class INode,Class Mesh, Class Point3, Class Point2, Class ViewExp, Class IColorManager, Class Ray, Class ManipHitData, List of Marker Types
class SimpleManipulator: public Manipulator, public ISimpleManipulator
Description:
This class is available in release 4.0 and later only.
The SimpleManipulator class provides a framework for implementing many common manipulators. It provides the following services:
· It supports an arbitrary number of gizmos made from PolyShape and/or Mesh objects.
· It creates and maintains tool tips in the viewport.
· It does hit testing, display and bounding box computations of the gizmos.
· It maintains an IParamBlock2 for the parameters of the Manipulator.
This class maintains a pointer to a parameter block. If the client of SimpleManipulator uses a single parameter block then SimpleManipulator can manage all the methods associated with SubAnims and References for the client.
If the client of SimpleManipulator maintains several parameter blocks then the client must implement the methods NumSubs(), SubAnim(i), SubAnimName(i), NumRefs(), GetReference(i) and SetReference(i) and call the SimpleManipulator methods when 'i' refers to the parameters maintained by SimpleManipulator.
Samples of Manipulators can be found in the SDK, \MAXSDK\SAMPLES\MANIPULATORS.
The Function Publishing interface to SimpleManipulators is defined as:
#define SIMPLE_MANIP_INTERFACE Interface_ID(0x617c41d4, 0x6af06a5f)
The following functions are not part of this class but are available for use with it in the making of gizmo objects:
Function:
Mesh* MakeSphere(Point3& pos, float radius, int segments);
Remarks:
This global function is available in release 4.0 and later only.
Creates a new mesh sphere at the given center position with the specified radius and segments count.
Parameters:
Point3& pos
The center point for the sphere in object space.
float radius
The radius for the sphere.
int segments
The number of segments for the sphere mesh.
Return Value:
A pointer to the sphere mesh. Developers are responsible for deleting this mesh when done.
Function:
Mesh* MakeTorus(Point3& pos, float radius, float radius2, int segs, int sides);
Remarks:
This global function is available in release 4.0 and later only.
Create a mesh torus with the given center point, outer radius, inner radius, and segment counts along the two circular dimensions of the torus.
Parameters:
Point3& pos
The center point in object space.
float radius
The first radius.
float radius2
The second radius.
int segs
The segment count along the vertical circular dimension.
int sides
The segment count along the horizontal circular dimension.
Return Value:
A pointer to the torus mesh created. Developers are responsible for deleting this mesh when done with it.
Function:
Mesh* MakeBox(Point3& pos, float l, float w, float h, int lsegs, int wsegs, int hsegs);
Remarks:
This global function is available in release 4.0 and later only.
Creates a mesh box with the given center point, length, width and height as well as segment parameters.
Parameters:
Point3& pos
The box is built from this position in size along +X, +Y and +Z. This coordinate is in object space.
float l
The length of the box.
float w
The width of the box.
float h
The height of the box.
int lsegs
The number of segments in the length dimension.
int wsegs
The number of segments in the width dimension.
int hsegs
The number of segments in the height dimension.
Return Value:
A pointer to the box mesh. Developers are responsible for deleting this mesh when done.
Function:
void AddCubeShape(PolyShape& shape, Point3& pos, float size);
Remarks:
This global function is available in release 4.0 and later only.
Creates a new series of lines in the form of a cube and adds it to the specified PolyShape with the given position and side length size.
Parameters:
PolyShape& shape
The PolyShape to add the box shape to.
Point3& pos
The position for the center of the cube shape in object space.
float size
The size of one side of the cube in object space.
Data Members:
protected:
int mDispSelectedIndex;
The Index of manipulator that the mouse is over, for display.
TSTR mToolTip;
The tooltip text.
float mGizmoScale;
The scaling factor of the gizmo.
IParamBlock2 *mpPblock;
The Parameter Block 2 for the manipulator.
RefTargetHandle mhTarget;
The handle to the manipulator reference target.
MouseState mState;
The state of the mouse, which is one of the following:
kMouseIdle
The mouse is idle, manipulator not active and the mouse is not over it.
kMouseDragging
The mouse is currently dragging the manipulator.
kMouseOverManip
The mouse is over the manipulator, but it is not being dragged.
BOOL mActiveViewOnly;
This flag defines whether the manipulator is shown in the active viewport only.
Interval mValid;
The validity interval of the reference.
Methods:
public:
Prototype:
SimpleManipulator();
Remarks:
Constructor.
Prototype:
SimpleManipulator(INode* pNode);
Remarks:
Constructor.
Prototype:
~SimpleManipulator();
Remarks:
Destructor.
Prototype:
void ClearPolyShapes();
Remarks:
Implemented by the system.
Removes all of the current gizmos in the manipulator. This is normally called at the top of UpdateShapes() to clear out any previous gizmos before creating new ones.
Prototype:
void AppendPolyShape(PolyShape* pPolyShape, DWORD flags = 0, Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS), Point3& selColor = GetSubSelColor());
Remarks:
Implemented by the system.
This method adds a new PolyShape gizmo to the manipulator. The shape is defined in the local coordinates of the node that owns the manipulator.
Parameters:
PolyShape* pPolyShape
A pointer to the poly shape to add.
DWORD flags = 0
The flags can have one or more of the following values:
kGizmoDontDisplay;
Tells the gizmo not to display. It will still hit test it.
kGizmoDontHitTest;
Tells the gizmo not to hit test. It will still display.
kGizmoScaleToViewport;
Tells the gizmo to scale itself to have a constant size in the viewport. In this case, the system uses the ManipulatorGizmo::mGizmoSize to determine how big the manipulator should be. It interprets mGizmoSize as pixels it this case. This flag only applies to mesh gizmo currently.
Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS)
The color of the gizmo when unselected.
Point3& selColor = GetSubSelColor()
The color of the gizmo when selected.
Prototype:
void AppendGizmo(GizmoShape* pGizmoShape, DWORD flags = 0, Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS), Point3& selColor = GetSubSelColor());
Remarks:
Implemented by the system.
This method adds a new GIzmoShape to the manipulator. The shape is defined in the local coordinates of the node that owns the manipulator.
Parameters:
GizmoShape* pGizmoShape
A pointer to the gizmo shape to add.
DWORD flags = 0
The flags can have one or more of the following values:
kGizmoDontDisplay;
Tells the gizmo not to display. It will still hit test it.
kGizmoDontHitTest;
Tells the gizmo not to hit test. It will still display.
kGizmoScaleToViewport;
Tells the gizmo to scale itself to have a constant size in the viewport. In this case, the system uses the ManipulatorGizmo::mGizmoSize to determine how big the manipulator should be. It interprets mGizmoSize as pixels it this case. This flag only applies to mesh gizmo currently.
Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS)
The color of the gizmo when unselected.
Point3& selColor = GetSubSelColor()
The color of the gizmo when selected.
Prototype:
void AppendMesh(Mesh* pMesh, DWORD flags = 0, Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS), Point3& selColor = GetSubSelColor());
Remarks:
Implemented by the system.
This method adds a new Mesh to the manipulator. The shape is defined in the local coordinates of the node that owns the manipulator.
Parameters:
Mesh* pMesh
A pointer to the mesh to add.
DWORD flags = 0
The flags can have one or more of the following values:
kGizmoDontDisplay;
Tells the gizmo not to display. It will still hit test it.
kGizmoDontHitTest;
Tells the gizmo not to hit test. It will still display.
kGizmoScaleToViewport;
Tells the gizmo to scale itself to have a constant size in the viewport. In this case, the system uses the ManipulatorGizmo::mGizmoSize to determine how big the manipulator should be. It interprets mGizmoSize as pixels it this case. This flag only applies to mesh gizmo currently.
Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS)
The color of the gizmo when unselected.
Point3& selColor = GetSubSelColor()
The color of the gizmo when selected.
Prototype:
void AppendMarker(MarkerType markerType, Point3& position, DWORD flags = 0, Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS), Point3& selColor = GetSubSelColor());
Remarks:
Implemented by the system.
This method adds a new Marker to the manipulator. The shape is defined in the local coordinates of the node that owns the manipulator.
Parameters:
MarkerType markerType
The marker type for marker gizmos. See the List of Marker Types
Point3& position
The position of the marker.
DWORD flags = 0
The flags can have one or more of the following values:
kGizmoDontDisplay;
Tells the gizmo not to display. It will still hit test it.
kGizmoDontHitTest;
Tells the gizmo not to hit test. It will still display.
kGizmoScaleToViewport;
Tells the gizmo to scale itself to have a constant size in the viewport. In this case, the system uses the ManipulatorGizmo::mGizmoSize to determine how big the manipulator should be. It interprets mGizmoSize as pixels it this case. This flag only applies to mesh gizmo currently.
Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS)
The color of the gizmo when unselected.
Point3& selColor = GetSubSelColor()
The color of the gizmo when selected.
Prototype:
void AppendText(TCHAR* pText, Point3& position, DWORD flags = 0, Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS), Point3& selColor = GetSubSelColor());
Remarks:
Implemented by the system.
This method adds a new Text to the manipulator. The shape is defined in the local coordinates of the node that owns the manipulator.
Parameters:
TCHAR* pText
The text string to add.
Point3& position
The position of the text.
DWORD flags = 0
The flags can have one or more of the following values:
kGizmoDontDisplay;
Tells the gizmo not to display. It will still hit test it.
kGizmoDontHitTest;
Tells the gizmo not to hit test. It will still display.
kGizmoScaleToViewport;
Tells the gizmo to scale itself to have a constant size in the viewport. In this case, the system uses the ManipulatorGizmo::mGizmoSize to determine how big the manipulator should be. It interprets mGizmoSize as pixels it this case. This flag only applies to mesh gizmo currently.
Point3& unselColor = GetUIColor(COLOR_SEL_GIZMOS)
The color of the gizmo when unselected.
Point3& selColor = GetSubSelColor()
The color of the gizmo when selected.
Prototype:
TSTR& GetManipName();
Remarks:
Implemented by the system.
This method returns the manipulator name.
Prototype:
void SetGizmoScale(float gizmoScale);
Remarks:
Implemented by the system.
This method allows you to set the scale of the gizmo.
Parameters:
float gizmoScale
The scale factor.
Prototype:
TSTR& GetToolTip();
Remarks:
Implemented by the system.
This method returns the tooltip string. Used internally.
Default Implementation:
{ return mToolTip; }
Prototype:
void SetToolTipWnd(HWND hWnd);
Remarks:
Implemented by the system.
Used internally.
Prototype:
void SetToolTipTimer(UINT timer);
Remarks:
Implemented by the system.
Used internally.
Prototype:
UINT GetToolTipTimer();
Remarks:
Implemented by the system.
Used internally.
Prototype:
HWND GetToolTipWnd();
Remarks:
Implemented by the system.
Used internally.
Prototype:
IParamBlock2* GetPBlock();
Remarks:
Implemented by the system.
This method returns a pointer to the parameter block.
Default Implementation:
{ return mpPblock; }
These must be implemented in the sub-class of SimpleManipulator
Prototype:
virtual void UpdateShapes(TimeValue t, TSTR& toolTip) = 0;
Remarks:
Implemented by the Plug-In.
This method gets called whenever the manipulator needs to update its gizmos. This is implemented by the manipulator to create the gizmos based on the current state of the node being manipulated.
Parameters:
TimeValue t
The time at which to update the shape.
TSTR& toolTip
The tool tip text to update.
Prototype:
virtual void ManipulatorSelected();
Remarks:
Implemented by the system.
Used internally.
Default Implementation:
{}
Prototype:
void SetManipTarget(RefTargetHandle hTarg);
Remarks:
Implemented by the system.
This tells the SimpleManipulator to make a reference to hTarg. This is normally called in the contructor of a manipulator to set a reference to whatever is being manipulated.
Parameters:
RefTargetHandle hTarg
The handle to the reference target.
Prototype:
RefTargetHandle GetManipTarget();
Remarks:
This method returns the handle to the manipulator reference target.
Default Implementation:
{ return mhTarget; }
Prototype:
void SetMouseState(MouseState state);
Remarks:
This method sets the state of the mouse.
Parameters:
MouseState state
One of the following values:
kMouseIdle
The mouse is idle, manipulator not active and the mouse is not over it.
kMouseDragging
The mouse is currently dragging the manipulator.
kMouseOverManip
The mouse is over the manipulator, but it is not being dragged.
Default Implementation:
{ mState = state; }
Prototype:
MouseState GetMouseState();
Remarks:
Implemented by the system.
This method returns the state of the mouse, which is one of the following values: kMouseIdle, kMouseDragging, or kMouseOverManip.
Default Implementation:
{ return mState; }
Prototype:
void OnButtonDown(TimeValue t, ViewExp* pVpt, IPoint2& m, DWORD flags, ManipHitData* pHitData);
Remarks:
Implemented by the system.
This method gets called when the mouse buttons is pressed within the manipulator context. Used internally.
Parameters:
TimeValue t
The time to display the object.
ViewExp* pVpt
An interface that may be used to call methods associated with the viewports.
IPoint2& m
The location of the tooltip.
DWORD flags
Not used, should be set to 0.
ManipHitData* pHitData
A pointer to the hitdata containing information on which manipulator was hit.
Prototype:
void OnMouseMove(TimeValue t, ViewExp* pVpt, IPoint2& m, DWORD flags, ManipHitData* pHitData);
Remarks:
This method gets called when the mouse is pressed down and moves within the manipulator context. It is the method that does the actual manipulator. It is up to the manipulator code to turn the mouse position into a new value for the parameter(s) being manipulated. It also updates the tooltip with the current value of the parameter.
Parameters:
TimeValue t
The time to display the object.
ViewExp* pVpt
An interface that may be used to call methods associated with the viewports.
IPoint2& m
The location of the tooltip.
DWORD flags
Not used, should be set to 0.
ManipHitData* pHitData
A pointer to the hitdata containing information on which manipulator was hit.
Prototype:
void OnButtonUp(TimeValue t, ViewExp* pVpt, IPoint2& m, DWORD flags, ManipHitData* pHitData);
Remarks:
Implemented by the system.
This method gets called when the mouse buttons is released within the manipulator context. Used internally.
Parameters:
TimeValue t
The time to display the object.
ViewExp* pVpt
An interface that may be used to call methods associated with the viewports.
IPoint2& m
The location of the tooltip.
DWORD flags
Not used, should be set to 0.
ManipHitData* pHitData
A pointer to the hitdata containing information on which manipulator was hit.
Prototype:
DisplayState MouseEntersObject(TimeValue t, ViewExp* pVpt, IPoint2& m, ManipHitData* pHitData);
Remarks:
Implemented by the system.
This method gets called when the mouse enters the manipulator object. Used interlally.
Parameters:
TimeValue t
The time to display the object.
ViewExp* pVpt
An interface that may be used to call methods associated with the viewports.
IPoint2& m
The location of the tooltip.
ManipHitData* pHitData
A pointer to the hitdata containing information on which manipulator was hit.
Return Value:
The display state indicating whether no redraw, a full redraw, or a post redraw is needed.
Prototype:
DisplayState MouseLeavesObject(TimeValue t, ViewExp* pVpt, IPoint2& m, ManipHitData* pHitData);
Remarks:
Implemented by the system.
This method gets called when the mouse leaves the manipulator object. Used internally.
Parameters:
TimeValue t
The time to display the object.
ViewExp* pVpt
An interface that may be used to call methods associated with the viewports.
IPoint2& m
The location of the tooltip.
ManipHitData* pHitData
A pointer to the hitdata containing information on which manipulator was hit.
Return Value:
The display state indicating whether no redraw, a full redraw, or a post redraw is needed.
Prototype:
IPoint2& GetTipPos();
Remarks:
Implemented by the system.
This method returns the position of the tooltip. Used internally.
Default Implementation:
{ return mToolTipPos; }
Prototype:
void GetLocalViewRay(ViewExp* pVpt, IPoint2& m, Ray& viewRay);
Remarks:
This method is normally called from a manipualtor's OnMouseMove method. It computes a ray that passes through the given mouse point in the given viewport. The result is in the local coordinates of the node owning the manipulator.
Parameters:
ViewExp* pVpt
An interface that may be used to call methods associated with the viewports.
IPoint2& m
The screen coordinate.
Ray& viewRay
The returned local view ray.
Prototype:
Invalidate();
Remarks:
This method invalidates the validity interval.
Default Implementation:
{ mValid = NEVER; }
Prototype:
void UnRegisterViewChange();
Remarks:
This method unregister the notifications so changes in the view are no longer registered.
Prototype:
void SetResettingFlag(BOOL val);
Remarks:
Used internally.
Prototype:
BOOL GetResettingFlag();
Remarks:
Used internally.
Prototype:
void KillToolTip();
Remarks:
This method will destroy the tooltip and its timer and cleans up.
Prototype:
Point3 GetUnselectedColor();
Remarks:
This method returns the color of the gizmo when unselected.