MPxManipulatorNode Class Reference
[OpenMayaUI - API module for user interface, Proxy classes]

#include <MPxManipulatorNode.h>

Inheritance diagram for MPxManipulatorNode:

[legend]

Collaboration diagram for MPxManipulatorNode:

[legend]

List of all members.

---

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.h, and squareScaleManipContext.h.

Public Member Functions
	MPxManipulatorNode ()
virtual	~MPxManipulatorNode ()
virtual MStatus	connectToDependNode (const MObject &dependNode)
virtual void	draw (M3dView &view, const MDagPath &path, M3dView::DisplayStyle style, M3dView::DisplayStatus status)
virtual MStatus	doPress (M3dView &view)
virtual MStatus	doDrag (M3dView &view)
virtual MStatus	doRelease (M3dView &view)
MStatus	finishAddingManips ()
MStatus	colorAndName (M3dView &view, MGLuint glName, bool glNameIsPickable, short colorIndex) const
MStatus	glFirstHandle (MGLuint &firstHandle)
MStatus	glActiveName (MGLuint &glName)
MStatus	mouseRay (MPoint &linePoint, MVector &lineDirection) const
MStatus	mouseRayWorld (MPoint &linePoint, MVector &lineDirection) const
MStatus	mousePosition (short &x_pos, short &y_pos)
MStatus	mouseDown (short &x_pos, short &y_pos)
MStatus	mouseUp (short &x_pos, short &y_pos)
MStatus	addDoubleValue (const MString &valueName, double defaultValue, int &valueIndex)
MStatus	addPointValue (const MString &valueName, const MPoint &defaultValue, int &valueIndex)
MStatus	addVectorValue (const MString &valueName, const MVector &defaultValue, int &valueIndex)
MStatus	setDoubleValue (int valueIndex, double value)
MStatus	setPointValue (int valueIndex, const MPoint &value)
MStatus	setVectorValue (int valueIndex, const MVector &value)
MStatus	getDoubleValue (int valueIndex, bool previousValue, double &value)
MStatus	getPointValue (int valueIndex, bool previousValue, MPoint &value)
MStatus	getVectorValue (int valueIndex, bool previousValue, MVector &value)
MStatus	connectPlugToValue (const MPlug &plug, int valueIndex, int &plugIndex)
short	mainColor ()
short	xColor ()
short	yColor ()
short	zColor ()
short	prevColor ()
short	lineColor ()
short	dimmedColor ()
short	selectedColor ()
short	labelColor ()
short	labelBackgroundColor ()
Static Public Member Functions
static MPxManipulatorNode *	newManipulator (const MString &manipName, MObject &manipObject, MStatus *ReturnStatus=NULL)
Static Public Attributes
static MObject	connectedNodes
	Connected node, message attribute.

---

Constructor & Destructor Documentation

MPxManipulatorNode::MPxManipulatorNode

(

)

Class constructor

MPxManipulatorNode::~MPxManipulatorNode

(

)

[virtual]

Class destructor

---

Member Function Documentation

MStatus MPxManipulatorNode::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]

node

the node to which the manipulator should be connected

Returns:

MS::kSuccess if successful, an error status otherwise. The base class returns MS::kFailure if there are no connections between manip values and plug values.

Examples:

squareScaleManipContext.cpp, and squareScaleManipContext.h.

void MPxManipulatorNode::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]	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 MPxManipulatorNode::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]

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 MPxManipulatorNode::doDrag

(

M3dView &

view

)

[virtual]

This method gets called when the manipulator recieves 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 MPxManipulatorNode::doRelease

(

M3dView &

view

)

[virtual]

This method gets called when the manipulator recieves 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 MPxManipulatorNode::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:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MPxManipulatorNode::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]	view	the view that is active
[in]	glName	the unsigned int name of the object. Make unique.
[in]	glNameIsPickable	if true, the component will be pickable
[in]	colorIndex	color to use. Can call one of class color methods.

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MPxManipulatorNode::glFirstHandle

(

MGLuint &

firstHandle

)

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

Parameters:

[in]

firstHandle

returns the first handle

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MPxManipulatorNode::glActiveName

(

MGLuint &

glName

)

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

Parameters:

[in]

glName

active handle

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MPxManipulatorNode::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]	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 MPxManipulatorNode::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]	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 MPxManipulatorNode::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_pos	returns the x port coordinate
[out]	y_pos	returns the y port coordinate

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MPxManipulatorNode::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_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 MPxManipulatorNode::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_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 MPxManipulatorNode::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]	valueName	name of the value
[in]	defaultValue	default double value
[in]	valueIndex	returned value index. Used in connectPlugToValue()

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MPxManipulatorNode::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]	valueName	name of the value
[in]	defaultValue	default MPoint value
[in]	valueIndex	returned value index. Used in connectPlugToValue()

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MPxManipulatorNode::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]	valueName	name of the value
[in]	defaultValue	default MVector value
[in]	valueIndex	returned value index. Used in connectPlugToValue()

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MPxManipulatorNode::setDoubleValue	(	int	valueIndex,
		double	value
	)

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 MPxManipulatorNode::setPointValue	(	int	valueIndex,
		const MPoint &	value
	)

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 MPxManipulatorNode::setVectorValue	(	int	valueIndex,
		const MVector &	value
	)

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 MPxManipulatorNode::getDoubleValue	(	int	valueIndex,
		bool	previousValue,
		double &	value
	)

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 MPxManipulatorNode::getPointValue	(	int	valueIndex,
		bool	previousValue,
		MPoint &	value
	)

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 MPxManipulatorNode::getVectorValue	(	int	valueIndex,
		bool	previousValue,
		MVector &	value
	)

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 MPxManipulatorNode::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]	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 * 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]	manipName	manipulator name
[in]	manipObject	manipulator object

Returns:

The new manipulator

short MPxManipulatorNode::mainColor

(

)

This method returns the main color index.

short MPxManipulatorNode::xColor

(

)

This method returns the color index of the x axis.

short MPxManipulatorNode::yColor

(

)

This method returns the color index of the y axis.

short MPxManipulatorNode::zColor

(

)

This method returns the color index of the z axis.

short MPxManipulatorNode::prevColor

(

)

This method returns the previously color used by the colorAndName() method.

short MPxManipulatorNode::lineColor

(

)

This method returns the color index of a line.

short MPxManipulatorNode::dimmedColor

(

)

This method returns the color index for a dimmed or unselectable component.

short MPxManipulatorNode::selectedColor

(

)

This method returns the color index of a selected component.

short MPxManipulatorNode::labelColor

(

)

This method returns the color index of a label.

short MPxManipulatorNode::labelBackgroundColor

(

)

This method returns the color index of a label background.