net.rim.blackberry.api.messagelist
Class ApplicationIndicator

java.lang.Object
  extended by net.rim.blackberry.api.messagelist.ApplicationIndicator

public final class ApplicationIndicator
extends Object

Represents an application indicator that consists of an icon and optional numeric value. The icon is placed in the banner on the Home screen along with other indicators such as new mail counter, calendar reminders, missed calls counter, and security status. An application can register only one indicator and has to register it every time the device starts. All indicators are cleared upon device restart.

Registered application indicators are not guaranteed to be displayed. Different factors play a role in whether the indicator is displayed, such as available indicators space, number of registered indicators, and current application preferences. Application indicators have the lowest drawing priority compared to system indicators such as the unread email counter or missed calls indicator.

Indicator dimensions depend on current theme and device screen size. The icon size varies from 10x10 up to 32x32. The provided ApplicationIcon can be resized up or down to take up the whole available space. Alternatively, the application icon can be set to remain unchanged. However in this case it may not be displayed if it doesn't fit the indicator area.

Application indicator users are encouraged to use small icons. If an indicator is initialized with a large icon, an exception is thrown. See the BlackBerry Theme Builder User Guide for information about optimal icon sizes on different themes and devices.

An application indicator can have an optional numeric value that usually serves as a counter. The value can be negative, 0, or positive. If the indicator is used as a counter then the best practice is to hide it when its value is equal to 0. Some applications may choose to show 0 as a counter value if such information is important to user, for example, the number of financial transactions in the current business day. Due to limited real estate, the indicator value can be truncated if it is very large. In such case the indicator will display '99+' or '999+', which means 'over a hundred' or 'over a thousand'.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

Field Summary
Category: Signed static int VALUE_LIMIT
          Defines the value limit.
 
Method Summary
Category: Signed  int getValue()
          Returns the current indicator value.
Category: Signed  boolean isVisible()
          Determines if the indicator should be displayed on the screen.
Category: Signed  void set(ApplicationIcon icon, int value)
          Sets a new icon and value for the indicator and repaints the indicator if it is displayed.
Category: Signed  void setIcon(ApplicationIcon icon)
          Sets a new icon for the indicator and repaints the indicator if it is displayed.
Category: Signed  void setNotificationState(boolean isNew)
          Sets or clears the "new" notification state.
Category: Signed  void setValue(int value)
          Sets a new indicator value and updates the indicator if it is displayed.
Category: Signed  void setVisible(boolean visible)
          Hides or displays the indicator.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

VALUE_LIMIT

public static final int VALUE_LIMIT
Defines the value limit. Large values might have '99+' style presentations.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0


Method Detail

isVisible

public boolean isVisible()
Determines if the indicator should be displayed on the screen. Note that even if the returned value is true, the indicator might not be visible on the screen, depending on real estate needs.

Returns:
true if the indicator should be displayed on the screen, false otherwise.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

setVisible

public void setVisible(boolean visible)
Hides or displays the indicator. Generally, the best practice is to hide the indicator when the count equals 0, leaving space for other indicators.

Parameters:
visible - If true, the indicator should be displayed, if false, the indicator is hidden.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

getValue

public int getValue()
Returns the current indicator value.

Returns:
Current indicator value.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

setValue

public void setValue(int value)
Sets a new indicator value and updates the indicator if it is displayed. If a very large value is provided, the indicator will use the '99+' style presentation.

Parameters:
value - New indicator value.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

setIcon

public void setIcon(ApplicationIcon icon)
             throws IllegalArgumentException
Sets a new icon for the indicator and repaints the indicator if it is displayed.

Parameters:
icon - A new indicator icon.
Throws:
IllegalArgumentException - if the icon is very large.
NullPointerException - if icon is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

set

public void set(ApplicationIcon icon,
                int value)
         throws IllegalArgumentException
Sets a new icon and value for the indicator and repaints the indicator if it is displayed.

Parameters:
icon - A new indicator icon.
value - New indicator value.
Throws:
IllegalArgumentException - if the icon is very large.
NullPointerException - if icon is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

setNotificationState

public void setNotificationState(boolean isNew)
Sets or clears the "new" notification state.

The "new" notification state should be used with indicators that represent a counter of unread messages. When the state is set to true then the indicator will be displayed with a special mark representing new messages that have not been viewed by the user. Note that the "new" and unread message statuses are different, because the user can mark an opened message as unread. A message is treated as "old" as soon as the user has viewed the message fully or partially. BlackBerry applications clear the "new" status when the global message list is opened and displays the new message.

Parameters:
isNew - If true, the indicator indicates new messages, if false, the indicator indicates no new messages.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.