Widgets基础篇（上）

文章参照自： http://developer.android.com/guide/topics/appwidgets/index.html

一、前言

所谓App Widgets就是微型应用程序的意思，它可以嵌入在其他应用程序（如主屏幕），并能定期更新其View。

这些View被当成用户界面的小部件，您可以使用App Widget provider来发布App Widgets。

一个能容纳其他的App Widgets的应用程序的组件，我们称之为App Widget host。 图1 就是一个音乐App Widget的截图。

图1

  在下面的文章中，我们将讲述如何使用App Widget provider来发布App Widget

二、基本原理

为了创建一个App Widget，你需要以下三部分：

AppWidgetProviderInfo

AppWidgetProviderInfo用于对App Widgets的元数据(metadata)进行描述，如App Widgets的布局，更新频率，和AppWidgetProvider类。它应该是在XML中定义。

AppWidgetProvider

AppWidgetProvider定义了一些基本方法，通过这些方法你可以很方便和App Widget进行交互。

AppWidgetProvider基于广播事件。当App Widget进行更新，启用，禁用和删除时，在AppWidgetProvider中，您将收到其对应的广播。

视图布局文件

为了让App Widget能进行显示，我们还需要为App Widget的提供一个布局文件

另外，你还可以实现一个用于对App Widget进行配置的Activity.该Activity是可选的，当用户添加App Widget时，该Acitivity将被启动。通过它可以在App Widget被创建时，做一些对App Widget的设置。这里的设置是指和App Widget的事务相关的设置，不是指AppWidgetProviderInfo的内容。

三、在Manifest中声明App Widget

首先，需要在你的应用程序的 AndroidManifest.xm 文件中声明一个 AppWidgetProvider 类， 比如示例1.

示例1

<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属性必须要进行设置, 该属性说明了我将使用哪个AppWidgetProvidere来提供App Widget。

<intent-filter>元素必须包含android:name属性为"android.appwidget.action.APPWIDGET_UPDATE"的Action，

即<action android:name="android.appwidget.action.APPWIDGET_UPDATE" />。该属性说明了AppWidgetProvider可以接收ACTION_APPWIDGET_UPDATE广播。

该广播是唯一你必须要声明接受的广播。AppWidgetManager能自动的把其他所有的App Widget广播发送到AppWidgetProvider

在<meta-data>元素中，必须要指定AppWidgetProviderInfo资源文件，必须要定义以下2个属性:

    * android:name - 它用于定义metadata元素的名字. 必须把该属性设置为“android.appwidget.provider”以表明该<meta-data>元素是用于描述AppWidgetProviderInfo资源文件位置的.

    * android:resource -该属性用于说明AppWidgetProviderInfo资源文件的位置。

四、编写AppWidgetProviderInfo配置文件

AppWidgetProviderInfo用于定义App Widget的基本属性，如显示的最小尺寸，其初始布局资源，更新频率，

和（可选）configuration Activity，该Activity将在其App Widget被创建时被启动。 

AppWidgetProviderInfo的定义必须在一个只有单一的<appwidget-provider>元素的XML资源文件中进行，该文件必须放在res/xml目录下。

示例2 ：

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

    android:minWidth="294dp"

    android:minHeight="72dp"

    android:updatePeriodMillis="86400000"

    android:previewImage="@drawable/preview"

    android:initialLayout="@layout/example_appwidget"

    android:configure="com.example.android.ExampleAppWidgetConfigure" 

    android:resizeMode="horizontal|vertical">

</appwidget-provider>

以下是关于<appwidget-provider>一些属性的介绍：

minWidth 和 minHeight 属性用于说明App Widget在屏幕上至少要占用多大的空间 。

默认的Home screen在放置App Widgets时，是以网格为基本单位，而不是以像素，这里的网格是指拥有一定的像素的长方形区域。

因为home屏幕的布局方向可能改变（网格的大小就会随之改变），所以你应该考虑最坏的情况，此时网格拥有74个像素的长和高。

然而你必须减去2个像素，以便避免在计算网格数量时，对像素进行取整，发生错误。

你应该使用下面的公式计算android:minWidth和android:minHeight：

(number of cells * 74) - 2

根据上面的公式，如果想你的App Widget占用4个网格的宽，1个网格的高话，那么android:minWidth和android:minHeight应该分别为"294dp"和"72dp"

注意：为了让你的App Widget能在各类平台上运行，你的App Widget不要超过4X4网格的尺寸。关于App Widget的设计的更多内容请参考 App Widget Design Guidelines

updatePeriodMillis 属性用于说明App Widget框架请求 AppWidgetProvider 的 onUpdate() 方法来更新 App Widget 的频率。但是这个频率是无法完全保证的，我们建议尽量减少更新的频率。有时可能一小时才更新一次，以便节约电池。你也可以提供一个配置，让用户自己设置更新的频率。有些人可能想15分钟就更新股票的价格，而有些人仅想1天就更新股票4次。

注意：如果手机在处于休眠状态时，而对App Widget进行更新的时间有到了，这时设备将醒来以便进行App Widget的更新。如果更新频率低于一个小时一次的话，并不会引起明显的电池消耗。如果你的更新非常频繁或你不想手机在处于休眠时还进行App Widget更新的话，请通过一个alarm来进行更新。你可以用 AlarmManager 来设置一个定期发送 AppWidgetProvider 的Intent的Alarm,且把Alarm的类型设置为 ELAPSED_REALTIME or RTC，这两种类型的Alarm只有在系统处于awake状态才会发送。另外此时，要把 android:updatePeriodMillis设置为"0"

initialLayout属性用于设置App Widget的布局文件。

configure属性用于说明在App Widget在被添加到Home Screen时，哪个configure Activity将首先启动。这是一个可选属性，关于次的更多内容请阅读后文。

previewImage属性在Android 3.0版本中才被添加，它用于指明 App  Widget的预览图片，它用于在用户选中该App Widget的图标，打算添加该App Widget时，进行显示，以便用户了解该App Widget的界面。如果没提供预览图标的话，显示的将是你的App Widget的启动图标。该属性和AndroidManifest.xml中的<receiver>元素的android:previewImage的属性一致。关于此的更多内容请参照后文。

The autoAdvanceViewId attribute specifies the view ID of the app widget subview that should be auto-advanced by the widget's host. Introduced in Android 3.0.

resizeMode属性在Android 3.1中才被添加，它用于说明App Widget重新调整大小的规则。通过该属性，你可以设置在什么方向允许调整App Widget的大小，可以是垂直、水平、或同时垂直和水平两个方向。用户可以按住App Widget来显示大小调整handle，通过在水平或垂直方向拖动handle来调整

App Widget在垂直或水平方向的尺寸。resizeMode属性的值可以是"horizontal", "vertical", "none"和"horizontal|vertical"

icon属性用于说明你的AppWidget在AppWidget picker列表中显示的图标，它应该和AndroidManifest.xml中的<receiver>元素的android:icon的属性一致

label属性用于说明你的AppWidget在AppWidget picker列表中显示的名字，它应该和AndroidManifest.xml中的<receiver>元素的android:label的属性一致。

关于<appwidget-provider>属性的更多内容请参照 AppWidgetProviderInfo

五、编写App Widget布局文件

你必须在XML文件中定义你的App Widget的布局文件，并把它保存在res/layout/目录下。你可以在 App Widget中使用如下的View,但是请你在开始你的App Widget的布局时请阅读 App Widget Design Guidelines.

如果你熟悉在XML中如何进行布局文件的编写，那么编写App Widget布局文件将非常的简单。因为App Widget的布局是基于 RemoteViews对象, 所以它并不能支持所有的View.

RemoteViews对象支持如下的一些View及其子类:

• FrameLayout
• LinearLayout
• RelativeLayout

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