net.rim.device.api.ui.component
Class SpinBoxField

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.component.SpinBoxField

Direct Known Subclasses:

TextSpinBoxField

public abstract class SpinBoxField
extends Field

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.

Editability

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).

Wrapping

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()).

Listeners

The SpinBoxField emits events when:

The selected index changes

The selected index changes when the index under the highlighted section changes. The highlighted section is the middle row of the spin box. 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.

The spin box wraps around

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.

The spin box stops

SpinBoxField.SPINBOX_STOPPED will be specified as the context

SpinBoxFieldManager

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.

Key methods

SpinBoxField.get(int)

For retrieving the value of an index

SpinBoxField.setRowHeight(int)

Set the height of each row in the spin box.

SpinBoxField.setVisibleRows(int)

Set the number of rows to show to the user.

SpinBoxField.setSelectedIndex(int newIndex) SpinBoxField.setSelectedIndex(int newIndex, boolean animate)

Set the currently selected index for the spin box.

See Also:

SpinBoxFieldManager, TextSpinBoxField

Since:

BlackBerry API 5.0.0

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.

Fields inherited from class net.rim.device.api.ui.Field

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

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 net.rim.device.api.ui.Field

drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getAccessibleContext, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredWidth, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyControl, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, moveFocus, navigationClick, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setDirty, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SPINBOX_STOPPED

public static final int SPINBOX_STOPPED

Indicates to the field change listener that the spin box stopped spinning after some movement.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

SPINBOX_WRAP_FIRST_TO_LAST_INDEX

public static final 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.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

SPINBOX_WRAP_LAST_TO_FIRST_INDEX

public static final 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.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

NO_WRAP

public static final long NO_WRAP

A style for the spin box that indicates the spin box will not wrap around.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

Constructor Detail

SpinBoxField

public SpinBoxField(long style)

Constructs a SpinBoxField with a style.

Parameters:

style - Styles supported include NO_WRAP and styles specified in sub-classes. SpinBoxFields are always focusable.

Since:

BlackBerry API 5.0.0

SpinBoxField

public SpinBoxField()

Construct the default SpinBoxField with the default row height and number of rows set.

Since:

BlackBerry API 5.0.0

Method Detail

getSpinBoxFieldManager

public SpinBoxFieldManager getSpinBoxFieldManager()

Returns the SpinBoxFieldManager that owns this field.

Returns:

the owning SpinBoxFieldManager or null if this field has no manager or the manager is not a SpinBoxFieldManager

See Also:

SpinBoxFieldManager

Since:

BlackBerry API 5.0.0

layout

protected void layout(int availableWidth,
                      int availableHeight)

Lays out the contents. Given the total available width and height, this method sets the boundaries (extent) of the field. The number of rows shown, the row width, and row height all contribute to the layout. Lays out field contents.

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.

Specified by:

layout in class Field

Parameters:

availableWidth - Amount of available horizontal space.

availableHeight - Amount of available vertical space.

See Also:

Field.layout(int, int), getRowHeight, getRowWidth, getVisibleRows

Since:

BlackBerry API 5.0.0

applyTheme

protected void applyTheme()

Called by the framework to tell each Field to apply theme attributes to itself.

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.

Overrides:

applyTheme in class Field

See Also:

Field.applyTheme()

Since:

BlackBerry API 5.0.0

keyChar

public boolean keyChar(char key,
                       int status,
                       int time)

Handles character generation events.

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.

Overrides:

keyChar in class Field

Parameters:

key - Character generated.

status - Modifier key status. See KeypadListener.

time - Number of milliseconds since the device was turned on.

Returns:

True if this method consumed the event; otherwise, false.

See Also:

KeyListener#keyChar

Since:

BlackBerry API 5.0.0

wrap

protected static int wrap(int low,
                          int value,
                          int high)

Wraps a value around a range. This is different from 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

Parameters:

low - the low value of the range, must be less than high, must be greater than or equal to 0.

value - the value to wrap

high - the highest value of the range, must be greater than low, must be greater than or equal to 0.

Returns:

the value in the range of low to high.

Since:

BlackBerry API 5.0.0

getRowHeight

public int getRowHeight()

Returns the height in pixels of each row on the spin box. See mapSpinBoxIndexToField for more details about the coordinate systems.

Returns:

the height in pixels of each row on the spin box.

Since:

BlackBerry API 5.0.0

setRowHeight

public void setRowHeight(int rowHeight)

Sets the height of each row in the spin box. 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.

Parameters:

rowHeight - the height in pixels of each row; must be greater than 0.

Throws:

IllegalArgumentException - if rowHeight is less than or equal to 0.

See Also:

SpinBoxFieldManager, SpinBoxField.getSpinBoxFieldManager()

Since:

BlackBerry API 5.0.0

setVisibleRows

public void setVisibleRows(int visibleRows)

Sets the number of rows that will be shown to the user. The number should be odd. If it is not odd, then it will be made odd by adding 1 to it. The center row will always be the "selected" object.

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.

Parameters:

visibleRows - the number of rows to show, should be odd, must be greater than 0.

Since:

BlackBerry API 5.0.0

getVisibleRows

public int getVisibleRows()

Returns the number of rows that will be shown to the user.

Returns:

the number of rows that will be shown to the user.

Since:

BlackBerry API 5.0.0

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus indicator for this field.

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).

Overrides:

drawFocus in class Field

Parameters:

graphics - Graphics context for drawing the focus.

on - True if the focus should be set; otherwise, false.

See Also:

Field.drawFocus(net.rim.device.api.ui.Graphics, boolean)

Since:

BlackBerry API 5.0.0

onUnfocus

protected void onUnfocus()

Invoked when a field loses the focus.

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.

Overrides:

onUnfocus in class Field

Since:

BlackBerry API 5.0.0

refresh

protected void refresh()

This method must be called when the contents/choices have changed. The same selected index tries to be maintained between refreshes.

Since:

BlackBerry API 5.0.0

paint

public void paint(Graphics graphics)

Invoked by the framework to redraw a portion of this field.

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.

Specified by:

paint in class Field

Parameters:

graphics - Graphics context for drawing in this field.

See Also:

#Field.paint

Since:

BlackBerry API 5.0.0

navigationMovement

protected boolean navigationMovement(int dx,
                                     int dy,
                                     int status,
                                     int time)

Invoked when a navigational motion occurs.

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.

Overrides:

navigationMovement in class Field

Parameters:

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.

Returns:

False (classes that extend Field must override this method to provide specific handling).

See Also:

net.rim.device.api.ui.Field.navigationMovement

Since:

BlackBerry API 5.0.0

getSelectedIndex

public int getSelectedIndex()

Returns the currently selected index.

Returns:

the currently selected index.

Since:

BlackBerry API 5.0.0

updateSelectedIndex

protected boolean updateSelectedIndex()

Updates the selected index based on the position of the spin box. This method should only be called when the spin box has settled i.e. not changing due to spinning or touching.

Returns:

true if and only if the selected index changed.

Since:

BlackBerry API 5.0.0

setSelectedIndex

public void setSelectedIndex(int newIndex)

Sets the selected index and animates the spin box as necessary. This is the same as calling setSelectedIndex(newIndex, true).

Parameters:

newIndex - the new index to select, 0 <= newIndex <= SpinBoxField.getCount()

animate - set to true to animate.

Throws:

IndexOutOfBoundsException - if 0 <= newIndex <= SpinBoxField.getCount()

Since:

BlackBerry API 5.0.0

setSelectedIndex

public void setSelectedIndex(int newIndex,
                             boolean animate)

Sets the selected index and moves the spin box as necessary.

Parameters:

newIndex - the new index to select, 0 <= newIndex <= SpinBoxField.getCount()

animate - set to true to animate.

Throws:

IndexOutOfBoundsException - if 0 <= newIndex <= SpinBoxField.getCount()

Since:

BlackBerry API 5.0.0

moveSelectedIndex

protected boolean moveSelectedIndex(int delta,
                                    boolean programmatic)

Moves (animated) the selected index. This is the same as calling moveSelectedIndex(delta, programmatic, true).

Parameters:

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.

Since:

BlackBerry API 5.0.0

moveSelectedIndex

protected boolean moveSelectedIndex(int delta,
                                    boolean programmatic,
                                    boolean animate)

Moves the selected index.

Parameters:

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.

Since:

BlackBerry API 5.0.0

getPreferredHeight

public int getPreferredHeight()

Retrieves this field's preferred height. Your implementation of getPreferredHeight() should return the height of your custom field if it has any amount of space available.

Managers may make use of this value during layout. Override this method to request a certain height for your field.

Overrides:

getPreferredHeight in class Field

Returns:

Preferred height for this field in pixels.

See Also:

Field.getPreferredHeight()

Since:

BlackBerry API 5.0.0

setEditable

public void setEditable(boolean editable)

Set the editable state of this field.

This method lets you change the style of this field by either adding, or removing, the Field.EDITABLE style.

Overrides:

setEditable in class Field

Parameters:

editable - If True, make this field editable; otherwise, make this field non-editable.

See Also:

Field.setEditable(boolean)

Since:

BlackBerry API 5.0.0

onFocus

protected void onFocus(int direction)

Invoked when a field receives the focus.

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:

• 1 indicates that the focus came from the previous field.
• -1 indicates that the focus came from the following field.
• 0 indicates that the focus was set directly, (that is, not by rolling the trackwheel)

Overrides:

onFocus in class Field

Parameters:

direction - Indicates from which direction the focus enters the field.

See Also:

Field.onFocus(int)

Since:

BlackBerry API 5.0.0

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)

Handles moving the focus within this field.

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.

Overrides:

moveFocus in class Field

Parameters:

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.

Returns:

Remaining scroll amount not used up, with the same sign.

See Also:

Field.moveFocus(int, int, int)

Since:

BlackBerry API 5.0.0

touchEvent

protected boolean touchEvent(TouchEvent message)

Indicates a touch event.

Overrides:

touchEvent in class Field

Parameters:

message - TouchEvent object containing various input parameters including the event type and touch coordinates.

Returns:

true for any 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.

Throws:

NullPointerException - if message is null.

See Also:

Field.touchEvent(net.rim.device.api.ui.TouchEvent)

Since:

BlackBerry API 5.0.0

drawRow

protected abstract void drawRow(Graphics graphics,
                                int index,
                                int x,
                                int y,
                                int width,
                                int height)

Draw the specified row in the given parameters.

Parameters:

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.

Since:

BlackBerry API 5.0.0

get

public abstract Object get(int index)

Retrieve the object at the given index.

Parameters:

index - The index to retrieve; must be an in bounds index.

Returns:

the object corresponding to the given index.

Since:

BlackBerry API 5.0.0

getCount

public abstract int getCount()

Returns The number of objects that could be displayed in the spin box.

Returns:

The number of objects that could be displayed in the spin box, must be >= 0;

Since:

BlackBerry API 5.0.0