net.rim.device.api.ui.component.progressindicator
Class ProgressBarField

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.component.progressindicator.ProgressBarField

public class ProgressBarField
extends Field

Represents the progress of a task that can be expressed with respect to a set of values. The progress is rendered as a horizontal bar that fills as the value approaches a predefined maximum value. This field takes a minimum value, a maximum value, and an initial value for the progress. The bar is filled as a representation of the percentage of the work accomplished.

The following styles are available to specify how the progress is displayed:

• ProgressBarField.NO_TEXT to not present text to represent the amount of work done
• ProgressBarField.PERCENT to represent the amount of work done as a percentage
• ProgressBarField.CURRENT_WITH_MAX to show the current value and the maximum value

NO_TEXT overrides both of the other styles. PERCENT overrides CURRENT_WITH_MAX. The default is to simply display the current value.

You can control the alignment of the text with the following styles:

• ProgressBarField.PROGRESS_TEXT_HCENTER, which horizontally centers the text (the default behavior)
• ProgressBarField.PROGRESS_TEXT_LEADING, which left aligns the text over the progress bar
• ProgressBarField.PROGRESS_TEXT_TRAILING, which right aligns the text over the progress bar

Since:

BlackBerry API 6.0.0

Field Summary
static int	CURRENT_WITH_MAX Display progress as current / max.
static int	NO_TEXT Do not display progress value with text.
static int	PERCENT Display progress as a percentage.
static int	PROGRESS_TEXT_HCENTER Center the progress text on the field.
static int	PROGRESS_TEXT_LEADING Align the progress text to the left of the field.
static int	PROGRESS_TEXT_TRAILING Align the progress text to the right of the field.

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

ProgressBarField(int min, int max, int initial, long style)
Constructs a new ProgressBarField instance.

Method Summary
void	changeConfiguration(int min, int max, int current) Changes the current configuration of this field.
protected void	drawFocus(Graphics graphics, boolean on) Draws the focus indicator for this field.
protected void	layout(int width, int height) Lays out this field's contents.
protected void	paint(Graphics graphics) Redraws this field.
void	updateValue(int val) Updates the current value of this field.

Methods inherited from class net.rim.device.api.ui.Field

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, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, 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, onDisplay, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROGRESS_TEXT_HCENTER

public static final int PROGRESS_TEXT_HCENTER

Center the progress text on the field. See DrawStyle.HCENTER.

This is the default alignment.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

PROGRESS_TEXT_LEADING

public static final int PROGRESS_TEXT_LEADING

Align the progress text to the left of the field. See DrawStyle.LEFT.

By default, the progress text is centered in the field.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

PROGRESS_TEXT_TRAILING

public static final int PROGRESS_TEXT_TRAILING

Align the progress text to the right of the field. See DrawStyle.RIGHT.

By default, the progress text is centered in the field.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

NO_TEXT

public static final int NO_TEXT

Do not display progress value with text.

By default, the current value is displayed as text.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

PERCENT

public static final int PERCENT

Display progress as a percentage.

By default, the current value is displayed as text.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

CURRENT_WITH_MAX

public static final int CURRENT_WITH_MAX

Display progress as current / max.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

Constructor Detail

ProgressBarField

public ProgressBarField(int min,
                        int max,
                        int initial,
                        long style)

Constructs a new ProgressBarField instance.

Parameters:

min - The minimum value for the progress.

max - The maximum value for the progress.

initial - The initial value for the progress.

style - The style bits to set for this field. You can use inherited styles, as well as styles defined for this field: ProgressBarField.NO_TEXT, ProgressBarField.PERCENT, ProgressBarField.CURRENT_WITH_MAX, ProgressBarField.PROGRESS_TEXT_HCENTER, ProgressBarField.PROGRESS_TEXT_LEADING, and ProgressBarField.PROGRESS_TEXT_TRAILING.

Since:

BlackBerry API 6.0.0

Method Detail

changeConfiguration

public void changeConfiguration(int min,
                                int max,
                                int current)

Changes the current configuration of this field. This does not invalidate this field.

Parameters:

min - The new minimum value for the progress.

max - The new maximum value for the progress.

current - The new current value for the progress.

Since:

BlackBerry API 6.0.0

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus indicator for this field. This field's manager invokes this method after painting the field to invert the border of the focus indicator.

Overrides:

drawFocus in class Field

Parameters:

graphics - Graphics context for drawing the focus.

on - true if the focus should be set, otherwise, false.

Since:

BlackBerry API 6.0.0

layout

protected void layout(int width,
                      int height)

Lays out this field's contents.

Specified by:

layout in class Field

Parameters:

width - Amount of available horizontal space.

height - Amount of available vertical space.

Since:

BlackBerry API 6.0.0

paint

protected void paint(Graphics graphics)

Redraws this field.

Specified by:

paint in class Field

Parameters:

graphics - Graphics context for drawing in this field.

Since:

BlackBerry API 6.0.0

updateValue

public void updateValue(int val)

Updates the current value of this field. This updates both the layout of the bar and the textual representation of the value. This does not invalidate the field. This method does not check bounds.

Parameters:

val - The new value for this field.

Since:

BlackBerry API 6.0.0