|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.swt.widgets.Widget
org.eclipse.swt.widgets.Control
org.eclipse.swt.widgets.Scrollable
org.eclipse.ercp.swt.mobile.ListBox
public class ListBox
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.
Note: Only one of SINGLE and MULTI may be specified.
Note: Only one layout style may be specified. If more than one layout style is specified, the actual style used is implementation dependent.
Note: Style modifiers are hints. Any number of modifier styles may be combined with a layout style
IMPORTANT: This class is not intended to be subclassed.
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) |
Fields inherited from class org.eclipse.swt.widgets.Control |
---|
enableTraverse, internal_parent |
Fields inherited from class org.eclipse.swt.widgets.Widget |
---|
internal_handle, internal_style |
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. |
boolean |
allowTraverseByArrowKey(Event event)
|
Point |
computeSize(int wHint,
int hHint,
boolean changed)
Returns the preferred size of the receiver. |
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. |
void |
dispose()
Disposes of the operating system resources associated with the receiver and all its descendents. |
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. |
Font |
getFont()
Returns the font that the receiver will use to paint textual information. |
ScrollBar |
getHorizontalBar()
Returns the receiver's horizontal scroll bar if it has one, and null if it does not. |
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. |
ScrollBar |
getVerticalBar()
Returns the receiver's vertical scroll bar if it has one, and null if it does not. |
void |
internal_createHandle(int index)
|
boolean |
isDisposed()
Returns true if the widget has been disposed,
and false otherwise. |
void |
pack()
Causes the receiver to be resized to its preferred size. |
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. |
protected void |
removeInternalFilter()
|
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 |
setBounds(int x,
int y,
int w,
int h)
Sets the receiver's size and location to the rectangular area specified by the arguments. |
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 |
setSize(int w,
int h)
Sets the receiver's size to the point specified by the arguments. |
void |
showSelection()
Shows the selection. |
protected boolean |
traverse(Event event)
|
Methods inherited from class org.eclipse.swt.widgets.Scrollable |
---|
computeTrim, getClientArea, internal_getNativeStyle |
Methods inherited from class org.eclipse.swt.widgets.Widget |
---|
addDisposeListener, addListener, checkSubclass, checkWidget, getData, getData, getDisplay, getStyle, internal_sendEvent, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, sendEvent, setData, setData, toString |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int LB_STYLE_NO_HEADING_TEXT
public static final int LB_STYLE_1LINE_ITEM
public static final int LB_STYLE_2LINE_ITEM
public static final int LB_MOD_SHOW_SELECTION_NUMBER
public static final int LB_MOD_SHOW_HEADING_ICONS
public static final int LB_MOD_SHOW_DETAIL_ICONS
Constructor Detail |
---|
public ListBox(Composite parent, int style, int layoutStyle)
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.
parent
- a composite control which will be the parent of the new
instance (cannot be null)style
- the style of control to constructlayoutStyle
- the layout style of control to construct
java.lang.IllegalArgumentException
- SWTException
- SWT.SINGLE
,
SWT.MULTI
Method Detail |
---|
public void addSelectionListener(SelectionListener listener)
widgetSelected
is called when the selection changes.
widgetDefaultSelected
is typically called when selection
is finalized.
listener
- instance called when selection events occur
java.lang.IllegalArgumentException
- SWTException
- SWTError
- removeSelectionListener(org.eclipse.swt.events.SelectionListener)
,
SelectionListener
public void deselect(int index)
index
- the index of the item to deselect
SWTException
- public void deselect(int start, int end)
start
- the start index of the items to deselectend
- the end index of the items to deselect
SWTException
- public void deselect(int[] indices)
indices
- the array of indices for the items to deselect
java.lang.IllegalArgumentException
- SWTException
- public void deselectAll()
SWTException
- public Point computeSize(int wHint, int hHint, boolean changed)
Control
The preferred size of a control is the size that it would
best be displayed at. The width hint and height hint arguments
allow the caller to ask a control questions such as "Given a particular
width, how high does the control need to be to show all of the contents?"
To indicate that the caller does not wish to constrain a particular
dimension, the constant SWT.DEFAULT
is passed for the hint.
If the changed flag is true
, it indicates that the receiver's
contents have changed, therefore any caches that a layout manager
containing the control may have been keeping need to be flushed. When the
control is resized, the changed flag will be false
, so layout
manager caches can be retained.
computeSize
in class Scrollable
wHint
- the width hint (can be SWT.DEFAULT
)hHint
- the height hint (can be SWT.DEFAULT
)changed
- true
if the control's contents have changed, and false
otherwise
Layout
,
Control.getBorderWidth()
,
Control.getBounds()
,
Control.getSize()
,
Control.pack(boolean)
,
"computeTrim, getClientArea for controls that implement them"public int getFocusIndex()
SWTException
- public int getSelectionCount()
SWTException
- SWTError
- getSelectionIndices()
public int[] getSelectionIndices()
Note: This is not the actual structure used by the receiver to maintain its selection, so modifying the array will not affect the receiver.
SWTException
- SWTError
- public void refreshItem(int index)
index
- an index into the data model array
SWTException
- java.lang.IllegalArgumentException
- refreshList()
public void refreshList()
SWTException
- refreshItem(int)
public void removeSelectionListener(SelectionListener listener)
listener
- instance called when selection events occur
java.lang.IllegalArgumentException
- SWTException
- SWTError
- addSelectionListener(org.eclipse.swt.events.SelectionListener)
,
SelectionListener
public void setFont(Font font)
setFont
in class Control
font
- the new font or null
SWTException
- java.lang.IllegalArgumentException
- setHeadingFont(org.eclipse.swt.graphics.Font)
public Font getFont()
Control
getFont
in class Control
public void setHeadingFont(Font font)
font
- the new font or null
SWTException
- java.lang.IllegalArgumentException
- public void select(int index)
index
- the index of the item to select
SWTException
- public void select(int start, int end)
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.
start
- the start of the rangeend
- the end of the range
SWTException
- setSelection(int,int)
public void select(int[] indices)
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.
indices
- the array of indices for the items to select
java.lang.IllegalArgumentException
- SWTException
- setSelection(int[])
public void selectAll()
If the receiver is single-select, do nothing.
SWTException
- public void setDataModel(ListBoxItem[] items)
null
or disposed are not displayed,
leaving a blank area within the layout.
items
- an array of ListBoxItems or null
SWTException
- java.lang.IllegalArgumentException
- ListBoxItem
public void setSelection(int index)
index
- the index of the item to select
SWTException
- public void setSelection(int start, int end)
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.
start
- the start index of the items to selectend
- the end index of the items to select
SWTException
- public void setSelection(int[] indices)
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.
indices
- the indices of the items to select
java.lang.IllegalArgumentException
- SWTException
- deselectAll()
,
select(int[])
public void showSelection()
SWTException
- public void pack()
Control
pack
in class Control
Control.computeSize(int, int, boolean)
public void setBounds(int x, int y, int w, int h)
Control
x
and
y
arguments are relative to the receiver's
parent (or its display if its parent is null), unless
the receiver is a shell. In this case, the x
and y
arguments are relative to the display.
Note: Attempting to set the width or height of the receiver to a negative number will cause that value to be set to zero instead.
setBounds
in class Control
x
- the new x coordinate for the receivery
- the new y coordinate for the receiverw
- the new width for the receiverh
- the new height for the receiverpublic void setSize(int w, int h)
Control
Note: Attempting to set the width or height of the receiver to a negative number will cause that value to be set to zero instead.
setSize
in class Control
w
- the new width for the receiverh
- the new height for the receiverpublic void internal_createHandle(int index)
internal_createHandle
in class Widget
public void dispose()
Widget
true
when sent the message isDisposed()
.
Any internal connections between the widgets in the tree will
have been removed to facilitate garbage collection.
NOTE: This method is not called recursively on the descendents
of the receiver. This means that, widget implementers can not
detect when a widget is being disposed of by re-implementing
this method, but should instead listen for the Dispose
event.
dispose
in class Control
Widget.addDisposeListener(org.eclipse.swt.events.DisposeListener)
,
Widget.removeDisposeListener(org.eclipse.swt.events.DisposeListener)
,
Widget.checkWidget()
protected void removeInternalFilter()
removeInternalFilter
in class Widget
public boolean isDisposed()
Widget
true
if the widget has been disposed,
and false
otherwise.
This method gets the dispose state for the widget. When a widget has been disposed, it is an error to invoke any other method using the widget.
isDisposed
in class Widget
true
when the widget is disposed and false
otherwisepublic ScrollBar getVerticalBar()
Scrollable
getVerticalBar
in class Scrollable
public ScrollBar getHorizontalBar()
Scrollable
getHorizontalBar
in class Scrollable
public boolean allowTraverseByArrowKey(Event event)
allowTraverseByArrowKey
in class Control
protected boolean traverse(Event event)
traverse
in class Control
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |