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:

• 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:

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. 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 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.