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