SHOW Framework
 

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:
AccessibleContext, DrawStyle, FieldLabelProvider, IComponent, InputMethodListener

public class ButtonField
extends Field
implements DrawStyle, FieldLabelProvider

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.

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, 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, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH
 
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(long style)
          Constructs a new ButtonField instance with provided style.
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.
 
Method Summary
  protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
   String getLabel()
          Retrieves this field's label.
   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 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.
 Category: Framework 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.
  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, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, 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, setChangeListener, setCookie, setEditable, setExtent, setFocus, setFocusListener, setFont, setNonSpellCheckable, setPosition, 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.


CONSUME_CLICK

public static final long CONSUME_CLICK
Indicates to the button consume the click event.
Since:
JDE 4.0.0

NEVER_DIRTY

public static final long NEVER_DIRTY
Indicates to the button not become dirty or muddy on the click event.
Since:
JDE 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, BARE, DrawStyle.ELLIPSIS, Field.FOCUSABLE and Field.NON_FOCUSABLE.

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, BARE, DrawStyle.ELLIPSIS, Field.FOCUSABLE and Field.NON_FOCUSABLE.
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.

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.

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.

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

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

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

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:
JDE 4.0.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.

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.

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.
Since:
JDE 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.
Since:
JDE 4.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:
False (event not consumed).

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:
False (classes that extend Field must override this method to provide specific handling).
Since:
JDE 4.0.0



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.