CreateParamDef (XSIFactory)

Introduced

4.0

Description

Creates a new custom parameter definition (ParamDef object).

ParamDef objects contain the definition of a parameter from which you can create new parameters on the fly for one or more property sets or operators. For example, you may want to use a double with the same min/max range and use it on multiple property sets or you may simply want a quick way to add parameters to a runtime scripted operator via scripting. You can create New ParamDef objects from the XSIFactory object.

Note: For a simplified version see XSIFactory.CreateParamDef2.

Scripting Syntax

    XSIFactory.CreateParamDef( ScriptName, Type, [Classification], [Capabilities], [Name], [Description], [DefaultValue], [Min], [Max], [SuggestedMin], [SuggestedMax] )

C# Syntax

    ParamDef XSIFactory.CreateParamDef( String in_ScriptName, siVariantType in_Type, siParamClassification in_classification, Int32 in_capabilities, String in_name, String in_description, Object in_default, Object in_Min, Object in_Max, Object in_SuggestedMin, Object in_SuggestedMax );

Parameters

Parameter | Type | Description
ScriptName | String | This argument specifies the ScriptName of a parameter (see Parameter.ScriptName). If the short name or long name arguments are not specified then this name is also used as the short name and description.
Type | siVariantType | Type of the custom parameter. The recommended types are: siString, siBool, siInt4, siUByte, and siDouble. The supported types are: siString, siBool, siDouble, siFloat, siInt4, siInt2, siUInt4, siUInt2, siByte, siUByte (see Parameter.ValueType).
Classification | siParamClassification | Classification of the custom parameter. Default Value: siClassifUnknown
Capabilities | (see Integer) bitfield based on siCapabilities | Capabilities of the custom parameter. If you create a custom operator parameter that is not inspectable, it does not appear in the interface, but is still available from scripting. If the parameter is read-only, it is greyed out in the interface, but is also available from scripting. The siPersistable flag optional and assumed to be enabled for all custom parameters. This establishes the default capability flags for all instances of the parameter, but these flags can be overridden on a per-instance basis via Parameter.Capabilities. Default Value: siPersistable+siAnimatable
Name | String | Short, user-friendly version of the custom parameter's name. This is the parameter name that appears in the Scene Explorer (unless Show Script Names is enabled). If this argument is not specified then the ScriptName argument is visible to users as the parameter's name (see SIObject.Name and Parameter.ScriptName). Default Value: ""
Description | String | Description of the custom parameter. If specified, this is a more descriptive name that appears as the parameter label when the customer property is inspected. For example, the long name of a parameter might be the user-friendly "Use Light Color as Energy" while the name might be the more script-friendly "use_color" (see Parameter.Description). Default Value: ""
DefaultValue | Variant | Default value of the custom parameter. A default value for numerical values (including boolean) is 0; the string default is "" (see Parameter.Default).
Min | Variant | Minimum value of the custom parameter. The types siString and siBool do not require a Min value. For all other numerical types the default is the minimum value possible for the type. For example, all unsigned values have a minimum value of 0 (see Parameter.Min).
Max | Variant | Maximum value of the custom parameter. The types siString and siBool do not require a Max value. For all other numerical types the default is the minimum value possible for the type. For example, the maximum value for siUByte is 255 (see Parameter.Max)
SuggestedMin | Variant | Suggested minimum value of the custom parameter. The types siString and siBool do not require a SuggestedMin value. The default suggested minimum value for numerical values is 0. The suggested minimum should be equal to or larger than the Min. This value is used to configure the range of UI controls (see Parameter.SuggestedMin).
SuggestedMax | Variant | Suggested maximum value of the custom parameter. The types siString and siBool do not require a SuggestedMax value. The default suggested maximum value for numerical values is 100. The suggested maximum should be equal to or smaller than the Max. This value is used to configure the range of UI controls (see Parameter.SuggestedMax).

Return Value

The newly created ParamDef object.

Examples

JScript Example

    /*
       This example illustrates how to add parameters to a custom operator
    */

    var null1 = GetPrim( "null" );

    var sop = XSIFactory.CreateScriptedOp( "MySOP", MySOP_Update.toString(), "JScript" );

    sop.AddOutputPort( null1.posx );

    // String
    var paramdef1 = XSIFactory.CreateParamDef( "text", siString, 0, siAnimatable, "Text", "a text parameter", "the text...");
    var param1 = sop.AddParameter( paramdef1 );

    // Boolean
    var paramdef2 = XSIFactory.CreateParamDef("bool", siBool, 0, siAnimatable, "Boolean", "a boolean parameter", true);
    var param2 = sop.AddParameter( paramdef2 );

    // Integer
    var paramdef3 = XSIFactory.CreateParamDef("int", siInt4, 0, siAnimatable, "Integer", "a integer parameter", -1, -5, 5);
    var param3 = sop.AddParameter( paramdef3 );

    // Double
    var paramdef4 = XSIFactory.CreateParamDef("dbl", siDouble, 0, siAnimatable && siReadOnly, "Double", "a double parameter", 0.69, 0.1, 10.9);
    var param4 = sop.AddParameter( paramdef4 );

    // Connect operator
    sop.Connect();

    // List operator's parameters
    var eParams = new Enumerator( sop.Parameters );
    for ( ; !eParams.atEnd(); eParams.moveNext() )
    {
       var param = eParams.item();

        Application.LogMessage( param.Name + " = " + param.Value );
    }

    function MySOP_Update( ctx, out )
    {
       out.Value = ctx.CurrentFrame;
    }

See Also

XSIFactory.CreateParamDef2 | CustomOperator.AddParameter | Parameter

Autodesk Softimage v7.5