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:

IComponent, InputMethodListener

public class CheckboxField

extends Field

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.

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

EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH

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 indicator 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.
protected boolean	keyChar(char key, int status, int time) Traps SPACE key generation 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	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.

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

drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getWidth, invalidate, invalidate, isDirty, isEditable, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isVisible, keyControl, keyDown, keyRepeat, keyStatus, keyUp, moveFocus, onFocus, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setPosition, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

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

Field Detail

Constructor Detail

CheckboxField

public CheckboxField()

Creates a new CheckboxField instance.

This builds an unchecked checkbox field with no label.

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.

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.

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 indicator for this field.

Overrides:

drawFocus in class Field

Since:

JDE 3.7.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 width of a checked check box. Only the checkbox portion of this field ever receives the focus.

Overrides:

getFocusRect in class Field

Parameters:

rect - To contain the local coordinates of the focus rect.

Since:

JDE 3.7.0

getLabel

public String getLabel()

Retrieves this field's label string.

Returns:

This field's label string.

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 - Ticks since device reset (this parameter is ignored).

Returns:

True if the space bar was pressed, and this method handled the event; otherwise, false.

Since:

JDE 3.7.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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

moveFocus

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

Handles moving the focus within this field.

This field's maanager invokes this method only when this field already ahs 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 - Ticks since device reset (this parameter ignored).

Returns:

Remaining scroll amount (see method description).

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0