PPGItem.UIItems operator

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.

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