<     > 

What is a Custom Command?

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;
}

Callbacks

Init

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?

• Does the command return a value?

• What arguments does the command take?

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;
}

Execute

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;
}

Autodesk Softimage v7.5     <     >