Eclipse eRCP
Release 1.1

org.eclipse.ercp.swt.mobile
Class SortedList

java.lang.Object
  extended byorg.eclipse.swt.widgets.Widget
      extended byorg.eclipse.swt.widgets.Control
          extended byorg.eclipse.swt.widgets.Scrollable
              extended byorg.eclipse.ercp.swt.mobile.SortedList
All Implemented Interfaces:
Drawable

public class SortedList
extends Scrollable

Instances of this class represent a selectable user interface object that displays a sorted list of text items. The items may be displayed in ascending or descending order. The sorting algorithm is platform and locale dependent.

If the FILTER style is specified during construction, an associated label is also displayed showing characters entered which are then used to filter the list to show fewer items. The selection state of items filtered out of the list is cleared.

IMPORTANT: This class is not intended to be subclassed.

Styles:
SINGLE, MULTI, UP, DOWN

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

Mode Styles:
FILTER

Events:
Selection, DefaultSelection


Field Summary
static int FILTER
          constructor style specifying filter field should be displayed
 
Constructor Summary
SortedList(Composite parent, int style)
          Construct a new instance of this class given its parent and a style value describing its behavior and appearance.
SortedList(Composite parent, int style, int modeStyle)
          Construct a new instance of this class given its parent, a style value describing its behavior and appearance, and a mode style describing additional behavior modes.
 
Method Summary
 void add(String item)
          Adds the argument to the receiver's list of items.
 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.
 String getFocus()
          Returns the text of the item currently focused in the receiver, or null if no item has focus.
 int getItemHeight()
          Returns the height (in pixels) of the area which would be used to display one of the items in the tree.
 String[] getSelection()
          Returns an array of Strings of items that are currently selected in the receiver.
 int getSelectionCount()
          Returns the number of items currently selected.
 void remove(String item)
          Searches the receiver's list starting at the first item until an item is found that is equal to the argument, and removes that item from the list.
 void removeAll()
          Removes all of the items from the receiver.
 void removeSelectionListener(SelectionListener listener)
          Removes the listener from the collection of listeners who are notified when the receiver's selection changes.
 void select(String item)
          Selects the first item that has text matching the given string.
 void setItems(String[] items)
          Sets the receiver's items to be the given array of items.
 void setSelection(String[] items)
          Sets the receiver's selection to be the given array of items.
 void showSelection()
          Scrolls the list as necessary to show the selected items.
 
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, getBackgroundImage, 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, setFont, 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

FILTER

public static final int FILTER
constructor style specifying filter field should be displayed

See Also:
Constant Field Values
Constructor Detail

SortedList

public SortedList(Composite parent,
                  int style)
Construct a new instance of this class given its parent and a style value describing its behavior and appearance.

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. SWT.UP (the default) means the list is sorted so that numbers go from low to high when the list is examined from top to bottom. SWT.DOWN means the list is sorted so that numbers go from high to low when examined from top to bottom.

Parameters:
parent - a composite control which will be the parent of the new instance (cannot be null)
style - the style of the control
Throws:
IllegalArgumentException -
SWTException -
See Also:
SWT.SINGLE, SWT.MULTI, SWT.UP, SWT.DOWN

SortedList

public SortedList(Composite parent,
                  int style,
                  int modeStyle)
Construct a new instance of this class given its parent, a style value describing its behavior and appearance, and a mode style describing additional behavior modes.

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. SWT.UP (the default) means the list is sorted in dictionary order from top to bottom (i.e. A, B, C, ...). SWT.DOWN means the list is sorted in reverse dictionary order from top to bottom (i.e. Z, Y, X, ...). The modeStyle may specify the class constant FILTER. This style adds a text entry field to the widget which does not receive focus, but will display characters entered while the list has focus. These characters are used to filter the list items so that fewer items are displayed in the list. The selection is cleared for any items not shown as a result of filtering.

Parameters:
parent - a composite control which will be the parent of the new instance (cannot be null)
style - the style of the control
modeStyle - the mode for the control
Throws:
IllegalArgumentException -
SWTException -
See Also:
SWT.SINGLE, SWT.MULTI, SWT.UP, SWT.DOWN, FILTER
Method Detail

add

public void add(String item)
Adds the argument to the receiver's list of items.

Parameters:
item - text to be added to the list
Throws:
IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the item 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:
setItems(String[]), remove(java.lang.String), removeAll()

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:
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:
ListBox.removeSelectionListener(org.eclipse.swt.events.SelectionListener), SelectionListener

getFocus

public String getFocus()
Returns the text of the item currently focused in the receiver, or null if no item has focus.

Returns:
the text of the item with focus
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

getItemHeight

public int getItemHeight()
Returns the height (in pixels) of the area which would be used to display one of the items in the tree.

Returns:
height in pixels
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_HEIGHT - if the operation fails because of an operating system failure

getSelection

public String[] getSelection()
Returns an array of Strings of items that are currently selected in the receiver.

Returns:
array 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_SELECTION - if the operation fails because of an operating system failure
See Also:
getSelectionCount()

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:
getSelection()

remove

public void remove(String item)
Searches the receiver's list starting at the first item until an item is found that is equal to the argument, and removes that item from the list.

Parameters:
item - text of item to remove
Throws:
IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the string is null
  • ERROR_INVALID_ARGUMENT - if the string is not found in the list
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:
add(String), removeAll()

removeAll

public void removeAll()
Removes all of the items from 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 parent
IllegalArgumentException -
  • ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure
See Also:
add(String), remove(String), setItems(String[])

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:
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

select

public void select(String item)
Selects the first item that has text matching the given string. If the argument is null, the selection is cleared.

Parameters:
item - text of item to select
Throws:
IllegalArgumentException -
  • ERROR_INVALID_ARGUMENT - if the string is not found in the list
SWTException -
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

setItems

public void setItems(String[] items)
Sets the receiver's items to be the given array of items.

Parameters:
items - array of text strings to be shown in list
Throws:
IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the string array 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:
add(java.lang.String)

setSelection

public void setSelection(String[] items)
Sets the receiver's selection to be the given array of items.

Parameters:
items - array of text strings to be selected in list
Throws:
IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the string array 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
See Also:
select(java.lang.String)

showSelection

public void showSelection()
Scrolls the list as necessary to show 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 parent
See Also:
select(java.lang.String), setSelection(java.lang.String[])

Eclipse eRCP
Release 1.1