AddColor (PPGLayout) *

Introduced

4.0

Description

This method is similar to PPGLayout.AddItem but it helps add a color widget to a layout. There are two variations of the Color widget, siControlRGBA and siControlRGB. Rather than a single parameter, this control reads and writes a separate parameter for each "channel" of the color.

To successfully create an RGBA color control on a CustomProperty, first add four siDouble or siFloat parameters to the control, for example "MyR", "MyG", "MyB", and "MyA". The naming scheme is not important but the parameters must be consecutive. This parameters should have a UI Range of 0 to 1 because the values are stored in normalized format. However you can have a larger actual Range if you want to support colors outside the normal color space. (See Parameter.SuggestedMax and Parameter.Max).

The default control for a siDouble parameter is siControlNumber, but the color widget can be displayed instead by calling this method and specifying the name of the first parameter, for example "MyR". To read the color value through the object model, just refer to the values of the four parameters, for example "MyG" will contain the normalized green component of the color.

Note: Shaders support colors directly as a native "strong" type. So rather than having multiple parameters of type siDouble or siFloat, they use a single parameter of type "Color".

Scripting Syntax

    PPGLayout.AddColor( RedComponentParamName, [Label], [Alpha] )

C# Syntax

    PPGItem PPGLayout.AddColor( String in_RedComponentParamName, String in_opt_Label, Boolean in_opt_Alpha );

Parameters

Parameter | Type | Description
RedComponentParamName | String | Script Name of the Parameter that represents the Red component of the color. The names of the Green, Blue and optional Alpha parameters do not need to be specified because Softimage uses the parameters that are consecutive after the Red component.
Label | String | Specify the text which appears to the left of the Color Widget. If not specified here, the name of the parameter (see SIObject.Name) or Parameter.ScriptName of the red component parameter appears instead.
Alpha | Boolean | Specifies whether the color should include an Alpha channel. This argument decides whether a siControlRGBA or siControlRBG is created. Default Value: false

Return Value

PPGItem

Examples

JScript Example

    /*
       Proxy Parameters are an useful way to centralize parameters from
       different objects on the same property, or even to build a simplified
       version of a property page.

       This example demonstrates creation of a custom property set
       that only shows a few items of the Shader that it controls,
       but maintains a pleasing layout.
    */

    NewScene( null, false ) ;
    var oSphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface" ) ;
    oSphere.AddMaterial( "Phong"  );

    var oPhongShader = oSphere.Material.Shaders(0) ;

    // This is a Boolean for enabling diffuse
    var oDiffuseEnable = oPhongShader.Parameters( "diffuse_inuse" ) ;

    // These are CompoundParameters, each with R,G,B sub-parameters
    var oAmbientParam = oPhongShader.Parameters( "ambient" ) ;
    var oDiffuseParam = oPhongShader.Parameters( "diffuse" ) ;

    var oCustomProperty = oSphere.AddProperty("CustomProperty",false,"Proxies");

    // We specify a name to avoid having a long one like "sphere_Material_Phong_diffuse_inuse"
    oCustomProperty.AddProxyParameter( oDiffuseEnable, "Enable", "Enable" );

    oCustomProperty.AddProxyParameter( oDiffuseParam.Parameters("red"), "Diffuse", "Diffuse" );
    oCustomProperty.AddProxyParameter( oDiffuseParam.Parameters("green"));
    oCustomProperty.AddProxyParameter( oDiffuseParam.Parameters("blue"));

    oCustomProperty.AddProxyParameter( oAmbientParam.Parameters("red"), "Ambient", "Ambient" );
    oCustomProperty.AddProxyParameter( oAmbientParam.Parameters("green"));
    oCustomProperty.AddProxyParameter( oAmbientParam.Parameters("blue"));

    // If we inspect the object now we would see 6 separate sliders,
    // each controlling a different component of the colors
    // We can create a custom layout to clean up the display

    var oLayout = oCustomProperty.PPGLayout

    oLayout.AddGroup( "Phong Diffuse" )

       oLayout.AddItem( "Enable" ) ;

       // Just for fun, show the ambient before the diffuse, which
       // is the opposite of the normal Phong Property Page
       oLayout.AddColor( "Ambient", "Ambient", false ) ;
       oLayout.AddColor( "Diffuse", "Diffuse", false ) ;

    oLayout.EndGroup() ;

    oLayout.Logic = Enable_OnChanged.toString() ;
    oLayout.Language = "JScript" ;

    // Show both dialogs.  You will see that both items
    // are identical.
    InspectObj ( oCustomProperty, null, null, siLock ) ;
    InspectObj ( oPhongShader, null, null, siLock ) ;

    function Enable_OnChanged()
    {
       // A little Property Page event code to properly
       // grey out the color controls if the Disable checkbox is
       // clicked

       bEnable = PPG.Enable.Value ;

       // To disable the color control we just disable the proxy
       // parameter representing the "red" component
       PPG.Ambient.Enable( bEnable ) ;
       PPG.Diffuse.Enable( bEnable ) ;
           }

See Also

PPGLayout.AddItem | PPGItem.Label | Parameter.ScriptName | siPPGControlType

Autodesk Softimage v7.5