Class UISelector

In this topic

Package com.ms.ui Previous This
Package Next

Class UISelector

public abstract class UISelector extends UIPanel implements 
            IUISelector, TimerListener
{
  // Constructors
  public UISelector();
  public UISelector(int selMode);

  // Methods
  public synchronized void addActionListener(IUIActionListener l);
  public synchronized void addItemListener(IUIItemListener l);
  public void addSelectedIndex(int index);
  public void addSelectedIndex(int index, boolean notify);
  public void addSelectedIndices(int indices[]);
  public void addSelectedIndices(int indices[], boolean notify);
  public void addSelectedItem(IUIComponent comp);
  public void addSelectedItem(IUIComponent comp, boolean notify);
  public void addSelectedItems(IUIComponent comps[]);
  public void addSelectedItems(IUIComponent comps[],
        boolean notify);
  public IUIComponent find(String prefix);
  public IUIComponent find(String prefix, boolean fromFocus);
  public IUIComponent find(String prefix, IUIComponent compStart);
  public IUIComponent find(String prefix, IUIComponent compStart,
        boolean keyable);
  public IUIComponent getAnchorItem();
  public IUIComponent getExtensionItem();
  public int getRoleCode();
  public int getSelectedIndex();
  public int[] getSelectedIndices();
  public IUIComponent getSelectedItem();
  public IUIComponent[] getSelectedItems();
  public int getSelectionMode();
  public int getStateCode();
  public boolean gotFocus(Event e, Object o);
  public boolean keyDown(Event e, int key);
  public boolean lostFocus(Event e, Object o);
  public boolean mouseDown(Event e, int x, int y);
  public boolean mouseDrag(Event e, int x, int y);
  protected void processActionEvent(UIActionEvent e);
  protected void processEvent(UIEvent e);
  protected void processItemEvent(UIItemEvent e);
  public void remove(int index);
  public void remove(IUIComponent comp);
  public synchronized void removeActionListener(
        IUIActionListener l);
  public synchronized void removeItemListener(IUIItemListener l);
  public void removeSelectedIndex(int index);
  public void removeSelectedIndex(int index, boolean notify);
  public void removeSelectedIndices(int indices[]);
  public void removeSelectedIndices(int indices[], boolean notify);
  public void removeSelectedItem(IUIComponent comp);
  public void removeSelectedItem(IUIComponent comp, boolean notify);
  public void removeSelectedItems(IUIComponent comps[]);
  public void removeSelectedItems(IUIComponent comps[],
        boolean notify);
  public void setAnchorItem(IUIComponent comp);
  public void setExtensionItem(IUIComponent comp);
  public void setSelected(boolean on);
  public void setSelectedIndex(int index);
  public void setSelectedIndex(int index, boolean notify);
  public void setSelectedIndices(int indices[]);
  public void setSelectedIndices(int indices[], boolean notify);
  public void setSelectedItem(IUIComponent comp);
  public void setSelectedItem(IUIComponent comp, boolean notify);
  public void setSelectedItems(IUIComponent comps[]);
  public void setSelectedItems(IUIComponent comps[],
        boolean notify);
  public void setSelectionMode(int selMode);
  public void timeTriggered(TimerEvent te);
}

This class implements an abstract selector control. The following diagram shows the classes that extend UISelector.

UISelector
|
+--UIList
|
+--UITabList
|
+--UITree

By implementing the IUISelector interface, UISelector supports the selection modes in the following table.

SINGLESELECT The user may only select one item at a time.

MULTISELECT The user may select or deselect any item by clicking it.

EXTENDSELECT Behaves like SINGLESELECT, except when either the SHIFT or the CTRL key is down. SHIFT+click extends selection to current position. CTRL+click selects or deselects the currently focused item, without affecting any other selections. CTRL+SHIFT+click is a combination of the two.

NOSELECT Items may only be selected programatically.

The following examples show how to call some of these methods for a UIList control.

// Create two list controls.
UIList fruits = new UIList();  // SINGLESELECT by default.
UIList vegetables = new UIList(UISelector.MULTISELECT);

// Add items to the fruits list.
IUIComponent f1 = fruits.add("apple");
IUIComponent f2 = fruits.add("banana");
IUIComponent f3 = fruits.add("cherry");
add(fruits);  // Add the control to the container.

// Set the selection in the fruits list to the first item,
// at index 0. A list select event will not be generated.
fruits.setSelectedIndex(0);

// Now add items to the vegetables list.
IUIComponent v1 = vegetables.add("carrot");
IUIComponent v2 = vegetables.add("broccoli");
IUIComponent v3 = vegetables.add("zucchini");
add(vegetables);  // Add the control to the container.

// Create an array of components that will set the
// selection to the first and third items in the 
// vegetables list.
UIComponent selComps[] = new UIComponent[2];
selComps[0] = v1;
selComps[1] = v3;

// Set the selection to the components 
// identified by the selComps array. Specify 
// that a list select event will be generated.
vegetables.setSelectedItems(selComps, true);

// Trap the list select event.
public boolean handleEvent(Event e)
{
   // A list select event is always generated
   // when the user selects an item. Calls to 
   // the setSelectedXXX and selectXXX methods 
   // can optionally generate this event.
   if (e.id == Event.LIST_SELECT)
   {
      if (e.target == vegetables)
      {
         // Do something here.
         return true;
      }
      else if (e.target == fruits)
      {
         // Do something here.
         return true;
      }
   }
   return false;
}

The addSelectedIndex and addSelectedItem methods are similar to setSelectedIndex and setSelectedItem, respectively. All four methods enable you to set an item's selected state. To clear a selection call fruits.removeSelectedIndex(i) or fruits.setSelectedIndex(-1). The first call will clear the ith selection. The last call will clear all selections.

The optional boolean argument in these methods is used to specify whether a LIST_SELECT or DESELECT event should be generated. For example, fruits.addSelectedIndex(i, false),will select the item at index i, without affecting anything else and will not generate a LIST_SELECT.

Comments:

Calls to the setSelectedXXX, removeSelectedXXX and addSelectedXXX methods should be made from the outermost level of the selector. For example, suppose you have a tree called food and this tree contains trees called fruit, vegetables, and meat. Suppose that the fruit tree has a banana item. To select the banana item, call food.setSelectedItem(banana) not fruit.setSelectedItem(banana).