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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by 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





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.