Command Class Reference
 
 
 
Command Class Reference

This reference page is linked to from the following overview topics: Custom Command Wizard.


#include <xsi_command.h>


Class 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 Repeat and Undo). 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 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.
Note:
For more information see 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" ) ) ;

                }
Inheritance diagram for Command:
SIObject CBase

List of all members.

Public Member Functions

  Command ()
  ~Command ()
  Command (const CRef &in_ref)
  Command (const Command &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
Command operator= (const Command &in_obj)
Command operator= (const CRef &in_ref)
ArgumentArray  GetArguments ()
CString  GetScriptingName () const
CStatus  PutScriptingName (const CString &in_Str)
CString  GetHandler ()
CStatus  PutHandler (const CString &)
CString  GetLanguage ()
CStatus  PutLanguage (const CString &)
CString  GetFileName ()
CStatus  PutFileName (const CString &)
CString  GetCode ()
CStatus  PutCode (const CString &)
bool  IsReturnValueEnabled ()
CStatus  EnableReturnValue (bool)
CString  GetCategory ()
CString  GetDescription ()
CStatus  PutDescription (const CString &)
CString  GetTooltip ()
CStatus  PutTooltip (const CString &)
CString  GetUID ()
bool  IsEnabled ()
CStatus  PutEnabled (bool)
bool  IsBuiltin ()
CStatus  Execute (CValue &out_return)
bool  GetFlag (LONG in_whichflag)
CStatus  SetFlag (LONG in_whichflag, bool in_newvalue)
bool  SupportsKeyAssignment ()
bool  CannotBeUsedInBatch ()
bool  IsNotLogged ()
CStatus  Update ()

Constructor & Destructor Documentation

Command ( )

Default constructor.

~Command ( )

Default destructor.

Command ( const CRef in_ref )

Constructor.

Parameters:
in_ref constant reference object.
Command ( const Command in_obj )

Copy constructor.

Parameters:
in_obj constant class object.

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]

Returns the type of the API class.

Returns:
The class type.

Reimplemented from SIObject.

Command& operator= ( const Command in_obj )

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.
Command& operator= ( const CRef in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_ref constant class object.
Returns:
The new Command object.

Reimplemented from SIObject.

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
CStatus PutScriptingName ( const CString in_Str )

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.
See also:
PluginRegistrar::RegisterCommand, SIObject::GetName, Application::CreateCommand
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
CStatus PutHandler ( const CString )

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
CStatus PutLanguage ( const CString )

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
CStatus PutFileName ( const CString )

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
CStatus PutCode ( const CString )

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
CStatus PutDescription ( const CString )

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
CStatus PutTooltip ( const CString )

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
CStatus Execute ( CValue out_return )

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
See also:
Command::CannotBeUsedInBatch, Command::IsNotLogged, Command::SupportsKeyAssignment
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 Init callback and reload the plug-in using the Plugin Manager dialog.
Since:
4.0

The documentation for this class was generated from the following file: