This class isn't really a wrapper around command options as such, it's mainly just a helper to auto generate some GUI code to create a menu item + option box dialog. More...

#include <CommandGuiHelper.h>

Public Types
enum	FileMode { kSave = 0, kLoad = 1, kDirectoryWithFiles = 2, kDirectory = 3, kMultiLoad = 4 }
	Used to describe the type of file dialog that should be used for a file path attribute. More...

enum	StringPolicy { kStringOptional, kStringMustHaveValue }
	determines if a text string argument is optional (e.g. a name of the object if specified, but falls back to a default if not), or whether it must exist (e.g. for a file to open) More...

Public Member Functions
	CommandGuiHelper (const char commandName, const char windowTitle, const char doitLabel, const char menuItemPath, bool hasOptionBox=true)
	ctor More...

	CommandGuiHelper (const char commandName, const char menuItemPath, bool checkBoxValue=false)
	ctor More...

	~CommandGuiHelper ()
	dtor - auto generates, and executes the GUI code.

void	addFlagOption (const char commandFlag, const char label, bool defaultVal, bool persist=true)
	add a boolean option value to the GUI More...

void	addBoolOption (const char commandFlag, const char label, bool defaultVal, bool persist=true)
	add a boolean option value to the GUI More...

void	addIntOption (const char commandFlag, const char label, int32_t defaultVal, bool persist=true)
	add an integer option value to the GUI More...

void	addIntSliderOption (const char commandFlag, const char label, int32_t minVal, int32_t maxVal, int32_t defaultVal, bool persist=true)
	add an integer option value to the GUI (with min/max, displayed as a slider) More...

void	addInt2Option (const char commandFlag, const char label, const int32_t defaultVal[2], bool persist=true)
	add a 2D integer option value to the GUI More...

void	addInt2Option (const char commandFlag, const char label, const int32_t a, const int32_t b, bool persist=true)
	add a 2D integer option value to the GUI More...

void	addInt3Option (const char commandFlag, const char label, const int32_t defaultVal[3], bool persist=true)
	add a 3D integer option value to the GUI More...

void	addInt3Option (const char commandFlag, const char label, const int32_t a, const int32_t b, const int32_t c, bool persist=true)
	add a 3D integer option value to the GUI More...

void	addInt4Option (const char commandFlag, const char label, const int32_t defaultVal[4], bool persist=true)
	add a 4D integer option value to the GUI More...

void	addInt4Option (const char commandFlag, const char label, const int32_t a, const int32_t b, const int32_t c, const int32_t d, bool persist=true)
	add a 4D integer option value to the GUI More...

void	addListOption (const char commandFlag, const char label, GenerateListFn generateList)
	adds a dynamic drop down list of items that will be displayed within an optionMenu control. The list of text strings will be generated within C++ by the custom generateList function, which will then be chosen to represent the list of options available for this command. When the command is executed, the selected item will be passed to the command as a text string. More...

void	addEnumOption (const char commandFlag, const char label, int defaultIndex, const char *const enumNames[], const int32_t enumValues[], bool persist=true, bool passAsString=false)
	add an enum option value to the GUI More...

void	addRadioButtonGroupOption (const char commandFlag, const char label, int defaultIndex, const char *const enumNames[], const int32_t enumValues[], bool persist=true, bool passAsString=false)
	Similar to the enum option, but this time with radio buttons. THE MAXIMUM NUMBER OF OPTIONS IS 4. If you exceed this, the code will default to using a combo box for display. More...

void	addDoubleOption (const char commandFlag, const char label, double defaultVal, bool persist=true)
	add a double precision option value to the GUI More...

void	addDoubleSliderOption (const char commandFlag, const char label, double minVal, double maxVal, double defaultVal, bool persist=true)
	add a double precision option value to the GUI (with min/max, displayed as a slider) More...

void	addVec2Option (const char commandFlag, const char label, const double defaultVal[2], bool persist=true)
	add a 2D vector option value to the GUI More...

void	addVec2Option (const char commandFlag, const char label, const double a, const double b, bool persist=true)
	add a 2D vector option value to the GUI More...

void	addVec3Option (const char commandFlag, const char label, const double defaultVal[3], bool persist=true)
	add a 3D vector option value to the GUI More...

void	addVec3Option (const char commandFlag, const char label, const double a, const double b, const double c, bool persist=true)
	add a 3D vector option value to the GUI More...

void	addVec4Option (const char commandFlag, const char label, const double defaultVal[4], bool persist=true)
	add a 4D vector option value to the GUI More...

void	addVec4Option (const char commandFlag, const char label, const double a, const double b, const double c, const double d, bool persist=true)
	add a 4D vector option value to the GUI More...

void	addColourOption (const char commandFlag, const char label, const double defaultVal[3], bool persist=true)
	add a colour option value to the GUI More...

void	addColourOption (const char commandFlag, const char label, const double a, const double b, const double c, bool persist=true)
	add a colour option value to the GUI More...

void	addStringOption (const char commandFlag, const char label, MString defaultVal, bool persist=true, StringPolicy policy=kStringOptional)
	add a string option value to the GUI More...

void	addFilePathOption (const char commandFlag, const char label, FileMode fileMode, const char filter="All files () (*)", StringPolicy policy=kStringOptional)
	add a file path option value to the GUI More...

Detailed Description

This class isn't really a wrapper around command options as such, it's mainly just a helper to auto generate some GUI code to create a menu item + option box dialog.

Note: The following example code demonstrates how to use the CommandGuiHelper class to autogenerate a menu item, which will be available in the menu path "USD" -> "polygons" -> "Create Cube"; This will call the mel command "polyCube". The total command called will be something akin to:

polyCube -constructionHistory true -width 1 -height 1.1 -depth 1.2 -subdivisionsX 1 subdivisionsY 2 -subdivisionsZ 3 -name "pCube"

However all of the numeric values will actually be stored as optionVar's. (see the optionVar mel command, or MGlobal class) If the command is "polyCube", and the flag is "constructionHistory", then the optionVar used to store the preference will be "polyCube_constructionHistory".

Whilst I'm using "polyCube" as an example of how to use this class, you'd probably want to use this for your own MPxCommand derived classes.

{
  AL::maya::CommandGuiHelper options("polyCube", "Create Polygon Cube", "Create", "USD/polygons/Create Cube");
  options.addBoolOption("constructionHistory", "Construction History", true, true);
  options.addDoubleOption("width", "Width", 1.0, true);
  options.addDoubleOption("height", "Height", 1.1, true);
  options.addDoubleOption("depth", "Depth", 1.2, true);
  options.addIntOption("subdivisionsX", "Subdivisions in X", 1, true);
  options.addIntOption("subdivisionsY", "Subdivisions in Y", 2, true);
  options.addIntOption("subdivisionsZ", "Subdivisions in Z", 3, true);
  options.addStringOption("name", "Name", "pCube", false);
  options.addVec3Option("axis", "Axis", 0, 1, 0, true);
}

If the above code is called somewhere within your initialisePlugin method, and you end up calling AL::maya::MenuBuilder::generatePluginUI() at the end of your initialise method, then that command (+optionBox) will be available on the main maya menu.

Member Enumeration Documentation

enum AL::maya::CommandGuiHelper::FileMode

Used to describe the type of file dialog that should be used for a file path attribute.

Enumerator
kSave	a save file dialog
kLoad	a load file dialog
kDirectoryWithFiles	a directory dialog, but displays files.
kDirectory	a directory dialog
kMultiLoad	multiple input files

enum AL::maya::CommandGuiHelper::StringPolicy

determines if a text string argument is optional (e.g. a name of the object if specified, but falls back to a default if not), or whether it must exist (e.g. for a file to open)

Enumerator
kStringOptional	if the string value is empty, the flag will be omitted.
kStringMustHaveValue	if the string is empty, it is an error.

Constructor & Destructor Documentation

AL::maya::CommandGuiHelper::CommandGuiHelper	(	const char *	commandName,
		const char *	windowTitle,
		const char *	doitLabel,
		const char *	menuItemPath,
		bool	hasOptionBox = `true`
	)

ctor

Parameters

commandName	the name of the mel command to execute
windowTitle	the title to display at the top of the option box.
doitLabel	The label that will appear on the 'Create/Yes/DoIt' button on the left hand side of the dialog
menuItemPath	determines the path to the menu item from the main menu.
hasOptionBox	If true, the dialog will only be executed when the option box button is clicked. If false, there will be no option box, and the GUI will always be displayed.

AL::maya::CommandGuiHelper::CommandGuiHelper	(	const char *	commandName,
		const char *	menuItemPath,
		bool	checkBoxValue = `false`
	)

ctor

add a menu item with a checkbox

Parameters

commandName	the name of the mel command to execute
menuItemPath	determines the path to the menu item from the main menu.
checkBoxValue	the default value for the checkbox

Member Function Documentation

void AL::maya::CommandGuiHelper::addBoolOption	(	const char *	commandFlag,
		const char *	label,
		bool	defaultVal,
		bool	persist = `true`
	)

add a boolean option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addColourOption	(	const char *	commandFlag,
		const char *	label,
		const double	defaultVal[3],
		bool	persist = `true`
	)

add a colour option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addColourOption	(	const char *	commandFlag,
		const char *	label,
		const double	a,
		const double	b,
		const double	c,
		bool	persist = `true`
	)

inline

add a colour option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
a	the default value for the 1st value of the flag
b	the default value for the 2st value of the flag
c	the default value for the 3rd value of the flag
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addDoubleOption	(	const char *	commandFlag,
		const char *	label,
		double	defaultVal,
		bool	persist = `true`
	)

add a double precision option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addDoubleSliderOption	(	const char *	commandFlag,
		const char *	label,
		double	minVal,
		double	maxVal,
		double	defaultVal,
		bool	persist = `true`
	)

add a double precision option value to the GUI (with min/max, displayed as a slider)

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not setoption
minVal	the minimum value for the slider range
maxVal	the maximum value for the slider range
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addEnumOption	(	const char *	commandFlag,
		const char *	label,
		int	defaultIndex,
		const char *const	enumNames[],
		const int32_t	enumValues[],
		bool	persist = `true`,
		bool	passAsString = `false`
	)

add an enum option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultIndex	the default index into the enumNames/enumValues for the enum
enumNames	an array of text string names (last string must be NULL) for the enum entries. e.g. const char* const enumStrings[] = { "up", "down", "left", "right", 0 };
enumValues	an array of integer values that match up to the enumNames. This array can be NULL, in which case it is assumed that the enum values are 0, 1, 2, 3, etc.
persist	if true, the GUI option will be persisted as an optionVar
passAsString	if true, the command will be passed the text string value of the enum. If false, a numeric value will be passed instead.

void AL::maya::CommandGuiHelper::addFilePathOption	(	const char *	commandFlag,
		const char *	label,
		FileMode	fileMode,
		const char *	filter = `"All files () ()"`,
		StringPolicy	policy = `kStringOptional`
	)

add a file path option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
fileMode	the type of file dialog you wish to have present
filter	the file extension filter for the file dialog
policy	is the file path optional (kStringOptional), or required? (kStringMustHaveValue)

void AL::maya::CommandGuiHelper::addFlagOption	(	const char *	commandFlag,
		const char *	label,
		bool	defaultVal,
		bool	persist = `true`
	)

add a boolean option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addInt2Option	(	const char *	commandFlag,
		const char *	label,
		const int32_t	defaultVal[2],
		bool	persist = `true`
	)

add a 2D integer option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addInt2Option	(	const char *	commandFlag,
		const char *	label,
		const int32_t	a,
		const int32_t	b,
		bool	persist = `true`
	)

inline

add a 2D integer option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
a	the default value for the 1st value of the flag
b	the default value for the 2st value of the flag
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addInt3Option	(	const char *	commandFlag,
		const char *	label,
		const int32_t	defaultVal[3],
		bool	persist = `true`
	)

add a 3D integer option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addInt3Option	(	const char *	commandFlag,
		const char *	label,
		const int32_t	a,
		const int32_t	b,
		const int32_t	c,
		bool	persist = `true`
	)

inline

add a 3D integer option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
a	the default value for the 1st value of the flag
b	the default value for the 2st value of the flag
c	the default value for the 3rd value of the flag
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addInt4Option	(	const char *	commandFlag,
		const char *	label,
		const int32_t	defaultVal[4],
		bool	persist = `true`
	)

add a 4D integer option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addInt4Option	(	const char *	commandFlag,
		const char *	label,
		const int32_t	a,
		const int32_t	b,
		const int32_t	c,
		const int32_t	d,
		bool	persist = `true`
	)

inline

add a 4D integer option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
a	the default value for the 1st value of the flag
b	the default value for the 2st value of the flag
c	the default value for the 3rd value of the flag
d	the default value for the 4th value of the flag
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addIntOption	(	const char *	commandFlag,
		const char *	label,
		int32_t	defaultVal,
		bool	persist = `true`
	)

add an integer option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addIntSliderOption	(	const char *	commandFlag,
		const char *	label,
		int32_t	minVal,
		int32_t	maxVal,
		int32_t	defaultVal,
		bool	persist = `true`
	)

add an integer option value to the GUI (with min/max, displayed as a slider)

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
minVal	the minimum value for the slider range
maxVal	the maximum value for the slider range
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addListOption	(	const char *	commandFlag,
		const char *	label,
		GenerateListFn	generateList
	)

adds a dynamic drop down list of items that will be displayed within an optionMenu control. The list of text strings will be generated within C++ by the custom generateList function, which will then be chosen to represent the list of options available for this command. When the command is executed, the selected item will be passed to the command as a text string.

Note: Only string command options are supported for this control type, and the command GUI must be created with the 'hasOptionBox' option of the constructor set to false.

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
generateList	The C++ command to build up a list of text strings for the GUI to display

void AL::maya::CommandGuiHelper::addRadioButtonGroupOption	(	const char *	commandFlag,
		const char *	label,
		int	defaultIndex,
		const char *const	enumNames[],
		const int32_t	enumValues[],
		bool	persist = `true`,
		bool	passAsString = `false`
	)

Similar to the enum option, but this time with radio buttons. THE MAXIMUM NUMBER OF OPTIONS IS 4. If you exceed this, the code will default to using a combo box for display.

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultIndex	the default index into the enumNames/enumValues for the enum
enumNames	an array of text string names (last string must be NULL) for the enum entries. e.g. const char* const enumStrings[] = { "up", "down", "left", "right", 0 };
enumValues	- an array of integer values that match up to the enumNames. This array can be NULL, in which case it is assumed that the enum values are 0, 1, 2, 3, etc.
persist	if true, the GUI option will be persisted as an optionVar
passAsString	- if true, the command will be passed the text string value of the enum. If false, a numeric value will be passed instead.

void AL::maya::CommandGuiHelper::addStringOption	(	const char *	commandFlag,
		const char *	label,
		MString	defaultVal,
		bool	persist = `true`,
		StringPolicy	policy = `kStringOptional`
	)

add a string option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar
policy	is the string optional (kStringOptional), or required? (kStringMustHaveValue)

void AL::maya::CommandGuiHelper::addVec2Option	(	const char *	commandFlag,
		const char *	label,
		const double	defaultVal[2],
		bool	persist = `true`
	)

add a 2D vector option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addVec2Option	(	const char *	commandFlag,
		const char *	label,
		const double	a,
		const double	b,
		bool	persist = `true`
	)

inline

add a 2D vector option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
a	the default value for the 1st value of the flag
b	the default value for the 2st value of the flag
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addVec3Option	(	const char *	commandFlag,
		const char *	label,
		const double	defaultVal[3],
		bool	persist = `true`
	)

add a 3D vector option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addVec3Option	(	const char *	commandFlag,
		const char *	label,
		const double	a,
		const double	b,
		const double	c,
		bool	persist = `true`
	)

inline

add a 3D vector option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
a	the default value for the 1st value of the flag
b	the default value for the 2st value of the flag
c	the default value for the 3rd value of the flag
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addVec4Option	(	const char *	commandFlag,
		const char *	label,
		const double	defaultVal[4],
		bool	persist = `true`
	)

add a 4D vector option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
defaultVal	the default value for the flag if not set
persist	if true, the GUI option will be persisted as an optionVar

void AL::maya::CommandGuiHelper::addVec4Option	(	const char *	commandFlag,
		const char *	label,
		const double	a,
		const double	b,
		const double	c,
		const double	d,
		bool	persist = `true`
	)

inline

add a 4D vector option value to the GUI

Parameters

commandFlag	the flag for the command
label	human readable GUI label for the option
a	the default value for the 1st value of the flag
b	the default value for the 2st value of the flag
c	the default value for the 3rd value of the flag
d	the default value for the 4th value of the flag
persist	if true, the GUI option will be persisted as an optionVar

The documentation for this class was generated from the following file:

src/lib/AL_USDMaya/AL/maya/CommandGuiHelper.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation