Scripting: Execute (Command)

Execute (Command)

Description

This callback is fired every time you invoke the command.

Use this callback to implement a command. This is where you process the arguments, peform some actions, and then return the result (if any). In other words, this callback is roughly equivalent to the XSIOnCommand and XSIOnCommandCPP legacy callbacks.

Applies To

Custom Commands

Syntax

public class <command_name>
{
        public bool Execute( Context in_context )
        {
                ...
        }
}

CStatus <command_name>_Execute( CRef& in_context )
{ 
        ... 
}

function <command_name>_Execute( in_arg0, in_arg1, in_arg2, ... )
{ 
        ... 
}

def <command_name>_Execute( in_arg0, in_arg1, in_arg2, ... ):
        ...

Function <command_name>_Execute( in_arg0, in_arg1, in_arg2, ... )
        ...
End Function

sub <command_name>_Execute 
{ 
        my (@in_args) = @; 
}

<command_name> is the name specified in the call to PluginRegistrar.RegisterCommand, with any spaces converted to underscores.

Parameters

Parameter	Language	Type	Description
in_args	Scripting	Depends on the argument	The list of arguments matches the arguments added to the command in the Init callback. The actual type of an argument depends on the argument handler (if any) and the value passed in by the caller.
in_context	C#	Context	Context.Source returns the Command. The command arguments and return value are stored as context attributes.
in_context	C++	CRef&	A reference to the Context object. The command arguments and return value are stored as context attributes.

Context Attributes

C++ and C# custom commands use context attributes to get the command arguments and to return values.

Attribute	Description
Arguments	C# An array of type System.Object. You must cast each element of the array to its proper type before being able to use it. C++ A CValueArray. Each element of this array is a CValue object that stores an argument, which could be a boolean, numeric, or string value, a single Softimage object, or a collection of objects. See Working with Arguments.
ReturnValue	Stores the return value of the command. See Returning Values.
UndoRequired	C++ API only Determines whether or not an undo stack must be maintained. See Undoing and Redoing Custom Commands.
UndoRedoData	C++ API only Stores the current activity in the undo stack, which can later be retrieved in the Undo callback See Undoing and Redoing Custom Commands.

Examples

// JScript code generated by the Command Wizard
function XSILoadPlugin( in_reg )
{
        in_reg.Author = "sblair";
        in_reg.Name = "NewCommand12Plugin";
        in_reg.Email = "";
        in_reg.URL = "";
        in_reg.Major = 1;
        in_reg.Minor = 0;

        in_reg.RegisterCommand("NewCommand12","NewCommand12");
        //RegistrationInsertionPoint - do not remove this line

        return true;
}

function XSIUnloadPlugin( in_reg )
{
        strPluginName = in_reg.Name;
        Application.LogMessage(strPluginName + " has been unloaded.");
        return true;
}

function NewCommand12_Init( ctxt )
{
        var oCmd;
        oCmd = ctxt.Source;
        oCmd.Description = "";
        oCmd.ReturnValue = true;

        var oArgs;
        oArgs = oCmd.Arguments;
        oArgs.AddWithHandler("Arg0","AnimatableParameters");
        oArgs.AddWithHandler("Arg1","Collection");
        oArgs.AddWithHandler("Arg2","SingleObj");
        oArgs.AddWithHandler("Arg3","Frame");
        oArgs.AddWithHandler("Arg4","MarkedParameters");
        oArgs.Add("Arg5",siArgumentInput);
        return true;
}

function NewCommand12_Execute( Arg0,Arg1,Arg2,Arg3,Arg4,Arg5 )
{

        Application.LogMessage("NewCommand12_Execute called");
        
        // 
        // TODO: Put your command implementation here.
        // 
        return true;
}

// C++ code generated by the Command Wizard
#include <xsi_application.h>
#include <xsi_context.h>
#include <xsi_pluginregistrar.h>
#include <xsi_status.h>
#include <xsi_argument.h>
#include <xsi_command.h>
using namespace XSI; 

SICALLBACK XSILoadPlugin( PluginRegistrar& in_reg )
{
        in_reg.PutAuthor(L"sblair");
        in_reg.PutName(L"CmdCppExamplePlugin");
        in_reg.PutEmail(L"");
        in_reg.PutURL(L"");
        in_reg.PutVersion(1,0);
        in_reg.RegisterCommand(L"CmdCppExample",L"CmdCppExample");
        //RegistrationInsertionPoint - do not remove this line

        return CStatus::OK;
}

SICALLBACK XSIUnloadPlugin( const PluginRegistrar& in_reg )
{
        CString strPluginName = in_reg.GetName();
        Application().LogMessage(strPluginName + L" has been unloaded.");
        return CStatus::OK;
}

SICALLBACK CmdCppExample_Init( CRef& in_ctxt )
{
        Context ctxt( in_ctxt );
        Command oCmd;
        oCmd = ctxt.GetSource();
        oCmd.PutDescription(L"");
        oCmd.EnableReturnValue(true);

        ArgumentArray oArgs;
        oArgs = oCmd.GetArguments();
        oArgs.AddWithHandler(L"Arg0",L"AnimatableParameters");
        oArgs.AddWithHandler(L"Arg1",L"Collection");
        oArgs.AddWithHandler(L"Arg2",L"SingleObj");
        oArgs.AddWithHandler(L"Arg3",L"Frame");
        oArgs.AddWithHandler(L"Arg4",L"MarkedParameters");
        oArgs.Add(L"Arg5");
        return CStatus::OK;
}

SICALLBACK CmdCppExample_Execute( CRef& in_ctxt )
{
        Context ctxt( in_ctxt );
        CValueArray args = ctxt.GetAttribute(L"Arguments");
        CValue Arg0 = args[0];
        CValue Arg1 = args[1];
        CValue Arg2 = args[2];
        CValue Arg3 = args[3];
        CValue Arg4 = args[4];
        CValue Arg5 = args[5];

        Application().LogMessage(L"CmdCppExample_Execute called");
        // 
        // TODO: Put your command implementation here.
        // 
        // Return a value by setting this attribute:
        ctxt.PutAttribute( L"ReturnValue", true );

        // Return CStatus::Fail if you want to raise a script error
        return CStatus::OK;
}