Custom Command Wizard

 
 
 

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

  1. Click FilePlug-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.

  2. Do one of the following:

    • To create the command in the User location, click FileNewCommand.

    • To create the command in a different location (such as a workgroup or an Add-on directory), expand the location in the Plug-in Tree, right-click the Plugins folder and click NewCommand.

    The command wizard appears.

  3. 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.

    The wizard automatically replaces spaces with underscores.

  4. 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).

  5. From the Coding Language list, select the language you want to generate.

  6. If you want to add the command to a menu:

  7. Click the Command Definition tab, and then type a description and tooltip for the command.

  8. If the command will not return a value, clear the Return Value check box.

  9. 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.

  10. 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.

  11. Click Generate Code to generate the custom command.

The generated plug-in is automatically loaded and executed, and the code is loaded into the script editor.

Notes

  • 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.

Plug-in Definition

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.

Command Name

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).

Plug-in Name

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.

Important

If you change the command name more than once the wizard overwrites your plug-in name again with a newly generated name based on the command name.

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.

Author

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.

Coding Language

Specifies the type of code (C++, C#, JScript, VBScript, Python) you want to generate.

Add to Menu

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.

Menu Label

Specifies the text that appears on the menu.

Output Directory

Specifies the location of the generated files.

Command Definition

The Command Definition tab allows you to set command properties and define the command arguments.

Description

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).

Tooltip

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.

Supports Key Assignment

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.

Cannot Be Used In Batch

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.

Not Logged

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.

Return Value

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.

Arguments

This section allows you to define the command arguments.

Name

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).

Default Value

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.

Handler

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.

Creative Commons License Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License