Flags and arguments

Flags and arguments can be passed to your command when it is called from the script editor.

To use flags and arguments with your command, you will need to create a syntax object, MSyntax, that defines your flags, and you will need to parse the flags and arguments from the command line by creating an MArgDatabase object from which you can extract them.

Flags are named options to a command. They can take arguments as passed parameters. For example, in the polyCube command, 'sx', 'sy', 'sz', and 'h' are command flags, and 10, 15, 5, and 20 are their respective arguments:

polyCube -sx 10 -sy 15 -sz 5 -h 20;

Arguments that do not require a named flag can also be passed to commands. For example, circle1 and sphere1 are arguments passed to this group command:

group -n group1 circle1 sphere1;

Flags and their arguments are added to a syntax object using the MSyntax::addFlag() method. Implement a newSyntax() function, and set the flag long name, short name, and argument type:

MSyntax myCommand::newSyntax()
{
    MSyntax syntax;
    syntax.addFlag("-f", "-firstFlagLongName", kUnsigned);
    syntax.addFlag("-s", "-secondFlagLongName", kString);
    return syntax;
}

The third parameter to addFlag() defines the argument type of the flag. If it is omitted, the flag takes no arguments. To pass an argument type as a parameter, set the type to kSelectionItem.

To add an argument that does not need a named flag, use MSyntax::addArg().

The syntax object is passed to registerCommand() in initializePlugin():

MStatus initializePlugin( MObject obj )
{ 
    MStatus status;
    MFnPlugin plugin(obj, "Autodesk - Example", "2.0", "Any");
    status = plugin.registerCommand("myCommand", myCommand::creator, myCommand::newSyntax); 
    return status;
}

The arguments and flags are parsed in doIt(). By convention, parsing is done in the parseArgs() function that is then called by doIt(). You will need to implement parseArgs() in your command code.

Parsing is done by creating an MArgDatabase object.MArgDatabase has member method that parse the flags and arguments passed to the command in its MArgList using the information in the syntax object.

MStatus myCommand::parseArgs(const MArgList& args)
{
    unsigned firstFlagArg;
    MString secondFlagArg;
    MArgDatabase argData(syntax(), args);
    [...]
    if (argData.isFlagSet("-f")) 
        argData.getFlagArgument("-f", 0, firstFlagArg);
    if (argData.isFlagSet("-s"))
        argData.getFlagArgument("-s", 0, secondFlagArg);
    [...]
}

You can reuse the same flag in the same command. For example:

myCommand -f 3 -s "hello" -s "there"

To do so, you will need to declare the flag to be multi-use using MSyntax::makeFlagMultiUse(). You will then need to use the MArgDatabase::numberOfFlagUses() to find the number of times a flag has been used, and then MArgDatabase::getFlagArgumentPosition() to get the position of the argument for each specific use of the flag, before using MArgDatabase::getFlagArgument() to extract the argument.