App Widgets-窗口小部件

应用程序窗口小部件（Widget）是微型的应用程序视图，它可以被嵌入到其它应用程序中（比如桌面）并接收周期性的更新。你可以通过一个AppWidgetProvider来发布一个Widget。可以容纳其它AppWidget的应用程序组件被称为AppWidget宿主程序。下面的截屏显示了一个音乐AppWidget。

本篇文章描述了如何通过使用AppWidgetProvider发布一个AppWidget。

基础知识

为了创建一个AppWidget，你需要使用下面这些：

AppWidgetProviderInfo对象

描述一个AppWidget元数据，比如AppWidget的布局，更新频率，以及AppWidgetProvider类。这个应该在XML里定义。

AppWidgetProvider类的实现

定义基本方法以允许你通过编程来和AppWidget通信，这基于广播事件。通过它，当AppWidget被更新、可用、禁用和删除的时候，都将接收到广播通知。

视图布局

在XML中定义AppWidget初始布局。

另外，你可以实现AppWidget配置Activity。这是一个可选的Activity，当用户添加AppWidget时加载它并允许用户修改AppWidget的设置。

下面的内容描述了如何建立这些组件：

在Manifest中声明一个应用小部件

首先，在应用程序AndroidManifest.xml文件中声明AppWidgetProvider类，比如：

<receiver android:name="ExampleAppWidgetProvider" >
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

<receiver>元素需要android:name属性，指定了AppWidget使用的AppWidgetProvider。

<intent-filter>元素必须包括一个含有android:name属性的<action>元素。该元素指定AppWidgetProvider接受ACTION_APPWIDGET_UPDATE广播。这是唯一你必须显式声明的广播。当需要的时候，必要时AppWidgetManager会自动发送所有其它AppWidget广播给AppWidgetProvider。

<meta-data>元素指定了AppWidgetProviderInfo资源并需要以下属性：

• android:name–指定元数据名称，使用android.appwidget.provider来确定AppWidgetProviderInfo描述的数据。
• android:resource–指定AppWidgetProviderInfo资源路径。

添加AppWidgetProviderInfo元数据

AppWidgetProviderInfo定义一个AppWidget的基本特性，比如最小布局尺寸，初始布局资源，刷新频率，以及创建时加载的一个配置Activity（可选的）。使用单独的一个<appwidget-provider>元素在XML资源里定义AppWidgetProviderInfo对象并保存到项目的res/xml/目录下。

比如：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="294dp"
    android:minHeight="72dp"
    android:updatePeriodMillis="86400000"
    android:initialLayout="@layout/example_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigure" >
</appwidget-provider>
 
<span style="font-family: Arial; background-color: #ffffff;"></span>

下面是<appwidget-provider>属性的总结：

• minWidth和minHeight属性的值指定了AppWidget布局需要的最小区域。

缺省的AppWidgets所在窗口的桌面位置基于有确定高度和宽度的单元网格中。如果AppWidget的最小长度或宽度和这些网格单元的尺寸不匹配，那么这个AppWidget将上舍入（上舍入即取比该值大的最接近的整数——译者注）到最接近的单元尺寸。

一般说来桌面布局方向可以变化（由此单元的尺寸也会变化），你应该假设最坏情况即单元尺寸高和宽是74像素。不过，你必须从最终的尺寸中减去2以把像素计算过程中产生的任何的整数舍入误差考虑在内。要找到像素密度无关的最小宽度和高度，使用这个公式：

(numberofcells*74)-2

依据这个公式，你应该使用72dp作为高度，294dp作为宽度。

• updatePerdiodMillis属性定义了AppWidget框架调用onUpdate()方法来从AppWidgetProvider请求一次更新的频度。实际更新时间并不那么精确，而且我们建议更新频率越低越好——最好每小时不超过一次以节省电源。你也许还会允许用户在配置中调整这个频率——一些人可能想每15分钟一次股票报价，或者一天只要四次。

注意：当到个更新的时间时，如果设备处于休眠状态，则设备将会被唤醒来执行更新操作。如果更新频率每小时不超过一次，这可能对电池的寿命不会产生值得注意的问题。但是，如果更新的很频繁，或者当设备处于休眠状态时不更新，那么你最好使用一个alarm来代替执行更新操作，这样不会唤醒设备。这种方式可以通过使用AlarmManager类实现。设置alarm的类型为ELAPSED_REALTIME或者RTC，这两种类型只有在设备处于唤醒状态时才会传递alarm，同时设置updatePeriodMillis为0.

• initialLayout属性指向定义AppWidget布局的资源。
• configure属性定义了当用户添加AppWidget时启动的Activity，以为他/她配置AppWidget特性。这是可选的

参见AppWidgetProviderInfo类以获取更多可以被<appwidget-provider>元素接受的属性信息。

创建AppWidget布局

你必须在XML中为你的AppWidget定义一个初始布局并保存到项目的res/layout/目录下。你可以使用如下所列的View对象来设计你的AppWidget，但是在此之前，请先阅读并理解AppWidgetDesignGuidelines.

如果你熟悉在XML中声明布局，那么创建这个AppWidget布局是很简单的。但是，你必须注意AppWidget布局是基于RemoteViews,而RemoteViews并不支持所有类型的布局或视图小部件。

一个RemoteViews对象（对应的，一个AppWidget）可以支持下面这个布局类：

• FrameLayout
• LinearLayout
• RelativeLayout

以及下面的控件类：

• AnalogClock
• Button
• Chronometer
• ImageButton
• ImageView
• ProgressBar
• TextView

但是不支持这些类的派生。

使用AppWidgetProvider类

AppWidgetProvider类扩展BroadcastReceiver作为处理AppWidget广播一个简便类。AppWidgetProvider只接收和这个AppWidget相关的事件广播，比如这个AppWidget被更新、删除、启用以及禁用。当这些广播事件发生时，AppWidgetProvider将接收到下面的方法调用：

onUpdate(Context,AppWidgetManager,int[])

这个方法调用来间隔性的更新AppWidget，间隔时间用AppWidgetProviderInfo里的updatePeriodMillis属性定义。这个方法也会在用户添加AppWidget时被调用，因此它应该执行必要的设置，比如为控件定义事件处理器并启动一个临时的服务Service，如果需要的话。但是，如果你已经声明了一个配置Activity，这个方法在用户添加AppWidget时将不会被调用，而只在后续更新时被调用。配置Activity有责任在配置完成时负责执行第一次更新。

onDeleted(Context,int[])

当AppWidget从宿主AppWidget中删除时被调用。

onEnabled(Context)

当一个AppWidget实例第一次创建时被调用。比如，如果用户添加两个你的AppWidget实例，只在第一次被调用。如果你需要打开一个新的数据库或者执行其他对于所有的AppWidget实例只需要发生一次的设置，那么这里是完成这个工作的好地方。

onDisabled(Context)

当你的AppWidget的最后一个实例被从宿主中删除时被调用。你应该在onEnabled(Context)中做一些清理工作，比如删除一个临时的数据库。

onReceive(Context,Intent)

这个接收到每个广播时都会被调用，而且在上面的回调函数之前。你通常不需要实现这个方法，因为缺省的AppWidgetProvider实现过滤所有AppWidget广播并恰当的调用上述方法。

注意:在Android1.5中，有一个问题，onDeleted()方法在该调用时不被调用。为了规避这个问题，你可以像Grouppost中描述的那样实现onReceive()来接收这个onDeleted()回调。

AppWidgetProvider最重要的回调函数是onUpdated()，因为它是在每个AppWidget添加进宿主时被调用的（除非你使用一个配置活动）。如果你的AppWidget要接受任何用户交互事件，那么你需要在这个回调函数中注册事件处理器。如果你的AppWidget不创建临时文件或数据库，或者执行其它需要清理的工作，那么onUpdated()可能是你需要定义的唯一的回调函数。比如，如果你想要一个带按钮的AppWidget，当点击时启动一个活动，你可以使用下面的AppWidgetProvider实现：

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        final int N = appWidgetIds.length;

        // Perform this loop procedure for each App Widget that belongs to this provider
        for (int i=0; i<N; i++) {
            int appWidgetId = appWidgetIds[i];

            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(context, 0, intent, 0);

            // Get the layout for the App Widget and attach an on-click listener to the button
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.appwidget_provider_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current App Widget
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

这个AppWidgetProvider仅定义了onUpdated()方法，定义一个PendingIntent，来启动一个Activity并使用setOnClickPendingIntent(int,PendingIntent)方法把它附着到这个AppWidget的按钮上。注意它包含了一个遍历appWidgetIds中所有项的循环，这是一个IDs数组，每个ID用来标识由这个Provider创建的一个AppWidget。这样，如果用户创建多于一个这个AppWidget的实例，那么它们将被同步更新。不过，对于所有的AppWidget实例，只有一个updatePeriodMillis时间表被管理。比如，如果这个更新时间表被定义为每隔两个小时，而且AppWidget的第二个实例是在第一个后面一小时添加的，那么它们将按照第一个所定义的周期来更新而第二个被忽略（它们将都是每2个小时进行更新，而不是每小时）。

注意:因为这个AppWidgetProvider是一个广播接收器BroadcastReceiver，不能保证你的进程在回调函数返回后仍然继续运行。如果你的AppWidget设置过程能持续几秒钟（比如当执行网页请求时）而且你要求你的进程继续，考虑在onUpdated()方法里启动一个服务Service。从这个服务里，你可以执行自己的AppWidget更新，而不必担心AppWidgetProvider由于一个应用程序无响应错误ApplicationNotResponding(ANR)而关闭。

接收AppWidget广播Intents

AppWidgetProvider只是一个简便类。如果你想直接接收AppWidget广播，你可以实现自己的BroadcastReceiver或者重写onReceive(Context,Intent)回调函数。你需要注意如下4个Intents

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED

创建一个AppWidget配置Activity

如果你想让用户在添加一个新的AppWidget时调整设置，你可以创建一个AppWidget配置Activity。这个Activity将被AppWidget宿主自动启动并允许用户在创建时配置可用的设置，比如AppWidget颜色，尺寸，更新周期或者其它功能设置。

这个配置活动应该在Android清单文件中声明为一个通用活动。不过，它将被通过ACTION_APPWIDGET_CONFIGUREaction而被AppWidget宿主启动，因此这个活动需要接受这个Intent。比如：

<activity android:name=".ExampleAppWidgetConfigure">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" />
    </intent-filter>
</activity>

当然，Activity必须在AppWidgetProviderInfoXML文件中声明，通过android:configure属性。比如，配置Activity可以声明如下：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigure" 
    ... >
</appwidget-provider>

注意这个活动是用全名声明的，因为它将从你的程序包外被引用。

这就是所有关于配置活动你一开始需要了解的。现在你需要一个真实的Activity。这儿就有，不过，当你实现这个活动时记住两件重要的事情：

• AppWidget宿主调用配置Activity而且配置Activity应该总是返回一个结果.这个结果应该包含这个通过启动该活动的意图传递的AppWidgetID(以EXTRA_APPWIDGET_ID保存在Intent的附加段Intentextras中)
• 当这个AppWidget被创建时将不会调用onUpdate()方法(当一个配置活动启动时,系统将不会发送ACTION_APPWIDGET_UPDATE广播).配置活动应该在AppWidget第一次被创建时负责从AppWidgetManager请求一个更新.不过,onUpdate()将在后续更新中被调用-只忽略第一次.

参见下面章节的代码片断,该示例说明了如何从配置中返回一个结果并更新这个AppWidget.

从配置Activity中更新一个AppWidget

当一个AppWidget使用一个配置Activity,那么当配置结束时,就应该由这个Activity来更新这个AppWidget.你可以直接通过AppWidgetManager请求一次更新操作.

下面是恰当的更新AppWidget以及关闭配置Activity这个过程的一个概要描述:

1.首先，从启动这个Activity的意图中获取AppWidgetID：

Intent intent = getIntent();
Bundle extras = intent.getExtras();
if (extras != null) {
    mAppWidgetId = extras.getInt(
            AppWidgetManager.EXTRA_APPWIDGET_ID, 
            AppWidgetManager.INVALID_APPWIDGET_ID);
}

2.实施你的AppWidget配置。

3.当配置完成后，通过调用getInstance(Context)获取一个AppWidgetManager实例:

AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

4.以一个RemoteViews布局调用updateAppWidget(int,RemoteViews)更新AppWidget:

RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
appWidgetManager.updateAppWidget(mAppWidgetId, views);

5.最后，创建返回Intent，设置到Activity结果，并结束这个Activity:

Intent resultValue = new Intent();
resultValue.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, mAppWidgetId);
setResult(RESULT_OK, resultValue);
finish();

提示:当你的配置Activity第一次打开时，设置Activity结果为RESULT_CANCELED。这样，如果用户在结束之前从Activity外返回，这个AppWidget宿主会接收到配置取消通知而不会添加这个AppWidget。