Class UIList

public class UIList extends UISelector
{
  // Constructors
  public UIList();
  public UIList(int selMode);
  public UIList(int selMode, int layoutStyle);

  // Methods
  public IUIComponent add(String s);
  public IUIComponent add(String s, int pos);
}

This class implements a list control. A UIList object can have a SINGLESELECT, MULTISELECT, or a EXTENDSELECT selection mode. By default, UIList uses UIVerticalFlowLayout for its layout manager, which provides support for multicolumn list controls. The following example shows several ways to construct a UIList object.

// Construct a single-selection, multicolumn list control.
UIList lst1 = 
   new UIList(UIList.SINGLESELECT, UIVerticalFlowLayout.MULTICOLUMN);

// Construct a list control that allows multiple items
// to be selected by clicking each individual item.
UIList lst2 = new UIList(UIList.MULTISELECT);

// Now add lst1 and lst2 to the container.
add(lst1);
add(lst2);

A UIList object is empty when it is first created. The add method allows extra text items to be inserted into the list control, as shown in the following example.

// Create an array of Strings.
String colors[] = {"Red", "Blue", "Green", "Black"};

// Add each item in the array to lst1.
for (int i=0; i<4; i++)
  lst1.add(colors[i]);

Note When add is called with a String, the list item is automatically hot-tracked. To override this default, call add with a UIText object, as shown in the following example.

UIList lst3 = new UIList();
UIList lst4 = new UIList();

// Add each item in the colors array to lst3,
// using UIText. By default, these items will
// not be hot-tracked.
for (int i=0; i<4; i++)
  lst3.add(new UIText(colors[i]));

// Add each item in the colors array to lst4,
// using UIText. To create hot-tracked items,
// specify the UIStatic.HOTTRACK style. 
for (int i=0; i<4; i++)
  lst4.add(new UIText(colors[i], UIStatic.HOTTRACK));

add(lst3);
add(lst4);

For more information about hot-tracking, see the UIText overview.

Note The hot-track color is the same color as the button text color. As a result, hot-tracking does not appear to be functional.

By default, a list select event is generated when an item in the list control is clicked. (An action event is generated when an item is double-clicked.) The following example shows how to use the handleEvent method to trap this event.

public boolean handleEvent(Event e)
{
   if ((e.id == Event.LIST_SELECT) && (e.target == lst1))
   {
      // Determine whether the first item in lst1 
      // was selected. The getSelectedIndex 
      // is for SINGLESELECT controls. If the 
      // selection mode is MULTISELECT or EXTENDSELECT, 
      // call getSelectedIndices.
      if (lst1.getSelectedIndex() == 0)
         cb.setChecked(true); // cb is a UICheckButton object.
      else
         cb.setChecked(false);

      return true;
   }
   return false;
}

UIList objects alone have no scrolling capabilities. Typically, a UIList control is placed inside a UIScrollViewer.

UIScrollViewer automatically inserts scroll bars when necessary. Also, placing the component inside a fixed size layout manager, such as UIScrollViewer, ensures that the size of the window will also be a fixed size also.

The following example adds a list control to a UIScrollViewer object.

UIList myList = new UIList();
myList.add("first item"); // Add an item to myList.
...  // Continue adding items to myList.

// Now create a UIScrollViewer object to display myList. 
UIScrollViewer sv = new UIScrollViewer(myList);

// Add sv to the container.
add(sv);

UIComponent
  |
  +--UIContainer
    |
    +--UIStateContainer
      |
      +--UIPanel
        |
        +--UISelector
          |
          +--UIList

Constructors

UIList

public UIList();

Creates an empty list control.

Remarks:

Call the add method to add items to the list. By default, the list control is a single-selection, single-column list.

UIList

public UIList(int selMode);

Creates an empty list control with the specified selection mode.

Parameter	Description
selMode	The selection mode of the control. Possible values include SINGLESELECT, MULTISELECT, or EXTENDSELECT.

Remarks:

Call the add method to add items to the list. By default, the list control is a single-column list.

Exceptions:

IllegalArgumentException if an undefined selection mode was specified.

UIList

public UIList(int selMode, int layoutStyle);

Creates an empty list control with the specified selection mode and layout style.

Parameter	Description
selMode	The selection mode of the control. Possible values include SINGLESELECT, MULTISELECT, or EXTENDSELECT.
layoutStyle	The layout style of the control. Possible values include UIVerticalFlowLayout.MULTICOLUMN, UIVerticalFlowLayout.FILL, or a bitwise combination of the two. (FILL extends the width of each list item's selectable area to the width of the item's column. This allows the item to be selected even when the horizontal area outside of its label is clicked.) Specify 0 for a single-column list with no fill.

Remarks:

Call the add method to add items to the list.

Exceptions:

IllegalArgumentException if an undefined selection mode or an undefined layout style was specified.

Methods

add

public IUIComponent add(String s);

Adds the specified text to the end of the list.

Return Value:

Returns the text component that was added, if successful; otherwise, returns null.

Parameter	Description
s	The text to be added.

Remarks:

By default, the text item is hot-tracked. To add an item that is not hot-tracked, pass a UIText object instead of a String. For more information about hot-tracking, see the UIList overview.

To remove an item from the list control, call the remove method (inherited through UISelector).

add

public IUIComponent add(String s, int pos);

Adds the specified text to the list at the specified position.

Return Value:

Returns the text component that was added, if successful; otherwise, returns null.

Parameter	Description
s	The text to be added.
pos	The zero-based index at which to add the text. To add the text at the end of the list, pass -1.

Remarks:

By default, the text item is hot-tracked. To add an item that is not hot-tracked, pass a UIText object instead of a String. For more information about hot-tracking, see the UIList overview.

To remove an item from the list control, call the remove method (inherited through UISelector).

Exceptions:

ArrayIndexOutOfBoundsException if an incorrect position is specified.