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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.ScrollView
          extended by net.rim.device.api.ui.Manager
              extended by 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:

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
cursorClick, cursorMovement, cursorUnclick, 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, shouldCursorScroll, subpaint, trackwheelClick, trackwheelUnclick
 
Methods inherited from class net.rim.device.api.ui.ScrollView
configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onExposed, 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, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidateAll, isEditable, isEnabled, isFocus, isLeftToRight, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onDisplay, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocus, setFocusListener, setFont, 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.
Throws:
IllegalArgumentException - If message is null.
Since:
BlackBerry API 6.0.0





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