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一般是一個你在應用程序中分配的硬編碼的值。