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

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.container.VerticalFieldManager
                  net.rim.device.api.ui.component.TitleBar
                      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):

• Application Icon
• Application Title
• Clock
• Notifications
• Battery Icon (properties)
• Signal Indicator (Wi-Fi® and cellular properties)

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, 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, 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

Field Detail

PROPERTY_BATTERY_VISIBILITY

public static final int PROPERTY_BATTERY_VISIBILITY

Property key for battery indicator visibility.

Acceptable property values:

• StandardTitleBar.BATTERY_VISIBLE_LOW_OR_CHARGING (default)
• StandardTitleBar.BATTERY_VISIBLE_ALWAYS

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:

• StandardTitleBar.PROPERTY_VALUE_ON (default)
• StandardTitleBar.PROPERTY_VALUE_OFF

  See Also:

  Constant Field Values

  Since:

  BlackBerry API 6.0.0

PROPERTY_CELLULAR_VISIBILITY

public static final int PROPERTY_CELLULAR_VISIBILITY

Property key for the signal indicator's cellular component's visibility.

Acceptable property values:

• StandardTitleBar.PROPERTY_VALUE_ON (default)
• StandardTitleBar.PROPERTY_VALUE_OFF

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