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

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.ScrollView
          net.rim.device.api.ui.Manager
              net.rim.device.api.ui.toolbar.ToolbarManager

All Implemented Interfaces:

AdjustmentListener

public class ToolbarManager
extends Manager

Represents a horizontal manager to provide quick access to commonly performed actions. The actions are defined by ToolbarButtonField.

A ToolbarManager can accept two types of fields:

• Instances of ToolbarButtonField, an atomic field that calls an ToolbarButtonField.invoke() method to execute an action.
• Instances of ToolbarSetManager, a group of ToolbarButtonField objects.

Fields in the toolbar are sorted based on their ordinals. Toolbar fields are sorted by their ordinals from low-to-high, left-to-right. Two or more fields can have the same ordinal, in which case the field that is added first is given higher priority. For example:

// initialize toolbar
...
toolbar.add( new MyToolbarButtonField( getImage("Foo"), 2 ) );
toolbar.add( new MyToolbarButtonField( getImage("Bar"), 3 ) );
toolbar.add( new MyToolbarButtonField( getImage("Cat"), 2 ) );
...


The toolbar will sort the buttons as: Foo, Cat, Bar.

This manager implements a valid return value for getPreferredHeight and, during layout, will use the minimum of the height provided and the value returned by getPreferredHeight. This manager also consumes all the width it is provided during layout, and lays out its controlled fields by providing each an equal share of the provided width.

Since:

BlackBerry API 6.0.0

Field Summary

Fields inherited from class net.rim.device.api.ui.Manager

BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_MASK, LEAVE_BLANK_SPACE, LEFTMOST, LEFTWARD, NO_HORIZONTAL_SCROLL, NO_HORIZONTAL_SCROLLBAR, NO_SCROLL_RESET, NO_VERTICAL_SCROLL, NO_VERTICAL_SCROLLBAR, QUANTA_FONT, RIGHTMOST, RIGHTWARD, TOPMOST, UPWARD, VERTICAL_SCROLL, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK

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

ToolbarManager()
Creates a ToolbarManager.

ToolbarManager(long style)
Creates a code>ToolbarManager with the specified style.

ToolbarManager(Field field)
Creates a toolbar with specified field.

Method Summary
void	add(Field field) Adds a field to this manager based on the ordinal of the field.
void	addAll(Field[] fields) Adds mutiple fields to the ToolbarManager by calling add(field) on each object in the specified array.
void	delete(Field field) Deletes the specified field from this Manager.
void	deleteRange(int start, int count) Deletes each field in the given range.
int	getPreferredHeight() Retrieves the preferred height of this ToolbarManager.
int	getPreferredWidth() Retrieves the preferred width of this ToolbarManager.
void	insert(Field field, int index) This method is not supported by ToolbarManager.
void	insertAll(Field[] fields, int index) This method is not supported by ToolbarManager.
static boolean	isToolbarSupported() Determines whether toolbar is supported on this device.
void	replace(Field oldField, Field newField) Replaces an existing field with a new field.
void	setVisible(boolean visible) Sets the visibility of the toolbar.
protected void	sublayout(int width, int height) If the VirtualKeyBoard is visible, the toolbar is not laid out.
protected boolean	touchEvent(TouchEvent message) Indicates a touch event.

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

deleteAll, getAccessibleContext, getField, getFieldAtLocation, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getHorizontalScroll, getLeafFieldWithFocus, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, invalidate, invalidate, invalidateFieldRange, invokeAction, isDataValid, isDirty, isDownArrowShown, isFocusable, isMuddy, isSelecting, isUpArrowShown, isValidLayout, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layout, layoutChild, makeMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, nextFocus, nextFocus, onFocus, onUnfocus, paint, paintChild, setDirty, setFocus, setHorizontalQuantization, setPositionChild, setScrollingInertial, setVerticalQuantization, setVirtualExtent, subpaint, trackwheelClick, trackwheelUnclick

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

configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onDisplay, onUndisplay, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling

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

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getScreen, getStyle, getTop, getVisualState, getWidth, invalidateAll, isEditable, isEnabled, isFocus, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, updateLayout

Methods inherited from class java.lang.Object

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

Constructor Detail

ToolbarManager

public ToolbarManager()

Creates a ToolbarManager.

Since:

BlackBerry API 6.0.0

ToolbarManager

public ToolbarManager(long style)

Creates a code>ToolbarManager with the specified style.

Since:

BlackBerry API 6.0.0

ToolbarManager

public ToolbarManager(Field field)

Creates a toolbar with specified field.

Equivalent to:

 ToolbarManager toolbar = new ToolbarManager();
 toolbar.add( field );
 ...
 

Parameters:

field - A field to add that is an instance of ToolbarButtonField or ToolbarSetManager

Since:

BlackBerry API 6.0.0

Method Detail

add

public void add(Field field)

Adds a field to this manager based on the ordinal of the field.

Overrides:

add in class Manager

Parameters:

field - A field of type ToolbarButtonField or ToolbarSetManager to add that is an instance .

Throws:

IllegalArgumentException - If field is not an instance of ToolbarButtonField or ToolbarSetManager.

Since:

BlackBerry API 6.0.0

addAll

public void addAll(Field[] fields)

Adds mutiple fields to the ToolbarManager by calling add(field) on each object in the specified array.

Overrides:

addAll in class Manager

Parameters:

fields - Array of Field objects to insert.

Throws:

IllegalArgumentException - If fields is not an instance of ToolbarButtonField or ToolbarSetManager.

Since:

BlackBerry API 6.0.0

delete

public void delete(Field field)

Deletes the specified field from this Manager.

Overrides:

delete in class Manager

Parameters:

field - Field to delete from this manager.

Throws:

IllegalArgumentException - If field is not an instance of ToolbarButtonField or ToolbarSetManager.

Since:

BlackBerry API 6.0.0

deleteRange

public void deleteRange(int start,
                        int count)

Deletes each field in the given range.

Overrides:

deleteRange in class Manager

Parameters:

start - Field The index to begin deletion at.

count - The number of fields to delete.

Since:

BlackBerry API 6.0.0

replace

public void replace(Field oldField,
                    Field newField)

Replaces an existing field with a new field.

Overrides:

replace in class Manager

Parameters:

oldField - A Field to be replaced that is an instance of ToolbarButtonField or ToolbarSetManager.

newField - The Field to replace oldField that is an instance of ToolbarButtonField or ToolbarSetManager.

Throws:

IllegalArgumentException - If oldField or newField is not an instance of ToolbarButtonField or ToolbarSetManager

IllegalArgumentException - if oldField ordinal does not match newField ordinal.

See Also:

Manager.delete(Field), Manager.insert(Field, int), Field.getIndex(), Field.getManager(), Field.setFocus()

Since:

BlackBerry API 6.0.0

getPreferredWidth

public int getPreferredWidth()

Retrieves the preferred width of this ToolbarManager.

Overrides:

getPreferredWidth in class Field

Returns:

The preferred width of this ToolbarManager.

Since:

BlackBerry API 6.0.0

getPreferredHeight

public int getPreferredHeight()

Retrieves the preferred height of this ToolbarManager.

Overrides:

getPreferredHeight in class Field

Returns:

The preferred height of this ToolbarManager.

Since:

BlackBerry API 6.0.0

insert

public void insert(Field field,
                   int index)

This method is not supported by ToolbarManager. Please use ToolbarManager.add(net.rim.device.api.ui.Field) to insert fields.

Overrides:

insert in class Manager

Parameters:

field - Field to insert.

index - Index to insert field at.

Throws:

UnsupportedOperationException - If this method is used.

Since:

BlackBerry API 6.0.0

insertAll

public void insertAll(Field[] fields,
                      int index)

This method is not supported by ToolbarManager. Please use ToolbarManager.addAll(net.rim.device.api.ui.Field[]) to insert fields.

Overrides:

insertAll in class Manager

Parameters:

field - Fields to insert.

index - Index at which to begin inserting.

Throws:

UnsupportedOperationException - If this method is used.

Since:

BlackBerry API 6.0.0

isToolbarSupported

public static boolean isToolbarSupported()

Determines whether toolbar is supported on this device.

Returns:

true if toolbar is supported; false otherwise.

Since:

BlackBerry API 6.0.0

setVisible

public void setVisible(boolean visible)

Sets the visibility of the toolbar. If the visibility is modified, the layout is updated to reflect the new visibility.

If the toolbar was set specificially via setToolbar in MainScreen, the toolbar is not shown if the VirtualKeyboard is visible.

Parameters:

visible - true if the toolbar should be displayed; false otherwise.

See Also:

MainScreen

Since:

BlackBerry API 6.0.0

sublayout

protected void sublayout(int width,
                         int height)

If the VirtualKeyBoard is visible, the toolbar is not laid out. Otherwise, the toolbar buttons are laid out from right-to-left.

Typically, layout is done in such a manner that each controlled ToolbarButtonField is provided enough width such that they all will have the same width. This is accomplished by taking the total width available during layout, and dividing it by the number of concrete ToolbarButtonField object's controlled by this Manager (including those added to any ToolbarSetManager added to this Manager).

There are two situations where this is not true. The first is if any controlled Field has the style USE_ALL_WIDTH. In this case, that Field receives all the remaining width during layout.

The second case is if a contained ToolbarButtonField overrides getPreferredWidth to return a non-zero value. In this case, that Field will receive the minimum of the available width and the returned preferred width.

This Manager does not scroll, so it is possible for greedy Field objects to consume all the available width before all Field objects have had a chance to layout. In this case they are simply skipped.

This Manager will consume the minimum of the height and the return value of getPreferredHeight.

Specified by:

sublayout in class Manager

Parameters:

width - Width available for this manager.

height - Height available for this manager.

Since:

BlackBerry API 6.0.0

touchEvent

protected boolean touchEvent(TouchEvent message)

Indicates a touch event.

Overrides:

touchEvent in class Manager

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