net.rim.device.api.ui.toolbar
Class ToolbarButtonField

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.toolbar.ToolbarButtonField
All Implemented Interfaces:
Runnable
Direct Known Subclasses:
ShowKeyboardToolbarButtonField, ToolbarSpacer

public class ToolbarButtonField
extends Field
implements Runnable

Represents a toolbar button field.

Each item has an ordinal specifying the sort order within the toolbar. The items are sorted left-to-right on the toolbar (with the higher ordinal on the left).

To create toolbar fields in your own application create instances of this class and populate them with a Command instance or extend this class. Your subclasses must implement the ToolbarButtonField.invoke() method which is called by the ToolbarManager.

Since:
BlackBerry API 6.0.0

Field Summary
 
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
 
Constructor Summary
ToolbarButtonField()
          Creates an instance of ToolbarButtonField with an ordinal of 0.
ToolbarButtonField(int ordinal)
          Creates an instance of ToolbarButtonField with a specified priority order.
ToolbarButtonField(int ordinal, long style)
          Creates an instance of ToolbarButtonField, which a specified order and style.
ToolbarButtonField(long style)
          Creates an instance of ToolbarButtonField with a specified style.
ToolbarButtonField(Image image, StringProvider text)
          Creates an instance of ToolbarButtonField with the specified image and text.
ToolbarButtonField(Image image, StringProvider text, int ordinal)
          Creates an instance of ToolbarButtonField with the specified image, text, and ordinal.
ToolbarButtonField(Image image, StringProvider text, int ordinal, long style)
          Creates an instance of ToolbarButtonField with the specified style, image, text, and ordinal.
ToolbarButtonField(StringProvider text)
          Create an instance of ToolbarButtonField with the specified text to use if an image or tooltip is not provided.
ToolbarButtonField(StringProvider text, int ordinal)
          Creates an instance of ToolbarButtonField with the specified text and ordinal.
 
Method Summary
 Command getCommand()
          Retrieves this ToolbarButtonField instance's associated Command
 Image getImage()
          Image used by this ToolbarButtonField.
 int getOrdinal()
          The ordinal defines the sort order for a ToolbarButtonField.
 int getPreferredHeight()
          Retrieves the preferred height of the ToolbarButtonField (equivalent to the preferred height of the ToolbarManager).
 int getPreferredWidth()
          By default this method returns 0.
 String getText()
          Retrieves the text used on a ToolbarButtonField if an image is not available or a tooltip is not provided.
 String getTooltip()
          Retrieves the text used as a tooltip when the user hovers over a ToolbarButtonField.
 void invoke()
          Performs an action when this ToolbarButtonField is clicked on if Command has been set.
 boolean isEnabled()
          Determines if the ToolbarButtonField is enabled.
protected  void layout(int width, int height)
          Always consumes the width and height provided.
protected  void onDisplay()
          If this field was previously obscured, invalidates and enables it.
protected  void onExposed()
          If this field was previously obscured, invalidates and enables it.
protected  void onObscured()
          If this field is obscured by another screen which is capable of accepting input or receiving focus, this method disables out the toolbar.
 void paint(Graphics g)
          Paints the ToolbarButtonField.
 void run()
          Calls the ToolbarButtonField.invoke() method if and only if the ToolbarButtonField is enabled.
 void setCommand(Command command)
          Sets the Command to invoke when a ToolbarButtonField is activated.
 void setCommandContext(Object commandContext)
          Sets command context to use when button is activated.
 void setEnabled(boolean enabled)
          Set whether this ToolbarButtonField is enabled or disabled.
 void setImage(Image image)
          Sets the image that is displayed on the ToolbarButtonField.
 void setText(StringProvider text)
          Sets the text to display on the ToolbarButtonField when an image is unavailable.
 void setTooltip(StringProvider tooltip)
          Sest the text that is displayed in the tooltip when the user hovers over this ToolbarButtonField.
 boolean touchEvent(TouchEvent message)
          Indicates a touch event.
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getAccessibleContext, 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, invokeAction, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onFocus, onMenuDismissed, onMenuDismissed, onUndisplay, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

ToolbarButtonField

public ToolbarButtonField()
Creates an instance of ToolbarButtonField with an ordinal of 0.

Since:
BlackBerry API 6.0.0

ToolbarButtonField

public ToolbarButtonField(int ordinal)
Creates an instance of ToolbarButtonField with a specified priority order.

Parameters:
ordinal - The priority order of this ToolbarButtonField.
Since:
BlackBerry API 6.0.0

ToolbarButtonField

public ToolbarButtonField(long style)
Creates an instance of ToolbarButtonField with a specified style.

Parameters:
style - style for this ToolbarButtonField.
Since:
BlackBerry API 6.0.0

ToolbarButtonField

public ToolbarButtonField(int ordinal,
                          long style)
Creates an instance of ToolbarButtonField, which a specified order and style.

Parameters:
ordinal - The priority order of this ToolbarButtonField.
style - The style for this ToolbarButtonField.
Since:
BlackBerry API 6.0.0

ToolbarButtonField

public ToolbarButtonField(StringProvider text)
Create an instance of ToolbarButtonField with the specified text to use if an image or tooltip is not provided.

Parameters:
text - Text to be displayed when the image is not available or a tooltip is not provided.
Since:
BlackBerry API 6.0.0

ToolbarButtonField

public ToolbarButtonField(StringProvider text,
                          int ordinal)
Creates an instance of ToolbarButtonField with the specified text and ordinal.

Parameters:
text - Text to be displayed when the image is not available or a tooltip is not provided.
ordinal - The priority order of this ToolbarButtonField.
Since:
BlackBerry API 6.0.0

ToolbarButtonField

public ToolbarButtonField(Image image,
                          StringProvider text)
Creates an instance of ToolbarButtonField with the specified image and text.

Parameters:
image - Image to use on the ToolbarButtonField.
text - Text to be displayed when the image is not available or a tooltip is not provided.
Since:
BlackBerry API 6.0.0

ToolbarButtonField

public ToolbarButtonField(Image image,
                          StringProvider text,
                          int ordinal)
Creates an instance of ToolbarButtonField with the specified image, text, and ordinal.

Parameters:
image - Image to use on the ToolbarButtonField.
text - Text to be displayed when the image is not available or a tooltip is not provided.
ordinal - The priority order of this ToolbarButtonField.
Since:
BlackBerry API 6.0.0

ToolbarButtonField

public ToolbarButtonField(Image image,
                          StringProvider text,
                          int ordinal,
                          long style)
Creates an instance of ToolbarButtonField with the specified style, image, text, and ordinal.

Note that a ToolbarButtonField is always Field.NON_FOCUSABLE

Parameters:
image - Image to use on the ToolbarButtonField.
text - Text to be displayed when the image is not available or a tooltip is not provided.
ordinal - The priority order of this ToolbarButtonField.
style - The style for this ToolbarButtonField (supports USE_ALL_WIDTH).
Since:
BlackBerry API 6.0.0


Method Detail

getCommand

public Command getCommand()
Retrieves this ToolbarButtonField instance's associated Command

Returns:
Command The Command associated with this ToolbarButtonField.
Since:
BlackBerry API 6.0.0

getImage

public Image getImage()
Image used by this ToolbarButtonField.

Returns:
The image or null if none available.
Since:
BlackBerry API 6.0.0

getOrdinal

public final int getOrdinal()
The ordinal defines the sort order for a ToolbarButtonField. The toolbar sorts its fields from lowest to highest, left to right.

Returns:
The ordinal number for this ToolbarButtonField.
See Also:
ToolbarManager.add(net.rim.device.api.ui.Field)
Since:
BlackBerry API 6.0.0

getPreferredHeight

public int getPreferredHeight()
Retrieves the preferred height of the ToolbarButtonField (equivalent to the preferred height of the ToolbarManager).

Overrides:
getPreferredHeight in class Field
Returns:
The preferred height of this ToolbarButtonField.
See Also:
ToolbarManager.getPreferredHeight()
Since:
BlackBerry API 6.0.0

getPreferredWidth

public int getPreferredWidth()
By default this method returns 0. Override this method to provide custom layouts.

Overrides:
getPreferredWidth in class Field
Returns:
The preferred width for this manager.
Since:
BlackBerry API 6.0.0

getText

public String getText()
Retrieves the text used on a ToolbarButtonField if an image is not available or a tooltip is not provided.

This will first try to retrieve a localized version of the text if a StringProvider was used. If that does not exist, it returns a plain String, if provided. If that also does not exist, this method returns null.

Returns:
the text used on a ToolbarButtonField if an image is not available or a tooltip is not provided, or null if none exists.
Since:
BlackBerry API 6.0.0

getTooltip

public String getTooltip()
Retrieves the text used as a tooltip when the user hovers over a ToolbarButtonField.

This will first try to retrieve a localized version of the text if a StringProvider was used. If that does not exist, this method returns a plain String, if provided. If that also does not exist, this method returns the text returned by ToolbarButtonField.getText().

Returns:
Text to use as a tooltip for this ToolbarButtonField.
Since:
BlackBerry API 6.0.0

invoke

public void invoke()
Performs an action when this ToolbarButtonField is clicked on if Command has been set. A click is defined as the following sequence of touch events: TouchEvent.DOWN, TouchEvent.CLICK, TouchEvent.UNCLICK and TouchEvent.UP.

Since:
BlackBerry API 6.0.0

isEnabled

public boolean isEnabled()
Determines if the ToolbarButtonField is enabled. A disabled toolbar button has a grayed out image (if any) or text and does not have a tooltip. It cannot be clicked on.

Overrides:
isEnabled in class Field
Returns:
True if the ToolbarButtonField is enabled, false otherwise.
Since:
BlackBerry API 6.0.0

layout

protected void layout(int width,
                      int height)
Always consumes the width and height provided.

Specified by:
layout in class Field
Parameters:
width - available width for layout
height - available height for layout
Since:
BlackBerry API 6.0.0

onDisplay

protected void onDisplay()
If this field was previously obscured, invalidates and enables it.

Overrides:
onDisplay in class Field
Since:
BlackBerry API 6.0.0

onExposed

protected void onExposed()
If this field was previously obscured, invalidates and enables it.

Overrides:
onExposed in class Field
Since:
BlackBerry API 6.0.0

onObscured

protected void onObscured()
If this field is obscured by another screen which is capable of accepting input or receiving focus, this method disables out the toolbar.

Overrides:
onObscured in class Field
Since:
BlackBerry API 6.0.0

paint

public void paint(Graphics g)
Paints the ToolbarButtonField. The ToolbarButtonField will first try to paint an image, if available. If none is available, it will paint the provided text, if any. If neither are available, nothing is painted.

Specified by:
paint in class Field
Parameters:
g - Graphics object
Since:
BlackBerry API 6.0.0

run

public final void run()
Calls the ToolbarButtonField.invoke() method if and only if the ToolbarButtonField is enabled.

Specified by:
run in interface Runnable
See Also:
Thread.run()
Since:
BlackBerry API 6.0.0

setCommand

public void setCommand(Command command)
Sets the Command to invoke when a ToolbarButtonField is activated. Also updates the enabled state of the ToolbarButtonField, depending on whether the command can execute or not.

Parameters:
command - Command to execute when this ToolbarButtonField is clicked.
See Also:
Command.canExecute(java.lang.Object)
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. If commandContext is null then this ButtonField instance will be passed to Command methods.
Since:
BlackBerry API 6.0.0

setEnabled

public void setEnabled(boolean enabled)
Set whether this ToolbarButtonField is enabled or disabled. If a ToolbarButtonField is enabled, the user can hover over the ToolbarButtonField to show a tooltip and click on it. A disabled ToolbarButtonField is displayed, but a user cannot interact with it.

Overrides:
setEnabled in class Field
Parameters:
enabled - If true to enable the ToolbarButtonField, false otherwise.
Since:
BlackBerry API 6.0.0

setImage

public void setImage(Image image)
Sets the image that is displayed on the ToolbarButtonField. This method calls Field.invalidate() after setting the image.

Parameters:
image -
Since:
BlackBerry API 6.0.0

setText

public void setText(StringProvider text)
Sets the text to display on the ToolbarButtonField when an image is unavailable. If no tooltip is set, the text is used as a tooltip.

Parameters:
text - Text that is displayed on the ToolbarButtonField.
Since:
BlackBerry API 6.0.0

setTooltip

public void setTooltip(StringProvider tooltip)
Sest the text that is displayed in the tooltip when the user hovers over this ToolbarButtonField.

Overrides:
setTooltip in class Field
Parameters:
tooltip - Text to display in the tooltip when the user hovers over this ToolbarButtonField.
Since:
BlackBerry API 6.0.0

touchEvent

public boolean touchEvent(TouchEvent message)
Indicates a touch event.

Overrides:
touchEvent in class Field
Parameters:
message - TouchEvent object containing various input parameters including the event type and touch coordinates.
Returns:
True if this method consumed the event; otherwise, false.
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.