Android开发之App Widget的学习及使用

• • （如下为本人对于官方文档的理解，能力有限，有错还望指出）

    一、首先，咱们先阅读下官方文档，后面活给出Demo程序

    App Widgets（应用程序 小工具，窗口小部件）

    App Widgets are miniature application views that can be embedded in other applications (such as the Home screen) and receive periodic（周期的，按期的） updates. These views are referred to as Widgets in the user interface, and you can publish one with an App Widget provider. An application component that is able to hold other App Widgets is called an App Widget host. The screenshot below shows the Music App Widget.

    应用程序窗口小部件是一个迷你的应用程序视图，它能够被嵌入在其余的应用程序中（如主屏幕）接收按期的更新。在用户接口中这些控件被归类为窗口小部件，你能够发布一个应用程序窗口小部件提供者。一个可以去持有其余应用程序窗口小部件的应用程序组件被称为应用程序窗口小部件宿主（后面给出app widget host 的官方文档的解析）。下面的屏幕快照展现了一个音乐窗口小部件

    This document describes how to publish an App Widget using an App Widget provider. For a discussion of creating your ownAppWidgetHostto host app widgets, see App Widget Host.

    本文档描述了如何使用窗口小部件提供者去发布一个窗口小部件。讨论建立你本身的AppWidgetHost 去红纸窗口小部件。看 App Widget Host

    Widget Design

    窗口小部件设计

    For information about how to design your app widget, read theWidgets design guide.

    对于如何去设计你本身的窗口小部件程序，请阅读这Widget的设计向导

    The Basics

    基本的

    To create an App Widget, you need the following:

    去建立一个窗口小部件程序，你须要如下的东西

    AppWidgetProviderInfo object AppWidgetProviderInfo 对象 Describes the metadata for an App Widget, such as the App Widget's layout, update frequency, and the AppWidgetProvider class. This should be defined in XML. 描述了窗口小部件程序的元素据，例如程序的布局，更新频率，还有AppWidgetProvider 类，这应该在xml中定义   AppWidgetProvider class implementation AppWidgetProvider 类的实现 Defines the basic methods that allow you to programmatically（编程，以编程的方式） interface with the App Widget, based on broadcast events. Through it, you will receive broadcasts when the App Widget is updated, enabled, disabled and deleted. 容许你基于广播事件为窗口小部件程序用编写接口去定义基本的方法，经过它，当着窗口小部件程序更新，启用，禁用，删除的时候，你将接受到广播通知。   View layout 视图布局

          Defines the initial layout for the App Widget, defined in XML.

    在xml中为窗口小部件程序定义初始化布局

    Additionally, you can implement an App Widget configuration Activity. This is an optionalActivitythat launches when the user adds your App Widget and allows him or her to modify App Widget settings at create-time.

    The following sections describe how to set up each of these components.

    此外，你能够实现应用程序窗口小部件配置Activity。当用户添加你的应用程序窗口小部件并容许他或者她去修改应用程序窗口小部件建立时间的设置时这是一个可选的启动activity，

    Declaring an App Widget in the Manifest

    应用程序小部件Manifest文件的说明

    First, declare theAppWidgetProviderclass in your application'sAndroidManifest.xmlfile. For example:

    第一，在你的应用程序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>

    The<receiver>element requires theandroid:nameattribute, which specifies theAppWidgetProviderused by the App Widget.

    这个<receiver>元素要求有android:name属性，它制定了应用程序小部件所使用的AppWidgetProvider

    The<intent-filter>element must include an<action>element with theandroid:nameattribute. This attribute specifies that theAppWidgetProvideraccepts theACTION_APPWIDGET_UPDATEbroadcast. This is the only broadcast that you must explicitly（明确的，明白的） declare. TheAppWidgetManagerautomatically sends all other App Widget broadcasts to the AppWidgetProvider as necessary.

    这个<intent-filter>元素必须包括一个有android:name属性的<action>元素，这个属性制定AppWidgetProvider接收这ACTION_APPWIDGET_UPDATE广播，你必须惟一明确的声明这个广播。这AppWidgetManager自动发送全部其余应用程序小部件的广播到AppWidgetProvider，这是必要的。

    The<meta-data>element specifies theAppWidgetProviderInforesource and requires the following attributes:

    • android:name- Specifies the metadata name. Useandroid.appwidget.providerto identify the data as theAppWidgetProviderInfodescriptor.

    这<meta-data>元素制定这AppWidgetProviderInfo 资源和要求如下的属性：

    android:name制定这个元素据名称，用android.appwidget.provider去标识数据做为AppWidgetProviderInfo的描述符（我的理解为别称）

    • android:resource- Specifies theAppWidgetProviderInforesource location.

    android:resource指定这AppWidgetProviderInfo资源的位置

    Adding the AppWidgetProviderInfo Metadata

    增长AppWidgetProviderInfo 元数据

    TheAppWidgetProviderInfodefines the essential qualities of an App Widget, such as its minimum layout dimensions, its initial layout resource, how often to update the App Widget, and (optionally) a configuration Activity to launch at create-time. Define the AppWidgetProviderInfo object in an XML resource using a single<appwidget-provider>element and save it in the project'sres/xml/folder.

    AppWidgetProviderInfo 定义了应用程序窗口小部件的基本属性，例如其最低限度的布局大小，其初始化布局资源，若是常常的更新应用程序窗口小部件，和一个可选的配置建立时间让Activity去启动。在一个xml资源文件中用一个单一的<appwidget-provider>元素定义AppWidgetProviderInfo对象并保存在项目的res/xml/文件夹。

    For example:

    例如

    <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"     android:minWidth="40dp"     android:minHeight="40dp"     android:updatePeriodMillis="86400000"     android:previewImage="@drawable/preview"     android:initialLayout="@layout/example_appwidget"     android:configure="com.example.android.ExampleAppWidgetConfigure"     android:resizeMode="horizontal|vertical"     android:widgetCategory="home_screen"> </appwidget-provider>

    Here's a summary of the<appwidget-provider>attributes:

    这是一个简易的<appwidget-provider>属性

    • The values for theminWidthandminHeightattributes specify the minimum amount of space the App Widget consumes by default. The default Home screen positions App Widgets in its window based on a grid of cells that have a defined height and width. If the values for an App Widget's minimum width or height don't match the dimensions of the cells, then the App Widget dimensions round up to the nearest cell size.

    这最小宽度和最小高度的属性的值指定这个应用程序创口小部件默认消耗的最小空间资源。默认在的主屏幕中应用程序窗口小部件的位置是基于一个被定义有高度和宽度的网格。若是这个应用程序窗口小部件的最小宽度和最小高度的值不匹配这个网格单元的大小。此时这个应用程序窗口小部件的大小就会四舍五入到最接近这个网格的大小

    See the App Widget Design Guidelines for more information on sizing your App Widgets.

    更多关于应用程序窗口小部件大小的信息请看 应用程序创口小部件设置向导App Widget Design Guidelines

    Note: To make your app widget portable across devices, your app widget's minimum size should never be larger than 4 x 4 cells.

    提示：为了让你的应用程序窗口小部件可以移植到多种设备，你的应用程序窗口小部件的最小大小不该大于4x4个网格单元

    • TheminResizeWidthandminResizeHeightattributes specify the App Widget's absolute minimum size. These values should specify the size below which the App Widget would be illegible or otherwise unusable. Using these attributes allows the user to resize the widget to a size that may be smaller than the default widget size defined by theminWidthandminHeightattributes. Introduced in Android 3.1.

    这 minResizeWidth 和minResizeHeight 属性指定了这个应用程序创口小部件的绝对大小。这些值应该指定 应用程序小部件的大小低于不可识别的或者其余不可用的。使用这些属性容许用户去从新定义这个窗口小部件的大小，其大小能够比默认的窗口小部件的最宽，最高属性的值要小。其在android3.1中被引入。

    • See the App Widget Design Guidelines for more information on sizing your App Widgets.

    • 更多关于应用程序窗口小部件大小的信息请看 应用程序创口小部件设置向导App Widget Design Guidelines

    • TheupdatePeriodMillisattribute defines how often the App Widget framework should request an update from theAppWidgetProviderby calling theonUpdate()callback method. The actual update is not guaranteed to occur exactly on time with this value and we suggest updating as infrequently as possible—perhaps no more than once an hour to conserve the battery. You might also allow the user to adjust the frequency in a configuration—some people might want a stock ticker to update every 15 minutes, or maybe only four times a day.

    updatePeriodMillis属性定义了一般这个应用程序窗口小部件框架应如何经过调用这个onUpdate()回调方法请求AppWidgetProvider的更新.实际的在某个时间正确的发生更新事件是没有被保证的，因此咱们建议更新尽量少--可能一个小时不超过一次，这样能够节省电能。你可能会容许用户在配置中去调整频率--人们可能但愿股票每15分钟更新一次，或者一天只更新四次

    Note: If the device is asleep when it is time for an update (as defined byupdatePeriodMillis), then the device will wake up in order to perform the update. If you don't update more than once per hour, this probably won't cause significant problems for the battery life. If, however, you need to update more frequently and/or you do not need to update while the device is asleep, then you can instead perform updates based on an alarm that will not wake the device. To do so, set an alarm with an Intent that your AppWidgetProvider receives, using theAlarmManager. Set the alarm type to eitherELAPSED_REALTIMEorRTC, which will only deliver the alarm when the device is awake. Then setupdatePeriodMillisto zero ("0").

    注意:若是设备处于睡眠状态的时候发生了更新事件（例如经过updatePeriodMillis定义），那么这个设备会被唤醒以便去执行更新操做。若是你每小时更新不超过一次，这可能就不会对电池的寿命形成严重的影响。然而，若是你须要更频繁地去更新以及可能在你设备处于睡眠状态时你不须要更新。这时候你能够基于一个不会唤醒设备的警报（alarm）替换原来的模式去执行更新操做。为此，使用AlarmManager去用一个你本身的AppWidgetProvider去接收的意图（Intent）去设置一个警报。设置这个alarm报警类型为ELAPSED_REALTIME或者RTC,这个类型将只去驱动这个报警当设备被唤醒时。而后设置updatePeriodMillis 为0

    • TheinitialLayoutattribute points to the layout resource that defines the App Widget layout.

    布局资源文件中initialLayout属性点定义了这个应用程序创口小部件的布局资源。

    • Theconfigureattribute defines theActivityto launch when the user adds the App Widget, in order for him or her to configure App Widget properties. This is optional (read Creating an App Widget Configuration Activitybelow).

    在用户增长应用程序小部件的时候这个configure属性定义了启动的Activity，这是可选的（阅读Creating an App Widget Configuration Activity下面）

    • ThepreviewImageattribute specifies a preview of what the app widget will look like after it's configured, which the user sees when selecting the app widget. If not supplied, the user instead sees your application's launcher icon. This field corresponds to theandroid:previewImageattribute in the<receiver>element in theAndroidManifest.xmlfile. For more discussion of usingpreviewImage, see Setting a Preview Image. Introduced in Android 3.0.

    配置previewImage属性后该属性将指定当用户选择这个应用程序小部件时的预览样子。若是不提供这个属性，用户看到的是程序的启动图标。在AndroidManifest.xml文件的<receiver>元素中对应的属性为android:previewImage。对于更多使用previewImage的讨论，请看Setting a Preview Image. 在Android 3.0 中引入

     

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

    autoAdvanceViewId属性指定了应用程序窗口小部件子视图的ID

    • TheresizeModeattribute specifies the rules by which a widget can be resized. You use this attribute to make homescreen widgets resizeable—horizontally, vertically, or on both axes. Users touch-hold a widget to show its resize handles, then drag the horizontal and/or vertical handles to change the size on the layout grid. Values for theresizeModeattribute include "horizontal", "vertical", and "none". To declare a widget as resizeable horizontally and vertically, supply the value "horizontal|vertical". Introduced in Android 3.1.

    resizeMode属性指定一个窗口小部件能够被调整大小的规则。使用这个属性让主屏幕的窗口小部件在水平方向或者垂直方向或者两个方向一块儿重置其外形大小。用户点击操控一个窗口小部件去显示其调整大小的操做，而后在网格布局中水平或者垂直方向拖拽去改变控件的大小。resizeMode实行的值包括"horizontal", "vertical", and "none".。使用"horizontal|vertical".去声明一个窗口小部件的大小是可在水平或者垂直方向课重置的。在android 3.1中引入

    • TheminResizeHeightattribute specifies the minimum height (in dps) to which the widget can be resized. This field has no effect if it is greater thanminHeightor if vertical resizing isn't enabled (seeresizeMode). Introduced in Android 4.0.

    minResizeHeight属性指定了可被重置大小的窗口小部件的最小高度（以dps为单位）。若是控件高度大远远大于最小高度或者若是在垂直方向重置大小是不被容许的，那么将不会有影响。android 4.0 中引入

    • TheminResizeWidthattribute specifies the minimum width (in dps) to which the widget can be resized. This field has no effect if it is greater thanminWidthor if horizontal resizing isn't enabled (seeresizeMode). Introduced in Android 4.0.

    minResizeWidth 属性指定了可被重置大小的窗口小部件的最小宽度（以dps为单位）。若是其控件宽度远远大于最小宽度或者若是在水平方向重置大小是不被容许的，那么该属性将不产生影响，Android 4.0中引入

    • ThewidgetCategoryattribute declares whether your App Widget can be displayed on the home screen (home_screen), the lock screen (keyguard), or both. Only Android versions lower than 5.0 support lock-screen widgets. For Android 5.0 and higher, onlyhome_screenis valid.

    widgetCategory属性声明你的应用程序窗口小部件是否能够显示在主屏幕(home_screen),锁屏(键盘守卫),或二者都有。只有安卓版本低于5.0支持锁定屏幕窗口小部件。Android 5.0和更高版本中,只有home_screen是有效的。

    See theAppWidgetProviderInfoclass for more information on the attributes accepted by the<appwidget-provider>element.

    对于可被<appwidget-provider>接受属性可看AppWidgetProviderInfo 类的更多信息

     

    App Widget Host— The AppWidgetHost provides the interaction with the AppWidget service for apps, like the home screen, that want to embed app widgets in their UI. An AppWidgetHost must have an ID that is unique within the host's own package. This ID remains persistent across all uses of the host. The ID is typically a hard-coded value that you assign in your application.

    窗口小部件宿主--这AppWidgetHost（例如主屏幕） 提供了与窗口小部件服务程序的交互，使窗口小部件程序可以嵌入在它的UI界面中。一个窗口小部件宿主在本身的包中必须有一个惟一的ID。ID将一直持久化在全部使用的主机里面。ID一般是一个你在应用程序中分配的硬编码的值。