## 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