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.

Layout

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

Behaviour

Displays a button.

Using a change listener to respond to button clicks

When the user clicks a ButtonField, the FieldChangeListener (that was set by invoking setChangeListener()) is notified by invoking its fieldChanged() method.

Code sample

In the following code sample, a field change listener is ued to respond to button clicks. After buttonField is added to a screen and the button is clicked, text is printed to System.out.

     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);
 

Specifying the functionality of a button by using commands

Since BlackBerry API 6.0, you can use the Command Framework API to specify the functionality of a button. The process is as follows:

  1. Define the functionality to be performed by using a CommandHandler. The command handler might be limited to your application, or might be registered so it is available to any application on the BlackBerry device.
  2. In your screen, optionally specify the context of the button by invoking setCommandContext(). The context might be required in order to determine what the command handler should do.
  3. Associate the button with a Command by invoking setCommand. The Command defines what to execute when the button is clicked by acting as a proxy to an instance of a class that extends a command handler. The command is only executed if there is no implementation of Runnable.

Code sample

In the following code sample, when the user clicks the button, a dialog appears indicating the context of the click. In this code sample, the command handler is defined for only this application. However, you could create a command handler so that it could be registered and available to any application. For more information, see Command Framework API.

 class MyUiScreen extends MainScreen
 {
     public MyUiScreen()
     {
         // Create ButtonField with command context
         ButtonField buttonField = new ButtonField("Test Button", ButtonField.CONSUME_CLICK | Field.FIELD_HCENTER);
         buttonField.setCommandContext(new Object()
         {
             public String toString()
             {
                 return "Button Context";
             }
         });
         // Set command to be invoked by the ButtonField
         buttonField.setCommand(new Command(new DialogCommandHandler()));

         add(buttonField);
     }

 // A CommandHandler implementation which will be executed unconditionally
 class DialogCommandHandler extends CommandHandler
 {
     public void execute(ReadOnlyCommandMetadata metadata, Object context)
     {
         Dialog.alert("Executing command for " + context.toString());
     }
 


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.
 Command getCommand()
          Retrieves this field's command.
 Object getCommandContext()
          Retrieves this field's command context.
 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 setCommand(Command command)
          Sets the command to execute when button is activated.
 void setCommandContext(Object commandContext)
          Sets command context to use when button is activated.
 void setDirty(boolean dirty)
          Sets the dirty state of the field.
 void setLabel(String label)
          Sets label string for this field.
 void setLabelLeft()
          If button has a label and an icon this method forces label to be on the left.
 void setLabelRight()
          If button has a label and an icon this method forces label to be on the right.
 void setLabelStringProvider(StringProvider label)
          Sets label StringProvider 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 touchEvent(TouchEvent message)
          Traps touch input events.
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, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, 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, setCommandItemProvider, setCookie, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, 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 - can be a combination of any generic field style: BARE ELLIPSIS FOCUSABLE 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. Note: USE_ALL_WIDTH style is not supported in ButtonField directly, but the same effect can be achieved by overriding getPreferredWidth to return a sufficient large width Integer.MAX_VALUE

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 - can be a combination of any generic field style: BARE ELLIPSIS FOCUSABLE 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. Note: USE_ALL_WIDTH style is not supported in ButtonField directly, but the same effect can be achieved by overriding getPreferredWidth to return a sufficient large width Integer.MAX_VALUE


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.

getCommand

public Command getCommand()
Retrieves this field's command.

Returns:
Command for field.
Since:
BlackBerry API 6.0.0

getCommandContext

public Object getCommandContext()
Retrieves this field's command context.

Returns:
Command for field.
Since:
BlackBerry API 6.0.0

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

setCommand

public void setCommand(Command command)
Sets the command to execute when button is activated. For more information, see Command Framework API. The command is only used if the instance does not contain a Runnable.

Parameters:
command - Command to use for the button.
Since:
BlackBerry API 6.0.0

setCommandContext

public void setCommandContext(Object commandContext)
Sets command context to use when button is activated.

Parameters:
commandContext - Command context to use when the Command instance is executed.
Since:
BlackBerry API 6.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.

setLabelStringProvider

public void setLabelStringProvider(StringProvider label)
Sets label StringProvider for this field.

Parameters:
label - Label StringProvider for this field.
Since:
BlackBerry API 6.0.0

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; false 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

touchEvent

protected boolean touchEvent(TouchEvent message)
Traps touch input events.

This method handles touch input events. DOWN events cause this ButtonField to enter a focused state, which is in fact handled at the Manager level. CLICK events cause this ButtonField to enter an active (pressed) state. UNCLICK events invoke invokeAction and trackwheelUnclick methods in sequence. The remaining touch input events are consumed and/or ignored.

Overrides:
touchEvent in class Field
Parameters:
message - TouchEvent object containing various input parameters including the event type and touch coordinates.
Returns:
True if the event was consumed; otherwise, false.
Throws:
IllegalArgumentException - If message is null.
See Also:
Field.touchEvent(net.rim.device.api.ui.TouchEvent)
Since:
BlackBerry API 6.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

setLabelLeft

public void setLabelLeft()
If button has a label and an icon this method forces label to be on the left. By default the label is on the right.

Since:
BlackBerry API 6.0.0

setLabelRight

public void setLabelRight()
If button has a label and an icon this method forces label to be on the right. By default the label is on the right.

Since:
BlackBerry API 6.0.0





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.