|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
net.rim.device.api.ui.component.ButtonField
public class ButtonField
Contains a button control.
The default alignment of a button is DrawStyle.VCENTER
and DrawStyle.HCENTER
. The label is centered vertically
and horizontally.
When the user clicks a ButtonField
, the FieldChangeListener
(that
was set by invoking setChangeListener()
) is notified by invoking its
fieldChanged()
method.
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);
Since BlackBerry API 6.0, you can use the Command Framework API
to specify the
functionality of a button. The process is as follows:
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.
setCommandContext()
. The context might be required
in order to determine what the command handler should do.
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.
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 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 java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int BARE
public static final long CONSUME_CLICK
public static final long NEVER_DIRTY
Constructor Detail |
---|
public ButtonField()
public ButtonField(long style)
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
public ButtonField(String label)
Provided a label string to show, this method builds a button field in the default style.
label
- Label string for the button.public ButtonField(String label, long style)
Provided a label string to show, and a style, this method builds a button field using your style.
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 |
---|
protected void drawFocus(Graphics graphics, boolean on)
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)
.
drawFocus
in class Field
graphics
- Graphics context used for drawing the focus.on
- True if the focus should be set; otherwise, false.public Command getCommand()
public Object getCommandContext()
public String getLabel()
public int getPreferredWidth()
Field.getPreferredWidth()
for more information.
This field's manager invokes this method to assist in its layout.
getPreferredWidth
in class Field
public int getPreferredHeight()
Field.getPreferredHeight()
for more information.
This field's manager invokes this method to assist in its layout.
getPreferredHeight
in class Field
public Runnable getRunnable()
protected boolean invokeAction(int action)
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.
invokeAction
in class Field
action
- the action to be performed on this field.
true
if the action was consumed; false
if the action was not consumed.protected boolean keyDown(int keycode, int time)
By default, this method returns false; custom fields that specially handle key down events must override this method.
keyDown
in class Field
keycode
- Code of key pressed.time
- Number of milliseconds since the device was turned on.
protected boolean keyUp(int keycode, int time)
By default, this method returns false; custom fields that specially handle key up events must override this method.
keyUp
in class Field
keycode
- Code of key released.time
- Number of milliseconds since the device was turned on.
protected boolean keyChar(char key, int status, int time)
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.
keyChar
in class Field
key
- Character generated by the event.status
- Modifier key status (this parameter is ignored).time
- Number of milliseconds since the device was turned on.
protected void layout(int width, int height)
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.
layout
in class Field
width
- Amount of available horizontal space.height
- Amount of available vertical space.protected void paint(Graphics graphics)
This field's manager invokes this method during the repainting process to instruct this field to repaint itself.
paint
in class Field
graphics
- Graphics context for repainting this field.protected void onUnfocus()
The method will not be invoked if this field does not already have the focus.
onUnfocus
in class Field
public void setCommand(Command command)
Command Framework API
.
The command is only used if the instance does not contain a Runnable.
command
- Command
to use for the button.public void setCommandContext(Object commandContext)
commandContext
- Command
context to use when the Command instance is executed.public void setDirty(boolean dirty)
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).
setDirty
in class Field
dirty
- Specify true if this field is dirty; otherwise, specify
false to set the field to clean.Field.isDirty()
,
Field.setMuddy(boolean)
public void setImage(Image image)
Note that this may cause the field to re-layout.
image
- New Image
for this field, null removes previous Image from field.public Image getImage()
Image
for this field, null if no Image set.public void setImageSize(int width, int height)
Note that setting a new size will cause the field to re-layout.
width
- Width of this field's image in pixels.height
- Height of this field's image in pixels.public void setLabel(String label)
label
- Label string for this field.public void setLabelStringProvider(StringProvider label)
label
- Label StringProvider for this field.public void setMuddy(boolean muddy)
setMuddy
in class Field
muddy
- True if this field should be made muddy; false to un-muddy
this field.Field.isMuddy()
,
Field.setDirty(boolean)
public void setRunnable(Runnable runnable)
Runnable
- The Runnable to setprotected boolean touchEvent(TouchEvent message)
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.
touchEvent
in class Field
message
- TouchEvent
object containing various input parameters
including the event type and touch coordinates.
IllegalArgumentException
- If message
is null.Field.touchEvent(net.rim.device.api.ui.TouchEvent)
protected boolean trackwheelClick(int status, int time)
The system invokes this method when passing on a trackwheel click event. This method is transparent, and the event is not consumed.
trackwheelClick
in class Field
status
- State of the modifier keys.time
- Number of milliseconds since the device was turned on.
protected boolean trackwheelUnclick(int status, int time)
The system invokes this method when passing on a trackwheel release event.
trackwheelUnclick
in class Field
status
- Bitfield of values defined by Keypad
.time
- Number of milliseconds since the device was turned on.
public AccessibleContext getAccessibleContext()
getAccessibleContext
in class Field
public void setLabelLeft()
public void setLabelRight()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal