Custom Commands (XSISDK)


Table of contents

Documentation

Be sure to read: Custom Commands (http://softimage.wiki.avid.com/sdkdocs/cus_cmds.htm)

Self-Installed Custom Commands

The recommended way to introduce your own command in the system is via a Self-Installed custom command. In the past many commands were created by dragging a script file onto a toolbar - however the resulting custom command is harder to maintain than a self-installed custom command.

XSI include a wizard to make it easy to create a command. Note: Even though the wizard does not support it, you can put multiple commands into a single script file. It is easy to merge multiple files generated by the wizard into a single file, just copy all the contents together and make sure there is only a single implementation of XSILoadPlugin that mentions all the code.

Returning a value - C++ API

The _Execute() method returns a CStatus, but this is only used to determine whether a Script Error should be issued. To actually return meaningful data, the returned CStatus object should be set to "OK", and the actual return data stored in the "ReturnValue" attribute of the context object.

For example this code snippet shows how to return a variable returnObj, which resumably contains some XSI object.

XSIPLUGINCALLBACK CStatus FooCommand_Execute( CRef& in_context )
{
    Context ctxt(in_context);

...Guts of the command removed...

    ctxt.PutAttribute( L"ReturnValue", returnObj.GetRef() );
    return CStatus::OK ;
}

Uniqueness of Name

Only a single command by a particular name can exist in the system. So it is strongly recommended than any custom command be carefully named so that it is unlikely that it would conflict with any other plug-in. A good way to do this is to use a prefix that is based on your name, your project or your company. For example "coolfxHelp" is a better command name than "Help".

Name versus Scripting Name

XSI supports providing a Command name that is different than the scripting name. Most XSI commands use this approach. However to avoid conflicts and for simplicity it is often better to use the same string for both. Both toolbars and custom menus let you specify a different label than the actual command name, and setting the label is better than naming a command just so that it looks good on a button or menu.

This page was last modified 04:55, 2 Oct 2010.
This page has been accessed 8175 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy