SHOW Framework
 

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

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.CheckboxField
All Implemented Interfaces:
AccessibleContext, FieldLabelProvider, IComponent, InputMethodListener

public class CheckboxField
extends Field
implements FieldLabelProvider

Contains a checkbox control.

Behaviour
Displays a checkbox before the text label. In the default font, this box appears either empty, or containing a check mark, depending upon the state of the field.

When this field has focus, the box appears inverted and the text label redrawn with the focus colors.

Pressing the spacebar when a checkbox field has the focus toggles its state.


Field Summary
 
Fields inherited from class net.rim.device.api.ui.Field
ACTION_INVOKE, 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
CheckboxField()
          Creates a new CheckboxField instance.
CheckboxField(String label, boolean checked)
          Constructs a new CheckboxField instance with label and starting state.
CheckboxField(String label, boolean checked, long style)
          Constructs a new CheckboxField instance with label, starting state, and style.
 
Method Summary
  protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus on both icon and the text label for this field.
   boolean getChecked()
          Retrieves this field's state.
   void getFocusRect(XYRect rect)
          Retrieves the focus region for this field.
   String getLabel()
          Retrieves this field's label string.
   int getPreferredHeight()
          Retrieves this field's preferred height.
   int getPreferredWidth()
          Retrieves this field's preferred width.
 Category: Framework protected  boolean invokeAction(int action)
          Invokes an action on this field.
  protected  boolean keyChar(char key, int status, int time)
          Traps SPACE key generation events.
  protected  boolean keyDown(int keycode, int time)
          Handles key down events.
  protected  void layout(int width, int height)
          Lays out this field's contents.
  protected  void makeContextMenu(ContextMenu contextMenu)
          Builds this field's context menu.
  protected  int moveFocus(int amount, int status, int time)
          Handles moving the focus within this field.
  protected  void onFocus(int direction)
          Invoked when a field receives the focus.
  protected  void onUnfocus()
          Invoked when a field loses the focus.
  protected  void paint(Graphics graphics)
          Redraws this field.
   void setChecked(boolean checked)
          Sets the state of this field.
   void setLabel(String label)
          Sets this field's label.
   String toString()
          Returns state as a String, "[Yes]" or "[No]".
 Category: Framework protected  boolean trackwheelClick(int status, int time)
          Indicates a trackwheel click event.
 
Methods inherited from class net.rim.device.api.ui.Field
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, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyControl, keyRepeat, keyStatus, keyUp, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CheckboxField

public CheckboxField()
Creates a new CheckboxField instance.

This builds an unchecked checkbox field with no label.

If full available width is desired, then Field.USE_ALL_WIDTH style must be specified using the appropriate constructor.


CheckboxField

public CheckboxField(String label,
                     boolean checked)
Constructs a new CheckboxField instance with label and starting state.

This builds a checkbox field with the Field.EDITABLE and Field.FOCUSABLE styles.

If full available width is desired, then Field.USE_ALL_WIDTH style must be specified using the appropriate constructor.

Parameters:
label - Label string for this field.
checked - Initial state of this field; true for checked, false for unchecked.

CheckboxField

public CheckboxField(String label,
                     boolean checked,
                     long style)
Constructs a new CheckboxField instance with label, starting state, and style.

This builds a checkbox field with the Field.EDITABLE and Field.FOCUSABLE styles.

If full available width is desired, then Field.USE_ALL_WIDTH style must be specified.

Parameters:
label - Label string for this field.
checked - Initial state of this field; true for checked, false for unchecked.
style - The style for this field.
Since:
JDE 3.7.0
Method Detail

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)
Draws the focus on both icon and the text label for this field.
Overrides:
drawFocus in class Field
Parameters:
graphics - Grpahics context for drawing the focus.
on - True if the focus should be set; otherwise, false.
Since:
JDE 3.6.0

getChecked

public boolean getChecked()
Retrieves this field's state.
Returns:
True if this field is checked; otherwise, false.

getFocusRect

public void getFocusRect(XYRect rect)
Retrieves the focus region for this field.

This method retrieves the focus region as the sum of width of a check box and the width of the text label. Both the checkbox portion and the label portion will receives the focus.

Overrides:
getFocusRect in class Field
Parameters:
rect - To contain the local coordinates of the focus rect.

getLabel

public String getLabel()
Retrieves this field's label string.
Returns:
This field's label string.

getPreferredHeight

public int getPreferredHeight()
Retrieves this field's preferred height. See Field.getPreferredHeight() for more information.

Managers may make use of this value during layout.

Overrides:
getPreferredHeight in class Field
Returns:
Preferred height for the field.
Since:
JDE 4.0.0

getPreferredWidth

public int getPreferredWidth()
Retrieves this field's preferred width. See Field.getPreferredWidth() for more information.

Managers make use of this value during layout.

Overrides:
getPreferredWidth in class Field
Returns:
Preferred width for the field.
Since:
JDE 4.0.0

invokeAction

protected boolean invokeAction(int action)
Invokes an action on this field. The only action that is recognized by this method is Field.ACTION_INVOKE, which toggles this field from being checked and unchecked.

If action is not a recognized action then this method does nothing and returns false, indicating that the action was not consumed.

Note that if this field is not editable (ie. Field.isEditable() returns false) then the action will not be consumed.

Overrides:
invokeAction in class Field
Parameters:
action - the action to be performed on this field.
Returns:
true if the action was consumed; false if the action was not consumed.
Since:
JDE 4.2.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)
Traps SPACE key generation events.

This method handles and consumes a key generation event, if it's the SPACE key that's generated; otherwise, this method does nothing and does not consume the event.

If the key pressed was the space bar, then this method toggles the state of this field (prompting a repaint to show the new state of the checkbox).

Overrides:
keyChar in class Field
Parameters:
key - Character generated by the event.
status - Modifier key status (this parameter is ignored).
time - Number of milliseconds since the device was turned on.
Returns:
True if the space bar was pressed, and this method handled the event; otherwise, false.

keyDown

protected boolean keyDown(int keycode,
                          int time)
Handles key down events.

This method handles and consumes a key generation event, if it's the "action"(5) key (for reduced keyboard device) that's generated; otherwise, this method does nothing and does not consume the event.

Overrides:
keyDown in class Field
Parameters:
keycode - Code of key pressed.
time - Number of milliseconds since the device was turned on.
Returns:
True if the "action" (5) key was pressed, and this method handled the event; otherwise, false.
Since:
JDE 4.0.0

layout

protected void layout(int width,
                      int height)
Lays out this field's contents.

This field's manager invokes this method during the layout process to instruct this field to arrange its contents, given an amount of avilable space.

Overrides:
layout in class Field
Parameters:
width - Amount of available horizontal space.
height - Amount of available vertical space.

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)
Builds this field's context menu. The framework uses Field.getContextMenu() to invoke this method to construct this field's context menu. You shouldn't invoke this method directly. If the UI is not operating in MODE_ADVANCD mode (and this field is Field.EDITABLE), this method builds this field's context menu adding a menu item for changing this field's value.
Overrides:
makeContextMenu in class Field
Parameters:
contextMenu - Context menu to create.

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)
Handles moving the focus within this field.

This field's manager invokes this method only when this field already has the focus. If this field is Field.EDITABLE, then this method handles the case where the user ALT-rolls the trackwheel (trapping these events to toggle the state of the checkbox). Otherwise, this field simply passes the roll amount of the event on.

Overrides:
moveFocus in class Field
Parameters:
amount - Amount rolled. This value is either entirely consumed if the field is Field.EDITABLE, or passed on entirely if the field is not editable.
status - Modifier key state: if not KeypadListener.STATUS_ALT, then this method does nothing and returns the entire roll amount.
time - Number of milliseconds since the device was turned on.
Returns:
Remaining scroll amount (see method description).

onFocus

protected void onFocus(int direction)
Description copied from class: Field
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
Since:
JDE 4.2.1

Following copied from class: Field
Parameters:
direction - Indicates from which direction the focus enters the field.

onUnfocus

protected void onUnfocus()
Description copied from class: Field
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:
JDE 4.2.1

paint

protected void paint(Graphics graphics)
Redraws this field.

This field's manager invokes this method during the repainting process to instruct this field to repaint itself.

Overrides:
paint in class Field
Parameters:
graphics - Graphics context for repainting this field.

setChecked

public void setChecked(boolean checked)
Sets the state of this field.
Parameters:
checked - Pass true to check this field's checkbox; false to clear this field's checkbox.

setLabel

public void setLabel(String label)
Sets this field's label.
Parameters:
label - Label string for this field: always appears just to the right of the checkbox.

toString

public String toString()
Returns state as a String, "[Yes]" or "[No]".
Overrides:
toString in class Object
Since:
JDE 4.2.0

Following copied from class: Object
Returns:
a string representation of the object.

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)
Indicates a trackwheel click event.

The system invokes this method when passing on a trackwheel click event.

The ALT-click combination will enter selection mode, or if in selection mode will copy.

Overrides:
trackwheelClick in class Field
Parameters:
status - Bitfield of values defined by Keypad.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
Since:
JDE 4.0.2
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.



Copyright 1999-2008 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.