You can use the Custom Command Wizard to generate the code for a self-installing plug-in that contains a custom command. In addition to generating the skeleton code for the plug-in and the command, the wizard can also generate the code required to add the command to a menu.
To create a custom command using the Custom Command Wizard
Click File
Plug-ins to open the Plug-in Manager.
In the Tools Development Environment layout, you can click the Plug-ins tab to switch to the Plug-in Manager view.
In the Command Name box, type a plug-in item name for the command.
The first character in a command name should be a letter. Subsequent characters can be letters, numbers, or underscore (_) characters.
If you want to change the plug-in name, type a different name in the Plug-in Name box. By default, the plug-in name is based on the command name (although spaces are not replaced by underscores).
From the Coding Language list, select the language you want to generate.
If you want to add the command to a menu:
From the Add to Menu list, select a menu anchor point.
In the Menu Label box, type the text you want to appear on the menu.
Click the Command Definition tab, and then type a description and tooltip for the command.
If the command will not return a value, clear the Return Value check box.
For C++ API, you can get the wizard to include the skeleton code for the Undo, Redo, and TermUndoRedo callbacks by checking the Undo/Redo Callbacks (C++ only) check box.
If you want to add arguments to the command:
Under Arguments, click Add.
Click in the Name box and type a name for the argument.
If you want to specify a default value, click in the Default Value box and then type the value. For strings, do not include the quotation marks: the wizard adds the quotation marks when it generates the code.
If you want to use an argument handler, click in the Handler box, and then click an argument handler.
The generated plug-in is automatically loaded and executed, and the code is loaded into the script editor.
You can use the wizard to add commands to an existing plug-in. Open the plug-in in a text editor or script editor, right-click in the editing pane, point to Tools, and then click Add Command.
To remove an argument, select the argument row by clicking the first column of the row (the empty box). Then click Remove.
You can save wizard presets for types of commands that you frequently want to generate.
The wizard creates a model named SDK_Wizards, and under that model puts a custom property for each command you create. You can open the wizard for a command by double-clicking the corresponding custom property.
The Plug-in Definition tab allows you to enter the information required to generate the XSLLoadPlugin function, which registers the plug-in items such as commands and menus with Softimage.
Specifies the name of the command (the plug-in item name). The first character should be a letter. Subsequent characters can be letters, numbers, or underscore (_) characters.
By default, this name is used both as the command name (in the user interface and in the list returned by XSIApplication.Commands or Application::GetCommands and as the scripting name (the name used to run the command). The command name is also used to name the generated callback functions.
If you want to have different names (for example, a longer, more descriptive name for the user interface and a shorter name for scripting), you'll have to edit the call to PluginRegistrar.RegisterCommand or PluginRegistrar::RegisterCommand in the generated XSILoadPlugin function. Note that changing the command name (the first argument to RegisterCommand) means you have to change the names of the command callback functions (such as Execute and Init).
Specifies the name of the plug-in. By default, the plug-in name is based on the command name. You may want to change this name if the plug-in will contain more than one command, or other plug-in items such as properties.
For example, if you initially change the command name from NewCommand to My Command and then tab to the Plug-in Name box, the command name and plug-in name will be My_Command and My CommandPlugin respectively. If you change the name of the plug-in to My Cmd Plugin, the command name stays the same. If you go back to the Command Name box again and change the command name to XYZ, the plug-in name automatically changes to XYZPlugin.
Identifies the author of the custom command (for example, type your name or the name of your organization). The Plug-in Manager displays this information for each plug-in.
Specifies a menu anchor point for the custom command. An anchor point is a specific location on a menu (for example, siMenuTbGetPrimitivePolygonMeshBasicID inserts a menu item between Torus and Dodecahedron on the GetPrimitivePolygon Mesh menu). Click ? for a description of available menu anchor points.
Leave None in this drop-down box if you don't want to add your custom command to a menu.
Specifies a brief description of the command. This description is displayed in the Softimage user interface (for example, in the Customize Toolbar and Keyboard Mapping dialog boxes).
Specifies a short description displayed when the user points to the command button on a toolbar. If no tooltip is defined, the description is displayed instead, and if no description is defined, the command name is displayed.
Specifies whether a keyboard shortcut can be assigned to the command in the Keyboard Mapping dialog box. Clear this check box if the command is a low-level helper function that you don't want to expose for general use.
Specifies whether the command can be used in scripts run from the command line using xsibatch or xsi -script. Select this check box if the command requires user input.
Specifies whether the command is logged to the command history. Disabling logging can improve performance; for example, if the custom command is called frequently by other scripts, or if the command takes a large collection of objects as an argument.
Specifies whether the command returns a value. Clear this check box if you command does not to return a value. If this check box is selected, but the command does not return a value, Softimage returns an empty Variant. If the check box is not selected, Softimage ignores any value returned by the command.
For a VBScript command, this check box determines whether the wizard generates a subroutine (cannot return a value) or a function (can return a value).
Undo/Redo Callbacks (C++ only)
Check this option to generate the skeleton code for the optional Undo, Redo, and TermUndoRedo callbacks if you are implementing the plug-in with the C++ API.
This section allows you to define the command arguments.
Specifies the name of the argument. The name must be a valid identifier (in general, the first character must be a letter and subsequent characters can be letters, numbers, or underscore (_) characters).
Specifies a default value for the argument. Do not include quotation marks when you type the default value. The wizard adds quotation marks when it generates the code.
Softimage determines the argument type from the default value, and tries to convert the argument value to that type when a user runs the command. For example, if the default value is true, the argument is a boolean value, and Softimage converts values such as 0, "0", and "false" to false. An argument value that cannot be converted to a boolean, such as "C:\Softimage", will cause a type mismatch error.
| To add this type of argument: |
Do this: |
|---|---|
| boolean |
In the Default Value box, type true or false. Do not add quotation marks. |
| string |
In the Default Value box, type a string. Do not add quotation marks. |
| number |
In the Default Value box, type a number. The wizard automatically adds quotation marks around the number, so you must edit the generated ArgumentCollection.Add or ArgumentArray::Add and remove the quotation marks. |
| Any type |
Leave the Default Value box empty and Handler set to None. You'll be able to pass in any type of value: boolean, string, number, array, or Softimage object. To be able to pass in JScript objects, you'll need to edit the generated ArgumentCollection.Add or ArgumentArray::Add and set the argument type to siDispatch. |
Specifies an argument handler that processes the argument values passed to the command. For example, the Collection/Selection argument handler converts strings such as "cube,cone" to collections, and null values into the current Selection.
If a command takes Softimage objects as arguments, you should consider using the SingleObj or Collection/Selection argument handlers.
| Argument Handler |
Description |
|---|---|
| None |
Specifies that no pre-processing is performed on the argument. |
| Animatable Marked Parameters |
Converts strings such as "Grid1,Grid2/Name" to an XSICollection or CRefArrayof animatable marked parameters. Similar to the Marked Parameters handler, but also filters out non-animatable parameters. If you want a default value for the argument, then in the Default Value box, type a marking list such as "/kine.pos". Default value: an XSICollection or CRefArray of all animatable marked parameters on the selected objects. |
| Collection/Selection |
Converts strings such as "*", "*.polymsh", and "cube,grid,light" to an XSICollection or CRefArray of objects. If you type an object list such as "*", "*#model*", or "*#3dobject" in the Default Value box, the Collection/Selection handler provides the specified collection of objects as the default argument value. Default value: an XSICollection or CRefArray containing the currently selected objects. |
| SingleObj |
Converts a string such as "MyGrid" to the corresponding X3DObject. Default value: a null value (an empty object). |
| Frame |
Provides the current frame number. Does nothing if a value (or a default value) is specified for the argument. Default value: the current frame number. |
| Frame Rate |
Provides the frame rate. Does nothing if a value (or a default value) is specified for the argument. Default value: the current frame rate. |
| Marked Parameters |
Converts strings such as "Grid1,Grid2/Name" to an XSICollection or CRefArrayof marked parameters. If you want a default value for the argument, then in the Default Value box, type a marking list such as "/kine.pos". Default value: an XSICollection or CRefArray of all marked parameters on the selected objects. |