RegisterCommand (PluginRegistrar)

Description

Registers a regular custom command in Softimage. The command will not register if a name clash occurs with another command.

Note: It is recommended that both the name and the scripting name be identical.

Scripting Syntax

    PluginRegistrar.RegisterCommand( Name, [ScriptName] )

C# Syntax

    PluginItem PluginRegistrar.RegisterCommand( String in_name, String in_ScriptName );

Parameters

Parameter | Type | Description
Name | String | The name of the custom command to register. If the same string is also used as the scripting name (which is recommended) then the name should begin with a letter and contain only letters, numbers and the underscore character. The command name is used to name the command callback functions such as Execute and Init. For example, the Execute callback for a command named "MyCommand" is "MyCommand_Execute". If a command name contains spaces (for example, "My Simple Command"), then you remove the spaces in the callback function names (for example, "MySimpleCommand_Init" and "MySimpleCommand_Execute"). The command name also appears in the Softimage user interface, and is the name of the command in the CommandCollection returned by XSIApplication.Commands. It is also the name you use when you call Menu.AddCommandItem. Command names must be unique. To avoid naming conflicts, we recommend using a prefix based on your company name or the plug-in name (for example, "ACME_TornadoKit_Apply").
ScriptName | String | The Command.ScriptingName of the command. To allow users to easily execute the command in scripts, the first character in the scripting name must be a letter. Subsequent characters can be letters, numbers, or underscore (_) characters.

Return Value

PluginItem

Examples

JScript Example

    /*--------------------------------------------------------------------
       This example shows how to register and implement a custom command
       When not specified, the Name argument is also used as the
       command's scripting name.

       README: Copy and paste the example into the script editor
       and run (F5).

       The command will be listed in the customize toolbar dialog in
       the 'Custom Commands' group.
    --------------------------------------------------------------------*/

    function  XSILoadPlugin( in_reg )
    {
       in_reg.Author = "Softimage Co.";
       in_reg.Name = "PluginRegistrar.RegisterCommand Example";
       in_reg.Major = 1;
       in_reg.Minor = 0;

       // register the ABC command plug-in item
       in_reg.RegisterCommand("ABCCommand", "ABC");
       return true;
    }

    // initialize the ABC command arguments
    function  ABCCommand_Init( in_ctxt )
    {
       var cmd = in_ctxt.Source;
       cmd.Arguments.Add("argument0");

       return true;
    }

    //function handler for the ABC command
    function  ABCCommand_Execute( in_arg )
    {
       Application.LogMessage("ABC command has been executed with argument: " + in_arg);
    }

    //--------------------------------------------------------------------
    // Code to bootstrap example into system
    //--------------------------------------------------------------------
    function ExampleSourceCode()
    {
       return "// XSISDK Doc Example\n" +
           ABCCommand_Init.toString() + "\n" +
           ABCCommand_Execute.toString() + "\n" +
           XSILoadPlugin.toString();
    }

    // if we are running from script editor save code to
    // examples addon folder in the user's directory.
    if (GetUserPref("ScriptingSessionActive"))
    {
       var ex_name  = "ExPluginRegistrarRegisterCommand";
       var ex_subfolder  = "Plugins";
       var ex_folder  = "XSISDKDocExamples";
       var ex_langsuffix = ".js";

       CreateAddonDirectories( InstallationPath(siUserPath), ex_folder );

       var fso = XSIFactory.CreateActiveXObject("Scripting.FileSystemObject");

       var filename = XSIUtils.BuildPath(
           InstallationPath(siUserAddonPath),
           ex_folder,
           "Application",
           ex_subfolder,
           ex_name+ex_langsuffix );

       if (!fso.FileExists(filename))
       {
           var f = fso.CreateTextFile ( filename );
           f.write( ExampleSourceCode() );
           f.close();

           Application.LoadPlugin(filename);
       }
    }

See Also

Plugin.Items | Definition Callbacks for Commands

Autodesk Softimage v7.5