net.rim.device.api.notification
Interface NotificationsEngineListener

All Superinterfaces:

NotificationsConstants

public interface NotificationsEngineListener
extends NotificationsConstants

The NotificationsEngineListener interface provides the API used to negotiate the pushing and popping of user interfaces from simple dialogs to complex screens in response to notification events. Only applications wishing to trigger such events need to implement this API. If the application simply wants to do something without requiring user input, such as playing a tune, it can simply use the appropriate NotificationEngine calls.

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 3.6.0

Field Summary

Fields inherited from interface net.rim.device.api.notification.NotificationsConstants

CALLERID_ADDRESSCARD_UID, CASUAL, CONTINUOUS_REPEAT, CRITICAL, CUSTOM_TUNE_NAME, DEFAULT_LEVEL, FORCED, FORCE_NO_REPEAT_NOTIFICATIONS_FLAG, IMPORTANT, IN_HOLSTER_ENGINE_STATE, MANUAL_TRIGGER, NOTIFICATION_LEVEL_KEY, NOTIFICATION_PRIVATE_FLAG_KEY, NOTIFICATION_REPEAT_COUNT, NOTIFICATION_REPEAT_DELAY, NO_RELATED_SOURCE, NO_SOURCE, OUT_OF_HOLSTER_ENGINE_STATE, OUT_OF_HOLSTER_TRIGGER, SENSITIVE, STOP_CONDITIONS

Method Summary
	void	deferredEventWasSuperseded(long sourceID, long eventID, Object eventReference, Object context) Signals that the event was superseded by a more recent one at the same or at greater level.
	void	notificationsEngineStateChanged(int stateInt, long sourceID, long eventID, Object eventReference, Object context) Signals that the state of the notifications engine has changed.
	void	proceedWithDeferredEvent(long sourceID, long eventID, Object eventReference, Object context) Signals that the listener is free to proceed with the event.

Method Detail

proceedWithDeferredEvent

void proceedWithDeferredEvent(long sourceID,
                              long eventID,
                              Object eventReference,
                              Object context)

Signals that the listener is free to proceed with the event. This usually means putting some kind of user interface up. The event remains active until one of the following happens:

The UI displayed must be invoked on a separate UiApplication instance, that is, rendering the UI on the calling thread MUST not occur. An example:

 public void proceedWithDeferredEvent(long sourceID, long eventID, Object eventReference, Object context)
 {
   app.invokeLater(new Runnable() { //where app is the UiApplication instance
       public void run() {
          //do work here to render the gui
       }
   });
 }
 

a) Listener calls NotificationsManager.cancelDeferredEvent with the active event id.

b) The listener's deferredEventWasSuperseded is called with the active event id.

Note that only one of the eventID and eventReference should be used. The eventReference is used if it's not null; otherwise, the eventID is used.

Parameters:

sourceID - Identifier of the application which triggered the notification.

eventID - Application-specific event identifier.

eventReference - Application-specific event reference.

context - Optional context for the operation.

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 3.6.0

deferredEventWasSuperseded

void deferredEventWasSuperseded(long sourceID,
                                long eventID,
                                Object eventReference,
                                Object context)

Signals that the event was superseded by a more recent one at the same or at greater level. As soon as this method returns, #proceedWithDeferredEvent will be called on the listener with the new active event.

Note that only one of the eventID and eventReference should be used. The eventReference is used if it's not null; otherwise, the eventID is used.

Parameters:

sourceID - Identifier of the application which triggered the notification.

eventID - Application-specific event identifier.

eventReference - Application-specific event reference.

context - Optional context for the operation.

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 3.6.0

notificationsEngineStateChanged

void notificationsEngineStateChanged(int stateInt,
                                     long sourceID,
                                     long eventID,
                                     Object eventReference,
                                     Object context)

Signals that the state of the notifications engine has changed.

Parameters:

state - Engine-specific state value.

sourceID - Identifier of the application which triggered the notification.

eventID - Application-specific event identifier of the active event.

eventReference - Application-specific event reference of the active event.

context - Optional context for the operation.

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 3.6.0