Softimage SDK Programmer's Guide > Customizing with the SDK > Custom Commands >

# Returning Values

Custom commands can return values, such as numbers, strings, objects, or collections of objects. To return a value, a command must Command.ReturnValue or Command::EnableReturnValue in the Init callback. The Execute callback then takes care of returning the value.

If the return value is not enabled, Softimage ignores any value returned by the command. If the return value is enabled, but the command does not return a value, Softimage returns an empty Variant.

For scripted commands, the return value is whatever value the Execute callback returns.

JScript Example: Returning a collection of objects from a custom command

    function MyCommand_Init( ctxt )
    {
    	var oCmd;
    	oCmd = ctxt.Source;

    	// This command returns a value
    	oCmd.ReturnValue = true;

    	var oArgs;
    	oArgs = oCmd.Arguments;

    	// By default, this arg will be a collection of all groups
    	oArgs.AddWithHandler("cloObjects","Collection", "#group*" );
    	return true;
    }

    function MyCommand_Execute( cloObjects )
    {
    	// Return all objects in the groups
    	return cloObjects.Expand();
    }

C++ commands put their return values in the ReturnValue attribute of the callback context.

C++ Example: Returning a collection of objects from a custom command

    XSIPLUGINCALLBACK CStatus MyCommand_Execute( CRef& in_ctxt )
    {
    	Context ctxt( in_ctxt );
    	CValueArray args = ctxt.GetAttribute(L"Arguments");

    	// This command uses the Collection argument handler
    	CValueArray collection = args[0];

    	// An array
    	CRefArray objects;

    	for ( long j = 0; j < collection.GetCount(); ++j )
    	{
    		CValue val = collection[j];
    		CRef ref( val );
    		if ( ref.GetClassID() == siX3DObjectID )
    		{
    			objects.Add( ref );
    		}
    	}

    	// Put the CRefArray in a CValue object
    	CValue retval( objects );

    	// Return the X3DObjects
    	ctxt.PutAttribute( L"ReturnValue", retval );

    	// This does the same thing as above:
    //	ctxt.PutAttribute( L"ReturnValue", objects );
    	return CStatus::OK;
    }