class MPxCommand

Jump to documentation

Inheritance:

MPxCommand

public members:

	MPxCommand ()
virtual	~MPxCommand ()
virtual MStatus	doIt ( const MArgList & args )
virtual MStatus	undoIt ( )
virtual MStatus	redoIt ( )
virtual bool	isUndoable () const
virtual bool	hasSyntax () const
MSyntax	syntax () const
bool	isHistoryOn () const
MString	commandString () const
MStatus	setHistoryOn ( bool state )
MStatus	setCommandString ( const MString & )
static void	displayInfo ( const MString & theInfo )
static void	displayWarning ( const MString & theWarning )
static void	displayError ( const MString & theError )
static void	displayWarning ( const MString & theWarning, bool wantDisplayLineNumber )
static void	displayError ( const MString & theError, bool wantDisplayLineNumber )
enum	MResultType kLong kDouble kString kNoArg
static void	clearResult ()
static void	setResult ( int val )
static void	setResult ( double val )
static void	setResult ( bool val )
static void	setResult ( const char* val )
static void	setResult ( const MString & val )
static void	setResult ( const MIntArray & val )
static void	setResult ( const MDoubleArray & val )
static void	setResult ( const MStringArray & val )
static void	appendToResult ( int val )
static void	appendToResult ( double val )
static void	appendToResult ( bool val )
static void	appendToResult ( const char* val )
static void	appendToResult ( const MString & val )
static void	appendToResult ( const MStringArray & val )
static MResultType	currentResultType ()
static MStatus	getCurrentResult ( int& val )
static MStatus	getCurrentResult ( double& val )
static MStatus	getCurrentResult ( MString & val )
static MStatus	getCurrentResult ( MIntArray & val )
static MStatus	getCurrentResult ( MDoubleArray & val )
static MStatus	getCurrentResult ( MStringArray & val )
static int	currentIntResult ( MStatus * ReturnStatus = NULL )
static double	currentDoubleResult ( MStatus * ReturnStatus = NULL )
static MString	currentStringResult ( MStatus * ReturnStatus = NULL )
MStatus	setUndoable ( bool state ) OBSOLETE

Documentation

Description

This is the proxy class for creating MEL commands through the API.

Each command is derived from this one, and must have a doIt method, and optionally undoIt, and redoIt methods.

The doIt method should collect whatever information is required to do the task, and store it in local class data. It should finally call redoIt to make the command happen. The redoIt method should do the actual work, using only the local class data. The undoIt method should undo the actual work, again using only the local class data.

Maya contains support for infinite levels of undo. If a command written in a plug-in changes the state of anything in Maya, it should implement undoIt and redoIt methods. As well, if the doIt method returns successfully, Maya will call the method's isUndoable method immediately afterwards. If that method returns true, the instance of this class is retained and passed to Maya's undo manager so that the undoIt and redoIt methods can be called when appropriate. If isUndoable returns false, the command instance is destroyed right away.

So, for example, if a command supports both query and edit modes, in query mode the command should set a flag so that the isUndoable method returns false to prevent that command instance from being retained by the undo manager. In edit mode, where the state of Maya is changed, isUndoable should return true to enable undo and redo.

Functions

MPxCommand:: MPxCommand ()

Constructor

MPxCommand:: ~MPxCommand ()

Description

Destructor. Local class data should be freed here.

MStatus MPxCommand:: doIt ( const MArgList & args )

Description

This method should perform a command by setting up internal class data and then calling the redoIt method. The actual action performed by the command should be done in the redoIt method. This is a pure virtual method, and must be overridden in derived classes.

Return Value

• Status code

Status Codes

• MS::kSuccess The command was successful
• MS::kFailure An error occured during the command

MStatus MPxCommand:: undoIt ( )

Description

This method should undo the work done be the redoIt method based on the internal class data only.

Return Value

• Status code

Status Codes

• MS::kSuccess The undo was successful
• MS::kFailure This method is not undoable

MStatus MPxCommand:: redoIt ( )

Description

This method should do the actual work of the command based on the internal class data only. Internal class data should be set in the doIt method.

Return Value

• Status code

Status Codes

• MS::kSuccess The redo was successful
• MS::kFailure An error occured during the redo

bool MPxCommand:: isUndoable ( ) const

Description

This method is used to specify whether or not the command is undoable. In the base class, it always returns false. If you are writing a command that might be eligible for undo, you should override this method.

After Maya executes the command's doIt method, it will call isUndoable. If isUndoable returns true, Maya will retain the instance of the class and pass it to Maya's undo manager so that the undoIt and redoIt methods can be called when appropriate. If isUndoable returns false, the command instance will be immediately destroyed.

So, for example, if a command supports both query and edit modes, in query mode the command should set a flag so that the isUndoable method returns false to prevent that command instance from being retained by the undo manager. In edit mode, where the state of Maya is changed, isUndoable should return true to enable undo and redo.

Return Value

• true This command is undoable
• false This command is not undoable (default)

bool MPxCommand:: hasSyntax ( ) const

Description

This method specifies whether or not the command has a syntax object.

Return Value

• true This command uses syntax objects
• false This command does not use syntax objects

MSyntax MPxCommand:: syntax () const

Description

This method is intended to be used in an MArgDataBase or MArgParser contructor when the plugin command's syntax is being initialized. The user should declare and define a syntax contstructing method that must be registered with Maya by passing the function pointer as a parameter in MFnPlugin::registerCommand(). The result is that when MPxCommand::syntax() is called it returns the syntax object that the user has created in the custom syntax constructing method that was registered. To avoid conflicts it is important that the user's custom syntax defining method be given a name other than "syntax." It can have any other name as long as it corresponds with the function pointer used to register the method with Maya.

Return Value

• The syntax object

bool MPxCommand:: isHistoryOn () const

Description

Returns whether history is on.

Return Value

• true History is on
• false History is off

MString MPxCommand:: commandString () const

Description

This method returns the command string that is associated with this command.

Return Value

• The command string for this command object

MStatus MPxCommand:: setHistoryOn ( bool state )

Description

This method specifies if history for this command is on.

Arguments

• state true if history is to be on , false otherwise

Return Value

• Status code

Status Codes

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus MPxCommand:: setCommandString ( const MString & name )

Description

Sets the command string that is associated with this command object.

Arguments

• name The command name to be set

Return Value

• Status code

Status Codes

• MS::kSuccess The command string was set
• MS::kFailure Object error

void MPxCommand:: displayInfo ( const MString & theInfo )

Description

This method is used to display information in the script editor.

Arguments

• theInfo The string to be displayed

void MPxCommand:: displayWarning ( const MString & theWarning )

Description

This method is used to display a warning in the script editor.

Arguments

• theWarning The warning string to be displayed

void MPxCommand:: displayError ( const MString & theError )

Description

This method is used to display an error in the script editor.

Arguments

• theError The error string to be displayed

void MPxCommand:: displayWarning ( const MString & theWarning, bool wantDisplayLineNumber )

Description

This method is used to display a warning in the script editor.

NOTE: Displaying of line numbers must be set in the MEL editor window before the wantDisplayLineNumber has an affect.

Arguments

• theWarning The warning string to be displayed
• wantDisplayLineNumber Set to true if you want the line number of this command to be displayed. See NOTE above.

void MPxCommand:: displayError ( const MString & theError, bool wantDisplayLineNumber )

Description

This method is used to display an error in the script editor.

NOTE: Displaying of line numbers must be set in the MEL editor window before the wantDisplayLineNumber has an affect.

Arguments

• theError The error string to be displayed
• wantDisplayLineNumber Set to true if you want the line number of this command to be displayed See NOTE above.

void MPxCommand:: clearResult ()

Description

Initializes the place where results from Maya commands get stored.

void MPxCommand:: setResult ( int val )

Description

This method puts the given value into the return value area for a command.

Arguments

• val The value to be set

void MPxCommand:: setResult ( double val )

Description

This method puts the given value into the return value area for a command.

Arguments

• val The value to be set

void MPxCommand:: setResult ( bool val )

Description

This method puts the given value into the return value area for a command.

Arguments

• val The value to be set

void MPxCommand:: setResult ( const char* val )

Description

This method puts the given value into the return value area for a command.

Arguments

• val The value to be set

void MPxCommand:: setResult ( const MString & val )

Description

This method puts the given value into the return value area for a command.

Arguments

• val The value to be set

void MPxCommand:: setResult ( const MIntArray & val )

Description

This method puts the given values into the return value area for a command.

Arguments

• val The value to be set

void MPxCommand:: setResult ( const MDoubleArray & val )

Description

This method puts the given values into the return value area for a command.

Arguments

• val The value to be set

void MPxCommand:: setResult ( const MStringArray & val )

Description

This method puts the given values into the return value area for a command.

Arguments

• val The value to be set

void MPxCommand:: appendToResult ( int val )

Description

This method will add the given value to the end of the result array of integers.
The result array can only be of a single type so this method can only be used when the result string has not been set or is already of integer type.

Note: appendToResult cannot be used in conjunction with setResult.

Arguments

• val The value to be added

void MPxCommand:: appendToResult ( double val )

Description

This method will add the given value to the end of the result array of doubles.
The result array can only be of a single type so this method can only be used when the result string has not been set or is already of type double.

Note: appendToResult cannot be used in conjunction with setResult.

Arguments

• val The value to be added

void MPxCommand:: appendToResult ( bool val )

Description

This method will add the given value to the end of the result array of integers.
The result array can only be of a single type so this method can only be used when the result string has not been set or is already of integer type.

Note: appendToResult cannot be used in conjunction with setResult.

Arguments

• val The value to be added

void MPxCommand:: appendToResult ( const char* val )

Description

This method will add the given value to the end of the result array of strings.
The result array can only be of a single type so this method can only be used when the result string has not been set or is already of type string.

Note: appendToResult cannot be used in conjunction with setResult.

Arguments

• val The value to be added

void MPxCommand:: appendToResult ( const MString & val )

Description

This method will add the given value to the end of the result array of strings.
The result array can only be of a single type so this method can only be used when the result string has not been set or is already of type string.

Note: appendToResult cannot be used in conjunction with setResult.

Arguments

• val The value to be added

void MPxCommand:: appendToResult ( const MStringArray & val )

Description

This method will add the given value to the end of the result array of strings.
The result array can only be of a single type so this method can only be used when the result string has not been set or is already of type string.

Note: appendToResult cannot be used in conjunction with setResult.

Arguments

• val The value to be added

MPxCommand::MResultType MPxCommand:: currentResultType ()

Description

This method will return the type of the current result for the command.

ReturnValue

• The result type

MStatus MPxCommand:: getCurrentResult ( int & val )

Description

This method gets the current node's result as a int, if possible.

Python Notes

This method is not supported in Python. Please see currentIntResult()

Arguments

• val Storage for the return value

Return Value

• MS:kSuccess A value was returned
• MS:kFailure Cannot convert result to int

int MPxCommand:: currentIntResult ( MStatus * ReturnStatus )

Description

This method gets the current node's result as a int, if possible.

Arguments

• ReturnStatus Optional status code. See below.

Return Value

• The int result.

• MS:kSuccess A value was returned
• MS:kFailure Cannot convert result to int

MStatus MPxCommand:: getCurrentResult ( double & val )

Description

This method gets the current node's result as a double, if possible.

Python Notes

This method is not supported in Python. Please see currentDoubleResult()

Arguments

• val Storage for the return value

Return Value

• MS:kSuccess A value was returned
• MS:kFailure Cannot convert result to double

double MPxCommand:: currentDoubleResult ( MStatus * ReturnStatus )

Description

This method gets the current node's result as a double, if possible.

Arguments

• ReturnStatus Optional status code. See below.

Return Value

• The double result.

• MS:kSuccess A value was returned
• MS:kFailure Cannot convert result to double

MStatus MPxCommand:: getCurrentResult ( MString & val )

Description

This method gets the current node's result as a string, if possible.

Python Notes

This method is not supported in Python. Please see currentStringResult()

Arguments

• val Storage for the return value

Return Value

• MS:kSuccess A value was returned
• MS:kFailure Cannot convert result to string

MString MPxCommand:: currentStringResult ( MStatus * ReturnStatus )

Description

This method gets the current node's result as a MString, if possible.

Arguments

• ReturnStatus Optional status code. See below.

Return Value

• The string result.

• MS:kSuccess A value was returned
• MS:kFailure Cannot convert result to double

MStatus MPxCommand:: getCurrentResult ( MIntArray & val )

Description

This method gets the current node's result as an array of integers, if possible.

Arguments

• val Storage for the return value

Return Value

• MS:kSuccess A value was returned
• MS:kFailure Cannot convert result to integer array

MStatus MPxCommand:: getCurrentResult ( MDoubleArray & val )

Description

This method gets the current node's result as an array of doubles, if possible.

Arguments

• val Storage for the return value

Return Value

• MS:kSuccess A value was returned
• MS:kFailure Cannot convert result to double array

MStatus MPxCommand:: getCurrentResult ( MStringArray & val )

Description

This method gets the current node's result as an array of strings, if possible.

Arguments

• val Storage for the return value

Return Value

• MS:kSuccess A value was returned
• MS:kFailure Cannot convert result to string array

MStatus MPxCommand:: setUndoable ( bool state )

Description

THIS IS AN OBSOLETE METHOD

This method currently has no effect on the undoability of a command and will be removed in a future Maya release.

Direct child classes:

- MSimple
- MPxToolCommand
- MPxPolyTweakUVCommand