Developer Resources > API Guide >  Command plug-ins > 
MPxCommand
 
 
 

The new hello command introduced earlier uses a proxy object to add new functionality to Maya (see MFnPlugin). This proxy object is derived from MPxCommand which provides all the functionality necessary for Maya to use the command as if it were built in.

A minimum of two methods must be defined. These are the doIt() method and the creator. 

class hello : public MPxCommand
{
public:
 	Status doIt( const MArgList& args );
	static void* creator();
};

doIt() and redoIt() methods

The doIt() method is a pure virtual method, and since there is no creator defined in the base class, you must define both doIt() and creator.

For simple commands, the doIt() method performs the actions of the command. In more complex commands, the doIt() method parses the argument list, the selection list, and whatever else may be necessary. It then uses this information to set data internal to the command before calling the redoIt() method, which does the bulk of the work. This avoids code duplication between the doIt() and redoIt() methods.

Verifying when methods are called

The following is a simple plug-in that outputs a string when any of its methods are called by Maya. You can use it to see when the methods are called. 

#include <stdio.h>
#include <maya/MString.h>
#include <maya/MArgList.h>
#include <maya/MFnPlugin.h>
#include <maya/MPxCommand.h>
#include <maya/MIOStream.h>
class commandExample : public MPxCommand
{
public:
	commandExample();
	virtual ~commandExample();
	MStatus doIt( const MArgList& );
	MStatus redoIt();
	MStatus undoIt();
	bool isUndoable() const;
	static void* creator();
};
commandExample::commandExample() {
	cout << “In commandExample::commandExample()\n”;
}
commandExample::~commandExample() {
	cout << “In commandExample::~commandExample()\n”;
}
MStatus commandExample::doIt( const MArgList& ) {
 	out << “In commandExample::doIt()\n”;
	return MS::kSuccess;
}
MStatus commandExample::redoIt() {
	cout << “In commandExample::redoIt()\n”;
	return MS::kSuccess;
}
MStatus commandExample::undoIt() {
	cout << “In commandExample::undoIt()\n”;
	return MS::kSuccess;
}
bool commandExample::isUndoable() const {
	cout << “In commandExample::isUndoable()\n”;
	return true;
}
void* commandExample::creator() {
	cout << “In commandExample::creator()\n”;
	return new commandExample();
}
MStatus initializePlugin( MObject obj )
{
	MFnPlugin plugin( obj, “My plug-in”, “1.0”, “Any” );
	plugin.registerCommand( “commandExample”, commandExample::creator );
	cout << “In initializePlugin()\n”;
	return MS::kSuccess;
}
MStatus uninitializePlugin( MObject obj )
{
	MFnPlugin plugin( obj );
	plugin.deregisterCommand( “commandExample” );
	cout << “In uninitializePlugin()\n”;
	return MS::kSuccess;
}

               
When you first load this
                  plug-in, notice that “In initializePlugin()” is printed immediately.
                  If you then type “commandExample” in the command window you will
                  see:
               

               
In commandExample::creator()
In commandExample::commandExample()
In commandExample::doIt()
In commandExample::isUndoable()

               
Note that the destructor
                  is not called. This is because the command object remains indefinitely
                  so that it can be undone, or redone (after being undone). 
               

               
This is how Maya’s undo mechanism works. Command
                  objects maintain information which allows them to undo themselves
                  when necessary. The destructor is called when the command falls
                  off the end of the undo queue, it is undone and not redone, or the
                  plug-in is unloaded.
               

               
If you now use 
                           Edit > Undo (or
                  you use the MEL undo command) and 
                           Edit
                           > Redo (or
                  you use the MEL redo command), the undoIt() and redoIt() methods of
                  the command get called when these menu items are invoked.
               

               
If
                  you modify this example so that the isUndoable() method returns
                  false rather than true (remember to unload the plug-in before recompiling)
                  when you run it, the output becomes:
               

               
In commandExample::creator()
In commandExample::commandExample()
In commandExample::doIt()
In commandExample::isUndoable()
In commandExample::~commandExample()

               
In this case the destructor
                  is called immediately since the command cannot be undone. Maya treats
                  a non-undoable command as an action that does not affect the scene
                  in any way. This means that no information needs to be saved after
                  the command executes, and when undoing and redoing commands, it
                  does not need to be executed since it does not change anything.
               

            

            
Helix example with undo
                  and redo
               

               
The following example
                  is another implementation of the helix plug-in. This version is
                  implemented as a full command with undo and redo. It works by taking
                  a selected curve and turning it into a helix.
               

               
#include <stdio.h>
#include <math.h>
#include <maya/MFnPlugin.h>
#include <maya/MFnNurbsCurve.h>
#include <maya/MPointArray.h>
#include <maya/MDoubleArray.h>
#include <maya/MPoint.h>
#include <maya/MSelectionList.h>
#include <maya/MItSelectionList.h>
#include <maya/MItCurveCV.h>
#include <maya/MGlobal.h>
#include <maya/MDagPath.h>
#include <maya/MString.h>
#include <maya/MPxCommand.h>
#include <maya/MArgList.h>
class helix2 : public MPxCommand {
public:
	helix2();
	virtual ~helix2();
	MStatus doIt( const MArgList& );
	MStatus redoIt();
	MStatus undoIt();
	bool isUndoable() const;
	static void* creator();

               
The command starts out
                  as the previous example, declaring the methods it will be defining.
               

               
private:
	MDagPath fDagPath;
	MPointArray fCVs;
	double radius;
	double pitch;
};

               
This command will be
                  modifying the model. So that it will be able to undo the changes
                  it makes, it allocates space to store the original definition of
                  the curve. It also stores the description of the helix so that it
                  can reproduce it if the redoIt method is called.
               

               
It is important to notice
                  that the command does not store a pointer to an MObject, but rather
                  uses an MDagPath to reference the curve for undo and redo. An MObject
                  is not guaranteed to be valid the next time your command is executed.
                  As a result, if you had used an MObject, Maya would likely core dump
                  when performing your undoIt() or redoIt(). An MDagPath however, being
                  simply a description of the path to the curve, is guaranteed to
                  be correct whenever your command is executed.
               

               
void* helix2::creator() {
	return new helix2;
}

               
The creator simply returns
                  an instance of the object.
               

               
helix2::helix2() : radius( 4.0 ), pitch( 0.5 ) {}

               
The constructor initializes
                  the radius and pitch.
               

               
helix2::~helix2() {}

               
The destructor does not
                  need to do anything since the private data will be cleaned up automatically. 
               

               
NoteData owned by Maya
                     should not be deleted.
                  

               

               
MStatus helix2::doIt( const MArgList& args ) {
 MStatus status;
 // Parse the arguments.
 for ( int i = 0; i < args.length(); i++ )
 if ( MString( “-p” ) == args.asString( i, &status )
 && MS::kSuccess == status )
	{
		double tmp = args.asDouble( ++i, &status );
		if ( MS::kSuccess == status )
			pitch = tmp;
	}
	else if ( MString( “-r” ) == args.asString( i, &status )
		&& MS::kSuccess == status )
	{
		double tmp = args.asDouble( ++i, &status );
		if ( MS::kSuccess == status )
			radius = tmp;
	}
	else
	{
		MString msg = “Invalid flag: “;
		msg += args.asString( i );
		displayError( msg );
		return MS::kFailure;
	}

               
As before, this simply
                  parses the arguments passed into the doIt() method and uses them
                  to set the internal radius and pitch fields which will be used by
                  the redoIt() method. The doIt() method is the only one that receives
                  arguments. The undoIt() and redoIt() methods each take their data
                  from internal data of the command itself.
               

               
In the final else-clause, the displayError()
                  method, inherited from MPxCommand, outputs the message in the command
                  window and in the command output window. Messages output with displayError()
                  are prefixed with “Error:”. Another option is displayWarning() which
                  would prefix the message with “Warning:”.
               

               
 // Get the first selected curve from the selection list.
	MSelectionList slist;
	MGlobal::getActiveSelectionList( slist );
	MItSelectionList list( slist, MFn::kNurbsCurve, &status );
	if (MS::kSuccess != status) {
		displayError( “Could not create selection list iterator” );
		return status;
	}
	if (list.isDone()) {
		displayError( “No curve selected” );
		return MS::kFailure;
	}
	MObject component;
	list.getDagPath( fDagPath, component );

               
This code gets the first
                  curve object off the selection list. The fDagPath field of the command
                  is set to the selected object selection is covered in detail in Chapter
                  2, “Selecting with the API”).
               

               
 return redoIt();
}

               
Once the internal data
                  of the command is set, the redoIt() method is called. The doIt()
                  method could perform the necessary actions itself, but these actions
                  are always identical to those performed by redoIt() so, having doIt() call
                  redoIt() reduces code duplication.
               

               
You might wonder why
                  doIt() calls redoIt() and not the other way around. Although this
                  is possible—the redoIt() method could take the cached data and
                  turn it into an MArgList which it could then pass to doIt()—it
                  would be far less efficient.
               

               
MStatus helix2::redoIt()
{
	unsigned i, numCVs;
	MStatus status;
	MFnNurbsCurve curveFn( fDagPath );
	numCVs = curveFn.numCVs();
	status = curveFn.getCVs( fCVs );
	if ( MS::kSuccess != status )
	{
		displayError( “Could not get curve’s CVs” );
		return MS::kFailure;
	}

               
This code gets the CVs
                  from the selected curve and stores them in the command’s internal
                  MPointArray. These stored CV positions could then be used if the
                  undoIt() method is called to return the curve to its original shape.
               

               
	MPointArray points(fCVs);
	for (i = 0; i < numCVs; i++)
		points[i] = MPoint( radius * cos( (double)i ),
			pitch * (double)i, radius * sin( (double)i ) );
	status = curveFn.setCVs( points );
	if ( MS::kSuccess != status )
	{
		displayError( “Could not set new CV information” );
		fCVs.clear();
		return status;
	}

               
As with the earlier helix
                  examples, this code sets the position of the curve’s CVs so that
                  the curve forms a helix. 
               

               
	status = curveFn.updateCurve();
	if ( MS::kSuccess != status )
	{
		displayError( “Could not update curve” );
		return status;
	}

               
The
                  updateCurve() method is used to inform Maya that the geometry of
                  the curve has changed. Failing to call this method after modifying
                  geometry causes the display of the object to remain unchanged.
               

               
	return MS::kSuccess;
}

               
Returning MS::kSuccess
                  at the completion of a function indicates to Maya that the operation
                  completed successfully.
               

               
MStatus helix2::undoIt()
{
	MStatus status;
	MFnNurbsCurve curveFn( fDagPath );
	status = curveFn.setCVs( fCVs );
	if ( MS::kSuccess != status)
	{
		displayError( “Could not set old CV information” );
		return status;
	}

               
These few lines take
                  the stored CV positions (the original positions of the curve’s CVs)
                  and resets them. 
               

               
NoteYou needn’t worry
                     about the number of CVs changing, or the curve being deleted in
                     an undo function. You assume that anything done after your command
                     has been undone before your undoIt() is called. As a result the
                     model is in the same state as it was immediately after your command
                     finished.
                  

               

               
	status = curveFn.updateCurve();
	if ( MS::kSuccess != status )
	{
		displayError( “Could not update curve” );
		return status;
	}
	fCVs.clear();
	return MS::kSuccess;
}

               
The MPointArray is cleared
                  here just as a precaution.
               

               
bool helix2::isUndoable() const
{
	return true;
}

               
This command is undoable.
                  It modified the model, but an undoIt() method has been provided
                  which returns the model to the state it was in before the command
                  was run.
               

               
MStatus initializePlugin( MObject obj )
{ 
	MFnPlugin plugin( obj, “Autodesk”, “1.0”, “Any”);
	plugin.registerCommand( “helix2”, helix2::creator );
	return MS::kSuccess;
}
MStatus uninitializePlugin( MObject obj )
{
	MFnPlugin plugin( obj );
	plugin.deregisterCommand( “helix2” );
	return MS::kSuccess;
}

               
The plug-in is completed
                  with the usual initialize and uninitialize functions.
               

            

         

         
         
Please send us your comments about this page