Object Model: PPGLayout.AddColor

PPGLayout.AddColor

Introduced

v4.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".

C# Syntax

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

Scripting Syntax

oReturn = PPGLayout.AddColor( RedComponentParamName, [Label], [Alpha] );

Return Value

PPGItem

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

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