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

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

All Implemented Interfaces:

DrawStyle

public class ButtonField
extends Field
implements DrawStyle

Contains a button control.

When the user presses a ButtonField the FieldChangeListener that was set by invoking setChangeListener() is notified by its fieldChanged() method being invoked. The code below demonstrates how to use this technique to respond to button presses.

     FieldChangeListener listener = new FieldChangeListener() {
         public void fieldChanged(Field field, int context) {
             ButtonField buttonField = (ButtonField) field;
             System.out.println("Button pressed: " + buttonField.getLabel());
         }
     };
     ButtonField buttonField = new ButtonField("Test Button");
     buttonField.setChangeListener(listener);
 

After buttonField is added to a screen, the text "Button pressed: Test Button" will be printed to System.out each time the button is pressed.

The default alignment of a button will be DrawStyle.VCENTER and DrawStyle.HCENTER. The label will be centered vertically and horizontally.

Behaviour
Displays a button.

Field Summary
static int	BARE Deprecated. Used only for non-color devices.
static long	CONSUME_CLICK Indicates to the button consume the click event.
static long	NEVER_DIRTY Indicates to the button not become dirty or muddy on the click event.

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

BASELINE, BOTTOM, ELLIPSIS, HALIGN_MASK, HCENTER, HDEFAULT, HFULL, LEADING, LEFT, RIGHT, TOP, TRAILING, TRUNCATE_BEGINNING, VALIGN_MASK, VCENTER, VDEFAULT, VFULL

Constructor Summary

ButtonField()
Constructs a new ButtonField instance.

ButtonField(String label)
Constructs a new ButtonField instance with provided label.

ButtonField(String label, long style)
Constructs a new ButtonField instance with provided label and style.

ButtonField(long style)
Constructs a new ButtonField instance with provided style.

Method Summary
protected void	drawFocus(Graphics graphics, boolean on) Draws the focus indicator for this field.
AccessibleContext	getAccessibleContext() Returns accessible representation of the field for a screen reader
String	getLabel() Retrieves this field's label.
int	getPreferredHeight() Retrieves this field's preferred height.
int	getPreferredWidth() Retrieves this field's preferred width.
Runnable	getRunnable() Returns the Runnable associated with this button's action.
protected boolean	invokeAction(int action) Invokes an action on this field.
protected boolean	keyChar(char key, int status, int time) Traps ENTER key generation events.
protected boolean	keyDown(int keycode, int time) Handles key down events.
protected boolean	keyUp(int keycode, int time) Handles key up events.
protected void	layout(int width, int height) Lays out this field's contents.
protected void	onUnfocus() Invoked when a field loses the focus.
protected void	paint(Graphics graphics) Redraws this field.
void	setDirty(boolean dirty) Sets the dirty state of the field.
void	setLabel(String label) Sets label string for this field.
void	setMuddy(boolean muddy) Sets the muddy state for this field.
void	setRunnable(Runnable runnable) Sets the Runnable to be invoked by this button's action.
protected boolean	trackwheelClick(int status, int time) Handles trackwheel click events.
protected boolean	trackwheelUnclick(int status, int time) Indicates a trackwheel release 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, getFocusRect, 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, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setEditable, setExtent, setFocus, setFocusListener, setFont, setNonSpellCheckable, setPosition, setVisualState, touchEvent, updateLayout

Methods inherited from class java.lang.Object

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

Field Detail

BARE

public static final int BARE

Deprecated. Used only for non-color devices.

See Also:

Constant Field Values

CONSUME_CLICK

public static final long CONSUME_CLICK

Indicates to the button consume the click event.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

NEVER_DIRTY

public static final long NEVER_DIRTY

Indicates to the button not become dirty or muddy on the click event.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

Constructor Detail

ButtonField

public ButtonField()

Constructs a new ButtonField instance.

ButtonField

public ButtonField(long style)

Constructs a new ButtonField instance with provided style.

Parameters:

style - Field style for the button: can be a combation of any generic field style, ButtonField.BARE, DrawStyle.ELLIPSIS, Field.FOCUSABLE, Field.NON_FOCUSABLE, any of Field's horizontal or vertical alignment styles. The default horizontal alignment will be DrawStyle.HCENTER, and the default vertical alignment will be DrawStyle.VCENTER.

ButtonField

public ButtonField(String label)

Constructs a new ButtonField instance with provided label.

Provided a label string to show, this method builds a button field in the default style.

Parameters:

label - Label string for the button.

ButtonField

public ButtonField(String label,
                   long style)

Constructs a new ButtonField instance with provided label and style.

Provided a label string to show, and a style, this method builds a button field using your style.

Parameters:

label - Label string for the button.

style - Field style for the button: can be a combation of any generic field style, ButtonField.BARE, DrawStyle.ELLIPSIS, Field.FOCUSABLE, Field.NON_FOCUSABLE and any of Field's horizontal or vertical alignment styles. The default horizontal alignment will be DrawStyle.HCENTER, and the default vertical alignment will be DrawStyle.VCENTER.

Method Detail

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus indicator for this field.

This field's manager invokes this method after applyThemeOnStateChangeing this field. The manager initializes the graphics object passed in for drawing with field-local coordinates.

This method inverts the focus rect obtained from Field.getFocusRect(net.rim.device.api.ui.XYRect).

Overrides:

drawFocus in class Field

Parameters:

graphics - Graphics context used for drawing the focus.

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

getLabel

public String getLabel()

Retrieves this field's label.

Returns:

Label string for this field.

getPreferredWidth

public int getPreferredWidth()

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

This field's manager invokes this method to assist in its layout.

Overrides:

getPreferredWidth in class Field

Returns:

Preferred width (in pixels) of this field.

getPreferredHeight

public int getPreferredHeight()

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

This field's manager invokes this method to assist in its layout.

Overrides:

getPreferredHeight in class Field

Returns:

Preferred height (in pixels) of this field.

getRunnable

public Runnable getRunnable()

Returns the Runnable associated with this button's action.

Since:

BlackBerry API 5.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 simulates this button being pressed.

If action is not a recognized action then this method does nothing and returns false, indicating that the action was not 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:

BlackBerry API 4.2.0

keyDown

protected boolean keyDown(int keycode,
                          int time)

Handles key down events.

By default, this method returns false; custom fields that specially handle key down events must override this method.

Overrides:

keyDown in class Field

Parameters:

keycode - Code of key pressed.

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

Returns:

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

Since:

BlackBerry API 4.0.0

keyUp

protected boolean keyUp(int keycode,
                        int time)

Handles key up events.

By default, this method returns false; custom fields that specially handle key up events must override this method.

Overrides:

keyUp in class Field

Parameters:

keycode - Code of key released.

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

Returns:

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

Since:

BlackBerry API 4.0.0

keyChar

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

Traps ENTER key generation events.

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

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 ENTER key was pressed, and this method handled the event; otherwise, false.

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 available space.

Specified by:

layout in class Field

Parameters:

width - Amount of available horizontal space.

height - Amount of available vertical space.

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.

Specified by:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

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.

Overrides:

onUnfocus in class Field

Since:

BlackBerry API 4.0.0

setDirty

public void setDirty(boolean dirty)

Sets the dirty state of the field.

Invoke this method to indicate either that a field's contents have changed (passing true), or that a field's changes have been dealt with and is no longer dirty (passing false).

Overrides:

setDirty in class Field

Parameters:

dirty - Specify true if this field is dirty; otherwise, specify false to set the field to clean.

See Also:

Field.isDirty(), Field.setMuddy(boolean)

Since:

BlackBerry API 4.0.0

setLabel

public void setLabel(String label)

Sets label string for this field.

Parameters:

label - Label string for this field.

setMuddy

public void setMuddy(boolean muddy)

Sets the muddy state for this field.

Overrides:

setMuddy in class Field

Parameters:

muddy - True if this field should be made muddy; flase to un-muddy this field.

See Also:

Field.isMuddy(), Field.setDirty(boolean)

Since:

BlackBerry API 4.0.0

setRunnable

public void setRunnable(Runnable runnable)

Sets the Runnable to be invoked by this button's action.

Parameters:

Runnable - The Runnable to set

Since:

BlackBerry API 5.0.0

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)

Handles trackwheel click events.

The system invokes this method when passing on a trackwheel click event. This method is transparent, and the event is not consumed.

Overrides:

trackwheelClick in class Field

Parameters:

status - State of the modifier keys.

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

Returns:

true if the click was consumed, otherwise false.

trackwheelUnclick

protected boolean trackwheelUnclick(int status,
                                    int time)

Indicates a trackwheel release event.

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

Overrides:

trackwheelUnclick in class Field

Parameters:

status - Bitfield of values defined by Keypad.

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

Returns:

true if the unclick was consumed, otherwise false.

Since:

BlackBerry API 4.0.0

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns accessible representation of the field for a screen reader

Overrides:

getAccessibleContext in class Field

Returns:

AccessibleContext instance

Since:

BlackBerry API 4.6.1