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.
PluginItem PluginRegistrar.RegisterCommand( String in_name, String in_ScriptName ); |
oReturn = PluginRegistrar.RegisterCommand( Name, [ScriptName] ); |
| 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. |
/*--------------------------------------------------------------------
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);
}
} |