ArgumentHandler

Object Hierarchy | Related C++ Class: ArgumentHandler

Inheritance

SIObject

ArgumentHandler

Introduced

v4.0

Description

An argument handler is an object that helps determine the value that is passed to a command. Argument handlers come into play when a command is invoked without providing a explicit value for an argument, or when the argument that was provided requires some processing before it can be sent to the command. For example the "Collection" argument handler can turn a string-based list of objects into a XSICollection representing those objects.

Argument handlers are widely used on built-in commands, and can be specified for custom commands (see ArgumentCollection.AddWithHandler). They make it easier to implement flexible custom commands, and reduce the amount of error handling necessary inside the command implementation.

Once specified as part of the command definition they act behind the scenes during the process of the command invocation. Neither the caller nor the implementation need to explicitly manipulate ArgumentHandler objects.

Note: Internally the state of an argument handler is stored in the value of the argument. For this reason a call to Argument.Handler clears any existing Argument.Value.

Methods

IsClassOf operator IsEqualTo operator    
       

Properties

Application Categories FullName operator Help
Name operator NestedObjects Origin OriginPath
Parent Type operator    
       

Examples

JScript Example

//Jscript example demonstrating how to use the Argument Handlers.
//It also shows how the implementation of Custom Command can
//be embedded directly inside the definition.
RemoveCommands() ;
InstallCommands() ;     
DemoCommands() ;
function DemoCommands()
{
        // First set up a little scenario to
        // show how the arg handlers will react
        newscene(null,false) ;
        var oGrid1 = ActiveSceneRoot.AddGeometry( "Grid","MeshSurface","G1" ) ;
        var oGrid2 = ActiveSceneRoot.AddGeometry( "Grid","MeshSurface","G2" ) ;
        var oGrid3 = ActiveSceneRoot.AddGeometry( "Grid","MeshSurface","G3" ) ;
        SelectObj( oGrid1 ) ;
        /////////////////////////////////////////////////////////////
        // Collection Arg Handler
        /////////////////////////////////////////////////////////////
        //If we provide no argument then the current selection
        //is passed as the argument:
        DemoCollectionArgHandler() ;
        //Result:
        //INFO : "DemoCollectionArgHandler called with 1 items"
        //INFO : "              Item 0 : G1"
        // Also very useful for turning string names of objects into
        // an XSICollection
        DemoCollectionArgHandler( "G1,G2" );
        //Result:
        // "DemoCollectionArgHandler called with 2 items"
        // "            Item 0 : G1"
        // "            Item 1 : G2"
        /////////////////////////////////////////////////////////////
        // SingleObj Arg Handler
        /////////////////////////////////////////////////////////////
        // The SingleObj arg handler is very
        // useful for converting from
        // a string to a object.  This is widely
        // used in Softimage internal commands
        DemoSingleObjArgHandler( "G1" ) ;
        //Result: "DemoSingleObjArgHandler called with G1(Type: polymsh)"
        // Of course if you already have the object pointer it
        // is identical to the above call, but even faster to do this:
        // In this case the arg handler has nothing to do:
        DemoSingleObjArgHandler( oGrid1 ) ;
        //Result: "DemoSingleObjArgHandler called with G1(Type: polymsh)"
        /////////////////////////////////////////////////////////////
        // FrameRate Arg Handler
        /////////////////////////////////////////////////////////////
        // Change the current framerate to film (24fps)
        SetValue("PlayControl.Format", 7, null);
        DemoFrameRateArgHandler() ;
        //Result : "DemoFrameRateArgHandler called with 24"
        // If you call with an specific value then
        // the ArgHandler does nothing
        DemoFrameRateArgHandler( 12.5 ) ;
        //Result : "DemoFrameRateArgHandler called with 12.5"
        /////////////////////////////////////////////////////////////
        // Frame Arg Handler
        /////////////////////////////////////////////////////////////
        SetValue("PlayControl.Current", 33, null);
        // This arghandler is very useful for commands
        // that normally operate on the current frame
        // but which could also be used to process a different
        // frame.
        //
        // By default the current frame is passed as the argument
        DemoFrameArgHandler() ;
        //Result : "DemoFrameArgHandler called with 33"
        // but the user can override
        DemoFrameArgHandler( 99 ) ;
        /////////////////////////////////////////////////////////////
        // MarkedParameters ArgHandler
        /////////////////////////////////////////////////////////////
        // This handler is very useful for collecting information
        // about which parameters have been marked on the currently
        // Selected objects
        //
        // Select the name and subdivu parameters on all three grids
        SelectObj( oGrid1 ) ;
        AddToSelection( oGrid2 ) ;
        AddToSelection( oGrid3 ) ;
        SetMarking( "Name" ) ;
        AddToMarking( "polymsh.geom.subdivu" ) ;
        // Remove G2 from the list, to demonstrate that even though
        // it also has marked parameters these are not passed in
        RemoveFromSelection( oGrid2 ) ;
        DemoMarkedParametersArgHandler() ;
        //Results:
        // "            Item 0 : G1.Name"
        // "            Item 1 : G1.polymsh.geom.subdivu"
        // "            Item 2 : G3.Name"
        // "            Item 3 : G3.polymsh.geom.subdivu"
        //and the command is logged in the history like this:
        //DemoMarkedParametersArgHandler("G1.Name,G1.polymsh.geom.subdivu,G3.Name,G3.polymsh.geom.subdivu");
        // You can also pass the marked parameters as a string.
        var bigMarkingString = "G1.Name," +
                                                  "G1.polymsh.geom.subdivu," +
                                                  "G2.Name," +
                                                  "G2.polymsh.geom.subdivu," +
                                                  "G3.Name," +
                                                  "G3.polymsh.geom.subdivu"             
        DemoMarkedParametersArgHandler(bigMarkingString);       
        // There is a short form using the "/" character
        // which is equivalent to the previous call:
        DemoMarkedParametersArgHandler("G1,G2,G3/name,polymsh.geom.subdivu");
        //Results:      
        // "DemoMarkedParametersArgHandler called with 6 items"
        // "            Item 0 : G1.Name"
        // "            Item 1 : G1.polymsh.geom.subdivu"
        // "            Item 2 : G2.Name"
        // "            Item 3 : G2.polymsh.geom.subdivu"
        // "            Item 4 : G3.Name"
        // "            Item 5 : G3.polymsh.geom.subdivu"
        /////////////////////////////////////////////////////////////
        // MarkedParameters ArgHandler
        /////////////////////////////////////////////////////////////
        // This handler is almost exactly the same as the 
        // MarkedParameter arg handler, except that it
        // will strip out the non-animatable parameters
        // that have been marked.  In this case it doesn't
        // pass the "G1.Name" and "G3.Name" parameters that have been
        // marked
        DemoAnimatableParametersArgHandler() ;  
        //Results:      
        // "DemoMarkedParametersArgHandler called with 2 items"
        // "            Item 0 : G1.polymsh.geom.subdivu"
        // "            Item 1 : G3.polymsh.geom.subdivu"
        //You can also pass a string and the same sort of 
        //shortcut works:
        DemoAnimatableParametersArgHandler("G1.polymsh.geom/subdivu,subdivv") ; 
        //Results:      
        // "DemoMarkedParametersArgHandler called with 2 items"
        // "            Item 0 : G1.polymsh.geom.subdivu"
        // "            Item 1 : G1.polymsh.geom.subdivv"
}
function RemoveCommands()
{
        Application.RemoveCommand( "DemoCollectionArgHandler" ) ;
        Application.RemoveCommand( "DemoSingleObjArgHandler" ) ;
        Application.RemoveCommand( "DemoFrameRateArgHandler" ) ;
        Application.RemoveCommand( "DemoFrameArgHandler" ) ;
        Application.RemoveCommand( "DemoMarkedParametersArgHandler" ) ;
        Application.RemoveCommand( "DemoAnimatableParametersArgHandler" ) ;
}
function InstallCommands()
{
        InstallArgDemoCommand( 
                "DemoCollectionArgHandler", 
                "Collection",
                OnDemoCollectionArgHandler.toString() ) ;
        InstallArgDemoCommand( 
                "DemoSingleObjArgHandler", 
                "SingleObj",
                OnDemoSingleObjArgHandler.toString() ) ;
        InstallArgDemoCommand( 
                "DemoFrameRateArgHandler", 
                "FrameRate",
                OnDemoFrameRateArgHandler.toString() ) ;
        InstallArgDemoCommand( 
                "DemoFrameArgHandler", 
                "Frame",
                OnDemoFrameArgHandler.toString() ) ;
        InstallArgDemoCommand( 
                "DemoMarkedParametersArgHandler", 
                "MarkedParameters",
                OnDemoMarkedParametersArgHandler.toString() ) ;
        InstallArgDemoCommand( 
                "DemoAnimatableParametersArgHandler", 
                "AnimatableParameters",
                OnDemoAnimatableParametersArgHandler.toString() ) ;
}
function InstallArgDemoCommand( in_Name, in_ArgHandlerName, in_Code )
{
        var oCmd = Application.CreateCommand( in_Name ) ;
        // Same as ScriptName
        oCmd.ScriptingName = in_Name ;  
        // Same of the routine to call inside the "in_Code" argument
        // We use a naming scheme based on command name
        oCmd.Handler = "On" + in_Name ; 
        // Embed the code rather than referring to file
        oCmd.Code = in_Code ;           
        oCmd.Language = "JScript" ;
        oCmd.ReturnValue = true ;
        oCmd.Arguments.AddWithHandler( "Arg", in_ArgHandlerName ) ;
        Application.AddCommand( oCmd ) ;
}
//
// Command implementations
//
function OnDemoCollectionArgHandler( in_arg )
{
        // We recieve a Selection object or an
        // XSICollection.  In either case we use the Count and Item
        // properties to access the items.
        Logmessage( "DemoCollectionArgHandler called with " + in_arg.Count + " items" ) ;
        for ( i = 0 ; i < in_arg.Count ; i++ )
        {
                Logmessage( "\t\tItem " + i + " : " + in_arg.Item(i).FullName ) ;
        }
        return in_arg ;
}
function OnDemoSingleObjArgHandler( in_arg )
{
        Logmessage( "DemoSingleObjArgHandler called with " + in_arg.Name + 
                                "(Type: " + in_arg.Type + ")" ) ;
        return in_arg ;
}
function OnDemoFrameRateArgHandler( in_arg )
{
        // Unless the user calls with a specific value for the argument
        // we get the current frame rate
        Logmessage( "DemoFrameRateArgHandler called with " + in_arg ) ;
        return in_arg ;
}
function OnDemoFrameArgHandler( in_arg )
{
        // Unless the user calls with a specific value for the argument
        // we get the current frame rate
        Logmessage( "DemoFrameArgHandler called with " + in_arg ) ;
        return in_arg ;
}
function OnDemoMarkedParametersArgHandler( in_arg )
{
        // We recieve a XSICollection with the Marked parameters 
        // on the selected objects
        Logmessage( "DemoMarkedParametersArgHandler called with " + in_arg.Count + " items" ) ;
        for ( i = 0 ; i < in_arg.Count ; i++ )
        {
                Logmessage( "\t\tItem " + i + " : " + in_arg.Item(i).FullName ) ;
        }
        return in_arg ;
}
function OnDemoAnimatableParametersArgHandler( in_arg )
{
        // We recieve a XSICollection with the Animatable Marked parameters 
        // on the selected objects
        Logmessage( "DemoMarkedParametersArgHandler called with " + in_arg.Count + " items" ) ;
        for ( i = 0 ; i < in_arg.Count ; i++ )
        {
                Logmessage( "\t\tItem " + i + " : " + in_arg.Item(i).FullName ) ;
        }
        return in_arg ;
}

See Also

Command Argument ArgumentCollection