net.rim.blackberry.api.messagelist.ApplicationMessageFolderRegistry
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public class ApplicationMessageFolderRegistry
Registry for application folders. Provides operations to register new application folders, assign icons and menu items for specific message type and statuses.
An application can register multiple folders similar to email such as Inbox, Sent, Deleted, etc. A folder stores application messages in the chronological order. Most graphical message list representations show folder items in the same order from most recent to the oldest. An application message can be added only to one folder, however, it may have various statuses and types. Application folders can not be nested and are represented as a simple collection.
An application folder is uniquely identified by folder ID for a given application. Additionally, folder has name attribute that will be displayed on Folder List screens. If application registers more than one folder then these folders will be grouped with a root element. Application may specify folder root element name.
Messages added to an application folder will be displayed in the global message list. Message element on GUI comprises of icon, date and time, contact and subject attributes. Some message screens may optionally display body attribute, for example, it will be shown on message preview screen. Message icons must be associated with message status and types in order to display icon in the message list. Icon registration is performed for particular message type, for example, application can register one icon for incoming messages and another icon for outgoing messages. Similarly, icon can be associated with message status, e.g. specific icon for new messages and another for opened. An application may use 0 value for both message type and status if it has only one kind of messages. If a new icon is registered for the same message type and status then no updates are triggered for visible messages. However, the new icon will be used in further paint procedures.
Application message can be assigned a number of context menu items. Similar to icon registration, menu items are associated with specific message type and status. For example, incoming message type can have View and Reply actions while outgoing message can have View action only. Menu items are associated with current or provided application descriptor which means that they will be executed in the given application context. If an application is not running at the moment a menu item is selected by user then it will be started automatically. The first registered menu item for a message type will be marked as Default item and it should have a label such as 'Open in XXXApplication'. This menu item is executed when user clicks on a message in the message list. Also the default menu item action is executed from the message preview screen to open the message in the application.
Note that application cannot register context menu items for bulk operations.
If user selects multiple messages in the list then the context menu will
include the generic operations only, such as Delete, Mark Opened and Mark
UnOpened. While the Delete action will be always present in the menu, the
Mark XXX operations can be configured through
ApplicationMessageFolderRegistry.setBulkMarkOperationsSupport(int, int, boolean, boolean) method
call. If user selects a number of messages of different types and chooses one
of the Mark XXX operation then affected messages will be only those that
support the operation. If none of the selected messages support the Mark XXX
action then the corresponding menu item is hidden. These bulk actions do not
affect which context menu items are displayed when an individual message is
selected. An application cannot set additional application specific context
menu items for bulk operations. By default no Mark XXX bulk operations are
allowed on application messages.
Application can specify whether folder messages should be merged with the global message list. If folder messages are not merged then they will not be visible in the global message list, however, messages will be searcheable and accessible through the [View Folder] screen. This can be used for Deleted or Junk Messages type folders. The following standard RIM folders are not merged: Phone Calls, Browser Messages, Junk and Deleted email messages. By default folder messages are merged and visible in the global message list.
Neither folders nor their messages are persisted automatically. So, folder registration and populating with messages must be performed each time the phone starts. This also applies to icon and menu items registration.
Collection of messages is always kept in memory even if its application is not running. Hence, its elements should be small java objects to leave memory for other applications. The message collection should be treated as a singleton object. When application is uninstalled then all its folders and message collections are cleaned up.
| Method Summary | ||
|---|---|---|
|
ApplicationMessageFolder |
getApplicationFolder(long folderId)
Retrieves application folder previously registered by folder ID for application specified by given descriptor. |
|
static ApplicationMessageFolderRegistry |
getInstance()
Retrieves registry instance. |
|
String |
getRootFolderName()
Returns root folder name used for grouping application folders. |
|
ApplicationMessageFolder |
registerFolder(long folderId,
String folderName,
ReadableList collection)
Registers an application message folder with folder ID and name. |
|
ApplicationMessageFolder |
registerFolder(long folderId,
String folderName,
ReadableList collection,
boolean mergeMessages)
Registers an application message folder with folder ID and name. |
|
ApplicationMessageFolder |
registerFolder(long folderId,
String folderName,
ReadableList collection,
ApplicationFolderIntegrationConfig integrationConfig)
Registers an application message folder with folder ID and name. |
|
void |
registerMessageIcon(int type,
int status,
ApplicationIcon icon)
Registers an icon for given message type and status |
|
void |
registerMessageMenuItems(int type,
int status,
ApplicationMenuItem[] menuItems)
Registers menu items for given message type and status. |
|
void |
registerMessageMenuItems(int type,
int status,
ApplicationMenuItem[] menuItems,
ApplicationDescriptor appDescriptor)
Registers menu items for given message type and status. |
|
void |
setBulkMarkOperationsSupport(int type,
int status,
boolean supportsBulkMarkOpen,
boolean supportsBulkMarkUnopened)
Specifies whether Mark Opened and Mark UnOpened bulk operations are supported for given message type and status. |
|
void |
setRootFolderName(String rootName)
Sets a new root folder name. |
|
boolean |
unregisterFolder(long folderId)
Unregister application folder by its ID. |
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Method Detail |
|---|
public void registerMessageMenuItems(int type,
int status,
ApplicationMenuItem[] menuItems)
throws IllegalArgumentException
ApplicationMessageFolderRegistry.registerMessageMenuItems(int, int, ApplicationMenuItem[], ApplicationDescriptor)
with ApplicationDescriptor.currentApplicationDescriptor()
parameter value.
type - application specific message typestatus - application specific message status, the lowest 16 bits
are reserved for internal use, refer to ApplicationMessage.Status for
the reserved statuses listmenuItems - optional menu items that will be available in message
context menu, the menu method run(Object)
will receive an ApplicationMessage instance
IllegalArgumentException - if menuItems parameter is of 0 length
NullPointerException - if menuItems is null
public void registerMessageIcon(int type,
int status,
ApplicationIcon icon)
type - application specific message typestatus - application specific message status, the lowest 16 bits
are reserved for internal use, refer to ApplicationMessage.Status for
the reserved statuses listicon - a message icon displayed in the global message list
NullPointerException - if icon is null
public void registerMessageMenuItems(int type,
int status,
ApplicationMenuItem[] menuItems,
ApplicationDescriptor appDescriptor)
throws IllegalArgumentException
The first menu item registered will be considered as default one and should be used for opening the message in the application.
type - application specific message typestatus - application specific message status, the lowest 16 bits
are reserved for internal use, refer to ApplicationMessage.Status for
the reserved statuses listmenuItems - optional menu items that will be available in message
context menu, the menu method run(Object)
will receive an ApplicationMessage instanceappDescriptor - application descriptor to associate the type with, menu
items will be executed in the given application context
IllegalArgumentException - if application descriptor points to a different from
current module OR menuItems parameter is of 0 length
NullPointerException - if menuItems is null or appDescriptor is null
public void setBulkMarkOperationsSupport(int type,
int status,
boolean supportsBulkMarkOpen,
boolean supportsBulkMarkUnopened)
throws IllegalArgumentException
type - application specific message typestatus - application specific message statussupportsBulkMarkOpen - specifis if bulk Mark Open operation is supported for this
type of messagesupportsBulkMarkUnopened - specifies if bulk Mark UnOpen operation is supported for
this type of message
IllegalArgumentException - if the application message type and status were not
registered beforepublic static ApplicationMessageFolderRegistry getInstance()
public ApplicationMessageFolder registerFolder(long folderId,
String folderName,
ReadableList collection)
throws IllegalArgumentException,
NullPointerException
folderId - unique for application folder ID, must be not equal to 0folderName - name of the foldercollection - a collection with ApplicationMessage elements
IllegalArgumentException - if folder ID is equal to 0 OR the folder with the same
name or ID was already registered OR the folderName has 0
length
NullPointerException - if folderName or collection parameter are null
public ApplicationMessageFolder registerFolder(long folderId,
String folderName,
ReadableList collection,
boolean mergeMessages)
throws IllegalArgumentException,
NullPointerException
folderId - unique for application folder ID, must be not equal to 0folderName - name of the foldercollection - a collection with ApplicationMessage elementsmergeMessages - defines if folder messages should be merged with the
global message list, the false value is used for
DeletedMessages-type folders so that its messages will not
be visible but accessible through other means
IllegalArgumentException - if folder ID is equal to 0 OR the folder with the same
name or ID was already registered OR the folderName has 0
length
NullPointerException - if folderName or collection parameter are null
public ApplicationMessageFolder registerFolder(long folderId,
String folderName,
ReadableList collection,
ApplicationFolderIntegrationConfig integrationConfig)
throws IllegalArgumentException,
NullPointerException
folderId - unique for application folder ID, must be not equal to 0folderName - name of the foldercollection - a collection with ApplicationMessage elementsintegrationConfig - defines how folder messages should be integrated
IllegalArgumentException - if folder ID is equal to 0 OR the folder with the same
name or ID was already registered OR the folderName has 0
length
NullPointerException - if folderName or collection parameter are null
public void setRootFolderName(String rootName)
throws NullPointerException,
IllegalArgumentException
The root folder name will be displayed on the [View Folder] dialog if and only if application registered more than one application message folders. Also, if there is an existing folder with the same name as the one you specified, the application name will be placed in parenthesis and appended to your specified folder name. For example, if your specified folder name is Inbox and the application name is ExampleApp, but a folder named Inbox already exists, then your folder name will be set to Inbox (ExampleApp).
rootName - new name to assign
NullPointerException - if rootName is null
IllegalArgumentException - if rootName has 0 lengthpublic String getRootFolderName()
public boolean unregisterFolder(long folderId)
throws IllegalArgumentException
If you had set a root folder name and you unregistered the last folder for
your application using this method, the root folder name will be lost. You can reassign
the root folder name using the setRootFolderName method.
folderId - folder ID provided during folder registration
IllegalArgumentException - if folder ID is equal to 0public ApplicationMessageFolder getApplicationFolder(long folderId)
folderId - folder ID provided during folder registration
|
|||||||||
| 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.