If you have already created a custom command and want to add it to other toolbars, see Adding Custom Commands to Custom Toolbars.
Creating Script-based Custom Commands
When you create a command, it becomes available to be added to a toolbar, mapped to a key, or used in scripts. There are two ways to create a script-based custom command:
• By dragging a script to a custom toolbar. See Dragging Scripts to a Toolbar. This is a simple method that does not provide many options, but it may be useful for beginners or for a quick solution.
• By creating a self-installing command. Self-installing commands do not need to be manually registered. If desired, you can give yourself a headstart by using the Self-Installing Command Wizard to automatically create a rough template for a script-based command, as described in Using the Self-installing Command Wizard. For more information self-installing commands, see the SDK Guides.
You can create a custom command by dragging a script onto a custom toolbar. This creates a button that runs a script from a custom toolbar.
|
|
If you have already created a custom command and want to add it to other toolbars, see Adding Custom Commands to Custom Toolbars. |
To create a custom command by dragging a script onto a toolbar
1. Make sure that a custom toolbar (or a toolbar tab in a shelf) is displayed.
To display an existing custom toolbar, choose it from the View > Toolbars menu on the main menu.
For more information about custom toolbars in general, see Toolbars and Shelves.
2. Do one of the following:
- Select one or more lines in the history or editing pane of the script editor and drag them onto the custom toolbar.
Note that text dragged from the editing pane is removed. To leave it in place, Ctrl+drag it onto a toolbar instead. You can also drag text from any program that supports drag-and-drop actions on Windows.
Note also that when dropping text onto a toolbar, if the text ends with “.preset” and the preset file can be loaded, then XSI assumes you are creating a button for a preset. In all other cases, XSI assumes you are creating a button for a script.
or
- Drag a saved script file from a browser onto your toolbar. On Windows, you can also drag from a folder window.
or
- Drag a link to a script file from a Net View onto your toolbar.
3. When prompted, choose Script Command (external file) and click OK.
The Add Script Command dialog box opens.
4. Specify a Command/Button Name for the script. This is the text that will appear as a label on the button.
If you dragged lines from the script editor, the default command name is of the form Scriptnumber; if you dragged a saved script file, the default is the file name.
|
If the Command/Button Name contains spaces, then it can be split and displayed on two lines on a button. 
|
5. Specify a Script Command Name. This is the name that gets logged to the command history when you click the button.
You can also use this name to invoke your custom command from within another script. The command name for scripting cannot use spaces or punctuation.
6. You can also provide a brief Description. This description is displayed in the Customize Toolbar dialog box if you later add the command to other toolbars as described in Adding Custom Commands to Custom Toolbars. It is also displayed in the Keyboard Mapping dialog box—see Mapping Custom Commands to Keys.
7. Specify the file name for the script, including the path. If you dragged lines from the script editor, a default file name is supplied. If you dragged a script file, it is copied to the location and file name you specify.
8. If necessary, select the scripting language from the pop-up list in the Language box. The box lists the supported languages that are installed on your computer.
If you dragged lines from the script editor onto the toolbar, the default language is the one specified in your preferences — see Scripting Languages for more information.
If you dragged a saved file, the default language is based on the file name extension: .vbs for VBScript, .js for JScript, .pls for PerlScript, and .pys for Python ActiveX Scripting Engine.
9. If your script does not contain any procedures, there is nothing more to do — click OK to close the Add Script Command dialog box and add the button to your toolbar.
If your script does contain procedures and you want to call them instead of global code (that is, script fragments that appear outside of a discrete function or subroutine), continue with the rest of these steps.
This parses the script and finds the procedures and arguments.
|
Parsing a script may execute global code, that is, any code that is not within a defined procedure. It will also run procedures that are called from global code. |
11. If your script contains procedures, you can specify which procedure to execute when the button is clicked. Select the desired procedure from the pop-up list in the Script Procedure box.
If you do not specify a procedure, only global code (script fragments that appear outside of a function or subroutine) is executed, as well as any procedures that are called from global code.
|
|
Even when a procedure is specified, global code may be executed before the procedure is called. This is a side-effect of parsing the script with some scripting engines. To be certain that your script behaves predictably in all situations, do not mix global code and procedures in a script file when defining custom commands. |
|
|
For some scripting languages, such as PerlScript and Python, XSI cannot find the procedures automatically. In these cases you must type the procedure name into the Script Procedure box manually. |
12. If the selected procedure contains arguments, they are listed under Parameters. For each argument, specify the value to use when the script is run by doing one of the following:
- Enter a value in the corresponding Value box. This value is used when you click the button to run the script.
or
- Click twice in the Value box and select Prompt On Run from the pop-up list. This option prompts you to enter a value in a dialog box when you click on the button to run the script.
|
|
For some scripting languages, such as PerlScript and Python, you need to add parameters manually. You can use the New button to add a parameter to the Parameters list. To change the order, select a parameter and click the arrow buttons. To delete a parameter, select it and click the delete button (X). 
|
|
|
Make sure to give meaningful names to your arguments. When your custom command runs and prompts for values, the names are the only clues to the arguments’ functions. |
13. Click OK. The Add Script Command dialog box closes and the new button is added to your custom toolbar.
Using the Self-installing Command Wizard
You can use the Self-Installing Command Wizard to create a rough template for a script-based custom command, including stubs for callback functions. You can easily update the generated script file directly to implement many commands and other types of plug-ins all in the same file.
For more information about self-installing commands, see the SDK Guides.
To create a template for a self-installing command:
1. Open the Plug-in Manager (File > Plug-in Manager from the main menu).
2. On the Tree, Plug-in, or Item tab, choose File > New > Command to launch the wizard.
3. On the Plug-in Definition tab, enter general information about your custom command.
4. Use the Command Definition tab to define the command properties along with its arguments.
- The Command section is used for describing the command properties such as the scripting name, description and the command flags.
- The Arguments section is used for defining the command arguments. Click Add to add a new argument to the table, and then modify its Name, Default Value, and Handler as desired. To remove an argument, click in the first column of the row (the empty box) to select it, then click Remove.
Remember that you can click ? for help on every option in the wizard.
5. To preview your custom command, click Generate Code. A script file is created and opened in a text editing window.
6. If desired, return to the Self-installing Command Wizard to refine your custom command, for example, to add more arguments or modify the scripting name, and then repeat the previous step.
If you close the wizard, you can reopen it by clicking the CCmdWizard node under the SDK_Wizards model in an explorer.
7. Once you are satisfied with the rough template, you can finish your custom command by overwriting the different command callbacks in the generated script. Do not regenerate the custom command once you have modified the script manually — doing so will overwrite your modifications.
Adding Multiple Commands to the Same Plug-in File
When you have created a plug-in command using the Self-Installing Command Wizard, you can easily add multiple commands to the same plug-in file.
1. Open the plug-in file in a XSI’s script or text editor. For example:
- On the Plug-ins or Items tab of the Plug-in Manager, right-click on the item and choose Edit.
- If the command is available from a button on a custom toolbar, right-click on the button and choose Edit Script.
2. Right-click in the text editing pane and choose Tools > Add Command.
3. Use the Command Wizard to add information about your command. For more details, click ?.
4. Click OK in the Command Wizard.
Stubs are created for the Init and Execute callbacks of your command.
5. Save the file. The plug-in is reloaded.
SOFTIMAGE|XSI v.6.01