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

The MPxToolCommand is the base class for creating commands that can be executed from within a context. Tool commands are similar to regular commands in that they are defined with command flags and can be executed from the Maya command line. However, they must perform extra duties, as the actions taken by a context do not come from the normal Maya command mechanism but from inside the methods of the MPxContext class. These duties are to alert Maya of the execution of the command so that the undo/redo and journalling mechanisms operate correctly on the command. The MPxToolCommand is a subclass of MPxCommand with the additional methods.

If a context wants to perform its own command, it must register the command when the context and context command are registered. A context can only have one tool command associated with it.

The following is an example of a tool command, the helixTool. As with the marqueeTool, the list of include files is omitted for brevity. See the helixTool.cpp file in devkit/plug-ins for the complete example. 

#define NUMBER_OF_CVS 20
class helixTool : public MPxToolCommand
{
public:
 helixTool(); 
 virtual ~helixTool(); 
 static void* creator();
 MStatus doIt( const MArgList& args );
 MStatus redoIt();
 MStatus undoIt();
 bool isUndoable() const;
 MStatus finalize();
 static MSyntax newSyntax();

         
The
            set of methods on MPxToolCommand are similar to those on MPxCommand
            but with the addition of finalize(). The finalize method is used
            to create a string representing the command and its arguments.
         

         
 void setRadius( double newRadius );
 void setPitch( double newPitch );
 void setNumCVs( unsigned newNumCVs );
 void setUpsideDown( bool newUpsideDown );

         
These methods are necessary
            since the properties of the helix will be set from the context object.
         

         
private:
 double radius; // Helix radius
 double pitch; // Helix pitch
 unsigned numCV; // Helix number of CVs
 bool upDown; // Helis upsideDown
 MDagPath path; // Dag path to the curve.
 // Don’t save the pointer!
};
void* helixTool::creator()
{
 return new helixTool;
}
helixTool::~helixTool() {}

         
These first two methods
            are identical to the earlier “helix2” example.
         

         
helixTool::helixTool()
{ 
 numCV = NUMBER_OF_CVS;
 upDown = false;
 setCommandString( “helixToolCmd” );
}

         
The constructor saves
            away the name of the MEL command for later use in the finalize()
            method.
         

         
MSyntax helixTool::newSyntax()
{
 MSyntax syntax;
 syntax.addFlag(kPitchFlag, kPitchFlagLong,
 MSyntax::kDouble);
 syntax.addFlag(kRadiusFlag, kRadiusFlagLong,
 MSyntax::kDouble);
 syntax.addFlag(kNumberCVsFlag, kNumberCVsFlagLong,
 MSyntax::kUnsigned);
 syntax.addFlag(kUpsideDownFlag, kUpsideDownFlagLong,
 MSyntax::kBoolean);
 return syntax;
}
MStatus helixTool::doIt( const MArgList &args )
{
 MStatus status;
 
 status = parseArgs(args);
 if (MS::kSuccess != status)
 return status;
 return redoIt();
}
MStatus helixTool::parseArgs(const MArgList &args)
{
 MStatus status;
 MArgDatabase argData(syntax(), args);
 if (argData.isFlagSet(kPitchFlag)) {
 double tmp;
 status = argData.getFlagArgument(kPitchFlag, 0, tmp);
 if (!status) {
 status.perror("pitch flag parsing failed.");
 return status;
 }
 pitch = tmp;
 }
 if (argData.isFlagSet(kRadiusFlag)) {
 double tmp;
 status = argData.getFlagArgument(kRadiusFlag, 0, tmp);
 if (!status) {
 status.perror("radius flag parsing failed.");
 return status;
 }
 radius = tmp;
 }
 if (argData.isFlagSet(kNumberCVsFlag)) {
 unsigned tmp;
 status = argData.getFlagArgument(kNumberCVsFlag,
 0, tmp);
 if (!status) {
 status.perror("numCVs flag parsing failed.");
 return status;
 }
 numCV = tmp;
 }
 if (argData.isFlagSet(kUpsideDownFlag)) {
 bool tmp;
 status = argData.getFlagArgument(kUpsideDownFlag,
 0, tmp);
 if (!status) {
 status.perror("upside down flag parsing failed.");
 return status;
 }
 upDown = tmp;
 }
 return MS::kSuccess;
}

         
This method is similar
            to the earlier helix example—it parses the arguments and
            uses them to set its internal state. In general, this command will
            be used through the UI, but since it is still a MEL command, it
            can be invoked from the MEL command shell.
         

         
MStatus helixTool::redoIt()
{
 MStatus stat;
 const unsigned deg = 3; // Curve Degree
 const unsigned ncvs = NUMBER_OF_CVS;// Number of CVs
 const unsigned spans = ncvs - deg; // Number of spans
 const unsigned nknots = spans+2*deg-1;// Number of knots
 unsigned i;
 MPointArray controlVertices;
 MDoubleArray knotSequences;
 int upFactor;
 if (upDown) upFactor = -1;
 else upFactor = 1;
 // Set up cvs and knots for the helix
 //
 for (i = 0; i < ncvs; i++)
 controlVertices.append( MPoint(
 radius * cos( (double)i ),
 upFactor * pitch * (double)i,
 radius * sin( (double)i ) ) );
 for (i = 0; i < nknots; i++)
 knotSequences.append( (double)i );
 // Now create the curve
 //
 MFnNurbsCurve curveFn;
 MObject curve = curveFn.create( controlVertices,
 knotSequences, deg, MFnNurbsCurve::kOpen,
 false, false, MObject::kNullObj, &stat );
 if ( !stat )
 {
 stat.perror(“Error creating curve”);
 return stat;
 }
 stat = curveFn.getPath( path );
 return stat;
}

         
This is essentially the
            same as the earlier helix example. 
         

         
MStatus helixTool::undoIt()
{
 MStatus stat; 
 MObject transform = path.transform();
 stat = MGlobal::removeFromModel( transform );
 return stat;
}

         
Again this is essentially
            the same as the earlier helix example. You should be noticing a
            pattern developing. It is quite easy to change a command into a tool.
            Little of the command has to be changed, additions just have to
            be made to hook the tool up to the UI.
         

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

         
This tool is undoable.
         

         
MStatus helixTool::finalize()
{
 MArgList command;
 command.addArg( commandString() );
 command.addArg( MString(kRadiusFlag) );
 command.addArg( radius );
 command.addArg( MString(kPitchFlag) );
 command.addArg( pitch );
 command.addArg( MString(kNumberCVsFlag) );
 command.addArg( (int)numCV );
 command.addArg( MString(kUpsideDownFlag) );
 command.addArg( upDown );
 return MPxToolCommand::doFinalize( command );
}

         
This
            method is the one noticeable addition to the tool which wasn’t necessary
            in the command. When a command is typed in it is easy to take it
            and print it out to a journal file. Since a tool is not typed in,
            but created through mouse input, no text string exists to be output
            to a journal file. The finalize() method solves this by outputting
            a string when the tool has completed. It is necessary for you to
            call MPxToolCommand::doFinalize() to have the command output to
            the journal file.
         

         
void helixTool::setRadius( double newRadius )
{
 radius = newRadius;
}
void helixTool::setPitch( double newPitch )
{
 pitch = newPitch;
}
void helixTool::setNumCVs( unsigned newNumCVs )
{
 numCV = newNumCVs;
}
void helixTool::setUpsideDown( double newUpsideDown )
{
 upDown = newUpsideDown;
}
const char helpString[] = “Click and drag to draw helix”;
class helixContext : public MPxContext
{

         
This is the context which
            will be executing the helixTool command.
         

         
public:
 helixContext();
 virtual void toolOnSetup( MEvent & event );
 virtual MStatus doPress( MEvent & event );
 virtual MStatus doDrag( MEvent & event );
 virtual MStatus doRelease( MEvent & event );
 virtual MStatus doEnterRegion( MEvent & event );

         
The set of methods are
            the same as for the marqueeTool example.
         

         
private:
 short startPos_x, startPos_y;
 short endPos_x, endPos_y;
 unsigned numCV;
 bool upDown;
 M3dView view;
 GLdouble height,radius;
};
helixContext::helixContext() 
{
 setTitleString( “Helix Tool” );
}
void helixContext::toolOnSetup( MEvent & )
{
 setHelpString( helpString );
}
MStatus helixContext::doPress( MEvent & event )
{
 event.getPosition( startPos_x, startPos_y );
 view = MGlobal::active3dView();
 view.beginGL();
 view.beginOverlayDrawing();
 return MS::kSuccess;
}

         
These three methods are
            essentially the same as the marqueeTool examples, the only difference
            being that doPress() for the helixTool does not need to determine
            the modifier key state.
         

         
MStatus helixContext::doDrag( MEvent & event )
{
 event.getPosition( endPos_x, endPos_y );
 view.clearOverlayPlane();
 glIndexi( 2 );
 int upFactor;
 if (upDown) upFactor = 1;
 else upFactor = -1;
 // Draw the guide cylinder
 //
 glMatrixMode( GL_MODELVIEW );
 glPushMatrix();
 glRotatef( upFactor * 90.0, 1.0f, 0.0f, 0.0f );
 GLUquadricObj *qobj = gluNewQuadric();
 gluQuadricDrawStyle(qobj, GLU_LINE);
 GLdouble factor = (GLdouble)numCV;
 radius = fabs(endPos_x - startPos_x)/factor + 0.1;
 height = fabs(endPos_y - startPos_y)/factor + 0.1;
 gluCylinder( qobj, radius, radius, height, 8, 1 );
 glPopMatrix();

         
This code draws a cylinder
            in the current view defining the outlines of the helix that will
            be generated.
         

         
 #ifndef _WIN32
 glXSwapBuffers(view.display(), view.window() );
 #else
 SwapBuffers(view.deviceContext() );
 #endif
 return MS::kSuccess;
}
MStatus helixContext::doRelease( MEvent & )
{
 // Clear the overlay plane & restore from overlay drawing
 //
 view.clearOverlayPlane();
 view.endOverlayDrawing();
 view.endGL();

         
The user has released
            the mouse so this code cleans up the OpenGL drawing.
         

         
 helixTool * cmd = (helixTool*)newToolCommand();
 cmd->setPitch( height/NumCVs );
 cmd->setRadius( radius );
 cmd->setNumCVs( numCV );
 cmd->setUpsideDown( upDown );
 cmd->redoIt();
 cmd->finalize();

         
This code creates the
            actual helixTool command, by calling the helixTool::creator method
            that you will register later, sets the radius and pitch, and then
            calls the redoIt() method to generate the data. As a last step,
            the finalize() method is called to ensure that this command is written
            out to the journal file. 
         

         
 return MS::kSuccess;
}
MStatus helixContext::doEnterRegion( MEvent & )
{
 return setHelpString( helpString );
}
void helixContex::getClassName( MString &name ) const
{
 name.set("helix");
}

         
The next four methods
            are used in the interaction between the context and the contextCommand’s
            edit and query methods. These will be called by the tool property
            sheet for the context. The MToolsInfo::setDirtyFlag() method alerts
            the tool property sheet so it can redraw itself with the new property
            values for the context.
         

         
void helixContext::setNumCVs( unsigned newNumCVs )
{
 numCV = newNumCVs;
 MToolsInfo::setDirtyFlag(*this);
}
void helixContext::setUpsideDown( bool newUpsideDown )
{
 upDown = newUpsideDown;
 MToolsInfo::setDirtyFlag(*this);
}
unsigned helixContext::numCVs()
{
 return numCV;
}
bool helixContext::upsideDown()
{
 return upDown;
}

         
The next class and implementation
            repeats the code from the marqueeTool example. This class is necessary
            to create instances of the tool context.
         

         
class helixContextCmd : public MPxContextCommand
{
public: 
 helixContextCmd();
 virtual MStatus doEditFlags();
 virtual MStatus doQueryFlags();
 virtual MPxContext* makeObj();
 virtual MStatus appendSyntax();
 static void* creator();
protected:
 helixContext * fHelixContext;
};
helixContextCmd::helixContextCmd() {}
MPxContext* helixContextCmd::makeObj()
{
 fHelixContext = new helixContext();
 return fHelixContext;
}
void* helixContextCmd::creator()
{
 return new helixContextCmd;
}

         
The next two methods
            handle the argument parsing for the command. There are two types
            of arguments—those which make modifications to the properties
            of a context, and those which query the properties of a context. 
         

         
NoteArgument parsing
               is done through the MPxContextCommand::parser() method which returns
               an MArgParser. This class is analogous to the MArgDatabase class
               that is used with the MPxCommand class.
            

         

         
MStatus helixContextCmd::doEditFlags()
{
 MArgParser argData = parser();
 if (argData.isFlagSet(kNumberCVsFlag)) {
 unsigned numCVs;
 status = argData.getFlagArgument(kNumberCVsFlag,
 0, numCVs);
 if (!status) {
 status.perror("numCVs flag parsing failed.");
 return status;
 }
 fHelixContext->setNumCVs(numCVs);
 }
 if (argData.isFlagSet(kUpsideDownFlag)) {
 bool upsideDown;
 status = argData.getFlagArgument(kUpsideDownFlag,
 0, upsideDown);
 if (!status) {
 status.perror("upsideDown flag parsing failed.");
 return status;
 }
 fHelixContext->setUpsideDown(upsideDown);
 }
 
 return MS::kSuccess;
}
MStatus helixContextCmd::doQueryFlags()
{
 MArgParser argData = parser();
 if (argData.isFlagSet(kNumberCVsFlag)) {
 setResult((int) fHelixContext->numCVs());
 }
 if (argData.isFlagSet(kUpsideDownFlag)) {
 setResult(fHelixContext->upsideDown());
 }
 return MS::kSuccess;
}
MStatus helixContextCmd::appendSyntax()
{
 MStatus status;
 MSyntax mySyntax = syntax();
 if (MS::kSuccess != mySyntax.addFlag(kNumberCVsFlag,
 kNumberCVsFlagLong, MSyntax::kUnsigned)) {
 return MS::kFailure;
 }
 if (MS::kSuccess != mySyntax.addFlag(kUpsideDownFlag,
 kUpsideDownFlagLong, MSyntax::kBoolean)) {
 return MS::kFailure;
 }
 return MS::kSuccess;
}
MStatus initializePlugin( MObject obj )
{
 MStatus status;
 MFnPlugin plugin( obj, “Autodesk”, “1.0”, “Any”);
 // Register the context creation command and the tool
 // command that the helixContext will use.
 // 
 status = plugin.registerContextCommand(
 “helixToolContext”, helixContextCmd::creator,
 “helixToolCmd”, helixTool::creator,
 helixTool::newSyntax);
 if (!status) {
 status.perror(“registerContextCommand”);
 return status;
 }
 return status;
}

         
The initializePlugin()
            method registers both the helix command and the context via a single
            register call.
         

         
MStatus uninitializePlugin( MObject obj)
{
 MStatus status;
 MFnPlugin plugin( obj );
 // Deregister the tool command and the context
 // creation command.
 //
 status = plugin.deregisterContextCommand(
 “helixToolContext” “helixToolCmd”);
 if (!status) {
 status.perror(“deregisterContextCommand”);
 return status;
 }
 return status;
}

         
MEL code similar to the
            marqueeTool example’s is necessary to attach the helixTool to the
            UI.
         

         
         
Please send us your comments about this page