Android---App Widget(四)
接收App Widget广播的Intent对象
AppWidgetProvider只是一个便利的类,如果你想要直接接收App Widget广播,你可以实现自己的BroadcastReceiver类或重写onReceive(Context, Intent)回调方法。你需要关心以下类型的Intent对象:
ACTION_APPWIDGET_OPTIONS_CHANGED
创建AppWidget的配置Activity
如果在用户添加一个新的App Widget时,你想要用户完成一些设置,那么你可以创建一个用于配置的Activity。这个Activity会由App Widget的持有者自动的启动,并允许用户在创建时给App Widget做一些有效的设置,如App Widget的颜色、大小、更新周期或其他的功能性设置。
这个配置Activity会作为一个普通的Activity在Android清单文件中声明。但是,它会由App Widget持有使用用ACTION_APPWIDGET_CONFIGURE操作来启动,因此这个Activity需要接受这个Intent对象。例如:
<activityandroid:name=".ExampleAppWidgetConfigure">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
</intent-filter>
</activity>
还有,这个Activity必须要在AppWidgetProviderInfo的XML文件中用android:configure属性来声明。例如:
<appwidget-providerxmlns:android="http://schemas.android.com/apk/res/android"
...
android:configure="com.example.android.ExampleAppWidgetConfigure"
... >
</appwidget-provider>
注意,这个Activity要使用完整的命名空间来声明,因为它会在你包范围之外被引用。
以上是启动带有配置Activity所要做的全部事情。现在需要实际的Activity。但是,在实现你的Activity时要记住两件重要的事情:
1. App Widget持有者会调用这个配置Activity,并且这个配置Activity要始终返回结果。这个结果应该包括App Widget的ID(它保存在Intent对象的附加信息中,键名:EXTRA_APPWIDGET_ID)。
2. 在AppWidget被创建时,onUpdate()方法不会被调用(因为在配置Activity被启动时,系统不会发送ACTION_APPWIDGET_UPDATE广播)。当App Widget被首次创建时,这个配置Activity会请求来自AppWidgetManager的更新。但是,onUpdate()方法会被后续的更新调用---它只是在第一次被跳过。
以下章节会看到从配置Activity返回结果和更新App Widget的代码片段。
从配置Activity中更新App Widget
当App Widget使用一个配置Activity时,在配置完成后,它会负责更行App Widget。直接向AppWidgetManager发送请求来完成更新。
以下是一个简要的更新App Widget并关闭配置Activity的过程:
1. 从启动Activity的Intent中获取App WidgetID:
Intent intent = getIntent();
Bundle extras = intent.getExtras();
if (extras != null) {
mAppWidgetId = extras.getInt(
AppWidgetManager.EXTRA_APPWIDGET_ID,
AppWidgetManager.INVALID_APPWIDGET_ID);
}
2. 执行App Widget的配置
3. 配置完成时,通过调用getInstance(Context)方法来获取一个AppWidgetManager的实例:
AppWidgetManagerappWidgetManager =AppWidgetManager.getInstance(context);
4. 调用updateAppWidget(int,RemoteViews)方法来更新带有RemoteViews布局的App Widget:
RemoteViews views =newRemoteViews(context.getPackageName(),
R.layout.example_appwidget);
appWidgetManager.updateAppWidget(mAppWidgetId, views);
5. 最后创建一个要返回的Intent对象,设置返回结果,并销毁当前Activity:
Intent resultValue =newIntent();
resultValue.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,mAppWidgetId);
setResult(RESULT_OK, resultValue);
finish();
提示:在你的配置Activity被首次打开时,把Activity的设置结果设置给RESULT_CANCELED。如果用户在设置结束之前退出了该Activity,那么用这种方法就会通知App Widget的持有者,配置被取消了,并且App Widget将不会被添加。
设置预览图片
Android3.0以后引入了previewImage字段,它用于指定AppWidget外观的预览图片,它会在Widget选择器中显示。如果不支持这个字段,那么App Widget的图片会用于预览。
以下是在XML中指定这个设置的方法:
<appwidget-providerxmlns:android="http://schemas.android.com/apk/res/android"
...
android:previewImage="@drawable/preview">
</appwidget-provider>
为了帮助你给App Widget创建预览图片,Android模拟器包含了一个叫做“Widget Preview”的应用程序。启动这个应用程序,给你的应用程序选择App Widget,并且给它创建要显示的预览图片,就可以创建一个App Widget的预览图片,然后保存它,并把它放到你的应用程序的可绘制资源中。
在锁屏上启用App Widget
Android4.2开始为用户引入了把Widget添加到锁屏上的能力。要指明你的App Widget在锁屏上是有效的,就要在XML文件中的AppWidgetProviderInfo中声明android:widgetCategory属性,这个属性支持两个值:”home_scree”和”keyguard”,一个App Widget能够声明支持其中之一或同时都支持。
默认情况下,每个App Widget都支持放到Home屏上,因此”home_screen”是android:widgetCategory属性的默认值。如果你想要App Widget在锁屏上也是有效的,就要添加”keyguard”属性值:
<appwidget-providerxmlns:android="http://schemas.android.com/apk/res/android"
...
android:widgetCategory="keyguard|home_screen">
</appwidget-provider>
如果你声明了一个Widget要同时显示在锁屏和主屏上,你会想到要根据显示的位置来定制Widget的外观。例如,你可能要给锁屏和主屏分别创建一个独立的布局文件。接下来要在运行时检查Widget的显示类别。通过调用getAppWidgetOptions()方法来获取一个Bundle对象,能够检查到你的Widget是要显示在锁屏还是主屏上。这个返回的Bundle对象会包含OPTION_APPWIDGET_HOST_CATEGORY健,它的值会是WIDGET_CATEGORY_HOME_SCREEN或WIDGET_APPWIDGET_HOST_CATEGORY之一。这个值被用于判断该Widget的持有者。在AppWidgetProvider中,你可以检查该Widget的种类,例如:
AppWidgetManager appWidgetManager;
int widgetId;
Bundle myOptions = appWidgetManager.getAppWidgetOptions(widgetId);
// Get the value of OPTION_APPWIDGET_HOST_CATEGORY
int category = myOptions.getInt(AppWidgetManager.OPTION_APPWIDGET_HOST_CATEGORY, -1);
// If the value is WIDGET_CATEGORY_KEYGUARD, it's a lockscreenwidget
boolean isKeyguard = category == AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD;
一旦你知道了Widget的种类,你就可以有选择的装载不同的布局,设置不同的属性等,例如:
int baseLayout =isKeyguard ? R.layout.keyguard_widget_layout: R.layout.widget_layout;
你还可以用android:initalKeyguardLayout属性给你的App Widget指定在锁屏上的初始布局。这个属性的工作方法与android:initialLayout属性相同,它提供了一个可以立即显示的布局,直到App Widget被初始化并可以更新布局。