MSyntax Class Reference
[OpenMaya - API module for common classes]

#include <MSyntax.h>

List of all members.


Detailed Description

Syntax for Commands.

This class is used to specify flags and arguments passed to commands. Once the syntax of the command has been defined by calls to the methods in this class, Maya will be able to automatically parse invocations of the command and reject syntactically invalid ones. When the doIt method of the command is invoked, the provided argument list can be parsed automatically into an instance of either the MArgDatabase class (for commands) or MArgParser class (for context commands) by passing the constructor for that class both the argument list and the syntax object for the command.

There are three type of arguments that can be specified via these syntax methods:

Note: command arguments and objects are incompatible and must not be combined in the syntax definition of a command. If an attempt is made to do so, neither command arguments or objects will be accessible via the MArgDatabase or MArgParser classes.

The addFlag method is used to add a flag argument to a command. Flags need to have a type specified for them from the list of available types in the MArgType enum and can take up to six parameters. Flags can be set as being allowed multiple times on the command line be calling the makeFlagMultiUse method.

The addArg method is used to add a command argument to a command. Such arguments must also have a type specified for them from the list of available types in the MArgType enum. If you specify an argument via this call, Maya will reject an invocation of the command as being syntactically invalid if an argument of the correct type is not provided. If the type kSelectionItem is provided, Maya will include the contents of the selection list as the argument to the command.

The setObjectType method is used to specify that the command requires an object list. Parameters to this method allow you to specify minimum and maximum numbers of objects. As well, if the useSelectionAsDefault method is used in conjunction with this, Maya will use the contents of the selection list as the objects for the command if none are specified.

The documentation for the MArgDatabase and MArgParser classes describe how to access the parsed information for a command inside the doIt method of that command.

Examples:

cgfxShaderCmd.cpp, cgfxShaderCmd.h, closestPointOnCurveCmd.cpp, closestPointOnCurveCmd.h, clusterWeightFunction.cpp, conditionTest.cpp, dagMessageCmd.cpp, deletedMsgCmd.cpp, eventTest.cpp, filteredAsciiFile.cpp, flipUVCmd.cpp, flipUVCmd.h, fxManagerCmd.cpp, fxManagerCmd.h, geometryCacheConverter.cpp, geometrySurfaceConstraint.cpp, helixTool.cpp, lockEvent.cpp, narrowPolyViewerCmd.cpp, nodeCreatedCBCmd.cpp, nodeCreatedCBCmd.h, nodeInfoCmd.cpp, particlePathsCmd.cpp, peltOverlapCmd.cpp, renderViewInteractiveRenderCmd.cpp, renderViewRenderCmd.cpp, renderViewRenderRegionCmd.cpp, scanDagSyntax.cpp, userMsgCmd.cpp, and viewCallbackTest.cpp.


Public Types

enum   MArgType {
   kInvalidArgType, kNoArg, kBoolean, kLong,
   kDouble, kString, kUnsigned, kDistance,
   kAngle, kTime, kSelectionItem, kLastArgType
}
  Argument types. More...
enum   MObjectFormat {
   kInvalidObjectFormat, kNone, kStringObjects, kSelectionList,
   kLastObjectFormat
}
  Object list types. More...

Public Member Functions

  MSyntax ()
  MSyntax (const MSyntax &other)
virtual  ~MSyntax ()
MSyntax operator= (const MSyntax &rhs)
MStatus  addFlag (const char *shortName, const char *longName, MArgType argType1=kNoArg, MArgType argType2=kNoArg, MArgType argType3=kNoArg, MArgType argType4=kNoArg, MArgType argType5=kNoArg, MArgType argType6=kNoArg)
MStatus  makeFlagMultiUse (const char *flag)
MStatus  makeFlagQueryWithFullArgs (const char *flag, bool queryArgsAreOptional)
MStatus  addArg (MArgType arg)
void  useSelectionAsDefault (bool useSelectionList=false)
MStatus  setObjectType (MObjectFormat objectFormat, unsigned int minimumObjects=0)
MStatus  setObjectType (MObjectFormat objectFormat, unsigned int minimumObjects, unsigned int maximumObjects)
void  setMinObjects (unsigned int minimumObjectCount)
void  setMaxObjects (unsigned int maximumObjectCount)
void  enableQuery (bool supportsQuery=true)
void  enableEdit (bool supportsEdit=true)
unsigned int  minObjects () const
unsigned int  maxObjects () const
bool  canQuery () const
bool  canEdit () const

Member Enumeration Documentation

Argument types.

MPxSelectionContext::argTypeNumericalInput(unsigned int index) const

This method is used by the feedback line to determine what units to display. Users should override this method to return the appropriate argument type for the given index of the numeric input field. Specifically, this method should be overridden to return one of the following:

Parameters:
[in]  index  the index of the numerical input whose argument type is requested
Returns:
MSyntax::kNoArg the default return value.
Enumerator:
kInvalidArgType   
kNoArg   
kBoolean   
kLong   
kDouble   
kString   
kUnsigned   
kDistance   
kAngle   
kTime   
kSelectionItem   
kLastArgType   

Object list types.

Enumerator:
kInvalidObjectFormat   
kNone   
kStringObjects   
kSelectionList   
kLastObjectFormat   

Constructor & Destructor Documentation

MSyntax::MSyntax (  ) 

The default class constructor.

MSyntax::MSyntax ( const MSyntax other  ) 

The copy constructor.

MSyntax::~MSyntax (  )  [virtual]

The class destructor.


Member Function Documentation

MSyntax & MSyntax::operator= ( const MSyntax rhs  ) 

The assignment operator.

MStatus MSyntax::addFlag ( const char *  shortName,
const char *  longName,
MArgType  argType1 = kNoArg,
MArgType  argType2 = kNoArg,
MArgType  argType3 = kNoArg,
MArgType  argType4 = kNoArg,
MArgType  argType5 = kNoArg,
MArgType  argType6 = kNoArg  
)

Adds a flag to the list of flags accepted for the given command. Also specifies any arguments required by the flag.

Parameters:
[in]  shortName  the string representing the short (< 4 character) version of the flag
[in]  longName  the string representing the int (> 3 character) version of the flag
[in]  argType1  type of the argument required by the flag, if any
[in]  argType2  another type of the argument required by the flag, if any
[in]  argType3  another type of the argument required by the flag, if any
[in]  argType4  another type of the argument required by the flag, if any
[in]  argType5  another type of the argument required by the flag, if any
[in]  argType6  another type of the argument required by the flag, if any
Returns:
Examples:

MStatus MSyntax::makeFlagMultiUse ( const char *  flag  ) 

Specifies that the given flag can be used by the command multiple times in on the same command line.

Parameters:
[in]  flag  the flag to be made multi-use
Returns:
Examples:

MStatus MSyntax::makeFlagQueryWithFullArgs ( const char *  flag,
bool  queryArgsAreOptional  
)

Specifies that the given flag will require all of its arguments in query mode. Usually flags do not take arguments in query mode, since you are getting values instead of setting them. However, sometimes it is necessary to take arguments on a flag to allow the user to provide information which will help specify the scope of a query.

Note that query arguments may be set to be optional. In that case the flag will be accepted with arguments or without. In that case, you must check at runtime to see how many arguments where passed to the flag.

Parameters:
[in]  flag  the flag which should be set to use arguments during query
[in]  queryArgsAreOptional  set to true if the flag arguments are optional
Returns:

MStatus MSyntax::addArg ( MArgType  arg  ) 

Specifies the type of one of the arguments to the command. This method can be called multiple times to specify multiple arguments to the command.

Parameters:
[in]  arg  the type of the argument to the command
Returns:
Examples:

void MSyntax::useSelectionAsDefault ( bool  useSelectionList = false  ) 

Specifies that the command will use the current selection list as arguments to the command if the command requires objects and none are provided}.

Parameters:
[in]  useSelectionList  if true, the command will use the current selection list as arguments if none are specified
Returns:
Examples:

MStatus MSyntax::setObjectType ( MObjectFormat  objectFormat,
unsigned int  minimumObjects = 0  
)

Specifies the representation of the objects passed to the command as either MObjects or MStrings. Also specifies the minimum number of objects required by the command.

Parameters:
[in]  objectFormat  the form of the objects passed to the command
[in]  minimumObjects  the minimum number of objects required by the command
Returns:
Examples:

MStatus MSyntax::setObjectType ( MObjectFormat  objectFormat,
unsigned int  minimumObjects,
unsigned int  maximumObjects  
)

Specifies the representation of the objects passed to the command as either MObjects or MStrings. Also specifies the upper and lower limits of the number of objects accepted by the command.

Parameters:
[in]  objectFormat  the form of the objects passed to the command
[in]  minimumObjects  the lower limit of the number of objects
[in]  maximumObjects  the upper limit of the number of objects
Returns:

void MSyntax::setMinObjects ( unsigned int  minimumObjectCount  ) 

Specifies the lower limit on the number of objects accepted by the command.

Parameters:
[in]  minimumObjectCount  the lower limit of the number of objects
Examples:

void MSyntax::setMaxObjects ( unsigned int  maximumObjectCount  ) 

Specifies the upper limit on the number of objects accepted by the command.

Parameters:
[in]  maximumObjectCount  the upper limit of the number of objects

void MSyntax::enableQuery ( bool  supportsQuery = true  ) 

Sets whether or not the command supports the query flag ("-q").

Parameters:
[in]  supportsQuery  if true, the command supports the query flag
Examples:

void MSyntax::enableEdit ( bool  supportsEdit = true  ) 

Sets whether or not the command supports the edit flag ("-e").

Parameters:
[in]  supportsEdit  if true, the command supports the edit flag
Examples:

unsigned int MSyntax::minObjects (  )  const

Returns the lower limit on the number of objects accepted by the command.

Returns:
The minimum number of objects

unsigned int MSyntax::maxObjects (  )  const

Returns the upper limit on the number of objects accepted by the command.

Returns:
The maximum number of objects

bool MSyntax::canQuery (  )  const

Returns whether or not the command supports the query flag ("-q").

Returns:
  • true can query
  • false cannot query

bool MSyntax::canEdit (  )  const

Returns whether or not the command supports the edit flag ("-e").

Returns:
  • true can edit
  • false cannot edit

Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6