## PPGLayout.AddButton

### Introduced

v4.0

### Description

Adds a button to a layout. Unlike other controls a button doesn't have to be associated with any particular Parameter on the inspected object. Instead it basically serves the purpose of executing some script code when pressed.
By default, the width of the button is automatically determined based on the text of the Label. However this can be overridden with the siUICX attribute. (See PPGItem.SetAttribute)

### C# Syntax

    PPGItem PPGLayout.AddButton( String in_ScriptName, String in_opt_Label );

### Scripting Syntax

    oReturn = PPGLayout.AddButton( ScriptName, [Label] );

### Return Value

PPGItem

### Parameters

Parameter | Type | Description
--- | --- | ---
ScriptName | String | A unique name for the button, which should not contain any space characters. This name is used to determine the logic subroutine to call when the button is pressed.
Label | String | Label of the button. If not specified then the ScriptName is displayed.

### Examples

#### 1. JScript Example

    /*

    	This example creates a custom property with a single parameter called "Data" and a button.

    	Each time you click the button the value is randomized

    */

    var oPSet = ActiveSceneRoot.AddProperty( "CustomProperty", false, "ButtonExample" ) ;

    oPSet.AddParameter3( "Data", siDouble, 0, 0, 1 ) ;

    var oLayout = oPSet.PPGLayout

    oLayout.AddRow() ;

    oLayout.AddItem( "Data" ) ;

    oLayout.AddButton( "Randomize" ) ;

    oLayout.EndRow() ;

    oLayout.Logic = Randomize_OnClicked.toString() ;

    oLayout.Language = "JScript" ;

    InspectObj( oPSet ) ;

    function Randomize_OnClicked()

    {

    	PPG.Data.Value = Math.random() ;

    }

#### 2. VBScript Example

    '

    ' This example creates a custom property with a single parameter called "Data" and a button.

    ' Each time you click the button the value is randomized

    '

    set oPSet = ActiveSceneRoot.AddProperty( "CustomProperty", false, "ButtonExample" )

    oPSet.AddParameter3 "Data", siDouble, 0, 0, 1

    set oLayout = oPSet.PPGLayout

    oLayout.AddRow

    oLayout.AddItem "Data"

    oLayout.AddButton "Randomize"

    oLayout.EndRow

    'Store a little VBScript code to react to the button press.

    'If this code was more sophisticated we could read it out

    'of a file

    oLayout.Logic = "sub Randomize_OnClicked"   & vbCrlf & "   PPG.Data.Value = Rnd" & vbCrlf & "end sub"

    oLayout.Language = "VBScript" 'Optional because this is the default

    InspectObj oPSet

#### 3. JScript Example

    /*

    	Example showing how to disable a button

    	Often certain buttons should be disabled if they don't apply in the current context.

    	In this case a button is only enabled if there is text entered in a edit box.  The

    	button gets enabled and disabled by the SomeText_OnChanged() callback.  This callback

    	is not called as characters are actually entered in the text box, but as soon as that

    	edit box loses focus (for example if the tab key is pressed )

    */

    var oPSet = ActiveSceneRoot.AddProperty( "CustomProperty", false, "ButtonExample" ) ;

    oPSet.AddParameter3( "SomeText", siString ) ;

    var oLayout = oPSet.PPGLayout

    oLayout.AddRow() ;

    oLayout.AddItem( "SomeText" ) ;

    var oItem = oLayout.AddButton( "ClickMe", "Click Me" ) ;

    // Set a PPGItem attribute to disable the control

    // (because initially there is no text inside SomeText)

    oItem.SetAttribute( "buttondisable", true ) ;

    oLayout.EndRow() ;

    oLayout.Logic = SomeText_OnChanged.toString() + ClickMe_OnClicked.toString() ;

    oLayout.Language = "JScript" ;

    InspectObj( oPSet ) ;

    // PPG Logic that is provided to the PPG

    function SomeText_OnChanged()

    {

    	// Button will be disabled until some text is entered

    	bDisableButton = ( PPG.SomeText.Value.length == 0 ) ;

    	// Get the layout

    	oPPGLayout = PPG.PPGLayout ;

    	// Lookup the PPGItem associated with the button

    	oPPGItem = oPPGLayout.Item( "ClickMe" ) ;

    	bAlreadyDisabled = oPPGItem.GetAttribute( "buttondisable" ) ;

    	if ( bDisableButton != bAlreadyDisabled )

    	{

    		oPPGItem.SetAttribute( "buttondisable", bDisableButton ) ;

    		// We only call refresh if we determine the state has

    		// actually changed

    		PPG.Refresh() ;

    	}

    }

    function ClickMe_OnClicked()

    {

    	// Will never be called if the SomeText is empty

    	XSIUIToolkit.MsgBox( "Value of text is " +  PPG.SomeText.Value ) ;

    }

### See Also

PPGLayout.AddItem PPGItem.Label PPGItem.Name PPG PPGLayout.Logic