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

java.lang.Object
  net.rim.device.api.ui.Field
      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