Detailed 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.
You can access all the built-in and custom commands installed in the system with Application::GetCommands.
- Note:
- Make sure the name you use as a key to access a command in Softimage is the string returned by SIObject::GetName rather than Command::GetScriptingName. 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
RepeatandUndo). You can find the ScriptingName of a command by running it and then checking the command log. You can also iterate over the entire collection of commands.
Commands are primarily called from scripts, in which case they are invoked by calling the string returned by Command::GetScriptingName 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 );
The C++ API function Application::ExecuteCommand can be used to execute both built-in and custom commands.
You can also place commands in toolbars and menus. There are two ways to place custom commands in Softimage menus. The first is through the command category (see the siCommandCategory enum) and the second, more powerful approach, is through the Menu API.
The arguments that a command accepts are encapsulated in its definition. All commands have a fixed number of arguments, and they are passed to the callback implementing the command in the order to be defined in the ArgumentArray. 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 plug-in based command is the most convenient for commands implemented with the C++ API. For information about the other approaches please see the Command object documentation in the Scripting Reference guide.
The plug-in based approach, new with v4.0, involves implementing the definition and implementation of the custom command inside a self-installed plug-in (see PluginRegistrar::RegisterCommand). Because multiple commands, Menu objects, CustomProperty objects and other elements can all be implemented inside the same .dll (or .so) module, it is often possible to write an entire sophisticated tool inside a single binary file.
- Note:
- A command defined in this fashion is not persisted inside the
.DSDynamicCommandMap file; instead its definition is regenerated by calling theInitcallback each time the application is started. To edit the command definition, change the code inside theInitcallback and reload the plug-in. To remove the custom command, remove the plug-in script or dll.
- Note:
- For more information see cus_cmds Custom Commands .
- Since:
- 4.0
- Example:
- This example is similar to the JScript example implemented in the Object Model reference for the Command object.
// ***************************************************************************** // // Example of Self-installed custom commands. // // Note: For Windows there must also be a .def file as part of the .dsp // and which contains the following contents: // // EXPORTS // XSILoadPlugin @1 PRIVATE // CommandHelloWorldCpp_Init @2 PRIVATE // CommandHelloWorldCpp_Execute @3 PRIVATE // CommandSimpleCpp_Init @4 PRIVATE // CommandSimpleCpp_Execute @5 PRIVATE // CommandSimpleObjectCpp_Init @6 PRIVATE // CommandSimpleObjectCpp_Execute @7 PRIVATE // // // ***************************************************************************** #include <xsi_application.h> #include <xsi_argument.h> #include <xsi_command.h> #include <xsi_context.h> #include <xsi_pluginregistrar.h> #include <xsi_status.h> #include <xsi_x3dobject.h> #include <xsi_model.h> using namespace XSI; #ifdef unix extern "C" #endif CStatus XSILoadPlugin( XSI::PluginRegistrar& in_reg ) { //This function is called by XSI to find out what commands or //other items have been defined inside this dll. in_reg.PutAuthor( L"Softimage" ); in_reg.PutName( L"cppcommanddemo Plug-in" ); in_reg.PutVersion( 1, 0 ); in_reg.RegisterCommand( L"CommandHelloWorldCpp", L"CommandHelloWorldCpp" ); in_reg.RegisterCommand( L"CommandSimpleCpp", L"CommandSimpleCpp" ); in_reg.RegisterCommand( L"CommandSimpleObjectCpp", L"CommandSimpleObjectCpp" ); return XSI::CStatus::OK; } #ifdef unix extern "C" #endif XSI::CStatus CommandHelloWorldCpp_Init( const XSI::CRef& in_context ) { //This function is called to give you the opportunity to define the command. Context ctx(in_context); Command cmd(ctx.GetSource()); cmd.EnableReturnValue( false ) ; // This command takes no arguments return CStatus::OK; } #ifdef unix extern "C" #endif XSI::CStatus CommandHelloWorldCpp_Execute( XSI::CRef& in_context ) { Application app; app.LogMessage( L"Hello world" ) ; // Return a failure status if you want the // calling script to halt return CStatus::OK; } #ifdef unix extern "C" #endif XSI::CStatus CommandSimpleCpp_Init( const XSI::CRef& in_context ) { Context ctx(in_context); Command cmd(ctx.GetSource()); cmd.EnableReturnValue( true ) ; ArgumentArray args = cmd.GetArguments(); // You must mention the arguments you want // The name is not important but must be unique args.Add( L"A" ); args.Add( L"B" ); return CStatus::OK; } #ifdef unix extern "C" #endif XSI::CStatus CommandSimpleCpp_Execute( XSI::CRef& in_context ) { Application app; Context ctxt(in_context); // Access the arguments to the command CValueArray args = ctxt.GetAttribute( L"Arguments" ); CValue argA = args[0] ; CValue argB = args[1] ; // Example of how you can // set the return value of the command CValue returnValue ; if ( argA.m_t == CValue::siString ) returnValue = (CString)argA + (CString)argB ; else returnValue = (double)argA + (double)argB ; ctxt.PutAttribute( L"ReturnValue", returnValue ); return CStatus::OK; } #ifdef unix extern "C" #endif XSI::CStatus CommandSimpleObjectCpp_Init( const XSI::CRef& in_context ) { Context ctx(in_context); Command cmd(ctx.GetSource()); cmd.EnableReturnValue( true ) ; ArgumentArray args = cmd.GetArguments(); args.AddObjectArgument( L"obj" ); return CStatus::OK; } #ifdef unix extern "C" #endif XSI::CStatus CommandSimpleObjectCpp_Execute( XSI::CRef& in_context ) { Application app; Context ctxt(in_context); // Access the arguments to the command CValueArray args = ctxt.GetAttribute( L"Arguments" ); CValue argObj = args[0] ; SIObject argSIObject = (CRef)argObj ; app.LogMessage( L"Name of the input object " + argSIObject.GetName() ) ; // Return a new object as the return value Model root = app.GetActiveSceneRoot(); X3DObject returnObj; root.AddGeometry( L"Grid", L"MeshSurface", L"", returnObj ); ctxt.PutAttribute( L"ReturnValue", returnObj.GetRef() ); // Return a failure status if you want the // calling script to halt return CStatus::OK; } // To try out this example compile and put the resulting dll or // so file in your \Application\Plugins directory or update // the XSI_PLUGINS env variable. // Then run the following JScript code: // Demonstrate the custom commands that are defined in the plug-in DemoCommands() ; function DemoCommands() { // It is simple to execute a custom command, especially one // like this with no return value or arguments. // Will log "Hello World" CommandHelloWorldCpp() ; // Will log "15" logmessage( CommandSimpleCpp( 5, 10 ) ); // Will log "concat" logmessage( CommandSimpleCpp( "con","cat" ) ) ; newscene( null, false ) ; var oSphere = ActiveSceneRoot.AddGeometry("Sphere", "NurbsSurface") ; //Will log: //INFO : "Name of the input object sphere" //INFO : "grid" logmessage( CommandSimpleObjectCpp( oSphere ) ) ; //XSI can also turn an string to an object: //INFO : "Name of the input object grid" //INFO : "grid1" logmessage( CommandSimpleObjectCpp( "grid" ) ) ; }
#include <xsi_command.h>
Constructor & Destructor Documentation
| Command | ( | ) |
Default constructor.
| ~Command | ( | ) |
Default destructor.
Member Function Documentation
| bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
- Parameters:
-
in_ClassID class type.
- Returns:
- true if the class is compatible, false otherwise.
Reimplemented from SIObject.
| siClassID GetClassID | ( | ) | const [virtual] |
Creates an object from another object. The newly created object is set to empty if the input object is not compatible.
- Parameters:
-
in_obj constant class object.
- Returns:
- The new Command object.
| ArgumentArray GetArguments | ( | ) |
Returns an array of Argument objects defined for this command.
- Since:
- 4.0
| CString GetScriptingName | ( | ) | const |
Returns the scripting name (ScriptingName) for the command.
The scripting name is used for executing the command; for example, from a script or by calling Application::ExecuteCommand. Sometimes this string is different from the actual name of the command, which is often used as a label for menu or buttons and may have space characters in it.
- See also:
- SIObject::GetName
- Since:
- 4.0
Sets the scripting name (ScriptingName) for the command. This name should not contain any spaces or start with a number. To avoid confusion it should be the same or very similar to the command's name.
- Parameters:
-
in_Str The new scripting name to set.
- Since:
- 4.0
| CString GetHandler | ( | ) |
Returns the handler name for a script-based command. The handler specifies 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 a command implemented with the C++ API as a self-installed plug-in this property is not necessary because the handler is determined based on the name of the command. For example the handler of HelloWorldCpp would be HelloWorldCpp_Execute().
- Since:
- 4.0
Sets the handler name for a script-based command. This is only necessary when defining a custom command that is implemented as a script.
- Deprecated:
- 9.5 (2011) This method is obsolete and must not be used.
| CString GetLanguage | ( | ) |
Returns the language used for implementing this command's handler function. The values can be one of the following:
CPP(using the Softimage C++ API)C#(C# using the Softimage Object Model via .NET)Python(Python scripting language using the Softimage Object Model)JScript(JScript using the Softimage Object Model)VBScript(VBScript using the Softimage Object Model)
The caller of a command does not need to be concerned with this property because any command can be called from any supported scripting language, C#, or the C++ API.
- Since:
- 4.0
Sets the language used for implementing this command. It is not necessary to call this function for a custom command implemented as a self-installed plug-in.
- Deprecated:
- 9.5 (2011) This method is obsolete and must not be used.
| CString GetFileName | ( | ) |
Returns the .dll or script file that implements the command. For many built-in commands this property is not specified.
- Since:
- 4.0
Sets the name of the file exposing the handler function. The full path should be specified. It is not necessary to set this property for a custom command implemented inside a self-installed plug-in.
- Deprecated:
- 9.5 (2011) This method is obsolete and must not be used.
| CString GetCode | ( | ) |
Returns the implementation of the command. This property only applies to script-based custom commands that are implemented by embedding the code directly in the command definition rather than using an external file. For commands implemented with the C++ API this returns an empty string.
- Since:
- 4.0
Sets the implementation of a script-based custom command. This is a convenient way to implement small, simple script-based custom commands. The code is stored as part of the Command definition.
- See also:
- Command::PutLanguage
- Deprecated:
- 9.5 (2011) This method is obsolete and must not be used.
| bool IsReturnValueEnabled | ( | ) |
Returns true if the custom command returns a value. If you call a command that does not return a value then Softimage always passes an empty CValue as the return value.
- Since:
- 4.0
| CStatus EnableReturnValue | ( | bool | ) |
Many custom commands return values, for example a newly created object or a calculated number. Other custom commands act like void functions in C++ and perform some operation but do not return any information. This function allows you to signal whether the custom command can be expected to return a value or not. The default behavior is true.
- Since:
- 4.0
| CString GetCategory | ( | ) |
Returns a string containing a list of the categories that the command belongs to. This information is similar to SIObject::Categories but this function returns a string delimited with the pipe (|) character rather than an array. Custom commands always belong to the Custom category. If the siCommandCategory argument was specified in the call to Application::CreateCommand then a string representing the specified category will be included in the returned string.
- Since:
- 4.0
| CString GetDescription | ( | ) |
Returns a string that describes the command.
- Since:
- 4.0
Optionally sets a descriptive string for the command. The description is shown in the Softimage user interface (for example on the Customize Toolbar dialog).
- Since:
- 4.0
| CString GetTooltip | ( | ) |
Returns the tooltip string for the command.
- Since:
- 4.0
Optionally sets the tooltip. This text will appear when the mouse hovers over a command button on a toolbar.
- Since:
- 4.0
| CString GetUID | ( | ) |
For advanced users. Returns the GUID that Softimage uses internally to distinguish between different custom commands. This can be used with the CreateToolbarButton command.
- Since:
- 4.0
| bool IsEnabled | ( | ) |
Returns false if the command has been disabled.
- Since:
- 4.0
| CStatus PutEnabled | ( | bool | ) |
Enables or disables a command. This flag only affects the user interface; it does not block the command from being executed from a script. This property is often used in conjunction with the Menu API. By default all custom commands are enabled.
- Since:
- 4.0
| bool IsBuiltin | ( | ) |
Distinguishes between custom commands and the commands that ship as part of the Softimage application (called either native or built-in commands).
- Since:
- 4.0
Executes the underlying command.
- Parameters:
-
out_return The value returned by the underlying command. If the command has no return value explicitly defined, Execute returns all output arguments in a CValueArray object. However, if the command defines a return value, you cannot extract any output arguments from it. This is because the command is not returning an output argument array, but a specific value. You can check the Return Value section in the reference documentation to see whether it uses an explicit return value and what that value is.
- Returns:
- CStatus::OK success
- CStatus::Fail failure
- Note:
- If the command expects arguments and none are specified then it is invoked with the default arguments.
The recommended way to execute a command from the C++ API is to call Application::ExecuteCommand
- Since:
- 4.0
| bool GetFlag | ( | LONG | in_whichflag | ) |
Returns the state of one of the various flags that affects command behavior. You can set the value of a flag with Command::SetFlag.
- Parameters:
-
in_whichflag Value from the siCommandCapabilities enum
- Since:
- 4.0
| CStatus SetFlag | ( | LONG | in_whichflag, |
| bool | in_newvalue | ||
| ) |
Sets the state of one of the various flags that affects command behavior. You can test the value of these flags with Command::GetFlag.
- Note:
- If the command already exists, you must call Command::Update to update the official definition of the command, otherwise the change is limited to the scope of that particular command object.
- Parameters:
-
in_whichflag Flag to set. in_newvalue True to enable the flag (default); false to disable it.
- Since:
- 4.0
| bool SupportsKeyAssignment | ( | ) |
Sets the state of the ::siSupportsKeyAssignment flag (shortcut for Command::GetFlag(siSupportsKeyAssignment) ).
- Since:
- 4.0
| bool CannotBeUsedInBatch | ( | ) |
Sets the state of the ::siCannotBeUsedInBatch flag (shortcut for Command::GetFlag(siCannotBeUsedInBatch) ).
- Since:
- 4.0
| bool IsNotLogged | ( | ) |
Sets the state of the ::siNoLogging flag (shortcut for Command::GetFlag(siNoLogging) ).
- Since:
- 4.0
| CStatus Update | ( | ) |
Commits changes to the current command to the command definition. Subsequent calls to the command need to match the new definition of the command. In other words, this allows you to change the behavior and signature of a command after it is added with Application::AddCommand.
- Tip:
- Alternatively, you could remove the command completely (with Application::RemoveCommand) and redefine it from scratch.
- Warning:
- Extra care must be taken when you update the definition of a command because it might break scripts that are relying on it.
- Note:
- You cannot update the definition of built-in commands.
- Warning:
- Do not call this for custom commands implemented in a self-installed plug-in because your changes will not be persisted the next time your plug-in is loaded. Instead you can adjust the definition code in the
Initcallback and reload the plug-in using the Plugin Manager dialog.
- Since:
- 4.0
The documentation for this class was generated from the following file:
