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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.Manager
          extended by net.rim.device.api.ui.container.HorizontalFieldManager
              extended by net.rim.device.api.ui.container.SpinBoxFieldManager
All Implemented Interfaces:
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.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, 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, getVisibleHeight, getVisibleWidth, 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, nextFocus, onFocus, onUndisplay, onUnfocus, paint, paintChild, replace, setDirty, setFocus, setHorizontalQuantization, setHorizontalScroll, setHorizontalScroll, setPositionChild, setScrollListener, setScrollingInertial, setVerticalQuantization, setVerticalScroll, setVirtualExtent, touchEvent, trackwheelClick, trackwheelUnclick
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getVisualState, getWidth, invalidateAll, isEditable, isFocus, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, 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





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.