Android---App Widget(四)

接收App Widget广播的Intent对象

AppWidgetProvider只是一个便利的类，如果你想要直接接收App Widget广播，你可以实现自己的BroadcastReceiver类或重写onReceive(Context, Intent)回调方法。你需要关心以下类型的Intent对象：

ACTION_APPWIDGET_UPDATE

ACTION_APPWIDGET_DELETED

ACTION_APPWIDGET_ENABLED

ACTION_APPWIDGET_DISABLED

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被初始化并可以更新布局。