Object Hierarchy | Related C++ Class: Command
Inheritance
SIObject
Command
Introduced
2.0
Description
Represents a Softimage command (either built-in or custom). This object encapsulates information on a command such as the name, category, arguments, where it is implemented etc. Custom commands behave just like built-in Softimage commands--they are logged in the history window and can be exposed to scripting.
The XSIApplication.Commands property provides access to all the built-in and custom commands installed in the system. For example, to get the definition of the Translate command, you can use 'set oCmd = Commands( "Translate" )'.
Note that the Commands property finds commands by SIObject.Name, not by Command.ScriptingName. You can find the Name of a command by running it and then checking the Edit menu (where the Name of the last executed command always appears after 'Repeat' and 'Undo'). You can also iterate over the entire collection of commands (see the first example below).
To find a command by its scripting name, use XSIApplication.GetCommandByScriptingName. You can find the ScriptingName of a command by running it and then checking the command log.
Commands are primarily called from scripts, in which case they are invoked by calling the Command.ScriptingName with the scripting syntax for calling a function, in effect they appear as if they are "helper functions" available to the script writer. For example to call the custom command "Foo" from jscript the syntax is "Foo( arg1, arg2 );" For scripts embedded inside Netview pages this syntax does not work, however all commands can be called as methods on the Application object (for example oApplication.Foo( arg1, arg2 ) ;). It is also possible to invoke a command through the Command.Execute method.
You can also place commands in toolbars (see CreateToolbarButton). And there are two ways to place custom commands in Softimage menus. The first is through the command category (see siCommandCategory) and the second, more powerful approach, is through the Menu API.
The Arguments that a command accepts is part of its definition. All commands have a fixed number of arguments, and they are passed to the callback implementing the command in the order that they are defined in the ArgumentCollection. It is possible to define a default value and an ArgumentHandler for each argument, so commands are often invoked without specifying each argument value explicitly.
Softimage supports three possible ways to define a custom command: the embedded command, the plug-in based command and the v1.5 command. They are all based on the same Command object API but they have some subtle differences.
The embedded approach, which is new with v4.0, involves storing the implementation code of the command directly inside the definition. (See Command.Code). This approach is convenient for simple commands and is the approach demonstrated widely in the examples under the Command and Argument objects. The command definition is persisted in a .DSDynamicCommandMap file and can also be transferred to other machines by packaging it inside a xsiaddon file. Commands of this sort can be created interactively with CreateAndEditCommand. The command definition can be changed interactively by calling EditCommand. It can be destroyed by calling XSIApplication.RemoveCommand.
The plug-in based approach, also new with v4.0, involves implementing the definition and implementation of the custom command inside a self-installed plug-in (see PluginRegistrar.RegisterCommand, the example in Command.Enabled and the SimpleCommand example that is part of the installation). This approach is ideal for complex scripts and supports the C++ API. Because multiple commands, Menus, CustomProperty objects and other elements can all be implemented inside the same Plugin module it is often possible to write an entire sophisticated tool inside a single script file or dll. A command defined in this fashion is not persisted inside the .DSDynamicCommandMap file, instead its definition is regenerated by calling the Init callback each time the application is started. To edit the command definition, change the code inside the Init callback and reload the plug-in. To remove the custom command, remove the plug-in script or dll.
The older workflow, which was introduced in v1.5, is still fully supported. The steps to defining a custom command with this approach are the following:
(1) Create a command object with XSIApplication.CreateCommand (2) Define the properties of the Command object using its properties. For example, Command.Language, Command.ReturnValue, Command.SetFlag, etc.
(3) Add any arguments you want to specify with ArgumentCollection.Add or ArgumentCollection.AddObjectArgument For example, myCommand.Arguments.Add "myArgName", siArgumentInput, true, siBool.
(4) Create the script file on disk (Command.FileName) and create a function (Command.Handler). This function takes the same number of arguments as were specified in the ArgumentCollection and it can return a value if Command.ReturnValue is true.
(5) Register the command in Softimage by using XSIApplication.AddCommand.
(6) The command is now available to be invoked. Softimage automatically stores the command definition so the command remains available in future Softimage sessions.
(7) To change the definition of the command either call XSIApplication.RemoveCommand and follow steps 2-5 again, or else call Command.Update.
(8) To remove the command from Softimage, use XSIApplication.RemoveCommand.
Note: For instructions on how to package a custom command as an add-on, see Add-on Packages.
Methods
|
|
|
Properties
|
|
|
See Also
|
|
|
|
Examples
• See Command.1.js
• See Command.2.js
• See Command.3.js
• See Command.4.vbs
• See Command.5.js
Autodesk Softimage 2011