## PPGItem.UIItems

### Introduced

v4.0

### Description

Returns or sets the list of items and values associated with a control as a 1-dimensional Array of Label/Value pairs (Variants). This property is used by controls which display items from a fixed list of choices (for example siControlCombo, siControlCheck, siControlRadio, and siControlIconList). Each label is a string and the value is a variant whose type should match the Parameter.ValueType of the associated parameter.

### C# Syntax

    // get accessor

    Object rtn = PPGItem.UIItems;

    // set accessor

    PPGItem.UIItems = Object;

### Examples

#### JScript Example

    // Example demonstrating how sophisticated UI can

    // be built using the PPGLayout API.

    //

    // It demonstrates how the PPGItem.UIItems

    // property can be used to store a list of objects

    // for a multi-selection ListBox Control.

    //

    // There are two listboxes.  The first shows all the

    // X3DObjects under the Scene Root.  The user

    // can move items from this list into a list of selected

    // objects.  This example could be adapted in various

    // ways, for example it could use the PickObject command.

    Main() ;

    function Main()

    {

    	// Create a simple custom property set

    	var oCustomProperty = ActiveSceneRoot.AddProperty(

    							"CustomProperty",

    							false,

    							"ObjectList" ) ;

    	oCustomProperty.AddParameter( "AllObjects", siString ) ;

    	oCustomProperty.AddParameter( "SelObjects", siString ) ;

    	// Establish the layout

    	// Which will be two list controls with 2 buttons

    	// in between

    	var oLayout = oCustomProperty.PPGLayout

    	oLayout.AddRow() ;

    	  oLayout.AddGroup( "", false, 45) ;

    		AddListBox( oLayout, "AllObjects" ) ;

    	  oLayout.EndGroup() ;

    	  oLayout.AddGroup( "", false, 10) ;

    	    oLayout.Addbutton( "Add", ">>" ) ;

    	    oLayout.Addbutton( "Remove", "<<" ) ;

    	  oLayout.EndGroup() ;

    	  oLayout.AddGroup( "", false, 45) ;

    	AddListBox( oLayout, "SelObjects" ) ;

    	  oLayout.EndGroup() ;

    	oLayout.EndRow() ;

    	oLayout.Language = "JScript" ;

    	oLayout.Logic = Add_OnClicked.toString() +

    			Remove_OnClicked.toString() +

    			MoveSelected.toString() ;

    	// Populate the "AllObjects" list control

    	AddSceneItemsToList( oLayout, "AllObjects" ) ;

    	// Let the user play with the UI

    	if ( !InspectObj( oCustomProperty, null,null ,siModal, false ) )

    	{

    		DoSomethingWithSelectedObjects( oCustomProperty ) ;

    	}

    	// Cleanup

    	DeleteObj( oCustomProperty ) ;

    }

    function AddListBox( in_oLayout, in_Name )

    {

    	// Insert a ListBox into the layout

    	var oItem = in_oLayout.AddItem( in_Name, "", "ListBox" ) ;

    	oItem.SetAttribute( "CY", 100 ) ;

    	oItem.SetAttribute( "NoLabel", true ) ;

    	//Note: Multi-selection list box control only applies to string parameter.

    	oItem.SetAttribute( siUIMultiSelectionListBox, true ) ;

    }

    function AddSceneItemsToList( in_oLayout, in_Name )

    {

    	// Populate the specified list with the

    	// names of objects in the scene

    	var oSceneItems = ActiveSceneRoot.FindChildren() ;

    	var aItems = new Array( oSceneItems.Count * 2 ) ;

    	for ( i = 0 ; i < oSceneItems.Count ; i++ )

    	{

    		// Both label and value will be the same string

    		aItems[i * 2] = oSceneItems.Item(i).Name ;

    		aItems[i * 2 + 1] = oSceneItems.Item(i).Name ;

    	}

    	var oItem = in_oLayout.Item(in_Name);

    	oItem.UIItems = aItems ;

    }

    function DoSomethingWithSelectedObjects( in_oPSet )

    {

    	oPPGItem = in_oPSet.PPGLayout.Item( "SelObjects" ) ;

    	// This is bit of an unusual scenario:

    	// Rather than using the Parameter Value, which is

    	// equal to the last Selected item in the list,

    	// we are interested in the entire list of items in the

    	// layout.  Note: because this data is part of the layout,

    	// not the Parameter, it is not persisted as part of

    	// the scene and is shared by all instances.

    	var vbItems = new VBArray(oPPGItem.UIItems);

    	var aItems = vbItems.toArray();

    	for ( i = 0 ; i < aItems.length ; i+= 2 )

    	{

    		logmessage( "Object " + aItems[i] + " was selected" ) ;

    	}

    }

    //Property Page Event code - this code executes

    //as the script logic of the Property Page.

    function Add_OnClicked()

    {

    	MoveSelected( "AllObjects", "SelObjects" ) ;

    }

    function Remove_OnClicked()

    {

    	MoveSelected( "SelObjects", "AllObjects" ) ;

    }

    function MoveSelected( in_FromList, in_ToList )

    {

    	// Figure out what was selected by the user

    	strSel = PPG.Inspected(0).Parameters(in_FromList).Value ;

    	if ( strSel.length == 0 )

    	{

    		logmessage( "Please select an item" ) ;

    		return ;

    	}

    	var oLayout = PPG.PPGLayout ;

    	var oToList = oLayout.Item( in_ToList ) ;

    	var oFromList = oLayout.Item( in_FromList ) ;

    	var vbItems = new VBArray(oToList.UIItems);

    	var aItems = vbItems.toArray();

    	//The value associated with Multi-selection list box is

    	//a string which is separated with semicolons.

    	var splitSel = strSel.split(";");

    	for( i = 0; i < splitSel.length; ++i)

    	{

    		// Add the string to the "ToList"

    		// Check if the item is already in the list

    		var bIsInTheList = false;

    		for ( j = 0 ; j < aItems.length ; j+=2 )

    		{

    			if ( aItems[j] == splitSel[i] )

    			{

    				logmessage( splitSel[i] + " is already in the list", siWarning ) ;

    				bIsInTheList = true;

    				break;

    			}

    		}

    		if(! bIsInTheList)

    		{

    			// Push the item to end of the list

    			var cntExistingItems = aItems.length

    			aItems[cntExistingItems] = splitSel[i] ; // Label

    			aItems[cntExistingItems+1] = splitSel[i] ; // Value

    			oToList.UIItems = aItems ;

    		}

    	}

    	// Remove the item from the "FromList"

    	vbItems = new VBArray(oFromList.UIItems);

    	var aCurrentItems = vbItems.toArray() ;

    	var aNewItems = new Array() ;

    	// Fill in the new array with everything except

    	// for the selected item

    	for ( i = 0 ; i < aCurrentItems.length; i++ )

    	{

    		var bIsInTheList = false;

    		for( j = 0; j < splitSel.length; j++)

    		{

    			if ( aCurrentItems[i] == splitSel[j] )

    			{

    				bIsInTheList = true;

    				break;

    			}

    		}

    		if(!bIsInTheList)

    		{

    			aNewItems[aNewItems.length] = aCurrentItems[i] ;

    		}

    	}

    	oFromList.UIItems = aNewItems ;

    	// Reset the selection

    	if ( aNewItems.length > 0 )

    	{

    		PPG.Inspected(0).Parameters(in_FromList).Value = aNewItems[0];

    	}

    	else

    	{

    		PPG.Inspected(0).Parameters(in_FromList).Value = "" ;

    	}

    	// A refresh is required to show the change

    	PPG.Refresh() ;

    }

### See Also

PPGLayout.AddEnumControl