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.

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 used 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.
Image	getImage() Returns this field's image.
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	setImage(Image image) Sets this field's image.
void	setImageSize(int width, int height) Sets size of this field's image.
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

cursorClick, cursorUnclick, 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, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isLeftToRight, 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, 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

setImage

public void setImage(Image image)

Sets this field's image.

Note that this may cause the field to re-layout.

Parameters:

image - New Image for this field, null removes previous Image from field.

Since:

BlackBerry API 7.0.0

getImage

public Image getImage()

Returns this field's image.

Returns:

image Current Image for this field, null if no Image set.

Since:

BlackBerry API 7.0.0

setImageSize

public void setImageSize(int width,
                         int height)

Sets size of this field's image.

Note that setting a new size will cause the field to re-layout.

Parameters:

width - Width of this field's image in pixels.

height - Height of this field's image in pixels.

Since:

BlackBerry API 7.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