net.rim.device.api.ui.component
Class StandardTitleBar

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.container.VerticalFieldManager
                  extended by net.rim.device.api.ui.component.TitleBar
                      extended by net.rim.device.api.ui.component.StandardTitleBar
All Implemented Interfaces:
AdjustmentListener

public class StandardTitleBar
extends TitleBar

Provides a standard title bar component with a standard set of optional title bar components and indicators.

The StandardTitleBar component implements the standard set of title bar components for BlackBerry applications. The components that are definable by applications are (from left to right on the title bar):

Each of the components listed above, save the battery icon, has an add and remove method that applications can use to customize the components used by their StandardTitleBar. The battery icon is always part of the title bar. Applications can however specify the battery icon's visibility settings using the StandardTitleBar.setPropertyValue(int, int) method.

The setPropertyValue() method can also be used to define the visibility properties of the signal indicator's Wi-Fi and cellular components.

You cannot change the order of components in the standard title bar. The positions are fixed to the order listed above. The order in which you call the add functions has no bearing on the position or order of these components.

Also, all title bar components that the application can customize are singular. Hence, multiple calls to each component's add method will not result in multiple instances of that component. Instead, add methods that take parameters will overwrite the previous definition of the component based on the values of the parameters. Methods that have no parameters will have no additional effect on the title bar's state.

Since:
BlackBerry API 6.0.0

Field Summary
static int BATTERY_VISIBLE_ALWAYS
          A property value specific to StandardTitleBar.PROPERTY_BATTERY_VISIBILITY, which specifies that the battery indicator should always be visible.
static int BATTERY_VISIBLE_LOW_OR_CHARGING
          A property value specific to StandardTitleBar.PROPERTY_BATTERY_VISIBILITY, which specifies that the battery indicator should only be visible when the battery is low or charging.
static int PROPERTY_BATTERY_VISIBILITY
          Property key for battery indicator visibility.
static int PROPERTY_CELLULAR_VISIBILITY
          Property key for the signal indicator's cellular component's visibility.
static int PROPERTY_VALUE_DEFAULT
          A generic property value that specifies that the property should be set to its default value.
static int PROPERTY_VALUE_OFF
          A generic property value that specifies that the property should be off.
static int PROPERTY_VALUE_ON
          A generic property value that specifies that the property should be on.
static int PROPERTY_WIFI_VISIBILITY
          Property key for the signal indicator's Wi-Fi component's visibility.
 
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
StandardTitleBar()
          Allocates a blank title bar.
 
Method Summary
 StandardTitleBar addClock()
          Adds the clock component to the StandardTitleBar object.
 StandardTitleBar addIcon(String iconFile)
          Adds an application icon, specified by file name, to the StandardTitleBar object.
 StandardTitleBar addIcon(Bitmap icon)
          Adds an application icon by passing in a bitmap to the StandardTitleBar object.
 StandardTitleBar addNotifications()
          Adds a notifications component to the StandardTitleBar object.
 StandardTitleBar addSignalIndicator()
          Adds the signal indicator component to the StandardTitleBar object.
 StandardTitleBar addTitle(String title)
          Adds a new title String to the StandardTitleBar object.
 int getPropertyValue(int propertyKey)
          Retrieves the value set for the specified property.
 StandardTitleBar removeClock()
          Removes the clock component from the StandardTitleBar object.
 StandardTitleBar removeIcon()
          Removes the application icon from the StandardTitleBar object.
 StandardTitleBar removeNotifications()
          Removes the notifications component from the StandardTitleBar object.
 StandardTitleBar removeSignalIndicator()
          Removes the signal indicator component from the StandardTitleBar object.
 StandardTitleBar removeTitle()
          Removes the title from the StandardTitleBar object.
 void setPropertyValue(int propertyKey, int propertyValue)
          Sets the property that is specified to the value that is provided.
 
Methods inherited from class net.rim.device.api.ui.container.VerticalFieldManager
getFieldAtLocation, getPreferredHeight, getPreferredWidth, nextFocus, sublayout, subpaint
 
Methods inherited from class net.rim.device.api.ui.Manager
add, addAll, cursorClick, cursorUnclick, delete, deleteAll, deleteRange, getAccessibleContext, getField, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getHorizontalScroll, getLeafFieldWithFocus, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, insert, insertAll, 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, onFocus, onUnfocus, paint, paintChild, replace, setDirty, setFocus, setHorizontalQuantization, setPositionChild, setScrollingInertial, setVerticalQuantization, setVirtualExtent, touchEvent, trackwheelClick, trackwheelUnclick
 
Methods inherited from class net.rim.device.api.ui.ScrollView
configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onDisplay, onExposed, 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, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidateAll, isEditable, isEnabled, isFocus, isLeftToRight, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onMenuDismissed, onMenuDismissed, onObscured, 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
 



Field Detail

PROPERTY_BATTERY_VISIBILITY

public static final int PROPERTY_BATTERY_VISIBILITY
Property key for battery indicator visibility.

Acceptable property values:

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PROPERTY_WIFI_VISIBILITY

public static final int PROPERTY_WIFI_VISIBILITY
Property key for the signal indicator's Wi-Fi component's visibility.

Acceptable property values:


PROPERTY_CELLULAR_VISIBILITY

public static final int PROPERTY_CELLULAR_VISIBILITY
Property key for the signal indicator's cellular component's visibility.

Acceptable property values:

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PROPERTY_VALUE_DEFAULT

public static final int PROPERTY_VALUE_DEFAULT
A generic property value that specifies that the property should be set to its default value.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PROPERTY_VALUE_ON

public static final int PROPERTY_VALUE_ON
A generic property value that specifies that the property should be on.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PROPERTY_VALUE_OFF

public static final int PROPERTY_VALUE_OFF
A generic property value that specifies that the property should be off.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

BATTERY_VISIBLE_ALWAYS

public static final int BATTERY_VISIBLE_ALWAYS
A property value specific to StandardTitleBar.PROPERTY_BATTERY_VISIBILITY, which specifies that the battery indicator should always be visible.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

BATTERY_VISIBLE_LOW_OR_CHARGING

public static final int BATTERY_VISIBLE_LOW_OR_CHARGING
A property value specific to StandardTitleBar.PROPERTY_BATTERY_VISIBILITY, which specifies that the battery indicator should only be visible when the battery is low or charging.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Constructor Detail

StandardTitleBar

public StandardTitleBar()
Allocates a blank title bar.

Every title bar has a battery icon and an active phone call notification that are displayed when appropriate. All other components must be explicitly added.

Since:
BlackBerry API 6.0.0


Method Detail

addIcon

public StandardTitleBar addIcon(String iconFile)
Adds an application icon, specified by file name, to the StandardTitleBar object.

The icon image can be of any size and aspect ratio, though it is recommended that the aspect ratio be 1:1. If necessary, scaling is performed on the icon to comply with the title bar's maximum bounds for the icon.

The image file types supported are limited to what is supported by EncodedImage.

Since a StandardTitleBar object can have only one application icon, multiple calls to this method will result in the latest call overwriting the previous definition of the application icon.

Parameters:
iconFile - Filename of the application icon.
Returns:
The StandardTitleBar object the application icon was added to.
See Also:
EncodedImage
Since:
BlackBerry API 6.0.0

addIcon

public StandardTitleBar addIcon(Bitmap icon)
Adds an application icon by passing in a bitmap to the StandardTitleBar object.

The icon can be of any size and aspect ratio. If the icon's height is greater than the maximum height of a title bar icon, then the icon is scaled down based on the maximum height. The aspect ratio of the icon is maintained.

If you have an EncodedImage that you would like to use as the icon, you can use EncodedImage.getBitmap() to convert the image to a Bitmap.

Since a StandardTitleBar object can have only one application icon, multiple calls to this method will result in the latest call overwriting the previous definition of the application icon.

Parameters:
icon - Bitmap object for the application icon.
Returns:
The StandardTitleBar object the application icon was added to.
See Also:
EncodedImage
Since:
BlackBerry API 6.0.0

removeIcon

public StandardTitleBar removeIcon()
Removes the application icon from the StandardTitleBar object.

No action is taken if an application icon is not defined for the StandardTitleBar object.

Returns:
The StandardTitleBar object the application icon was removed from.
Since:
BlackBerry API 6.0.0

addTitle

public StandardTitleBar addTitle(String title)
Adds a new title String to the StandardTitleBar object.

There is no length restriction on the title, though any title that is too long to fit will be truncated and an ellipsis will be appended.

Since a StandardTitleBar can have only one title, multiple calls to this method will result in the latest call overwriting the previous definition of the title.

Parameters:
title - The new title String for the StandardTitleBar object.
Returns:
The StandardTitleBar object the title was added to.
Since:
BlackBerry API 6.0.0

removeTitle

public StandardTitleBar removeTitle()
Removes the title from the StandardTitleBar object.

No action is taken if a title is not defined for the StandardTitleBar object.

Returns:
The StandardTitleBar object the title was removed from.
Since:
BlackBerry API 6.0.0

addClock

public StandardTitleBar addClock()
Adds the clock component to the StandardTitleBar object.

Since each StandardTitleBar has only one clock component, multiple calls to this method will have no effect on the StandardTitleBar object.

Returns:
The StandardTitleBar object the clock was added to.
Since:
BlackBerry API 6.0.0

removeClock

public StandardTitleBar removeClock()
Removes the clock component from the StandardTitleBar object.

No action is taken if a clock is not defined for the StandardTitleBar object.

Returns:
The StandardTitleBar object the clock was removed from.
Since:
BlackBerry API 6.0.0

addNotifications

public StandardTitleBar addNotifications()
Adds a notifications component to the StandardTitleBar object.

The notifications component displays the most recent device notifications that have yet to be addressed by the user. This includes such things as unread emails or SMS messages, as well as others.

The notifications component contains at least two slots for new notifications to be presented. The number of available slots is determined by the amount of available space.

Since each StandardTitleBar has only one notifications component, multiple calls to to this method will have no effect on the StandardTitleBar object.

Returns:
The StandardTitleBar object the notifications were added to.
Since:
BlackBerry API 6.0.0

removeNotifications

public StandardTitleBar removeNotifications()
Removes the notifications component from the StandardTitleBar object.

No action is taken if a notifications component is not defined for the StandardTitleBar object.

Returns:
The StandardTitleBar object the notification component was removed from.
Since:
BlackBerry API 6.0.0

addSignalIndicator

public StandardTitleBar addSignalIndicator()
Adds the signal indicator component to the StandardTitleBar object.

The signal indicator displays the wireless coverage indicators, and Wi-Fi, GPS, and Bluetooth® connection indicators, if applicable.

Since each StandardTitleBar has only one signal component, multiple calls to this method will have no effect on the StandardTitleBar object.

Returns:
The StandardTitleBar object the signal indicator was added to.
Since:
BlackBerry API 6.0.0

removeSignalIndicator

public StandardTitleBar removeSignalIndicator()
Removes the signal indicator component from the StandardTitleBar object.

No action is taken if a signal indicator component is not defined for the StandardTitleBar object.

Returns:
The StandardTitleBar object the signal indicator was removed from.
Since:
BlackBerry API 6.0.0

setPropertyValue

public void setPropertyValue(int propertyKey,
                             int propertyValue)
Sets the property that is specified to the value that is provided.

Properties are specified as key-value pairs. The following properties and values can be used (PROPERTY_VALUE_DEFAULT can be used with any property):

Property key Values
StandardTitleBar.PROPERTY_BATTERY_VISIBILITY StandardTitleBar.BATTERY_VISIBLE_ALWAYS, StandardTitleBar.BATTERY_VISIBLE_LOW_OR_CHARGING
StandardTitleBar.PROPERTY_WIFI_VISIBILITY StandardTitleBar.PROPERTY_VALUE_ON, StandardTitleBar.PROPERTY_VALUE_OFF
StandardTitleBar.PROPERTY_CELLULAR_VISIBILITY StandardTitleBar.PROPERTY_VALUE_ON, StandardTitleBar.PROPERTY_VALUE_OFF

Parameters:
propertyKey - The property key.
propertyValue - Value to set the property to.
Throws:
IllegalArgumentException - If propertyValue does not represent an appropriate value for the specified property or propertyKey is not valid.
Since:
BlackBerry API 6.0.0

getPropertyValue

public int getPropertyValue(int propertyKey)
Retrieves the value set for the specified property.

Properties are specified as key-value pairs. The following properties and values can be used (PROPERTY_VALUE_DEFAULT can be used with any property):

Property key Values
StandardTitleBar.PROPERTY_BATTERY_VISIBILITY StandardTitleBar.BATTERY_VISIBLE_ALWAYS, StandardTitleBar.BATTERY_VISIBLE_LOW_OR_CHARGING
StandardTitleBar.PROPERTY_WIFI_VISIBILITY StandardTitleBar.PROPERTY_VALUE_ON, StandardTitleBar.PROPERTY_VALUE_OFF
StandardTitleBar.PROPERTY_CELLULAR_VISIBILITY StandardTitleBar.PROPERTY_VALUE_ON, StandardTitleBar.PROPERTY_VALUE_OFF

Parameters:
propertyKey - The property key.
Returns:
The value set for the specified property.
Throws:
IllegalArgumentException - If propertyKey is not valid.
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