Command Editor

 
 
 

| Description | Arguments | Implementation

Modifies the properties of an existing custom command, or displays the properties of a built-in command.

To modify/display the properties of a command: Choose View Customize Toolbars, select a group on the left and a command on the right, and click Details

NoteYou cannot create or modify the properties of a self-installing command using the Command Editor.

Description

Name

The descriptive name that appears in lists such as the Customize Toolbar dialog box, the Keyboard Mapping dialog box, and the explorer. It is not the name used to invoke the command in scripts.

Scripting Name

The name used to invoke the command in scripts.

Description

A brief description of the command. This is typically used for describing a command in the Softimage user interface, such as in the Customize Toolbar and Keyboard Mapping dialog boxes.

ToolTip

A short string that is displayed when the mouse pointer hovers over a button on a toolbar. If no tooltip is defined, the tooltip uses the Description instead, and if no Description is defined it uses the Name.

Category

A pipe-delimited ("|") string containing a list of the categories that the command belongs to. This information is used for filtering commands in lists. Custom commands always belong to the category "Custom".

Enabled

Enables or disables a command. Disabled commands appear dimmed and cannot be chosen on menus. This option affects only the user interface; it does not block the command from being executed from a script.

Supports Key Assignment

Allows the command to appear in the Keyboard Mapping dialog box and be assigned to a key. You can turn this off, for example, if the command is a low-level helper that you don't want to be used directly.

Cannot Be Used in Batch

Prevents the command from being used in scripts run from the command line using xsibatch or xsi -script. Activate this option if the command requires user input.

Is Not Logged

Prevents the command from being logged in the command history.

Built-in

Indicates whether the command is native to Softimage or not. This option is always off for custom commands and cannot be changed.

Arguments

ReturnValue

Specifies whether the command returns a value. If false, Softimage assumes there is no return value, regardless of whether or not the implementation actually tries to return a value.

If true, Softimage tries to return a value. If the command does not actually return anything, an empty Variant is returned.

To return a value using VBScript, use Function... End Function instead of Sub... End Sub.

Argument List

Lists the arguments of the commands, if any.

Name

The name of the argument. For custom commands, you can click in the cell and type a new name.

Type

The type of argument: Input or Output. For custom commands, all arguments are Input.

Default Value

The value of the argument that is used when no value is specified in the command call. For custom commands, you can click in the cell and type a new value.

Handler

The name of a handler that preprocesses the argument value passed in the command call. For custom commands, you can click in the cell and select a value from the list.

  • None: No preprocessing is performed on the argument.

  • Animatable Marked Parameters: This argument handler is identical to the Marked Parameters argument handler (below), except it filters out any parameters in the list that are not animatable. This is a convenient way to avoid having to write extra error-handling code in the command implementation.

  • Collection/Selection: When no argument value is specified, this argument handler passes the current selection to the command.

    When a string is specified, it is resolved into an XSICollection containing all the specified objects. Wildcards and lists of objects are supported with the same syntax as used by SelectObj. For example "*", "*.polymsh", "cube1,grid2,light1", and so on.

  • SingleObj: When no argument value is specified, this argument handler passes NULL (an empty object) as the value. When a string is specified, Softimage attempts to resolve it to an object. For example "MyGrid" would be converted to the X3DObject representing that grid. In effect, its behavior is similar to calling Dictionary.GetObject. When an object is specified, the argument handler just passes it directly to the command.

  • Frame: When no argument value is specified, this argument handler sends the current frame number as the value of the argument. If a value (or default value) is specified for the argument, then this Argument Handler does nothing.

  • Frame Rate: When no argument value is specified, this argument handler sends the current frame rate, for example 25. If a value (or default value) is specified for the argument, then this argument handler does nothing.

  • Marked Parameters: This argument handler is similar to the Collection/Selection argument handler, except it deals with marked parameters.

    When no argument value is specified, this argument handler passes an XSICollection containing all the parameters that have been marked on the selected objects. Note that only selected objects are considered when determining the marking list.

    When a string value is specified, Softimage attempts to resolve this into an XSICollection with the specified arguments. Wildcards such as "*" and "/" are supported. For example, "Grid1,Grid2/Name" will resolve into the parameters Grid1.Name and Grid2.Name.

Add Argument

Adds a new argument for custom commands. Click this button, then edit the columns of the new parameter in the Argument List above.

Remove Argument

Removes the last argument in the list.

Implementation

Language

The language in which the command is written.

Handler

The name of the function or subroutine that implements the command. In other words, the handler is the name of the callback function that Softimage calls each time the command is invoked.

For custom commands implemented in script files, specify the name of the appropriate function or subroutine. The handler is required if you want to pass arguments to the command or implement multiple commands in the same script file. If you do not specify a handler, then global code is executed.

For commands implemented in compiled libraries (.dll or .so files), the name is fixed and the handler is ignored.

For embedded commands, the handler is required if you want to pass arguments to the command.

Implementation

The location where the command handler is stored:

  • Embedded: the handler is stored directly in the command map file in your user application path. For custom commands, enter the handler code in the editing pane under Embedded Code. This is useful for short "macros" that consist of a few commands. For longer scripts, it is easier to use an external script file or plug-in.

  • in Script File (or DLL): the handler is in an external file. For custom commands, specify the file in File Name below.

File Name

The path and name of the external file containing the command handler.

Embedded Code

Generate Stub

Generates a stub function, including arguments, in the editing pane below. Use this button only when creating a new custom command. Regenerating will overwrite any existing code.

[Editing Pane]

Contains the code for embedded command handlers. Edit the text to modify custom commands.

If you are using a handler, the code in the corresponding function or subroutine will be executed when the command is called. If you are not using a handler, global code is executed.