Maya API How-To #26

How can I use MSyntax in query mode, and still allow the user to specify an argument for a flag?

When specifying the MSyntax for a MPxCommand plug-in you can choose to enable query mode for the syntax object via the MSyntax::enableQuery() method. This is all well and good, but for one apparent limitation: When the syntax is parsed, all flags which are queried merely indicate they've been used, but do not communicate any argument values the user may have specified. For example:

myCommand -mode "foo";

You can parse this command with code similar to the following:

if ( argParser.isFlagSet( MODE_FLAG ) )
{
  MString argValue;
  argParser.getFlagArgument( MODE_FLAG, 0, argValue );
}

The string "foo", specified for the flag '-mode', will be returned in the MString argValue.

However, if the user enters the following:

myCommand -q -mode "foo";

Here the query mode trumps the argument; the parser indicates only that it was invoked in query mode and that the '-mode' flag was specified. It does not provide the "foo" argument value for the '-mode' flag.

However, if you place an argument before the query flag you can benefit from both behaviors:

// Specify '-mode' flag _before_ '-query' flag.
//
myCommand -mode "foo" -q;

Here the MSyntax object still indicates that it's in query mode, and the '-mode' flag provides its "foo" argument.

This also explains why you'll find some of Maya's native commands being fussy about where the '-q' flag is specified; e.g.:

particleInstancer -name "instancer" -q -scale "particle"`;

skinPercent -transform joint3 -q skinCluster1 shape.cv[100];

12 Sep 2004