org.eclipse.ercp.swt.mobile
Class ListBox

java.lang.Object
  extended by org.eclipse.swt.widgets.Widget
      extended by org.eclipse.swt.widgets.Control
          extended by org.eclipse.swt.widgets.Scrollable
              extended by org.eclipse.ercp.swt.mobile.ListBox
All Implemented Interfaces:
Drawable

public class ListBox
extends Scrollable

Instances of this class represent a selectable user interface object that displays a list of items consisting of text and icons from a data model. Each list item may include combinations of heading text, heading icons, detail text, and detail icons. The layout and display of the various text and icons is variable depending upon the style and modifier constants passed to the constructor. Only one LB_STYLE_xxxx layout style constant may be specified. The LB_STYLE_NO_HEADING_TEXT style displays detail text on a single line per item. The LB_STYLE_1LINE_ITEM style displays heading text next to detail text in a single row. The LB_STYLE_2LINE_ITEM style displays heading text above detail text in a two line cell.

The following diagrams show the general layout for each layout style:

LB_STYLE_NO_HEADING_TEXT

Detail Text
Detail Text
Detail Text
Detail Text

LB_STYLE_1LINE_ITEM

Heading Text Detail Text
Heading Text Detail Text
Heading Text Detail Text
Heading Text Detail Text

LB_STYLE_2LINE_ITEM

Heading Text
Detail Text
Heading Text
Detail Text
Heading Text
Detail Text

The specific placement of item elements is locale and platform-dependent. LB_MOD_xxxx style modifiers are hints which are implemented in a platform-dependent fashion or perhaps not at all. They may be specified by or-ing any number of LB_MOD_xxxx constants with one selected layout style. Heading and detail icons are optionally displayed on any of the style layouts by specifying the LB_MOD_SHOW_HEADING_ICONS or LB_MOD_SHOW_DETAILS_ICONS modifiers. Heading and detail icons, if both displayed, are separated within the layout to indicate that they are distinct from each other. The LB_MOD_SHOW_SELECTION_NUMBER modifier is a hint for the ListBox to display a single digit next to each item which indicates that pressing that number selects the item. A list may be SINGLE or MULTI select. However, due to typical layout contraints, MULTI select is a hint that is guaranteed to be implemented only when no style modifiers are used.

The following is a possible layout for LB_STYLE_1LINE_ITEM | LB_MOD_SHOW_DETAIL_ICONS | LB_MOB_SHOW_SELECTION_NUMBER:

1 Heading Detail Text icon
2 Heading Detail Text icon
3 Heading Detail Text icon
4 Heading Detail Text icon

The model data is provided by an array of ListBoxItems. The array is not copied. The array is used until the ListBox is destroyed or a new data model is set.

IMPORTANT: This class is not intended to be subclassed. On some platforms, the fonts of the heading and detail texts are defined by the layout styles. ListBox allows setting the fonts even if the underlying platform does not, but in this case the appearance of the control will not change.

Styles:
SINGLE, MULTI

Note: Only one of SINGLE and MULTI may be specified.

Layout Styles:
LB_STYLE_NO_HEADING_TEXT
LB_STYLE_1LINE_ITEM
LB_STYLE_2LINE_ITEM

Note: Only one layout style may be specified. If more than one layout style is specified, the actual style used is implementation dependent.

Layout Style Modifiers:
LB_MOD_SHOW_SELECTION_NUMBER
LB_MOD_SHOW_HEADING_ICONS
LB_MOD_SHOW_DETAIL_ICONS

Note: Style modifiers are hints. Any number of modifier styles may be combined with a layout style

Events:
Selection, DefaultSelection

IMPORTANT: This class is not intended to be subclassed.

See Also:
ListBoxItem

Field Summary
static int LB_MOD_SHOW_DETAIL_ICONS
          shows icons associated with detail text
static int LB_MOD_SHOW_HEADING_ICONS
          shows icon associated with heading text
static int LB_MOD_SHOW_SELECTION_NUMBER
          shows a single digit number aligned with each item which may be used to select the item.
static int LB_STYLE_1LINE_ITEM
          single line item, 2 columns
static int LB_STYLE_2LINE_ITEM
          double line item, 1 column with heading and detail combined
static int LB_STYLE_NO_HEADING_TEXT
          single line item, 1 column (default)
 
Constructor Summary
ListBox(Composite parent, int style, int layoutStyle)
          Constructs a new instance of this class given its parent, a style value describing its selection behavior, and a style value describing its layout.
 
Method Summary
 void addSelectionListener(SelectionListener listener)
          Adds the listener to the collection of listeners who will be notified when the receiver's selection changes, by sending it one of the messages defined in the SelectionListener interface.
 void deselect(int index)
          Deselects the item at the given zero-relative index in the receiver.
 void deselect(int[] indices)
          Deselects the items at the given zero-relative indices in the receiver.
 void deselect(int start, int end)
          Deselects the items at the given zero-relative indices in the receiver.
 void deselectAll()
          Deselects all selected items in the receiver.
 int getFocusIndex()
          Returns the zero-relative index of the item which currently has the focus in the receiver, or -1 if no item has focus.
 int getSelectionCount()
          Returns the number of items currently selected.
 int[] getSelectionIndices()
          Returns the zero-relative indices of the items which are currently selected in the receiver.
 void refreshItem(int index)
          Notifies this ListBox that the data for the item at the given index has been updated and the item display needs to be refreshed.
 void refreshList()
          Notifies this ListBox that multiple items may have been updated and the entire list display needs to be refreshed.
 void removeSelectionListener(SelectionListener listener)
          Removes the listener from the collection of listeners who are notified when the receiver's selection changes.
 void select(int index)
          Selects the item at the given zero-relative index in the receiver's list.
 void select(int[] indices)
          Selects the items at the given zero-relative indices in the receiver.
 void select(int start, int end)
          Selects the items in the range specified by the given zero-relative indices in the receiver.
 void selectAll()
          Selects all of the items in the receiver.
 void setDataModel(ListBoxItem[] items)
          Establishes the data model for this ListBox.
 void setFont(Font font)
          Sets the font for the details text of an item.
 void setHeadingFont(Font font)
          Sets the font for the heading text of an item.
 void setSelection(int index)
          Selects the item at the given zero-relative index in the receiver.
 void setSelection(int[] indices)
          Selects the items at the given zero-relative indices in the receiver.
 void setSelection(int start, int end)
          Selects the items in the range specified by the given zero-relative indices in the receiver.
 void showSelection()
          Shows the selection.
 
Methods inherited from class org.eclipse.swt.widgets.Scrollable
computeTrim, getClientArea, getHorizontalBar, getVerticalBar
 
Methods inherited from class org.eclipse.swt.widgets.Control
addControlListener, addFocusListener, addKeyListener, addMouseListener, addMouseMoveListener, addPaintListener, addTraverseListener, computeSize, computeSize, forceFocus, getBackground, getBorderWidth, getBounds, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getParent, getShell, getSize, getToolTipText, getVisible, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removePaintListener, removeTraverseListener, setBackground, setBackgroundImage, setBounds, setBounds, setCapture, setEnabled, setFocus, setForeground, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, setSize, setSize, setToolTipText, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, update
 
Methods inherited from class org.eclipse.swt.widgets.Widget
addDisposeListener, addListener, checkSubclass, checkWidget, dispose, getData, getData, getDisplay, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, setData, setData, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LB_STYLE_NO_HEADING_TEXT

public static final int LB_STYLE_NO_HEADING_TEXT
single line item, 1 column (default)

See Also:
Constant Field Values

LB_STYLE_1LINE_ITEM

public static final int LB_STYLE_1LINE_ITEM
single line item, 2 columns

See Also:
Constant Field Values

LB_STYLE_2LINE_ITEM

public static final int LB_STYLE_2LINE_ITEM
double line item, 1 column with heading and detail combined

See Also:
Constant Field Values

LB_MOD_SHOW_SELECTION_NUMBER

public static final int LB_MOD_SHOW_SELECTION_NUMBER
shows a single digit number aligned with each item which may be used to select the item.

See Also:
Constant Field Values

LB_MOD_SHOW_HEADING_ICONS

public static final int LB_MOD_SHOW_HEADING_ICONS
shows icon associated with heading text

See Also:
Constant Field Values

LB_MOD_SHOW_DETAIL_ICONS

public static final int LB_MOD_SHOW_DETAIL_ICONS
shows icons associated with detail text

See Also:
Constant Field Values
Constructor Detail

ListBox

public ListBox(Composite parent,
               int style,
               int layoutStyle)
Constructs a new instance of this class given its parent, a style value describing its selection behavior, and a style value describing its layout.

The style value is either one of the style constants defined in class SWT which is applicable to instances of this class, or must be built by bitwise OR 'ing together (that is, using the int "|" operator) two or more of those SWT style constants. Style bits are also inherited from superclasses.

The layoutStyle value is one or more of the class layout style constants which may be combined by bitwise OR 'ing. Use of styles not applicaple to this class are ignored.

Parameters:
parent - a composite control which will be the parent of the new instance (cannot be null)
style - the style of control to construct
layoutStyle - the layout style of control to construct
Throws:
java.lang.IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the parent is null
SWTException -
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
  • ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
See Also:
SWT.SINGLE, SWT.MULTI
Method Detail

addSelectionListener

public void addSelectionListener(SelectionListener listener)
Adds the listener to the collection of listeners who will be notified when the receiver's selection changes, by sending it one of the messages defined in the SelectionListener interface.

widgetSelected is called when the selection changes.
widgetDefaultSelected is typically called when selection is finalized.

Parameters:
listener - instance called when selection events occur
Throws:
java.lang.IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the listener is null
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
SWTError -
  • ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure
See Also:
removeSelectionListener(org.eclipse.swt.events.SelectionListener), SelectionListener

deselect

public void deselect(int index)
Deselects the item at the given zero-relative index in the receiver. If the item at the index was already deselected, it remains deselected. Indices that are out of range are ignored.

Parameters:
index - the index of the item to deselect
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

deselect

public void deselect(int start,
                     int end)
Deselects the items at the given zero-relative indices in the receiver. If the items at the given zero-relative indexes in the receiver are selected, they are deselected. If they were not selected, they remain deselected. The range of the indices is inclusive. Indices that are out of range are ignored.

Parameters:
start - the start index of the items to deselect
end - the end index of the items to deselect
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

deselect

public void deselect(int[] indices)
Deselects the items at the given zero-relative indices in the receiver. If the items at the given zero-relative indexes in the receiver are selected, they are deselected. If they were not selected, they remain deselected. Indices that are out of range and duplicate indices are ignored.

Parameters:
indices - the array of indices for the items to deselect
Throws:
java.lang.IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the set of indices is null
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

deselectAll

public void deselectAll()
Deselects all selected items in the receiver.

Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

getFocusIndex

public int getFocusIndex()
Returns the zero-relative index of the item which currently has the focus in the receiver, or -1 if no item has focus.

Returns:
the index of the selected item
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

getSelectionCount

public int getSelectionCount()
Returns the number of items currently selected.

Returns:
count of selected items
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
SWTError -
  • ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure
See Also:
getSelectionIndices()

getSelectionIndices

public int[] getSelectionIndices()
Returns the zero-relative indices of the items which are currently selected in the receiver. The array is empty if no items are selected.

Note: This is not the actual structure used by the receiver to maintain its selection, so modifying the array will not affect the receiver.

Returns:
the array of indices of the selected items
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
SWTError -
  • ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure

refreshItem

public void refreshItem(int index)
Notifies this ListBox that the data for the item at the given index has been updated and the item display needs to be refreshed.

Parameters:
index - an index into the data model array
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
java.lang.IllegalArgumentException -
  • ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the array minus 1 (inclusive)
See Also:
refreshList()

refreshList

public void refreshList()
Notifies this ListBox that multiple items may have been updated and the entire list display needs to be refreshed.

Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
See Also:
refreshItem(int)

removeSelectionListener

public void removeSelectionListener(SelectionListener listener)
Removes the listener from the collection of listeners who are notified when the receiver's selection changes.

Parameters:
listener - instance called when selection events occur
Throws:
java.lang.IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the listener is null
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
SWTError -
  • ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure
See Also:
addSelectionListener(org.eclipse.swt.events.SelectionListener), SelectionListener

setFont

public void setFont(Font font)
Sets the font for the details text of an item. If the argument is null, the default font will be used.

Overrides:
setFont in class Control
Parameters:
font - the new font or null
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
java.lang.IllegalArgumentException -
  • ERROR_INVALID_ARGUMENT - if the argument has been disposed
See Also:
setHeadingFont(org.eclipse.swt.graphics.Font)

setHeadingFont

public void setHeadingFont(Font font)
Sets the font for the heading text of an item. If the argument is null, the default font will be used.

Parameters:
font - the new font or null
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
java.lang.IllegalArgumentException -
  • ERROR_INVALID_ARGUMENT - if the argument has been disposed
#see ListBox#setFont

select

public void select(int index)
Selects the item at the given zero-relative index in the receiver's list. If the item at the index was already selected, it remains selected. Indices that are out of range are ignored.

Parameters:
index - the index of the item to select
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

select

public void select(int start,
                   int end)
Selects the items in the range specified by the given zero-relative indices in the receiver. The range of indices is inclusive. The current selection is not cleared before the new items are selected.

If an item in the given range is not selected, it is selected. If an item in the given range was already selected, it remains selected. Indices that are out of range are ignored and no items will be selected if start is greater than end. If the receiver is single-select and there is more than one item in the given range, then all indices are ignored.

Parameters:
start - the start of the range
end - the end of the range
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
See Also:
setSelection(int,int)

select

public void select(int[] indices)
Selects the items at the given zero-relative indices in the receiver. The current selection is not cleared before the new items are selected.

If the item at a given index is not selected, it is selected. If the item at a given index was already selected, it remains selected. Indices that are out of range and duplicate indices are ignored. If the receiver is single-select and multiple indices are specified, then all indices are ignored.

Parameters:
indices - the array of indices for the items to select
Throws:
java.lang.IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the array of indices is null
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
See Also:
setSelection(int[])

selectAll

public void selectAll()
Selects all of the items in the receiver.

If the receiver is single-select, do nothing.

Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setDataModel

public void setDataModel(ListBoxItem[] items)
Establishes the data model for this ListBox. The provided array is used for the life of the ListBox or until a new data model is set. Elements of a ListBoxItem which are null or disposed are not displayed, leaving a blank area within the layout.

Parameters:
items - an array of ListBoxItems or null
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
java.lang.IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the items is null
See Also:
ListBoxItem

setSelection

public void setSelection(int index)
Selects the item at the given zero-relative index in the receiver. If the item at the index was already selected, it remains selected. The current selected is first cleared, then the new items are selected. Index that is out of range are ignored.

Parameters:
index - the index of the item to select
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setSelection

public void setSelection(int start,
                         int end)
Selects the items in the range specified by the given zero-relative indices in the receiver. The range of indices is inclusive. The current selection is cleared before the new items are selected.

Indices that are out of range are ignored and no items will be selected if start is greater than end. If the receiver is single-select and there is more than one item in the given range, then all indices are ignored.

Parameters:
start - the start index of the items to select
end - the end index of the items to select
Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setSelection

public void setSelection(int[] indices)
Selects the items at the given zero-relative indices in the receiver. The current selection is cleared before the new items are selected.

Indices that are out of range and duplicate indices are ignored. If the receiver is single-select and multiple indices are specified, then all indices are ignored.

Parameters:
indices - the indices of the items to select
Throws:
java.lang.IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the array of indices is null
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
See Also:
deselectAll(), select(int[])

showSelection

public void showSelection()
Shows the selection. If the selection is already showing in the receiver, this method simply returns. Otherwise, the items are scrolled until the selection is visible. When multiple items are selected, the selection of which item becomes visible is implementation-dependent.

Throws:
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver