|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectnet.rim.blackberry.api.messagelist.ApplicationIndicator
public final class ApplicationIndicator
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'.
| Field Summary | ||
|---|---|---|
|
static int |
VALUE_LIMIT
Defines the value limit. |
| Method Summary | ||
|---|---|---|
|
int |
getValue()
Returns the current indicator value. |
|
boolean |
isVisible()
Determines if the indicator should be displayed on the screen. |
|
void |
set(ApplicationIcon icon,
int value)
Sets a new icon and value for the indicator and repaints the indicator if it is displayed. |
|
void |
setIcon(ApplicationIcon icon)
Sets a new icon for the indicator and repaints the indicator if it is displayed. |
|
void |
setNotificationState(boolean isNew)
Sets or clears the "new" notification state. |
|
void |
setValue(int value)
Sets a new indicator value and updates the indicator if it is displayed. |
|
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 |
|---|
public static final int VALUE_LIMIT
| Method Detail |
|---|
public boolean isVisible()
true, the indicator might not be visible
on the screen, depending on real estate needs.
true if the indicator should be displayed on the screen, false otherwise.public void setVisible(boolean visible)
visible - If true, the indicator should be displayed, if
false, the indicator is hidden.public int getValue()
public void setValue(int value)
value - New indicator value.
public void setIcon(ApplicationIcon icon)
throws IllegalArgumentException
icon - A new indicator icon.
IllegalArgumentException - if the icon is very large.
NullPointerException - if icon is null.
public void set(ApplicationIcon icon,
int value)
throws IllegalArgumentException
icon - A new indicator icon.value - New indicator value.
IllegalArgumentException - if the icon is very large.
NullPointerException - if icon is null.public void setNotificationState(boolean isNew)
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.
isNew - If true, the indicator indicates new messages,
if false, the indicator indicates no new messages.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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.