Class AwtUIList

public class AwtUIList extends AwtUIControl implements 
            IAwtUIItemSelectable
{
  // Constructors
  public AwtUIList();
  public AwtUIList(int selMode);
  public AwtUIList(int selMode, int layoutStyle);

  // Methods
  public IUIComponent add(String s);
  public IUIComponent add(String s, int pos);
  public void addActionListener(ActionListener l);
  public void addItem(String item);
  public void addItem(String item, int pos);
  public void addItemListener(ItemListener 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, boolean fromFocus);
  public IUIComponent find(String prefix, IUIComponent compStart);
  public IUIComponent find(String prefix);
  public IUIComponent getBase();
  public String getItem(int posn);
  public int getSelectedIndex();
  public int[] getSelectedIndices();
  public IUIComponent getSelectedItem();
  public IUIComponent[] getSelectedItems();
  public int getSelectionMode();
  protected void processActionEvent(ActionEvent e);
  protected void processHostEvent(AWTEvent e);
  protected void processItemEvent(ItemEvent e);
  public void remove(int index);
  public void remove(IUIComponent comp);
  public synchronized void removeActionListener(ActionListener l);
  public synchronized void removeItemListener(ItemListener 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 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);
}

This class implements the functionality of a UIList object in an AWT-based control. An AwtUIList control is an AwtUIHost component whose associated root container holds a UIList object. By hosting this object, an AwtUIList control integrates AFC with AWT. Although an AwtUIList control is fully compatible with AWT, a UIList control is optimized for performance and size.

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

Panel
  |
  +--AwtUIHost
    |
    +--AwtUIControl
      |
      +--AwtUIList

Constructors

AwtUIList

public AwtUIList();

Creates an empty AWT-based list control.

Remarks:

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

AwtUIList

public AwtUIList(int selMode);

Creates an empty AWT-based list control with the specified selection mode.

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

Remarks:

Call add or addItem 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.

AwtUIList

public AwtUIList(int selMode, int layoutStyle);

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

Parameter	Description
selMode	The selection mode of the control. Possible values include IUISelector.SINGLESELECT, IUISelector.MULTISELECT, or IUISelector.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.) Pass 0 for a single-column list with no fill.

Remarks:

Call add or addItem 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 a 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, call the inherited add method that takes an IUIComponent parameter and pass a UIText object. For more information about hot-tracking, see the UIList overview.

See Also: addItem, remove

add

public IUIComponent add(String s, int pos);

Adds the specified text to a 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, call the inherited add method that takes an IUIComponent parameter and pass a UIText object. For more information about hot-tracking, see the UIList overview.

See Also: addItem, remove

addActionListener

public void addActionListener(ActionListener l);

Adds the specified action listener. The listener receives all action events generated for the control.

Return Value:

No return value.

Parameter	Description
l	The action listener to be added.

See Also: removeActionListener

addItem

public void addItem(String item);

Adds the specified text to the end of the list.

Return Value:

No return value.

Parameter	Description
item	The text to be added.

Remarks:

By default, the text item is hot-tracked. To add an item that is not hot-tracked, call the inherited add method that takes an IUIComponent parameter and pass a UIText object. For more information about hot-tracking, see the UIList overview.

See Also: add, remove

addItem

public void addItem(String item, int pos);

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

Return Value:

No return value.

Parameter	Description
item	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, call the inherited add method that takes an IUIComponent and pass a UIText object. For more information about hot-tracking, see the UIList overview.

See Also: add, remove

addItemListener

public void addItemListener(ItemListener l);

Adds the specified item listener. The listener receives all item events generated for the control. (Item events are generated when the state of an item changes.)

Return Value:

No return value.

Parameter	Description
l	The item listener to be added.

See Also: removeItemListener

addSelectedIndex

public void addSelectedIndex(int index);

Selects the component at the specified index, without affecting other selections. By default, list select events are not generated.

Return Value:

No return value.

Parameter	Description
index	The zero-based index of the item to be selected.

addSelectedIndex

public void addSelectedIndex(int index, boolean notify);

Selects the component at the specified index, without affecting other selections. Optionally generates list select events.

Return Value:

No return value.

Parameter	Description
index	The zero-based index of the item to be selected.
notify	If true, list select events will be generated; otherwise, list select events will not be generated.

addSelectedIndices

public void addSelectedIndices(int indices[]);

Selects the components at the specified indices, without affecting other selections. By default, list select events are not generated.

Return Value:

No return value.

Parameter	Description
indices	An array containing the indices of the items to be selected.

addSelectedIndices

public void addSelectedIndices(int indices[], boolean notify);

Selects the components at the specified indices, without affecting other selections. Optionally generates list select events.

Return Value:

No return value.

Parameter	Description
indices	An array containing the indices of the items to be selected.
notify	If true, list select events will be generated; otherwise, list select events will not be generated.

addSelectedItem

public void addSelectedItem(IUIComponent comp);

Selects the specified component, without affecting other selections. By default, list select events are not generated.

Return Value:

No return value.

Parameter	Description
comp	The component to be selected.

addSelectedItem

public void addSelectedItem(IUIComponent comp, boolean notify);

Selects the specified component, without affecting other selections. Optionally generates list select events.

Return Value:

No return value.

Parameter	Description
comp	The component to be selected.
notify	If true, list select events will be generated; otherwise, list select events will not be generated.

addSelectedItems

public void addSelectedItems(IUIComponent comps[]);

Selects the specified components, without affecting other selections. By default, list select events are not generated.

Return Value:

No return value.

Parameter	Description
comps	An array containing the components to be selected.

addSelectedItems

public void addSelectedItems(IUIComponent comps[], boolean notify);

Selects the specified components, without affecting other selections. Optionally generates list select events.

Return Value:

No return value.

Parameter	Description
comps	An array containing the component to be selected.
notify	If true, list select events will be generated; otherwise, list select events will not be generated. Currently not used.

find

public IUIComponent find(String prefix, boolean fromFocus);

Searches the control for an item whose name begins with the specified prefix. The search begins from either the current focus, or the first item in the selector.

Return Value:

Returns the first matching component, if a match is found; Otherwise, returns null.

Parameter	Description
prefix	The prefix string to search for.
fromFocus	If true, the search begins from the current focus. Otherwise, the search begins with the first item in the selector.

find

public IUIComponent find(String prefix, IUIComponent compStart);

Searches the selector control for an item whose name begins with the specified prefix. The search begins at compStart.

Return Value:

Returns The first matching component, if a match is found; otherwise, returns null.

Parameter	Description
prefix	The prefix string to search for.
compStart	The component at which the search begins. If it is null, the search will begin at the 1st item (according to navigate).

find

public IUIComponent find(String prefix);

Searches the control for an item whose name begins with the specified prefix. The search starts at the first item in the control.

Return Value:

Returns the first matching component; otherwise, returns null if a matching component is not found.

Parameter	Description
prefix	The prefix string to search for.

getBase

public IUIComponent getBase();

Retrieves the UI component that the control is based on.

Return Value:

Returns the UIList object associated with the control.

Remarks:

When the AWT-based control is first created, it is associated with a UIList object.

getItem

public String getItem(int posn);

Retrieves the string at the specified index.

Return Value:

Returns a string identifying the item at the specified index if the item is a UIText item, otherwise, returns null.

Parameter	Description
posn	The zero-based index of the string.

getSelectedIndex

public int getSelectedIndex();

Retrieves the zero-based index of the currently selected item.

Return Value:

Returns the index of the selected item or -1 if an item is not selected.

Remarks:

If the control's selection mode is MULTISELECT or EXTENDSELECT, you can also call getSelectedIndices.

For related code examples, see the UISelector overview.

See Also: getSelectedItem, setSelectedIndex

getSelectedIndices

public int[] getSelectedIndices();

Retrieves the zero-based indices of all currently selected items.

Return Value:

Returns an array of the indices of the selected items, or null if no item is selected.

See Also: getSelectedIndex, getSelectedItems, setSelectedIndices

getSelectedItem

public IUIComponent getSelectedItem();

Retrieves the currently selected item.

Return Value:

Returns the selected component; otherwise, returns null if no component is selected.

Remarks:

If the control's selection mode is MULTISELECT or EXTENDSELECT, you can also call getSelectedItems.

For related code examples, see the UISelector overview.

See Also: getSelectedIndex, setSelectedItem

getSelectedItems

public IUIComponent[] getSelectedItems();

Retrieves all currently selected items.

Return Value:

Returns an array of the selected components or returns null if a component is not selected.

See Also: getSelectedItem, getSelectedIndices, setSelectedItems

getSelectionMode

public int getSelectionMode();

Retrieves the selection mode of the control.

Return Value:

Returns one of the following three selection modes: IUISelector.SINGLESELECT, IUISelector.MULTISELECT, or IUISelector.EXTENDSELECT.

See Also: setSelectionMode

processActionEvent

protected void processActionEvent(ActionEvent e);

Processes action events.

Return Value:

No return value.

Parameter	Description
e	The action event.

Remarks:

This method is called by processHostEvent and dispatches the event to a registered action listener. When overriding this method, call the super method processActionEvent to ensure the default event processing continues normally.

See Also: addActionListener

processHostEvent

protected void processHostEvent(AWTEvent e);

Processes the specified event.

Return Value:

No return value.

Parameter	Description
e	The event.

Remarks:

This method is automatically invoked if a listener has has been registered through a call to addXXXListener. Depending on the type of event, processHostEvent calls one of the following methods.

Event type	Method called
action event	processActionEvent
item event	processItemEvent
component event	processComponentEvent (inherited through AwtUIHost)
container event	processContainerEvent (inherited through AwtUIHost)
focus event	processFocusEvent (inherited through AwtUIHost)
key event	processKeyEvent (inherited through AwtUIHost)
mouse event	processMouseEvent (inherited through AwtUIHost)
mouse motion event	processMouseMotionEvent (inherited through AwtUIHost)

When overriding processHostEvent, call the super method processHostEvent to ensure the default event processing continues normally.

processItemEvent

protected void processItemEvent(ItemEvent e);

Processes item events.

Return Value:

No return value.

Parameter	Description
e	The item event.

Remarks:

This method is called by processHostEvent and dispatches the event to a registered item listener. When overriding this method, call the super method processItemEvent to ensure the default event processing continues normally.

See Also: addItemListener

remove

public void remove(int index);

Removes the component at the specified index.

Return Value:

No return value.

Parameter	Description
index	The zero-based index of the component to be removed.

remove

public void remove(IUIComponent comp);

Removes the specified component from the control.

Return Value:

No return value.

Parameter	Description
comp	The component to be removed.

Remarks:

For an example of calling remove, see UISelector.remove.

Overrides:

remove(IUIComponent) in AwtUIControl.

removeActionListener

public synchronized void removeActionListener(ActionListener l);

Removes the specified action listener. The listener no longer receives the control's action events.

Return Value:

No return value.

Parameter	Description
l	The action listener to be removed.

See Also: addActionListener

removeItemListener

public synchronized void removeItemListener(ItemListener l);

Removes the specified item listener. The listener no longer receives the control's item events.

Return Value:

No return value.

Parameter	Description
l	The item listener to be removed.

See Also: addItemListener

removeSelectedIndex

public void removeSelectedIndex(int index);

Deselects the component at the specified index, without affecting other selections. By default, list deselect events are not generated.

Return Value:

No return value.

Parameter	Description
index	The zero-based index of the item to be deselected.

removeSelectedIndex

public void removeSelectedIndex(int index, boolean notify);

Deselects the component at the specified index, without affecting other selections. Optionally generates list select events.

Return Value:

No return value.

Parameter	Description
index	The zero-based index of the item to be deselected.
notify	If true, list deselect events will be generated; otherwise, list deselect events will not be generated.

removeSelectedIndices

public void removeSelectedIndices(int indices[]);

Deselects the components at the specified indices, without affecting other selections. By default, list deselect events are not generated.

Return Value:

No return value.

Parameter	Description
indices	An array containing the indices of the items to be deselected.

removeSelectedIndices

public void removeSelectedIndices(int indices[], boolean notify);

Deselects the components at the specified indices, without affecting other selections. Optionally generates list deselect events.

Return Value:

No return value.

Parameter	Description
indices	An array containing the indices of the items to be deselected.
notify	If true, list deselect events will be generated; otherwise, list deselect events will not be generated.

removeSelectedItem

public void removeSelectedItem(IUIComponent comp);

Deselects the specified component, without affecting other selections. By default, list deselect events are not generated.

Return Value:

No return value.

Parameter	Description
comp	The component to be deselected.

removeSelectedItem

public void removeSelectedItem(IUIComponent comp, boolean notify);

Deselects the specified component, without affecting other selections. Optionally generates list deselect events.

Return Value:

No return value.

Parameter	Description
comp	The component to be deselected.
notify	If true, list deselect events will be generated; otherwise, list deselect events will not be generated.

removeSelectedItems

public void removeSelectedItems(IUIComponent comps[]);

Deselects the specified components, without affecting other selections. By default, list deselect events are not generated.

Return Value:

No return value.

Parameter	Description
comps	An array containing the components to be deselected.

removeSelectedItems

public void removeSelectedItems(IUIComponent comps[], boolean notify);

Deselects the specified components, without affecting other selections. Optionally generates list deselect events.

Return Value:

No return value.

Parameter	Description
comps	An array containing the component to be deselected.
notify	If true, list deselect events will be generated; otherwise, list deselect events will not be generated.

setSelectedIndex

public void setSelectedIndex(int index);

Sets the selection to the component at the specified index. By default, a list select event is not generated.

Return Value:

No return value.

Parameter	Description
index	The zero-based index of the item to be selected.

Remarks:

This method clears any previous selection. If the control's selection mode is MULTISELECT or EXTENDSELECT, you can also call setSelectedIndices to select multiple items at a time.

See Also: setSelectedItem, addSelectedIndex, getSelectedIndex

setSelectedIndex

public void setSelectedIndex(int index, boolean notify);

Sets the selection to the component at the specified index and optionally generates a list select event.

Return Value:

No return value.

Parameter	Description
index	The zero-based index of the item to be selected.
notify	If true, a list select event will be generated; otherwise, a list select event will not be generated.

Remarks:

This method clears any previous selection. If the control's selection mode is MULTISELECT or EXTENDSELECT, you can also call setSelectedIndices to select multiple items at a time.

See Also: setSelectedItem, addSelectedIndex, getSelectedIndex

setSelectedIndices

public void setSelectedIndices(int indices[]);

Sets the selection to the components at the specified indices. List select events are not generated.

Return Value:

No return value.

Parameter	Description
indices	An array containing the zero-based indices of the items to be selected.

Remarks:

This method clears any previous selection. If the control's selection mode is SINGLESELECT, you can also call setSelectedIndex.

See Also: setSelectedItems, getSelectedIndices

setSelectedIndices

public void setSelectedIndices(int indices[], boolean notify);

Sets the selection to the components at the specified indices and optionally generates list select events.

Return Value:

No return value.

Parameter	Description
indices	An array containing the zero-based indices of the items to be selected.
notify	If true, list select events will be generated; otherwise, list select events will not be generated.

Remarks:

This method clears any previous selection. If the control's selection mode is SINGLESELECT, you can also call setSelectedIndex.

See Also: setSelectedItems, getSelectedIndices

setSelectedItem

public void setSelectedItem(IUIComponent comp);

Sets the selection to the specified component. A list select event is not generated.

Return Value:

No return value.

Parameter	Description
comp	The item to be selected.

Remarks:

This method clears any previous selection. If the control's selection mode is MULTISELECT or EXTENDSELECT, you can also call setSelectedItems to select multiple items at a time.

Exceptions:

IllegalArgumentException if the specified component is not an immediate child of the control.

See Also: setSelectedIndex, addSelectedItem, getSelectedItem

setSelectedItem

public void setSelectedItem(IUIComponent comp, boolean notify);

Sets the selection to the specified component, and optionally generates a list select event.

Return Value:

No return value.

Parameter	Description
comp	The item to be selected.
notify	If true, a list select event will be generated; otherwise, a list select event will not be generated.

Remarks:

This method clears any previous selection. If the control's selection mode is MULTISELECT or EXTENDSELECT, you can also call setSelectedItems to select multiple items at a time.

Exceptions:

IllegalArgumentException if the specified component is not an immediate child of the control.

See Also: setSelectedIndex, addSelectedItem, getSelectedItem

setSelectedItems

public void setSelectedItems(IUIComponent comps[]);

Sets the selection to the specified components. List select events are not generated.

Return Value:

No return value.

Parameter	Description
comps	An array containing the items to be selected.

Remarks:

This method clears any previous selection. If the control's selection mode is SINGLESELECT, you can also call setSelectedItem.

Exceptions:

IllegalArgumentException if any component in the array is not an immediate child of the control.

See Also: setSelectedIndices, getSelectedItems

setSelectedItems

public void setSelectedItems(IUIComponent comps[], boolean notify);

Sets the selection to the specified components, and optionally generates list select events.

Return Value:

No return value.

Parameter	Description
comps	An array containing the items to be selected.
notify	If true, list select events will be generated; otherwise, list select events will not be generated.

Remarks:

This method clears any previous selection. If the control's selection mode is SINGLESELECT, you can also call setSelectedItem.

Exceptions:

IllegalArgumentException if any component in the array is not an immediate child of the control.

See Also: setSelectedIndices, getSelectedItems

setSelectionMode

public void setSelectionMode(int selMode);

Sets the selection mode of the control.

Return Value:

No return value.

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

Exceptions:

IllegalArgumentException if an undefined selection mode was specified.

See Also: getSelectionMode