Class AwtUIChoice

public class AwtUIChoice extends AwtUIControl implements 
            IAwtUIItemSelectable
{
  // Constructors
  public AwtUIChoice();

  // Methods
  public IUIComponent add(IUIComponent comp);
  public Component add(Component comp);
  public void addItem(String s);
  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 addString(String s);
  public IUIComponent getAnchorItem();
  public IUIComponent getBase();
  public IUIComponent getExtensionItem();
  public int getSelectedIndex();
  public int[] getSelectedIndices();
  public IUIComponent getSelectedItem();
  public IUIComponent[] getSelectedItems();
  public Object[] getSelectedObjects();
  public int getSelectionMode();
  public int getStyle();
  public String getValueText();
  protected void processHostEvent(AWTEvent e);
  protected void processItemEvent(ItemEvent e);
  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 setAnchorItem(IUIComponent comp);
  public void setExtensionItem(IUIComponent comp);
  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 setStyle(int style);
  public void setValueText(String s);
}

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

Note Only IUISelector.SINGLESELECT mode is supported in UIChoice.

Panel
  |
  +--AwtUIHost
    |
    +--AwtUIControl
      |
      +--AwtUIChoice

Constructors

AwtUIChoice

public AwtUIChoice();

Creates an empty AWT-based choice control.

Remarks:

Call add, addItem, or addString to add items to the control's pop-up list.

Methods

add

public IUIComponent add(IUIComponent comp);

Adds the specified UI component to the end of the control's pop-up list.

Return Value:

Returns the component that was added.

Parameter	Description
comp	The UI component to be added to the control.

Overrides:

add(IUIComponent) in AwtUIControl.

See Also: addString, addItem

add

public Component add(Component comp);

Adds the specified AwtUI component to the end of the control's pop-up list. Pure AWT components cannot be added.

Return Value:

Returns the control itself.

Parameter	Description
comp	The AwtUI component to be added to the control.

Overrides:

add(Component) in AwtUIControl.

Exceptions:

IllegalArgumentException if a pure AWT component was added.

See Also: addString, addItem

addItem

public void addItem(String s);

Adds the specified text to the end of the control's pop-up list.

Return Value:

No return value.

Parameter	Description
s	The text to be added to the control.

See Also: add, addString

addItemListener

public void addItemListener(ItemListener l);

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

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.

See Also: removeSelectedIndex

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.

See Also: removeSelectedIndex

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.

See Also: removeSelectedIndices

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.

See Also: removeSelectedIndices

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.

See Also: removeSelectedItem

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.

See Also: removeSelectedItem

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.

See Also: removeSelectedItems

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.

See Also: removeSelectedItems

addString

public IUIComponent addString(String s);

Adds the specified text to the end of the control's pop-up list.

Return Value:

Returns the text component that was added.

Parameter	Description
s	The text to be added to the control.

See Also: add, addItem

getAnchorItem

public IUIComponent getAnchorItem();

Retrieves the component that is the current anchor in extend select mode by calling UIChoice.getAnchorItem.

Return Value:

Returns the component that is the anchor.

See Also: setAnchorItem

getBase

public IUIComponent getBase();

Retrieves the UI component that the control is based on.

Return Value:

Returns the UIChoice object associated with the control.

Remarks:

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

getExtensionItem

public IUIComponent getExtensionItem();

Retrieves the item to which a selection, in EXTENDEDSELECT mode, last extended from the anchor. This method calls UIChoice.getExtensionItem.

Return Value:

Returns the extension item.

See Also: setExtensionItem, com.ms.ui.UIChoice.getExtensionItem

getSelectedIndex

public int getSelectedIndex();

Retrieves the index of the choice control's currently selected item.

Return Value:

Returns the index of the selected component.

See Also: 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, if an item is selected; otherwise, returns -1.

See Also: setSelectedIndices

getSelectedItem

public IUIComponent getSelectedItem();

Retrieves the control's currently selected item.

Return Value:

Returns the selected component.

See Also: setSelectedItem, setSelectedItem

getSelectedItems

public IUIComponent[] getSelectedItems();

Retrieves all currently selected items.

Return Value:

Returns an array of the selected components, if a component is selected; otherwise, returns null.

See Also: setSelectedItems

getSelectedObjects

public Object[] getSelectedObjects();

Retrieves the selected items in the control.

Return Value:

Returns the currently selected item.

Remarks:

This method implements getSelectedObjects in the IAwtUIItemSelectable interface. Only one item in the control can be selected at a time.

getSelectionMode

public int getSelectionMode();

Retrieves the current selection mode.

Return Value:

Returns the current mode.

See Also: setSelectionMode

getStyle

public int getStyle();

Retrieves the current style of the control.

Return Value:

Returns an integer containing the current style setting. For a list of possible values, see setStyle.

getValueText

public String getValueText();

Retrieves the current value text.

Return Value:

No return value.

Parameter	Description
s	The string containing the current text value.

See Also: setValueText

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 been registered through a call to addXXXListener. Depending on the type of event, processHostEvent calls one of the following methods.

Event type	Method called
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

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.

See Also: addSelectedIndex

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.

See Also: addSelectedIndex

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.

See Also: addSelectedIndices

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.

See Also: addSelectedIndices

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.

See Also: addSelectedItem

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.

See Also: addSelectedItem

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.

See Also: addSelectedItems

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.

See Also: addSelectedItems

setAnchorItem

public void setAnchorItem(IUIComponent comp);

Sets the item used as an anchor in EXTENDSELECT mode by calling UIChoice.setAnchorItem. You cannot set the anchor item to null.

Note Resetting the anchor automatically sets the current extension item to null. If the extension item is intended to set both to specific items, call setAnchorItem, followed by setExtensionItem.

Setting the anchor in an IUISelector other than the outermost position, has no effect.

Return Value:

No return value.

Parameter	Description
comp	The component that will be the new anchor.

Exceptions:

IllegalArgumentException if the component is not a child of the selector, or if the component is null.

See Also: getAnchorItem, com.ms.ui.UIChoice.setAnchorItem

setExtensionItem

public void setExtensionItem(IUIComponent comp);

Sets the item to which a selection, in EXTENDEDSELECT mode, extends from an anchor.

Note This method calls UIChoice.setExtensionItem .

Return Value:

No return value.

Parameter	Description
comp	The component that will be the new extension item.

Exceptions:

IllegalArgumentException if comp is not a child of the selector.

See Also: getExtensionItem, com.ms.ui.UIChoice.setExtensionItem

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.

See Also: 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.

Remarks:

This method clears any previous selection.

See Also: getSelectedIndex

setSelectedIndices

public void setSelectedIndices(int indices[]);

Sets the selection to the components at the specified indices. By default, list select events are not gerenated.

Return Value:

No return value.

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

Remarks:

This method clears any previous selection.

See Also: 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 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.

See Also: getSelectedIndices

setSelectedItem

public void setSelectedItem(IUIComponent comp);

Sets the control's currently selected item.

Return Value:

No return value.

Parameter	Description
comp	The component to be selected.

See Also: 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.

Remarks:

This method clears any previous selection.

See Also: getSelectedItem

setSelectedItems

public void setSelectedItems(IUIComponent comps[]);

Sets the selection to the specified components. By default, 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.

See Also: 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.

Remarks:

This method clears any previous selection.

See Also: getSelectedItems

setSelectionMode

public void setSelectionMode(int selMode);

Sets the current selection mode.

Return Value:

No return value.

Parameter	Description
selMode	The selection mode.

Exceptions:

IllegalArgumentException if a mode other than IUISelector.SINGLESELECT is used.

See Also: getSelectionMode

setStyle

public void setStyle(int style);

Sets the current style for the control. To restore the default style, call setStyle(0).

Return Value:

No return value.

Parameter	Description
style	The style of the control. You can pass THICK to specify using a thick border around the choice and its elements.

Exceptions:

IllegalArgumentException if an undefined style was specified.

setValueText

public void setValueText(String s);

Sets the current text value. This method searches through the items in the choice list using the given string as a prefix. It attempts to find a matching item.

Return Value:

No return value.

Parameter	Description
s	The string to set.

See Also: getValueText