A custom command is a reusable block of scripting or C++ code that performs a specific task. A custom command can be run by other commands and scripts, by menu items, by keyboard shortcuts, and by toolbar buttons.
In a self-installing plug-in, a custom command is implemented by two callbacks: Init and Execute. For custom commands implemented with the C++ API, you can also handle undoing and redoing changes to user data with the Undo, Redo, and TermUndoRedo callbacks.
JScript Example: Skeleton code for a custom command
//------------------------------------------------------------------ // Install callback for the plug-in //------------------------------------------------------------------ function XSILoadPlugin( in_reg ) { in_reg.Author = "Command Wizard User"; in_reg.Name = "MyCommands"; in_reg.Major = 1; in_reg.Minor = 0; // Register a command named "MyCommand" in_reg.RegisterCommand("MyCommand","MyCommand"); return true; } //------------------------------------------------------------------ // Initialize the command named "MyCommand" //------------------------------------------------------------------ function MyCommand_Init( ctxt ) { // Get the Command object from the Context object var oCmd; oCmd = ctxt.Source; // Set some basic command properties oCmd.Description = "A skeleton command"; oCmd.Tooltip = "My command"; // The command returns a value oCmd.ReturnValue = true; // Get the ArgumentCollection var oArgs; oArgs = oCmd.Arguments; // Add an argument oArgs.Add("Arg0",siArgumentInput); return true; } //------------------------------------------------------------------ // Implement the command named "MyCommand" //------------------------------------------------------------------ function MyCommand_Execute( Arg0 ) { // TODO: Put your command implementation here. return true; }
C++ Example: Skeleton code for a C++ custom command
#include <xsi_application.h> #include <xsi_context.h> #include <xsi_pluginregistrar.h> #include <xsi_status.h> #include <xsi_argument.h> #include <xsi_command.h> #include <xsi_menu.h> using namespace XSI; //------------------------------------------------------------------ // Install callback for the plug-in //------------------------------------------------------------------ XSIPLUGINCALLBACK CStatus XSILoadPlugin( PluginRegistrar& in_reg ) { in_reg.PutAuthor(L"Command Wizard User"); in_reg.PutName(L"MyNewCPPCommandPlugin"); in_reg.PutVersion(1,0); // Register a command named "MyCPPCommand" in_reg.RegisterCommand(L"MyCPPCommand",L"MyCPPCommand"); return CStatus::OK; } //------------------------------------------------------------------ // Initialize the command named "MyCommand" //------------------------------------------------------------------ XSIPLUGINCALLBACK CStatus MyCPPCommand_Init( CRef& in_ctxt ) { // Construct a Context from the CRef Context ctxt( in_ctxt ); // Get the Command object from the Context Command oCmd; oCmd = ctxt.GetSource(); // Set some basic command properties oCmd.PutDescription(L"My CPP Command"); oCmd.PutTooltip(L"MyCPPCommand"); // The command returns a value oCmd.EnableReturnValue(true); // Add an argument ArgumentArray oArgs; oArgs = oCmd.GetArguments(); oArgs.Add(L"Arg0"); return CStatus::OK; } //------------------------------------------------------------------ // Implement the command named "MyCPPCommand" //------------------------------------------------------------------ XSIPLUGINCALLBACK CStatus MyCPPCommand_Execute( CRef& in_ctxt ) { // Construct a Context from the CRef Context ctxt( in_ctxt ); // Get the arguments from the Context CValueArray args = ctxt.GetAttribute(L"Arguments"); CValue Arg0 = args[0]; // ... // Put a return value in the Context ctxt.PutAttribute( L"ReturnValue", Arg0 ); return CStatus::OK; }
Softimage calls the Init callback when the plug-in is loaded. The Init callback is where you define the command:
What capabilities does the command support? Can it be assigned a keyboard shortcut? Logged to the command history? Used in batch mode?
function MyNewCommand_Init( ctxt ) { var oCmd; oCmd = ctxt.Source; oCmd.Description = "A simple command"; oCmd.Tooltip = "Do nothing"; // Set the command capabilities oCmd.SetFlag(siSupportsKeyAssignment,false); // true by default oCmd.SetFlag(siCannotBeUsedInBatch,true); // false by default oCmd.SetFlag(siNoLogging,true); // false by default // Allow the command to return values oCmd.ReturnValue = true; // Add a single argument var oArgs; oArgs = oCmd.Arguments; oArgs.Add("Arg0",siArgumentInput); return true; }
The Execute callback implements the command. Softimage calls Execute every time the command is invoked.
If you use a scripting language to implement the command, the Execute callback function has the same arguments and return value as the command:
function MyNewCommand_Execute( Arg0 ) { Application.LogMessage("MyNewCommand_Execute"); // TODO: Implement the command // Return something return Arg0; }
In C++, the command arguments and return value are stored as attributes in the callback context:
XSIPLUGINCALLBACK CStatus MyCPPCommand_Execute( CRef& in_ctxt ) { Context ctxt( in_ctxt ); CValueArray args = ctxt.GetAttribute(L"Arguments"); CValue Arg0 = args[0]; // TODO: Implement the command // Return a value ctxt.PutAttribute( L"ReturnValue", Arg0 ); return CStatus::OK; }