Tuesday, March 8, 2011

Using the BlackBerry Notifications Manager


Creative Commons Licence
This work is licenced under a Creative Commons Licence.

Quite often we want to be able to notify the user that some event has happened. It is nice to be able to allow the user to configure what form that notification takes depending on the profile in use (Normal, Silent, Vibrate, etc.). The procedure to do this is quite simple, although when I first tackled this problem the documentation was confusing. I like to have a state class that keeps the data used to trigger the notification. This can become important if you application has a complex notification system. In this example it isn't really necessary, but here is my storage class Notify:

/*
* Notify.java
*
* © Richard Buckley www.hrbuckley.net, 2011
*
* This work is licenced under the Creative
* Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
* To view a copy of this licence, visit
* http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to
* Creative Commons, 171 Second Street, Suite 300, San Francisco,
* California 94105, USA.
*/

package src.notify;

import net.rim.device.api.notification.NotificationsManager;
import net.rim.device.api.notification.NotificationsEngineListener;

// The Notify class is just a helper to keep track of the data needed to invoke
// and cancel the notification. Mainly they keep track of the _eventId so the
// notification can be canceled, if you want to implement that, it is not used
// here and this could be rolled into the main program if simplification is more
// important.

final class Notify
{
    long _sourceId;
    long _eventId;
    int _priority;
    int _triggerIndex;
    long _timeout;

    public Notify(long sourceid, long eventid, int priority, long timeout,
            int triggerIndex) {
        _sourceId = sourceid;
        _eventId = eventid;
        _priority = _priority;
        _triggerIndex = triggerIndex;
        _timeout = timeout;
    }

    // invoke the event
    public void fire() {
        // triggerImmediateEvent causes non-interactable events to fire, such as Tunes, Vibrations and LED flashing
        NotificationsManager.triggerImmediateEvent(_sourceId, 0, this, null);
    }

    // cancel the event
    public void cancel() {
        NotificationsManager.cancelImmediateEvent(_sourceId, 0, this, null);
    }

}
Somewhere in the initialization of your code you must register a UID, Name and level with the OS. This will cause the name you have chosen to appear in the profiles where the user can get creative. Then it is a simple matter of firing the appropriate notification at the right time.

/*
* Notify.java
*
* © Richard Buckley www.hrbuckley.net, 2011
*
* This work is licenced under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
* To view a copy of this licence, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to
* Creative Commons, 171 Second Street, Suite 300, San Francisco, California 94105, USA.
*/

package src.notify;

import net.rim.device.api.notification.NotificationsConstants;
import net.rim.device.api.notification.NotificationsManager;

// A skeleton class that will fire notifications.
//
class MyNotifierClass {
    public static final long NOTIFY1 0x6deb32addca8d89aL; // src.notify.Notify1
    public static final long NOTIFY2 0xd8759a3149fe119L; // src.notify.Notify2

    private Notify        _notify1, _notify2;
    private long          _EVENT_ID;

    public MyNotifierClass() {
        _EVENT_ID = 0L;

        //New Notifications Sources - these will show up as editable configurations in the Profiles application
        NotificationsManager.registerSource( NOTIFY1, "Notify 1", NotificationsConstants.IMPORTANT );
        NotificationsManager.registerSource( NOTIFY2, "Notify 2", NotificationsConstants.IMPORTANT );
    }

    public void someMethod() {
        _notify1 = new Notify(NOTIFY1, ++_EVENT_ID, 500, -1, NotificationConstants.MANUAL_TRIGGER);
       _notify1.fire();
    }

    public void someOtherMethod() {
         _notify2 = new Notify(NOTIFY2, ++_EVENT_ID, 500, -1, NotificationConstants.MANUAL_TRIGGER);
        _notify2.fire();
    }
}


No comments:

Post a Comment