Registering Commands

C++ Example: Registering a custom command

XSIPLUGINCALLBACK CStatus XSILoadPlugin( PluginRegistrar& in_reg )
{
	in_reg.PutAuthor(L"Command Wizard User");
	in_reg.PutName(L"MyCommands");
	in_reg.PutVersion(1,0);

	// This plug-in contains two custom commands
	in_reg.RegisterCommand(L"MyCommand",L"MyCommand");
	in_reg.RegisterCommand(L"My Other Command",L"MyCommand2");

	return CStatus::OK;
}

JScript Example: Registering a custom command

function XSILoadPlugin( in_reg )
{
	in_reg.Author = "Command Wizard User";
	in_reg.Name = "MyNewCommandPlugin";
	in_reg.Major = 1;
	in_reg.Minor = 0;

	// This plug-in contains two custom commands
	in_reg.RegisterCommand("MyNewCommand","MyNewCommand");

	// Register a second command and set the plug-in categories
	var myPluginItem = in_reg.RegisterCommand(L"My Other Command",L"MyCommand2");
	myPluginItem.Categories = Array( "Example", "Custom" );

	return true;
}

Command Name

The first parameter to RegisterCommand or RegisterCommand is the command name. This is the name that appears in the Softimage user interface, and the name of the command in the commands collection returned by XSIApplication.Commands or Application::GetCommands.

The command name is also used to name the callback functions such as Execute and Init. For example, the Execute callback for a command named "MyCommand" is "MyCommand_Execute".

The first character in a command name should be a letter. Subsequent characters can be letters, numbers, underscore (_) characters, or spaces. 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").

Scripting Name

The second parameter to RegisterCommand or RegisterCommand is the Command.ScriptingName or Command::GetScriptingName, the name used to run the command from scripting or C++ code. The first character should be a letter. Subsequent characters can be letters, numbers, or underscore (_) characters. The scripting name cannot contain spaces.

If you want to be able to run the command from any scripting language, the first character must be a letter (VBScript does not support the underscore as the first character in a name).

The scripting name can include spaces, hyphens, or other characters, but then the command cannot be executed by referring to it by its scripting name. For example, if the scripting name is "My-Command", then the only way to execute the command is through the object model:

// Command.Name = "MyCommand", Command.ScriptingName = "My-Command"
var oCmd = Application.Commands( "MyCommand" );
oCmd.Execute();

Application.ExecuteScriptCommand( "123MyCommand" );