|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
net.rim.device.api.ui.component.SpinBoxField
public abstract class SpinBoxField
A user interface component for selecting a single item from a list where the user can spin through the various choices. This component is useful when the candidates for selection are sequential e.g. months, numbers, or a list in alphabetical order.
This particular class is abstract. There are subclasses that implement different types of spin boxes i.e. spin boxes for text or bitmaps. The respective classes should actually be instantiated. If none of the provided implementations solve your use cases, you may extend this class to render the spin box to your liking.
On non-touch devices, users need to be able to navigate to different fields within the same
screen. This can be addressed by setting this field's editability.
This field can be locked for editing using SpinBoxField.setEditable(boolean)
. If Field.isEditable()
is true
,
then the user can manipulate the spin box to select a choice. Otherwise, the user cannot spin
through the choices. For touch screen only devices, this field is always editable.
Additionally, if this spin box is added to a SpinBoxFieldManager
, the
the developer can specify whether or not clicking on the spin box will lock the spin boxes
for editing. This will allow users to focus on other fields on non-touch devices.
See SpinBoxFieldManager.setClickToLock(boolean)
.
Spin boxes act like a wheel and can wrap around from the first choice to the last choice.
This functionality can be disabled if the style SpinBoxField.NO_WRAP
is specified. Wrapping
is automatically disabled when the number of choices is less than or equal to
the number of visible rows (SpinBoxField.getVisibleRows()
).
SpinBoxField
emits events when:
FieldChangeListener.fieldChanged(net.rim.device.api.ui.Field, int)
is called with the changed spin box, and a context
flag specifying if the index changed programmatically or not.FieldChangeListener.fieldChanged(net.rim.device.api.ui.Field, int)
is called when the spin box moves from either
the first to the last index or the last to the first index. The direction of the wrapping is
specified by SpinBoxField.SPINBOX_WRAP_LAST_TO_FIRST_INDEX
and SpinBoxField.SPINBOX_WRAP_FIRST_TO_LAST_INDEX
.SpinBoxField.SPINBOX_STOPPED
will be specified as the context
This class should be used in conjunction with a SpinBoxFieldManager
.
Note that if this field belongs to a SpinBoxFieldManager
some properties
of this field cannot be set directly: row height and number of rows to display to the user.
If these properties are set in the SpinBoxField
then the SpinBoxField
is added to a manager, then the properties are set to that of the manager's.
The properties must be set through the manager. Think of it like a singing group. Each SpinBoxField
is a singer in the group, but they can't perform without permission from their manager i.e.
SpinBoxFieldManager
.
See the documentation for SpinBoxFieldManager
and other implementations of the SpinBoxfield
for
details on how to use the SpinBoxField
.
SpinBoxField.get(int)
SpinBoxField.setRowHeight(int)
SpinBoxField.setVisibleRows(int)
SpinBoxField.setSelectedIndex(int newIndex)
SpinBoxField.setSelectedIndex(int newIndex, boolean animate)
SpinBoxFieldManager
,
TextSpinBoxField
Field Summary | ||
---|---|---|
static long |
NO_WRAP
A style for the spin box that indicates the spin box will not wrap around. |
|
static int |
SPINBOX_STOPPED
Indicates to the field change listener that the spin box stopped spinning after some movement. |
|
static int |
SPINBOX_WRAP_FIRST_TO_LAST_INDEX
Indicates to the field change listener that the spin box wrapped from the first index to the last index. |
|
static int |
SPINBOX_WRAP_LAST_TO_FIRST_INDEX
Indicates to the field change listener that the spin box wrapped from the last index to the first index. |
Constructor Summary | ||
---|---|---|
SpinBoxField()
Construct the default SpinBoxField with the default row height and
number of rows set. |
||
SpinBoxField(long style)
Constructs a SpinBoxField with a style. |
Method Summary | ||
---|---|---|
protected void |
applyTheme()
Called by the framework to tell each Field to apply theme attributes to itself. |
|
protected void |
drawFocus(Graphics graphics,
boolean on)
Draws the focus indicator for this field. |
|
protected abstract void |
drawRow(Graphics graphics,
int index,
int x,
int y,
int width,
int height)
Draw the specified row in the given parameters. |
|
abstract Object |
get(int index)
Retrieve the object at the given index. |
|
abstract int |
getCount()
Returns The number of objects that could be displayed in the spin box. |
|
int |
getPreferredHeight()
Retrieves this field's preferred height. |
|
int |
getRowHeight()
Returns the height in pixels of each row on the spin box. |
|
int |
getSelectedIndex()
Returns the currently selected index. |
|
SpinBoxFieldManager |
getSpinBoxFieldManager()
Returns the SpinBoxFieldManager that owns this field. |
|
int |
getVisibleRows()
Returns the number of rows that will be shown to the user. |
|
boolean |
keyChar(char key,
int status,
int time)
Handles character generation events. |
|
protected void |
layout(int availableWidth,
int availableHeight)
Lays out the contents. |
|
protected int |
moveFocus(int amount,
int status,
int time)
Handles moving the focus within this field. |
|
protected boolean |
moveSelectedIndex(int delta,
boolean programmatic)
Moves (animated) the selected index. |
|
protected boolean |
moveSelectedIndex(int delta,
boolean programmatic,
boolean animate)
Moves the selected index. |
|
protected boolean |
navigationMovement(int dx,
int dy,
int status,
int time)
Invoked when a navigational motion occurs. |
|
protected void |
onFocus(int direction)
Invoked when a field receives the focus. |
|
protected void |
onUnfocus()
Invoked when a field loses the focus. |
|
void |
paint(Graphics graphics)
Invoked by the framework to redraw a portion of this field. |
|
protected void |
refresh()
This method must be called when the contents/choices have changed. |
|
void |
setEditable(boolean editable)
Set the editable state of this field. |
|
void |
setRowHeight(int rowHeight)
Sets the height of each row in the spin box. |
|
void |
setSelectedIndex(int newIndex)
Sets the selected index and animates the spin box as necessary. |
|
void |
setSelectedIndex(int newIndex,
boolean animate)
Sets the selected index and moves the spin box as necessary. |
|
void |
setVisibleRows(int visibleRows)
Sets the number of rows that will be shown to the user. |
|
protected boolean |
touchEvent(TouchEvent message)
Indicates a touch event. |
|
protected boolean |
updateSelectedIndex()
Updates the selected index based on the position of the spin box. |
|
protected static int |
wrap(int low,
int value,
int high)
Wraps a value around a range. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int SPINBOX_STOPPED
public static final int SPINBOX_WRAP_FIRST_TO_LAST_INDEX
public static final int SPINBOX_WRAP_LAST_TO_FIRST_INDEX
public static final long NO_WRAP
Constructor Detail |
---|
public SpinBoxField(long style)
style
- Styles supported include NO_WRAP
and styles specified in sub-classes.
SpinBoxField
s are always focusable.public SpinBoxField()
SpinBoxField
with the default row height and
number of rows set.
Method Detail |
---|
public SpinBoxFieldManager getSpinBoxFieldManager()
SpinBoxFieldManager
that owns this field.
SpinBoxFieldManager
or
null if this field has no manager or the manager is
not a SpinBoxFieldManager
SpinBoxFieldManager
protected void layout(int availableWidth, int availableHeight)
This method is abstract; any class that extends Field must implement this method appropriate to its needs.
Invoked after the screen has been created, or when system
parameters change (for example, after a system font change).
Field.getExtent()
will return a valid value after this method is
invoked. Implementations of this method must invoke Field.setExtent(int, int)
with the size used by the field.
During this call, Field.setExtent(int, int)
must be called with parameters
such that both width and height are between 0 and the values passed
into this function for the Manager to be able to position this Field
properly.
Fields may cache system attributes for efficiency (such as the current system font); however, they cannot depend on these attributes remaining unchanged. When one of these attributes changes, a message event is sent to that effect: in these cases, this method refetch and cache these attributes.
layout
in class Field
availableWidth
- Amount of available horizontal space.availableHeight
- Amount of available vertical space.Field.layout(int, int)
,
getRowHeight
,
getRowWidth
,
getVisibleRows
protected void applyTheme()
It will be called prior to the first layout(int, int), and after each time theme information has changed.
A subclass should implement this if it is theme aware and has fonts, colors, or layout information that needs to be calculated. Always call super.applyTheme() as the first line in overriding implementations.
applyTheme
in class Field
Field.applyTheme()
public boolean keyChar(char key, int status, int time)
This field's manager invokes this method to send this field a character event.
Special keystroke handling code should be implemented in the Field keyDown method. However, this code checks for cut, copy, or paste keystrokes and dispatches to the appropriate field.
While selection mode is on, ESC cancels selection, and SHIFT+DEL cuts selection.
keyChar
in class Field
key
- Character generated.status
- Modifier key status. See KeypadListener
.time
- Number of milliseconds since the device was turned on.
KeyListener#keyChar
protected static int wrap(int low, int value, int high)
MathUtilities.wrap(int, int, int)
.
This method calculates the value's overflow over high
or underflow under low
.
The wrapping could be thought of a clock where low
is at the 12 o'clock position and
high
is at the 11 o'clock position. Any value can be placed on the clock. The value of
low
must be less than high
.
For example:
low = 0
high = 5
value_1 = 6
result_1 = 0
value_2 = -3
result_2 = 3
low
- the low value of the range,
must be less than high
,
must be greater than or equal to 0.value
- the value to wraphigh
- the highest value of the range,
must be greater than low
,
must be greater than or equal to 0.
low
to high
.public int getRowHeight()
mapSpinBoxIndexToField
for more details about
the coordinate systems.
public void setRowHeight(int rowHeight)
SpinBoxManager
calling this method will have no effect. Heights must be controlled
through the spin box manager.
rowHeight
- the height in pixels of each row; must be greater than 0.
IllegalArgumentException
- if rowHeight
is less than or equal to 0.SpinBoxFieldManager
,
SpinBoxField.getSpinBoxFieldManager()
public void setVisibleRows(int visibleRows)
Note that if this field belongs to a SpinBoxManager
calling this method will have no effect. Heights must be controlled
through the spin box manager.
visibleRows
- the number of rows to show,
should be odd,
must be greater than 0.public int getVisibleRows()
protected void drawFocus(Graphics graphics, boolean on)
A field's manager invokes this method after painting the field. The
manager initializes the graphics object passed in for drawing with
field-local coordinates. It is also assumed that the region is already drawn
correctly with the opposing state for the on
parameter.
When overriding this method, fields should use Field.drawHighlightRegion(net.rim.device.api.ui.Graphics, int, boolean, int, int, int, int)
to render focus and select regions instead of hardcoding the logic.
By default this method invokes Field.drawHighlightRegion(net.rim.device.api.ui.Graphics, int, boolean, int, int, int, int)
to render
the focus indicator using the rect obtained from Field.getFocusRect(net.rim.device.api.ui.XYRect)
.
drawFocus
in class Field
graphics
- Graphics context for drawing the focus.on
- True if the focus should be set; otherwise, false.Field.drawFocus(net.rim.device.api.ui.Graphics, boolean)
protected void onUnfocus()
The method will not be invoked if this field does not already have the focus.
By default, this method clears the muddy bit and removes selection. If your custom field requires special handling upon losing the focus, you must override this method. Don't forget to call this method on the parent though, or the muddy bit won't get cleared.
onUnfocus
in class Field
protected void refresh()
public void paint(Graphics graphics)
This is an abstract method; any class that extends Field must implement this method appropriate to its needs.
A field's manager invokes this method when an area of this field has been marked as invalid. All painting should be done in field-local coordinates (for example, 0,0 is the top left corner of the field's pane).
The clipping rectangle is available (in local coordinates) through
Graphics.getClippingRect()
. You can use this rectangle to
determine the minimal amount of drawing required to satisfy the paint
request. Large controls should make use of this for more efficient
painting, particularly during scroll operations.
Preconditions for the paint method
Routines that invoke this method on a field ensure that
this.getFont() == graphics.getFont()
and that the
appropriate clipping rect and transformation stack are set up, so that
this method draws on the appropriate area of this field.
Should you implement a layout manager (for example) of your own, be aware that you must ensure these conditions are met before invoking this method in child Fields.
paint
in class Field
graphics
- Graphics context for drawing in this field.#Field.paint
protected boolean navigationMovement(int dx, int dy, int status, int time)
The source of the navigation event can be determined by checking the
KeypadListener.STATUS_TRACKWHEEL
and KeypadListener.STATUS_FOUR_WAY
bits in the status
parameter; exactly one of them will be set.
navigationMovement
in class Field
dx
- Magnitude of navigational motion: negative for a move left
and postive for a move right.dy
- Magnitude of navigational motion: negative for an upwards
move, and positive for a downwards move.status
- Bitfield of values defined by KeypadListener
.time
- Number of milliseconds since the device was turned on.
net.rim.device.api.ui.Field.navigationMovement
public int getSelectedIndex()
protected boolean updateSelectedIndex()
public void setSelectedIndex(int newIndex)
setSelectedIndex(newIndex, true)
.
newIndex
- the new index to select,
0 <= newIndex <= SpinBoxField.getCount()
animate
- set to true to animate.
IndexOutOfBoundsException
- if 0
<= newIndex
<= SpinBoxField.getCount()
public void setSelectedIndex(int newIndex, boolean animate)
newIndex
- the new index to select,
0 <= newIndex <= SpinBoxField.getCount()
animate
- set to true to animate.
IndexOutOfBoundsException
- if 0
<= newIndex
<= SpinBoxField.getCount()
protected boolean moveSelectedIndex(int delta, boolean programmatic)
moveSelectedIndex(delta, programmatic, true)
.
delta
- the change in index i.e. newIndex - _selectedIndex
programmatic
- set to true if the call was initiated programmatically i.e.
not from the user.protected boolean moveSelectedIndex(int delta, boolean programmatic, boolean animate)
delta
- the change in index i.e. newIndex - _selectedIndex
programmatic
- set to true if the call was initiated programmatically i.e.
not from the user.animate
- set to true to animate.public int getPreferredHeight()
Managers may make use of this value during layout. Override this method to request a certain height for your field.
getPreferredHeight
in class Field
Field.getPreferredHeight()
public void setEditable(boolean editable)
This method lets you change the style of this field by either adding,
or removing, the Field.EDITABLE
style.
setEditable
in class Field
editable
- If True, make this field editable; otherwise, make this
field non-editable.Field.setEditable(boolean)
protected void onFocus(int direction)
The method will not be invoked if this field already has focus. Also,
it will not be invoked if this field returns false from
Field.isFocusable()
.
Managers should find a child field that accepts focus and cascade this method's call to it.
The direction value indicates how the focus came to enter the field:
onFocus
in class Field
direction
- Indicates from which direction the focus enters the
field.Field.onFocus(int)
protected int moveFocus(int amount, int status, int time)
This method is called by the framework only when the field already has focus.
By default, this method returns the amount parameter provided to it; custom fields must override this method to handle focus movement events.
Prior to invoking this method, the framework invokes
Field.focusRemove()
. After invoking this method, the framework invokes
Field.focusAdd(boolean)
.
This method also clears this field's muddy state.
moveFocus
in class Field
amount
- Number of positions to move, positive means down, negative
means up.status
- Modifier key status applied when the trackwheel
roll occurred (combination of applicable modifier keycode values from
KeypadListener
).time
- Number of milliseconds since the device was turned on.
Field.moveFocus(int, int, int)
protected boolean touchEvent(TouchEvent message)
touchEvent
in class Field
message
- TouchEvent
object containing various input parameters
including the event type and touch coordinates.
CLICK
or UNCLICK
that occur outside
of this manager; true for any events that occur within the bounds of this manager;
UP
is always consumed; returns false otherwise.
NullPointerException
- if message
is null.Field.touchEvent(net.rim.device.api.ui.TouchEvent)
protected abstract void drawRow(Graphics graphics, int index, int x, int y, int width, int height)
graphics
- graphics context, never null.index
- which index to draw.x
- The top left x coordinate where drawing could begin.y
- The top left y coordinate where drawing could begin.width
- the width available.height
- the height available.public abstract Object get(int index)
index
- The index to retrieve; must be an in bounds index.
public abstract int getCount()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.