Public Member Functions | Static Public Member Functions | Static Public Attributes

MPxManipulatorNode Class Reference

This reference page is linked to from the following overview topics: Extension for Autodesk Maya 2013, Writing a Manipulator, Manipulator Containers, Connect Manipulators to the Show Manipulator Tool, Removal of MStatus return codes from .NET API.


Search for all occurrences

Detailed Description

Base class for manipulator creation.

MPxManipulatorNode is the base class used for creating user-defined manipulators. This class is derived from MPxNode since manipulators in Maya are dependency nodes.

An MPxManipulatorNode should implement the following method:

virtual void draw(M3dView &view, const MDagPath &path,M3dView::DisplayStyle style, M3dView::DisplayStatus status);

Additionally, several of the following virtuals will need to be defined:

virtual MStatus doPress( M3dView& view );
virtual MStatus doDrag( M3dView& view );
virtual MStatus doRelease( M3dView& view );

Implement the following method to properly support undo:

virtual MStatus connectToDependNode(const MObject &dependNode);

The draw() method is very important since drawing and picking are done together. The colorAndName() method should be called before drawing a GL component that should be pickable. Several color methods which return color indexes that Maya use are provided to allow custom manipulators to have a similar look.

When drawing a GL pickable component, an active name must be set. Use the glFirstHandle() to get this value from the base class.

A manipulator can be connected to a depend node instead of updating a node attribute directly in one of the do*() methods. To connect to a depend node, you must:

This class can work standalone or with MPxManipContainer.

Examples:

lineManip.h, lineManipContainer.cpp, lineManipContainer.h, squareScaleManip.cpp, squareScaleManip.h, and squareScaleManipContext.h.

#include <MPxManipulatorNode.h>

Inheritance diagram for MPxManipulatorNode:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 MPxManipulatorNode ()
 Class constructor.
virtual ~MPxManipulatorNode ()
 Class destructor.
virtual MStatus connectToDependNode (const MObject &dependNode)
 This method connects the manipulator to the dependency node.
virtual void draw (M3dView &view, const MDagPath &path, M3dView::DisplayStyle style, M3dView::DisplayStatus status)
 This method is overloaded to draw the manipulators.
virtual MStatus doPress (M3dView &view)
 This method gets called when the manipulator receives a mouse down event.
virtual MStatus doDrag (M3dView &view)
 This method gets called when the manipulator receives a mouse drag event.
virtual MStatus doRelease (M3dView &view)
 This method gets called when the manipulator receives a mouse release event.
virtual MStatus doMove (M3dView &view, bool &refresh)
 This method gets called when the manipulator receives a mouse move event, if the manipulator registered for mouse move events.
MStatus finishAddingManips ()
 This method should be called from the user-defined manipulator plug-in near the end of the connectToDependNode method so that the converter in the manipulator can be initialized.
MStatus colorAndName (M3dView &view, MGLuint glName, bool glNameIsPickable, short colorIndex) const
 This method is used to set the color of the GL component that is being drawn next.
MStatus glFirstHandle (MGLuint &firstHandle)
 This method is used to find the unsigned int value that should be used for the first GL handle.
MStatus glActiveName (MGLuint &glName)
 This method returns the unsigned int value which specifies the current active handle.
MStatus mouseRay (MPoint &linePoint, MVector &lineDirection) const
 This method returns the location of the mouse within a view.
MStatus mouseRayWorld (MPoint &linePoint, MVector &lineDirection) const
 This method returns the location of the mouse within a view.
MStatus mousePosition (short &x_pos, short &y_pos)
 This method returns the current mouse position within a view.
MStatus mouseDown (short &x_pos, short &y_pos)
 This method returns the mouse down position within a view.
MStatus mouseUp (short &x_pos, short &y_pos)
 This method returns the mouse up position within a view.
MStatus registerForMouseMove ()
 This method registers this manipulator to receive mouse move events.
MStatus deregisterForMouseMove ()
 This method deregisters this manipulator from receiving mouse move events.
MStatus addDoubleValue (const MString &valueName, double defaultValue, int &valueIndex)
 Manipulators which call connectPlugToValue() must first create the value on the node.
MStatus addPointValue (const MString &valueName, const MPoint &defaultValue, int &valueIndex)
 Manipulators which call connectPlugToValue() must first create the value on the node.
MStatus addVectorValue (const MString &valueName, const MVector &defaultValue, int &valueIndex)
 Manipulators which call connectPlugToValue() must first create the value on the node.
MStatus setDoubleValue (int valueIndex, double value)
 This method is used for setting a double value associated with the manipulator.
MStatus setPointValue (int valueIndex, const MPoint &value)
 This method is used for setting an MPoint value associated with the manipulator.
MStatus setVectorValue (int valueIndex, const MVector &value)
 This method is used for setting a MVector value associated with the manipulator.
MStatus getDoubleValue (int valueIndex, bool previousValue, double &value)
 This method is used for getting a double value associated with the manipulator.
MStatus getPointValue (int valueIndex, bool previousValue, MPoint &value)
 This method is used for getting a MPoint value associated with the manipulator.
MStatus getVectorValue (int valueIndex, bool previousValue, MVector &value)
 This method is used for getting a MVector value associated with the manipulator.
MStatus connectPlugToValue (const MPlug &plug, int valueIndex, int &plugIndex)
 This method is called in the connectToDependNode() virtual if it is implemented for the custom manipulator.
MStatus addDependentPlug (const MPlug &plug)
 This method adds the plug to the list of those to be keyframed.
MStatus dependentPlugsReset ()
 This method resets the list of dependent plugs for this manipulator.
short mainColor ()
 This method returns the main color index.
short xColor ()
 This method returns the color index of the x axis.
short yColor ()
 This method returns the color index of the y axis.
short zColor ()
 This method returns the color index of the z axis.
short prevColor ()
 This method returns the previously color used by the colorAndName() method.
short lineColor ()
 This method returns the color index of a line.
short dimmedColor ()
 This method returns the color index for a dimmed or unselectable component.
short selectedColor ()
 This method returns the color index of a selected component.
short labelColor ()
 This method returns the color index of a label.
short labelBackgroundColor ()
 This method returns the color index of a label background.

Static Public Member Functions

static MPxManipulatorNodenewManipulator (const MString &manipName, MObject &manipObject, MStatus *ReturnStatus=NULL)
 This static function is used to create a user-defined manipulator.
static const char * className ()
 Returns the name of this class.

Static Public Attributes

static MObject connectedNodes
 Connected node, message attribute.

Member Function Documentation

MStatus connectToDependNode ( const MObject node) [virtual]

This method connects the manipulator to the dependency node.

This is a virtual method and needs to be overridden from the plug-in.

Parameters:
[in]nodethe node to which the manipulator should be connected
Returns:
Examples:
squareScaleManipContext.cpp, and squareScaleManipContext.h.
void draw ( M3dView view,
const MDagPath path,
M3dView::DisplayStyle  style,
M3dView::DisplayStatus  status 
) [virtual]

This method is overloaded to draw the manipulators.

Selection is also setup with this method using the colorAndName() method call.

    // Begin the drawing
    view.beginGL();

    // Place before you draw the manipulator component that can
    // be pickable.
    MGLuint glPickableItem;
    glFirstHandle( glPickableItem );

    // Top
    topName = glPickableItem;
    colorAndName( view, glPickableItem, true, mainColor() );
    gGLFT->glBegin( GL_LINES );
        gGLFT->glVertex3fv( tl );
        gGLFT->glVertex3fv( tr );
    gGLFT->glEnd();

    // Right
    glPickableItem++;
    rightName = glPickableItem;
    colorAndName( view, glPickableItem, true, mainColor() );
    gGLFT->glBegin( GL_LINES );
        gGLFT->glVertex3fv( tr );
        gGLFT->glVertex3fv( br );
    gGLFT->glEnd();

    // ...

    // End the drawing
    view.endGL();
Parameters:
[in]viewthe view in which to draw
[in]paththe current path
[in]stylethe display appearance
[in]statusthe display status
Examples:
lineManip.h, lineManipContainer.h, squareScaleManip.h, and squareScaleManipContext.h.
MStatus doPress ( M3dView view) [virtual]

This method gets called when the manipulator receives a mouse down event.

You should return kUnknownParameter to allow Maya to process the event also.

Parameters:
[in]viewthe view that is active
Returns:
Examples:
lineManip.h, lineManipContainer.h, squareScaleManip.h, and squareScaleManipContext.h.
MStatus doDrag ( M3dView view) [virtual]

This method gets called when the manipulator receives a mouse drag event.

You should return kUnknownParameter to allow Maya to process the event also.

Parameters:
[in]viewthe view that is active
Returns:
Examples:
lineManip.h, lineManipContainer.h, squareScaleManip.h, and squareScaleManipContext.h.
MStatus doRelease ( M3dView view) [virtual]

This method gets called when the manipulator receives a mouse release event.

You should return kUnknownParameter to allow Maya to process the event also.

Parameters:
[in]viewthe view that is active
Returns:
Examples:
lineManip.h, lineManipContainer.h, squareScaleManip.h, and squareScaleManipContext.h.
MStatus doMove ( M3dView view,
bool &  refresh 
) [virtual]

This method gets called when the manipulator receives a mouse move event, if the manipulator registered for mouse move events.

To register for mouse move events, invoke registerForMouseMove() in the postConstructor of your manipulator.

You should return kUnknownParameter to allow Maya to process the event also.

Parameters:
[in]viewthe view that is active
[out]refreshif true, refresh the view on this event. Default is false.
Returns:
MStatus finishAddingManips ( )

This method should be called from the user-defined manipulator plug-in near the end of the connectToDependNode method so that the converter in the manipulator can be initialized.

The converter cannot be initialized until all the connections from the manip values to the plug values have been specified.

Returns:
MStatus colorAndName ( M3dView view,
MGLuint  glName,
bool  glNameIsPickable,
short  colorIndex 
) const

This method is used to set the color of the GL component that is being drawn next.

It is also used to set GL name of the component so that picking can be supported.

Parameters:
[in]viewthe view that is active
[in]glNameGL "name" (an unsigned int) of the component. Must be unique.
[in]glNameIsPickableIf true, the component will be pickable
[in]colorIndexColor to use, as provided by one of the *Color() methods in this class.
Returns:
MStatus glFirstHandle ( MGLuint &  firstHandle)

This method is used to find the unsigned int value that should be used for the first GL handle.

Parameters:
[out]firstHandleReturns the first handle.
Returns:
MStatus glActiveName ( MGLuint &  glName)

This method returns the unsigned int value which specifies the current active handle.

Parameters:
[out]glNameactive handle
Returns:
MStatus mouseRay ( MPoint linePoint,
MVector lineDirection 
) const

This method returns the location of the mouse within a view.

The location is defined by a point and a direction through the point. Both point and direction are in local space.

Parameters:
[out]linePointlocal space line point of mouse
[out]lineDirectionlocal direction of mouse in view
Returns:
MStatus mouseRayWorld ( MPoint linePoint,
MVector lineDirection 
) const

This method returns the location of the mouse within a view.

The location is defined by a point and a direction through the point. Both point and direction are in world space.

Parameters:
[out]linePointworld space line point of mouse
[out]lineDirectionworld direction of mouse in view
Returns:
MStatus mousePosition ( short &  x_pos,
short &  y_pos 
)

This method returns the current mouse position within a view.

The position is in port coordinates.

Parameters:
[out]x_posreturns the x port coordinate
[out]y_posreturns the y port coordinate
Returns:
MStatus mouseDown ( short &  x_pos,
short &  y_pos 
)

This method returns the mouse down position within a view.

The position is in port coordinates.

Parameters:
[out]x_posreturns the mouse down x port coordinate
[out]y_posreturns the mouse down y port coordinate
Returns:
MStatus mouseUp ( short &  x_pos,
short &  y_pos 
)

This method returns the mouse up position within a view.

The position is in port coordinates.

Parameters:
[out]x_posreturns the mouse up x port coordinate
[out]y_posreturns the mouse up y port coordinate
Returns:
MStatus registerForMouseMove ( )

This method registers this manipulator to receive mouse move events.

When registered, the doMove() function will be invoked on mouse move events.

Returns:
MStatus deregisterForMouseMove ( )

This method deregisters this manipulator from receiving mouse move events.

Returns:
MStatus addDoubleValue ( const MString valueName,
double  defaultValue,
int &  valueIndex 
)

Manipulators which call connectPlugToValue() must first create the value on the node.

Use this method to create a value of double type.

Parameters:
[in]valueNameName of the value.
[in]defaultValueDefault value.
[out]valueIndexIndex assigned to this value by Maya. Used in connectPlugToValue().
Returns:
MStatus addPointValue ( const MString valueName,
const MPoint defaultValue,
int &  valueIndex 
)

Manipulators which call connectPlugToValue() must first create the value on the node.

Use this method to create a value of double MPoint.

Parameters:
[in]valueNameName of the value.
[in]defaultValueDefault value.
[out]valueIndexIndex assigned to this value by Maya. Used in connectPlugToValue().
Returns:
MStatus addVectorValue ( const MString valueName,
const MVector defaultValue,
int &  valueIndex 
)

Manipulators which call connectPlugToValue() must first create the value on the node.

Use this method to create a value of double MVector.

Parameters:
[in]valueNameName of the value.
[in]defaultValueDefault value.
[out]valueIndexIndex assigned to this value by Maya. Used in connectPlugToValue().
Returns:
MStatus setDoubleValue ( int  valueIndex,
double  value 
)

This method is used for setting a double value associated with the manipulator.

Parameters:
[in]valueIndexthe index of the value to be set
[in]valuethe value to set it to
Returns:
MStatus setPointValue ( int  valueIndex,
const MPoint value 
)

This method is used for setting an MPoint value associated with the manipulator.

Parameters:
[in]valueIndexthe index of the value to be set
[in]valuethe value to set it to
Returns:
MStatus setVectorValue ( int  valueIndex,
const MVector value 
)

This method is used for setting a MVector value associated with the manipulator.

Parameters:
[in]valueIndexthe index of the value to be set
[in]valuethe value to set it to
Returns:
MStatus getDoubleValue ( int  valueIndex,
bool  previousValue,
double &  value 
)

This method is used for getting a double value associated with the manipulator.

Parameters:
[in]valueIndexthe index of the value to be set
[in]previousValueif true, get the previous value. if false, get the current value
[out]valuereturn the double value
Returns:
MStatus getPointValue ( int  valueIndex,
bool  previousValue,
MPoint value 
)

This method is used for getting a MPoint value associated with the manipulator.

Parameters:
[in]valueIndexthe index of the value to be set
[in]previousValueif true, get the previous value. if false, get the current value
[out]valuereturn the double value
Returns:
MStatus getVectorValue ( int  valueIndex,
bool  previousValue,
MVector value 
)

This method is used for getting a MVector value associated with the manipulator.

Parameters:
[in]valueIndexthe index of the value to be set
[in]previousValueif true, get the previous value. if false, get the current value
[out]valuereturn the double value
Returns:
MStatus connectPlugToValue ( const MPlug plug,
int  valueIndex,
int &  plugIndex 
)

This method is called in the connectToDependNode() virtual if it is implemented for the custom manipulator.

It will connect a plug to an already added manipulator value of the same type.

Parameters:
[in]plugthe plug to connect the value to
[in]valueIndexthe index of the value. index is set by add*Value() method
[out]plugIndexa new index for the plug that is being connected
Returns:
MPxManipulatorNode * newManipulator ( const MString manipName,
MObject manipObject,
MStatus ReturnStatus = NULL 
) [static]

This static function is used to create a user-defined manipulator.

The manipObject argument is set to the new manipulator node. Note that the manipName argument must be the name of a manipulator derived from MPxManipulatorNode. Also note that this method creates the newManipulator, but doesn't add it to the DAG. The primary use of this method is in conjunction with MPxSelectionContext::addManipulator, to add user-defined manipulators to a context.

Parameters:
[in]manipNamemanipulator name
[out]manipObjectmanipulator object
[out]ReturnStatusStatus code.
Returns:
The new manipulator
MStatus addDependentPlug ( const MPlug plug)

This method adds the plug to the list of those to be keyframed.

The call to addDependentPlug() should happen prior to the manipulator identifying the plugs to be set. For example, if your manipulator sets plugs based on the selection list or modifier keys you could call addDependentPlug() from your doPress() method. Note that the dependentPlugsReset() method is provided to clear out the list and should be called prior to addDependentPlugs().

Parameters:
[in]plugthe plug to keyframe when using this manipulator
Returns:
MStatus dependentPlugsReset ( )

This method resets the list of dependent plugs for this manipulator.

Call this method prior to adding plugs via addDependentPlug() such as from your doPress() method.

Returns:
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

Reimplemented from MPxNode.


MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode
MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode MPxManipulatorNode