- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

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

# MPxManipulatorNode Class Reference
OpenMayaUI - API module for user interface | Proxy classes

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, 3.9 UI draw manager, 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.

To draw the manipulator in Viewport 2.0, the plugin must also implement preDrawUI() and drawUI(). Note that selection relies on the default viewport draw pass so the draw() method must still be implemented even if the manipulator is not intended for use in the default viewport. preDrawUI() is called before drawUI() and should be used to prepare and cache data which will be needed to draw the manipulator in drawUI().

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:

- Call add*Value() in the postConstructor() of the node
- Call conectPlugToValue() in connectToDependNode()
- Call set*Value() in one of the do*() virtuals

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:
[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 | preDrawUI (const M3dView &view)
| This method is not available in Python.
virtual void | drawUI (MHWRender::MUIDrawManager &drawManager, const MHWRender::MFrameContext &frameContext) const
| This method is not available in Python.
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. Search for all occurrences
short | xColor ()
| This method returns the color index of the x axis. Search for all occurrences
short | yColor ()
| This method returns the color index of the y axis. Search for all occurrences
short | zColor ()
| This method returns the color index of the z axis. Search for all occurrences
short | prevColor ()
| This method returns the previously color used by the colorAndName() method. Search for all occurrences
short | lineColor ()
| This method returns the color index of a line. Search for all occurrences
short | dimmedColor ()
| This method returns the color index for a dimmed or unselectable component. Search for all occurrences
short | selectedColor ()
| This method returns the color index of a selected component. Search for all occurrences
short | labelColor ()
| This method returns the color index of a label. Search for all occurrences
short | labelBackgroundColor ()
| This method returns the color index of a label background.
## Static Public Member Functions
static MPxManipulatorNode * | newManipulator (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 Search for all occurrences
static MObject | connectedNodes
| Connected node, message attribute. Search for all occurrences

## Member Function Documentation

MStatus connectToDependNode | ( | const MObject & | node | ) | `[virtual]`

Search for all occurrences

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] | node | the node to which the manipulator should be connected

Returns:
  - MS::kSuccess Operation successful
  - MS::kFailure If there are no connections between manipulator values and plug values

Examples:
  squareScaleManipContext.cpp, and squareScaleManipContext.h.

void preDrawUI | ( | const M3dView & | view | ) | `[virtual]`

Search for all occurrences

This method is not available in Python.

This method is used to setup some drawing data for drawing the manipulator in Viewport 2.0 .

The data updated and cached in this function will be used later during 'drawUI()'.

This method is only called when the manipulator needs to be drawn in Viewport 2.0.

This method need only be overridden if custom data is needed for drawing in drawUI(). If no such data is needed, this method may be left unimplemented.

This function is empty in this base class.

Parameters:

  [in] | view | The view in which to draw

Examples:
  lineManip.h.

void drawUI | ( | MHWRender::MUIDrawManager & | drawManager,
|  | const MHWRender::MFrameContext & | frameContext
| ) |  | const`[virtual]`

Search for all occurrences

This method is not available in Python.

This is the primary method for drawing the manipulator in Viewport 2.0.

All drawing should occur using the MUIDrawManager and any data cached in preDrawUI(). Raw OpenGL calls are not supported and if used behaviour will be undefined. Selection must still be handled in the draw() method, this method is only for display.

This method is only called when the manipulator needs to be drawn in Viewport 2.0.

This function is empty in this base class.

Parameters:

  [in] | drawManager | The MUIDrawManager used to draw some simple UI
  [in] | frameContext | Frame level context information

Examples:
  lineManip.h.

void draw | ( | M3dView & | view,
|  | const MDagPath & | path,
|  | M3dView::DisplayStyle | style,
|  | M3dView::DisplayStatus | status
| ) |  | `[virtual]`

Search for all occurrences

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] | view | the view in which to draw
  [in] | path | the current path
  [in] | style | the display appearance
  [in] | status | the display status

Examples:
  lineManip.h, lineManipContainer.h, squareScaleManip.h, and squareScaleManipContext.h.

MStatus doPress | ( | M3dView & | view | ) | `[virtual]`

Search for all occurrences

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] | view | the view that is active

Returns:
  - MS::kSuccess Operation successful
  - MS::kUnknownParameter Allow Maya to process event

Examples:
  lineManip.h, lineManipContainer.h, squareScaleManip.h, and squareScaleManipContext.h.

MStatus doDrag | ( | M3dView & | view | ) | `[virtual]`

Search for all occurrences

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] | view | the view that is active

Returns:
  - MS::kSuccess Operation successful
  - MS::kUnknownParameter Allow Maya to process event

Examples:
  lineManip.h, lineManipContainer.h, squareScaleManip.h, and squareScaleManipContext.h.

MStatus doRelease | ( | M3dView & | view | ) | `[virtual]`

Search for all occurrences

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] | view | the view that is active

Returns:
  - MS::kSuccess Operation successful
  - MS::kUnknownParameter Allow Maya to process event

Examples:
  lineManip.h, lineManipContainer.h, squareScaleManip.h, and squareScaleManipContext.h.

MStatus doMove | ( | M3dView & | view,
|  | bool & | refresh
| ) |  | `[virtual]`

Search for all occurrences

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] | view | the view that is active
  [out] | refresh | if true, refresh the view on this event. Default is false.

Returns:
  - MS::kSuccess Operation successful
  - MS::kUnknownParameter Allow Maya to process event

MStatus finishAddingManips | ( |  | ) |

Search for all occurrences

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:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus colorAndName | ( | M3dView & | view,
|  | MGLuint | glName,
|  | bool | glNameIsPickable,
|  | short | colorIndex
| ) |  | const

Search for all occurrences

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] | view | the view that is active
  [in] | glName | GL "name" (an unsigned int) of the component. Must be unique.
  [in] | glNameIsPickable | If true, the component will be pickable
  [in] | colorIndex | Color to use, as provided by one of the *Color() methods in this class.

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus glFirstHandle | ( | MGLuint & | firstHandle | ) |

Search for all occurrences

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

Parameters:

  [out] | firstHandle | Returns the first handle.

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus glActiveName | ( | MGLuint & | glName | ) |

Search for all occurrences

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

Parameters:

  [out] | glName | active handle

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus mouseRay | ( | MPoint & | linePoint,
|  | MVector & | lineDirection
| ) |  | const

Search for all occurrences

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] | linePoint | local space line point of mouse
  [out] | lineDirection | local direction of mouse in view

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus mouseRayWorld | ( | MPoint & | linePoint,
|  | MVector & | lineDirection
| ) |  | const

Search for all occurrences

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] | linePoint | world space line point of mouse
  [out] | lineDirection | world direction of mouse in view

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus mousePosition | ( | short & | x_pos,
|  | short & | y_pos
| ) |  |

Search for all occurrences

This method returns the current mouse position within a view.

The position is in port coordinates.

Parameters:

  [out] | x_pos | returns the x port coordinate
  [out] | y_pos | returns the y port coordinate

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus mouseDown | ( | short & | x_pos,
|  | short & | y_pos
| ) |  |

Search for all occurrences

This method returns the mouse down position within a view.

The position is in port coordinates.

Parameters:

  [out] | x_pos | returns the mouse down x port coordinate
  [out] | y_pos | returns the mouse down y port coordinate

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus mouseUp | ( | short & | x_pos,
|  | short & | y_pos
| ) |  |

Search for all occurrences

This method returns the mouse up position within a view.

The position is in port coordinates.

Parameters:

  [out] | x_pos | returns the mouse up x port coordinate
  [out] | y_pos | returns the mouse up y port coordinate

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus registerForMouseMove | ( |  | ) |

Search for all occurrences

This method registers this manipulator to receive mouse move events.

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

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus deregisterForMouseMove | ( |  | ) |

Search for all occurrences

This method deregisters this manipulator from receiving mouse move events.

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

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

Search for all occurrences

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

Use this method to create a value of double type.

Parameters:

  [in] | valueName | Name of the value.
  [in] | defaultValue | Default value.
  [out] | valueIndex | Index assigned to this value by Maya. Used in connectPlugToValue().

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus addPointValue | ( | const MString & | valueName,
|  | const MPoint & | defaultValue,
|  | int & | valueIndex
| ) |  |

Search for all occurrences

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

Use this method to create a value of double MPoint.

Parameters:

  [in] | valueName | Name of the value.
  [in] | defaultValue | Default value.
  [out] | valueIndex | Index assigned to this value by Maya. Used in connectPlugToValue().

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus addVectorValue | ( | const MString & | valueName,
|  | const MVector & | defaultValue,
|  | int & | valueIndex
| ) |  |

Search for all occurrences

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

Use this method to create a value of double MVector.

Parameters:

  [in] | valueName | Name of the value.
  [in] | defaultValue | Default value.
  [out] | valueIndex | Index assigned to this value by Maya. Used in connectPlugToValue().

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus setDoubleValue | ( | int | valueIndex,
|  | double | value
| ) |  |

Search for all occurrences

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

Parameters:

  [in] | valueIndex | the index of the value to be set
  [in] | value | the value to set it to

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus setPointValue | ( | int | valueIndex,
|  | const MPoint & | value
| ) |  |

Search for all occurrences

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

Parameters:

  [in] | valueIndex | the index of the value to be set
  [in] | value | the value to set it to

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus setVectorValue | ( | int | valueIndex,
|  | const MVector & | value
| ) |  |

Search for all occurrences

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

Parameters:

  [in] | valueIndex | the index of the value to be set
  [in] | value | the value to set it to

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus getDoubleValue | ( | int | valueIndex,
|  | bool | previousValue,
|  | double & | value
| ) |  |

Search for all occurrences

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

Parameters:

  [in] | valueIndex | the index of the value to be set
  [in] | previousValue | if true, get the previous value. if false, get the current value
  [out] | value | return the double value

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus getPointValue | ( | int | valueIndex,
|  | bool | previousValue,
|  | MPoint & | value
| ) |  |

Search for all occurrences

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

Parameters:

  [in] | valueIndex | the index of the value to be set
  [in] | previousValue | if true, get the previous value. if false, get the current value
  [out] | value | return the double value

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus getVectorValue | ( | int | valueIndex,
|  | bool | previousValue,
|  | MVector & | value
| ) |  |

Search for all occurrences

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

Parameters:

  [in] | valueIndex | the index of the value to be set
  [in] | previousValue | if true, get the previous value. if false, get the current value
  [out] | value | return the double value

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MStatus connectPlugToValue | ( | const MPlug & | plug,
|  | int | valueIndex,
|  | int & | plugIndex
| ) |  |

Search for all occurrences

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] | plug | the plug to connect the value to
  [in] | valueIndex | the index of the value. index is set by add*Value() method
  [out] | plugIndex | a new index for the plug that is being connected

Returns:
  - MS::kSuccess operation successful
  - MS::kFailure operation failed

MPxManipulatorNode * newManipulator | ( | const MString & | manipName,
|  | MObject & | manipObject,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

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] | manipName | manipulator name
  [out] | manipObject | manipulator object
  [out] | ReturnStatus | Status code.

Returns:
  The new manipulator

MStatus addDependentPlug | ( | const MPlug & | plug | ) |

Search for all occurrences

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] | plug | the plug to keyframe when using this manipulator

Returns:
  - MS::kSuccess Operation successful
  - MS::kFailure Invalid object

MStatus dependentPlugsReset | ( |  | ) |

Search for all occurrences

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:
  - MS::kSuccess Operation successful
  - MS::kFailure Invalid object

const char * className | ( |  | ) | `[static]`

Search for all occurrences

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