Command System: Executing

From The Foundry MODO SDK wiki
Jump to: navigation, search

This article explores the syntax used when executing commands. Executing a command is how the user performs an action that affects the user interface or scene. Scripts and plug-ins can also execute commands when it is safe; in the case of scripts, command execution is their primary means of interacting with the application.

Basic Execution

Commands are executed by entering their name and any necessary arguments. The kinds of values that arguments can accept depend on the argument's datatype. Common datatypes are described later on, but right now we'll deal with how to pass arguments to commands and execute them.

cmds.saveList

The cmds.saveList command was executed by entering its internal name (as opposed to the user names or button names shown in the user interface) without any arguments:

Explicitly Naming Arguments

Arguments can be set by explicitly specifying their name followed by a colon and the value of the argument. We could have provided the filename argument and skipped the file dialog entirely:

cmds.saveList filename:"d:\cmdlist.txt"

We could also specify the verbose argument but still pick the file from a file dialog:

cmds.saveList verbose:1

When you explicitly name your arguments, they don't even need to be in the order defined by the command:

cmds.saveList verbose:1 filename:{d:\cmdlist.txt}

Implicitly Named Arguments

In the above examples the argument name is included with its value, with a colon separating them two. The name is optional if the arguments are in order and none are skipped. For example, you could execute this command with the filename argument set just by doing this:

cmds.saveList "d:\cmdlist.txt"

You can skip naming arguments until you want to skip an argument entirely, or if you want to set the arguments out of order.

Wrapping arguments: Quotes and Curly Braces

Quotes and curly braces can be used when an argument contains a spaces, colons or other special characters that may be parsed by the command system. Spaces, for example, are used to separate arguments while colons are used to separate the argument name from its value. Curly braces can be used instead of quotes in cases where quotes are themselves part of the value. Curly braces can also be nested, making them extremely useful when wrapping arguments in Macros for substitutions.

cmds.saveList {d:\cmdlist.txt}

Values with Units: Using Square Braces

Square brackets can be used to provide values with units. In general, you'll want to stick with raw values in meters, radians, etc. The square brace syntax is best when you need to specifically operate in the current unit system, and as such it is rare to use it in scripts or plug-ins.

For example, the item.channel command switches its value argument's datatype based on the channel argument. In the following example, the pos.X channel is a distance datatype:

item.channel pos.X 0.1

As the basic units for the distance datatype is meters, this sets the "pos.X" channel to 0.1 meters. Also notice that because "pos.X' does not have any colons or spaces in it, we were able to leave out the quotes.

To provide more human-readable values, square braces can be used to specify units. This works exactly like entering values into edit fields, including mathematical operations and unit system support. Now you can directly set the value to 10 cm:

item.channel pos.X [10 cm]

It's important to remember that square braces use the current unit system unless units are specific provided. If the unit system was set to English, this:

item.channel pos.X [10]

would be parsed as ten feet, not ten meters. Since the user may have set to unit system to any arbitrary value, it is usually best to either specify units or always use the default units of the datatype (i.e.: do not use square braces), unless you really want to check the unit system preferences every time you execute a command.

Square braces also act like quotes and curly braces, allowing spaces and colons within.

Return Codes

Once a command has executed, a success or failure code is returned. Commands can fail to execute for a number of reasons, including that the command is disabled, the wrong number of arguments were passed, an unknown argument name was used, the user clicked Cancel to abort a dialog, a required argument was not set, and so on. All of these will usually open a dialog to report the error. If the command was executed from a Command History viewport, the error will also show up in the [[Command History Viewport#Results|Results] tab. All command failures are reported to the Event Log viewport as well.

Special Prefixes

Commands are executed with certain default properties that determine how that interact with the user. By default, error, informational and file dialogs will open if there are syntax errors in the command string, errors from command execution, or if the command needs user attention. Also, dialogs requesting argument values will not appear if all of the remaining arguments are option.

Often it is desirable to suppress these dialogs from scripts and plug-ins, while other times it is useful to force them to open. On the flip side, Macros automatically suppresses all sub-commands dialogs, but there may be times where you'll want to see those dialogs.

To facilitate this, modo supports special prefixes that can be added to the beginning of the command name. These allow error dialogs to be suppressed or force the the command dialog to open.

These prefixes can be used in the Command entry, from within scripts and plug-ins, from the Form Editor and Input Editor, and anywhere else commands are executed.

Suppressing Dialogs: !

Error dialogs can be suppressed by prefixing the command name with an exclamation point. If a command didn't have enough arguments and would have opened a command dialog, that will also be suppressed. Commands that open custom user interfaces should respect this flag and fail to open their UIs.

scene.saveAs c:	est.lxo
!scene.saveAs c:	est.lxo

Here the first scene.saveAs command saves the current mesh to c: est.lxo. If we tried to execute that same command a second time, we would be presented with a dialog asking us if we want to overwrite the file. Since we don't want to see that dialog, we can prefix the command with an exclamation point. Now no dialogs will appear when scene.saveAs is used.

Suppressing All Dialogs: !!

The single exclamation point syntax only suppresses that specific command's error dialogs. If a command executes sub-commands, they may still show dialogs. This could occur for scripts using dialog.open, for example.

To suppress sub-command dialogs, use two exclamation points. This will keep any dialogs from any sub-commands from appearing.

!!@C:MyScript.pl

Showing Dialogs: +

Although the default behavior is to show dialogs when executing commands, sub-commands may have been suppressed using the exclamation point syntax or by the parent command itself. To get around this issue, we can prefix the command name with a plus sign.

The plus sign acts as the inverse of the exclamation point, forcing the command to open any dialogs that might otherwise be suppressed. For example, macros always suppress commands executed within them, so this can be used to make them appear.

This simple macro creates a dialog using an argument and displays it. Notice the plus before the dialog.open command.

1)  #LXMacro#
2)  #
3)  # InfoDialog.lxm
4)  # Opens an info dialog.  The first argument passed in will
5)  # be displayed in the title, and the second argument will
6)  # fill in the message body.
7)  #
8) 
9)  # Setup
10) dialog.setup info
11) dialog.title {%1}
12) dialog.msg {%2}
13)
14) # Open the dialog
15) +dialog.open

See the Macros article for details on how to write macros.

Showing All Dialogs: ++

As with the exclamation point syntax, the single plus affects only the single command it prefixes, with sub-commands performing their default behavior. To force all sub-command dialogs to open, two plusses can be used.

Showing Command Dialogs: ?

Many commands have optional arguments. If these arguments are not set, the command uses its defaults and carries on as normal, and only if a required argument is missing does a dialog open you can fill in the values.

There are cases where you want to see the command dialog even if all of the required arguments are set. The legacy viewport.3Dview command consisted only of optional arguments, but you might have wanted to assign it to a key and open it's command dialog. In other cases, you may have set all the arguments to some defaults, but also want the dialog to open so the user can change them.

The question mark syntax will force an argument dialog to open before the command is executed. The user can then fill in optional arguments or change required arguments and execute the command as normal.

This example will first set the item.name command's first argument to Enter Name, then open the arguments dialog so the user can enter a new name. If the leading question mark was not present, the selected items would simply be renamed to Enter Name, and no dialog would open.

?item.name "Enter Name"

More Information