BlackBerry 应用程序开发者指南第二卷：高级–第11章管理通知(Notification)

Confach 发表于 April 29, 2008 6:04 am

版权信息 :严禁转载, 若想推荐或收藏，请用链接的形式.

网址：http://www.inblackberry.com/web/development/docs/guide-vol-2-manage-notification.html

第11章管理通知(Notification)

通知API

增加事件

响应事件

自定义系统的通知

通知API

通知API(net.rim.device.api.notification)让你可以为你的应用程序增加自定义事件,并且当自定义事件发生时,又允许你定义用户接收的通知类型.

注:当你的应用程序第一次访问通知API时,它将检查一个ControlledAccessException.如果系统管理员使用应用程序控制限制访问通知API,一将抛出个运行时异常.为获取更多信息,参看”BlackBerry应用程序开发者指南 第2卷:高级 第一卷:基础”.

通知事件类型	描述
短暂事件	系统通知,例如LED闪烁,振动或铃声.
延续事件	应用程序指定的通知,例如一个UI.

对于短暂事件,只要事件一发生,BlackBerry设备就会使用一个系统通知, 例如LED闪烁,振动或铃声,尽快将消息发送给用户.应用程序不可以请求一指定类型的通知.在手持设备配置(Profile)列表里,用户通过选择一个活动的配置和设置配置选项来控制它们如何接收短暂事件的通知.为了将一个自定义的系统通知加入到短暂事件,请实现Consequence接口.

在延续的事件里,BlackBerry设备根据事件的优先级将它们安排在一个队列里.当事件发生时,事件影响的应用程序可能为用户提供一个自定义的通知,一般是通过显示一个用户界面(UI)元素,例如一个对话框来完成.为了监听延续的事件,实现NotificationsEngineListener接口.BlackBerry设备不会为延续事件提供一个系统级的通知.

增加事件

注册一个新的事件源

创建一个唯一long ID

为每个通知事件定义一个long ID.

public static final long ID_1 = 0xdc5bf2f81374095L;

注:使用BlackBerry IDE将一个String转化为一个long,为你的应用程序创建一个long的标记符:

1.在BlackBerry IDE文本里,输入一个字符串.
2.选择字符串,右击,然后单击Convert “string” to Long.

定义一个源对象

定义一个为事件提供源的对象. toString()的实现返回显示在配置列表里的字符串.

Object event = new Object() {

public String toString() {

return "Notification Demo";

}

将你的应用程序注册一个通知源

为了将你的应用程序作为一个事件源加入到手持设备的配置列表里,调用NotificationsManager.registerSource().在此方法里,指定一个唯一的事件ID,源对象以及通知级别.

通知级别设置了事件的优先级,它决定了延续事件发生的顺序.以最高级到最低级的顺序,级别如下:

NotificationsConstants.CRITICAL
NotificationsConstants.SENSITIVE
NotificationsConstants.IMPORTANT
NotificationsConstants.DEFAULT_LEVEL
NotificationsConstants.CASUAL

注:优先级仅适用于延续事件.只要短暂事件触发,它们就会发生.当触发一个延续事件时,指定一个过期时间.如果事件在最高级事件之前已经过期,用户可能不会接收到此最低级事件的通知.

当BlackBerry设备启动时注册事件源

为了注册一个事件源,创建一个带有libMain()的工程,在BlackBerry设备启动时进行注册.

创建一个类库工程

1.在BlackBerry IDE, 创建一个工程.

2.右击工程,单击Properties.

3.单击 Application标签.

4.在Project type 下拉列里,单击Library.

5.选择Auto-run on startup.

6.单击OK.

7.定义libMain().

public static final long ID_1 = 0xdc5bf2f81374095L;

public static final Object event = new Object() {

public String toString()

{

return "Sample Notification Event #1";

}

};

public static void libMain(String[] args) {

NotificationsManager.registerSource(ID_1, event,

NotificationsConstants.CASUAL);

}

触发一个短暂事件

调用triggerImmediateEvent().短暂事件由标准的系统通知描述,例如铃声,振动,或LED.

NotificationsManager.triggerImmediateEvent(ID_1, 0, this, null);

triggerImmediateEvent方法接受下面的参数:

参数	描述
sourceID	启动事件(当调用registerSource()时指定)的应用程序的标志符.
eventID	应用程序事件标志符.
eventReference	应用程序事件cookie.
context	可选的上下文对象.

在大多数情况下,不要使用短暂事件,因为BlackBerry设备事件通知不会充分说明发生了什么事情.例如,如果BlackBerry设备振动,对于用户来说,它将很难知道到底是在你的应用程序里发生了一个事件,还是一个新消息已经到达了.如果你使用了短暂消息,考虑实现一个自定义的通知,例如一个特殊的铃声,来区分你的应用程序事件和其他BlackBerry设备事件.为获取更多信息,参看122页的”自定义系统通知”.

触发一个延续事件

调用negotiateDeferredEvent().一个延续事件让你的应用程序以一个UI元素,例如一个对话框通知用户

NotificationsManager.negotiateDeferredEvent(ID_1, 0, this, -1,

NotificationsConstants.MANUAL_TRIGGER, null);

negotiateDeferredEvent(long, long, Object, long, int, Object) 方法接受下面的参数:

参数	描述
sourceID	启动事件(当调用registerSource()时指定)的应用程序的标志符.
eventID	应用程序事件标志符.
eventReference	应用程序事件cookie.
timeout	事件过期时间,以毫秒计,当调用方法时的相对时间(忽略过期时间,除非trigger是OUT_OF_HOLSTER_TRIGGER)
trigger	要么是NotificationsConstants.OUT_OF_HOLSTER_TRIGGER,它指定了当BlackBerry设备和计算机断开时的事件,要么是NotificationsConstants.MANUAL_TRIGGER,它指定了应用程序本身触发事件.
context	可选对象,可以存储附加的,任意的参数来控制事件通知的状态或者行为.

如果你调用negotiateDeferredEvent(long, long, Object, long, int, Object),你的应用程序必须实现NotificationEventListener来监听事件并充分响应它.为获取更多信息,参看121页的”响应事件”.

取消一个事件

取消一个短暂事件

调用cancelImmediateEvent(long, long, Object, Object), 然后指定源以及事件ID．

NotificationsManager.cancelImmediateEvent(ID_1, 0, this, null);

取消一个延续事件

调用 cancelDeferredEvent(long, long, Object, int, Object), 然后指定源以及事件ID．

NotificationsManager.cancelDeferredEvent(ID_1, 0, this, NotificationsConstants.MANUAL_TRIGGER, null);

取消所有延续事件

调用cancelAllDeferredEvents(long, int, Object)方法取消所有应用程序启动的是延续事件.

NotificationsManager.cancelAllDeferredEvents(ID_1, NotificationsConstants.MANUAL_TRIGGER, null);

注.如果你调用negotiateDeferredEvent()方法,但没有指定过期事件,你必须调用cancelDeferredEvent()方法取消事件,否则事件永远不过期.

代码实例

例: NotificationDemo.java

/**

* NotificationsDemo.java

package com.rim.samples.docs.notifications;

import net.rim.device.api.notification.*;

import net.rim.device.api.ui.*;

import net.rim.device.api.ui.component.*;

import net.rim.device.api.ui.container.*;

import net.rim.device.api.system.*;

import net.rim.device.api.util.*;

import com.rim.samples.docs.baseapp.*;

public class NotificationsDemo extends BaseApp {

public static final long ID_1 = 0xdc5bf2f81374095L;

private long _eventIdGenerator;

private static Object er;

public static final Object event = new Object() {

public String toString() {

return "Sample Notification Event #1";

}

};

public static void main(String[] args) {

NotificationsManager.registerSource(ID_1, event, NotificationsConstants.CASUAL);

NotificationsManager.registerConsequence(ConsequenceDemo.ID,

new ConsequenceDemo());

NotificationsDemo app = new NotificationsDemo();

app.enterEventDispatcher();

}

public NotificationsDemo() {

MainScreen mainScreen = new MainScreen();

mainScreen.setTitle("Notification Demo App");

mainScreen.addKeyListener(this);

mainScreen.addTrackwheelListener(this);

NotificationsManager.registerNotificationsEngineListener(ID_1,

new NotificationsEngineListenerImpl(this));

pushScreen(mainScreen);

}

private MenuItem triggerItem = new MenuItem(null, 0, 100, 10) {

public void run() {

NotificationsManager.triggerImmediateEvent(ID_1, 0, this, null);

}

public String toString() {

return "Trigger event";

}

};

private MenuItem deferItem = new MenuItem(null, 0, 100, 10) {

public void run() {

long timeout = -1; // Ignored unless trigger is OUT_OF_HOLSTER_TRIGGER.

int trigger = NotificationsConstants.MANUAL_TRIGGER;

Object er = new Object();

NotificationsManager.negotiateDeferredEvent(ID_1, ++_eventIdGenerator,

er, timeout, trigger, null);

}

public String toString() {

return "Start deferred event";

}

};

private MenuItem cancelItem = new MenuItem(null, 0, 100, 10) {

public void run() {

int trigger = NotificationsConstants.MANUAL_TRIGGER;

NotificationsManager.cancelDeferredEvent(ID_1, _eventIdGenerator, er,

trigger, null);

}

public String toString() {

return "Cancel deferred event";

}

};

public void makeMenu( Menu menu, int instance ) {

menu.add(triggerItem);

menu.add(deferItem);

menu.add(cancelItem);

super.makeMenu(menu, instance);

}

public void onExit() {

System.exit(0);

}

private static class NotificationsEngineListenerImpl implements

NotificationsEngineListener {

private UiApplication _app;

}

public NotificationsEngineListenerImpl(UiApplication app) {

_app = app;

}

public void deferredEventWasSuperseded(long sourceID, long eventID,

Object eventReference, Object context) {

final long _eventID = eventID;

er = eventReference;

_app.invokeLater(new Runnable() {

public void run() {

NotificationsManager.cancelDeferredEvent(ID_1, _eventID, er,

NotificationsConstants.MANUAL_TRIGGER, null);

}

});

}

public void notificationsEngineStateChanged(int stateInt, long sourceID,

long eventID, Object eventReference, Object context) {

if(stateInt == NotificationsConstants.OUT_OF_HOLSTER_ENGINE_STATE) {

// Perform some action if handheld is removed from holster.

}

if(stateInt == NotificationsConstants.IN_HOLSTER_ENGINE_STATE) {

// Perform some action if handheld is inserted into holster.

}

public void proceedWithDeferredEvent(long sourceID, long eventID,

Object eventReference, Object context) {

final long _eventID = eventID;

}

_app.invokeLater(new Runnable() {

public void run() {

String s = "This event has occurred: " + _eventID;

Dialog d = new Dialog(Dialog.D_OK, s, Dialog.OK,

Bitmap.getPredefinedBitmap(Bitmap.INFORMATION), 0);

};

private MenuItem cancelItem = new MenuItem(null, 0, 100, 10) {

BlackBerry 应用程序开发者指南 第二卷：高级–第11章 管理通知(Notification)

第11章 管理通知(Notification)

通知API

增加事件

注册一个新的事件源

触发一个短暂事件

触发一个延续事件

取消一个事件

代码实例

BlackBerry 应用程序开发者指南第二卷：高级–第11章管理通知(Notification)

第11章管理通知(Notification)