SHOW Signed
 

net.rim.blackberry.api.messagelist
Class ApplicationIndicator

java.lang.Object
  |
  +--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 indicators area along with others such as new mail counter, calendar reminders, missed calls counter, security status and others. Application can register only one indicator and has to register it every time the phone starts. All indicators are cleared upon phone restart.

Registered application indicators are not guaranteed to be displayed. Different factors play role in visibility decision making 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 unread email counter or missed calls indicator.

Indicator dimensions depend on current theme and phone screen size. The icon size varies from 10x10 up to 24x24. The provided icon can be resized up or down to take up the whole available space. Alternatively, application icon can be set to remain unchanged, however, in this case it may be cut if it doesn't fit the indicator area.

Application indicator users are encouraged to use small icons. If indicator is initialized with a big icon then an exception is thrown.

Indicator can have optional numeric value that usually serves as a counter. The value can be negative, 0 or positive. If 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 number of financial transactions in the current business day. Due to limited real estate, indicator value can be truncated if it is very big. 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:
JDE 4.6.0

Field Summary
 Category: Signed static int VALUE_LIMIT
          Defines the value limit.
 
Method Summary
 Category: Signed  int getValue()
          Retrieves current count value
 Category: Signed  boolean isVisible()
          Retrieves if indicator should be drawn on the screen.
 Category: Signed  void set(ApplicationIcon icon, int value)
          Sets new icon and value and repaints itself if visible.
 Category: Signed  void setIcon(ApplicationIcon icon)
          Sets a new Icon to the indicator and repaints itself if visible.
 Category: Signed  void setValue(int value)
          Sets new value and updates indicator if visible.
 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. Bigger values would have '99+' presentations.
Since:
JDE 4.6.0
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.
Method Detail

getValue

public int getValue()
Retrieves current count value
Returns:
current indicator value
Since:
JDE 4.6.0
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.

isVisible

public boolean isVisible()
Retrieves if indicator should be drawn on the screen. Note that even if returned value is true then it does not mean that it is currently visible on the screen.
Returns:
true if indicator should be drawn on the screen, false otherwise
Since:
JDE 4.6.0
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.

set

public void set(ApplicationIcon icon,
                int value)
         throws IllegalArgumentException
Sets new icon and value and repaints itself if visible.
Parameters:
icon - a new indicator icon
value - new indicator value
Throws:
IllegalArgumentException - if given icon size is very big
Since:
JDE 4.6.0
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.

setIcon

public void setIcon(ApplicationIcon icon)
             throws IllegalArgumentException
Sets a new Icon to the indicator and repaints itself if visible.
Parameters:
icon - a new indicator icon
Throws:
IllegalArgumentException - if given icon size is very big
Since:
JDE 4.6.0
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.

setValue

public void setValue(int value)
Sets new value and updates indicator if visible. If very big value is provided then indicator will display '99+' or '999+'.
Parameters:
value - new indicator value
Since:
JDE 4.6.0
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.

setVisible

public void setVisible(boolean visible)
Hides or displays the indicator. Usually when count is equal to 0, application may hide the indicator to leave space for others.
Parameters:
visible - defines if indicator should be displayed
Since:
JDE 4.6.0
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.



Copyright 1999-2008 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.