net.rim.device.api.ui.container
Class SpinBoxFieldManager

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.ScrollView
          net.rim.device.api.ui.Manager
              net.rim.device.api.ui.container.HorizontalFieldManager
                  net.rim.device.api.ui.container.SpinBoxFieldManager

All Implemented Interfaces:

AdjustmentListener, FocusChangeListener

public class SpinBoxFieldManager
extends HorizontalFieldManager
implements FocusChangeListener

Manages a set of SpinBoxFields.

The spin box manager dictates the height of each row and the number of rows that are shown for each spin box. If a SpinBoxField is owned by a manager then SpinBoxField.setVisibleRows and SpinBoxField.setRowHeight will have no effect. Note that row heights are fixed. Each row must have the same height.

To add spin boxes to the manager, use the SpinBoxFieldManager.add(net.rim.device.api.ui.Field) or SpinBoxFieldManager.insert(net.rim.device.api.ui.Field, int) methods just like you would with any field manager. You may add non-SpinBoxField fields to the manager, but it is not recommended. The spin boxes will be arranged horizontally. Since the row heights are equal as well as the number of rows shown, each spin box should line up accordingly.

Spin Boxes must have Field.isEditable() be true in order to edit them. The editablity can be toggled by clicking anywhere on the manager or spin box.

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. Use SpinBoxFieldManager.setClickToLock(boolean) to specify that when a user clicks on the spin box or its manager, it will be locked/unlocked for editing.

Sample Usage

      // an array of choices for the months.
      final String[] MONTHS = { "January", "February", "March", "April", "May", "June",
          "July", "August", "September", "October", "November", "December"};

      // an array of choices for years
      final String[] YEARS = { "2001", "2002", "2003", "2004", "2005", "2006", "2007",
          "2008", "2009", "2010", "2011", "2012", "2013", "2014"};

      // use a text spin box to display these choices
      SpinBoxField monthSpinBox = new TextSpinBoxField(MONTHS);
      SpinBoxField _yearsSpinBox = new TextSpinBoxField(YEARS);

      // create a manager for these spin boxes
      SpinBoxFieldManager spinBoxManager = new SpinBoxFieldManager();

      // add the spin boxes
      spinBoxManager.add(monthSpinBox);
      spinBoxManager.add(yearsSpinBox);

      // adjust properties
      spinBoxManager.setVisibleRows(5);
      spinBoxManager.setRowHeight(40);

      // ...
      // add the spin box manager to a screen or other manager.
      // To retrieve selections, use the spin box field references directly
      // or use manager.getField(index)
      // ...
 

See Also:

SpinBoxField

Since:

BlackBerry API 5.0.0

Field Summary

Fields inherited from class net.rim.device.api.ui.container.HorizontalFieldManager

LOCALE_AWARE_LAYOUT

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

BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_MASK, LEAVE_BLANK_SPACE, LEFTMOST, LEFTWARD, NO_HORIZONTAL_SCROLL, NO_HORIZONTAL_SCROLLBAR, NO_SCROLL_RESET, NO_VERTICAL_SCROLL, NO_VERTICAL_SCROLLBAR, QUANTA_FONT, RIGHTMOST, RIGHTWARD, TOPMOST, UPWARD, VERTICAL_SCROLL, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK

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

Fields inherited from interface net.rim.device.api.ui.FocusChangeListener

FOCUS_CHANGED, FOCUS_GAINED, FOCUS_LOST

Constructor Summary

SpinBoxFieldManager()
Default constructor with no style specified.

SpinBoxFieldManager(long style)
Construct an instance while specifying a style.

Method Summary
void	add(Field field) Adds a field to this manager.
void	focusChanged(Field field, int eventType) Called by a field when focus enters, leaves or changes. Handles redrawing the background of the spinbox when the focus changes.
int	getRowHeight() Returns the height in pixels of a single row of the spin box.
int	getVisibleRows() Returns the number of rows that each spin box shows.
void	insert(Field field, int index) Inserts a field into this manager.
protected boolean	invokeAction(int action) Invokes an action on the field in this manager that currently has the focus.
boolean	isClickToLock() Returns true if and only if the user can click the spin box to lock/unlock it for editing.
void	setClickToLock(boolean clickToLock) Sets whether or not the user can click on the spinbox to lock/unlock it for editing.
void	setEditable(boolean editable) Set the editable state of this field.
void	setRowHeight(int rowHeight) Sets the row height for all rows in the spin box.
void	setVisibleRows(int numRows) Sets the number of rows that will be displayed for each spin box.
protected void	sublayout(int maxWidth, int maxHeight) Lays out this manager's controlled fields.

Methods inherited from class net.rim.device.api.ui.container.HorizontalFieldManager

getFieldAtLocation, getPreferredHeight, getPreferredWidth, nextFocus, subpaint

Methods inherited from class net.rim.device.api.ui.Manager

addAll, delete, deleteAll, deleteRange, getAccessibleContext, getField, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getHorizontalScroll, getLeafFieldWithFocus, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, insertAll, invalidate, invalidate, invalidateFieldRange, isDataValid, isDirty, isDownArrowShown, isFocusable, isMuddy, isSelecting, isUpArrowShown, isValidLayout, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layout, layoutChild, makeMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, nextFocus, onFocus, onUnfocus, paint, paintChild, replace, setDirty, setFocus, setHorizontalQuantization, setPositionChild, setScrollingInertial, setVerticalQuantization, setVirtualExtent, touchEvent, trackwheelClick, trackwheelUnclick

Methods inherited from class net.rim.device.api.ui.ScrollView

configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onDisplay, onUndisplay, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling

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

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getScreen, getStyle, getTop, getVisualState, getWidth, invalidateAll, isEditable, isEnabled, isFocus, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEnabled, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, updateLayout

Methods inherited from class java.lang.Object

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

Constructor Detail

SpinBoxFieldManager

public SpinBoxFieldManager()

Default constructor with no style specified.

Since:

BlackBerry API 5.0.0

SpinBoxFieldManager

public SpinBoxFieldManager(long style)

Construct an instance while specifying a style. TODO: what styles are and are not suppoted.

Parameters:

style - style bitmask

Since:

BlackBerry API 5.0.0

Method Detail

setRowHeight

public void setRowHeight(int rowHeight)

Sets the row height for all rows in the spin box. This method will change the row height property in each of the spin boxes that this manager owns.

Parameters:

rowHeight - the height of the row in pixels, must be >e 0.

Since:

BlackBerry API 5.0.0

getRowHeight

public int getRowHeight()

Returns the height in pixels of a single row of the spin box.

Returns:

the height in pixels of a single row of the spin box.

Since:

BlackBerry API 5.0.0

setVisibleRows

public void setVisibleRows(int numRows)

Sets the number of rows that will be displayed for each spin box. The number should be odd. If it is not odd, then it will be made odd by adding 1 to it. This method will also set the number of rows to show for each spin box that this manager owns.

Parameters:

numRows - 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 each spin box shows.

Returns:

the number of rows to show.

Since:

BlackBerry API 5.0.0

setClickToLock

public void setClickToLock(boolean clickToLock)

Sets whether or not the user can click on the spinbox to lock/unlock it for editing. This is useful if there are other fields the user needs to navigate to.

Parameters:

clickToLock - set to true if the user can click the spin box to lock/unlock it for editing.

Since:

BlackBerry API 5.0.0

isClickToLock

public boolean isClickToLock()

Returns true if and only if the user can click the spin box to lock/unlock it for editing.

Returns:

true if and only if the user can click the spin box to lock/unlock it for editing.

Since:

BlackBerry API 5.0.0

add

public void add(Field field)

Adds a field to this manager.

Invoke this method to add a new field at the end of this manager's list of controlled fields.

Notice that only one manager is allowed to control any single field, and a field can never manage itself.

Overrides:

add in class Manager

Parameters:

field - Field to add.

See Also:

Manager#add

Since:

BlackBerry API 5.0.0

insert

public void insert(Field field,
                   int index)

Inserts a field into this manager.

Invoke this method to insert a new field into this manager's list of controlled fields. You provide the field to add, and the index position you wish the new field to occupy.

Overrides:

insert in class Manager

Parameters:

field - Field to insert.

index - Index at which to insert.

See Also:

Manager#insert

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:

Manager#setEditable

Since:

BlackBerry API 5.0.0

sublayout

protected void sublayout(int maxWidth,
                         int maxHeight)

Lays out this manager's controlled fields.

The framework invokes this method to direct this manager to lay out its controlled fields.

Overrides:

sublayout in class HorizontalFieldManager

Parameters:

maxWidth - Horizontal space available for this manager.

maxHeight - Vertical space available for this manager.

See Also:

Manager#sublayout

Since:

BlackBerry API 5.0.0

invokeAction

protected boolean invokeAction(int action)

Invokes an action on the field in this manager that currently has the focus. If no field has the focus then this method does nothing and returns that the action was not consumed.

Overrides:

invokeAction in class Manager

Parameters:

action - the action to be performed on the field in this manager that currently has the focus.

Returns:

true if the action was consumed by the field on which the action was performed; false if the action was not consumed or no field has the focus in this manager.

See Also:

Manager#invokeAction

Since:

BlackBerry API 5.0.0

focusChanged

public void focusChanged(Field field,
                         int eventType)

Called by a field when focus enters, leaves or changes.

Handles redrawing the background of the spinbox when the focus changes.

Specified by:

focusChanged in interface FocusChangeListener

Parameters:

field - The field that caused the focus event.

eventType - Indicates the type of focus event.

See Also:

FocusChangeListener

Since:

BlackBerry API 5.0.0