カスタムコマンドとは

カスタムコマンドとは、特定のタスクを実行するスクリプトコードまたは C++ コードの再利用可能なブロックです。カスタムコマンドは、他のコマンドやスクリプト、メニュー項目、キーボードショートカット、およびツールバーボタンによって実行できます。

自己インストールプラグインでは、カスタムコマンドは Init および Execute の 2 つのコールバックで実装されます。また、C++ API で実装したカスタムコマンドに対しては、Undo、Redo および TermUndoRedo コールバックを使用して、ユーザデータに対する変更を元に戻したり、やり直したりすることもできます。

JScript の例: カスタムコマンドのスケルトンコード

//------------------------------------------------------------------
// 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++ の例: C++ カスタムコマンドのスケルトンコード

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

コールバック

Init(初期)

Softimage は、Init コールバックを、プラグインがロードされるときに呼び出します。Init コールバックでは、次の点についてコマンドを定義します。

コマンドが対応する機能コマンドにキーボードショートカットを割り当てることができるかコマンドがコマンドヒストリに記録できるかバッチモードで使用できるかどうか
コマンドが値を戻すかどうか
コマンドが取得する引数

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

Execute コールバックはコマンドを実装します。Softimage では、コマンドが呼び出されるたびに Execute を呼び出します。

コマンドの実装にスクリプト言語を使用する場合、Execute コールバック関数はコマンドと同じ引数を受け取り、値を戻します。

function MyNewCommand_Execute( Arg0 )
{
	Application.LogMessage("MyNewCommand_Execute");

	// TODO: Implement the command

	// Return something
	return Arg0;
}

C++ では、コマンド引数と戻り値が属性としてコールバックコンテキストに格納されます。

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

自己インストールカスタムコマンドを実装する方法を示したカスタムコマンドのサンプルを参照してください。このサンプルは、Softimage SDK のインストールフォルダにある examples フォルダにあります。

カスタム コマンドとは