android widget的中文文檔

元素指定了AppWidgetProviderInfo的信息並且必須包含下面兩個信息。

android:name:這個屬性指定了元數據的名稱。使用android.appwidget.provider來指定數據作為AppWidgetProviderInfo的描述信息。

anndroid:resources 來指定AppWidgetProviderInfo描述信息的位置。

3.添加AppWidgetProviderInfo的元數據

AppWidgetProviderInfo定義了App Widget的基本信息，例如布局尺寸的最小值，和初始化布局文件的資源，更新app widget的頻率，同時你還可以定義在創建widget的時候啟動一個activity，這一項是可選的。你需要在res下新建一個xml目錄，在這個目錄中創建一個xml文件，這個xml文件的根元素必須要是，例如下面的例子。

minWidth和minHeight屬性指定了app widget布局文件所需要最小尺寸。

在主屏幕上放置的app widget取決於定義了寬和高的網格，如果我們自定義的最小寬或者高不和屏幕網格中的格子不匹配，那麼app widget的尺寸會自動的變成與當前格子最匹配的尺寸，因為屏幕的方向是可以改變的，因此網格格子尺寸大小也是可以變化的，所以建議你假設格子的寬和高的值為74像素，同時，你應該從最終的尺寸計算中減去2,因為可能會出現的像素計算問題。為了計算出最佳的寬和高，建議你使用下面的公式。

(number of cells * 74) - 2

因此，可以使用72來作為一個app widget的高，使用294來作為一個app widget的寬，寬度包含了四個格子。

updatePeriodMillis屬性定義了app widget要求調用AppWidgetProvider 實現類的onUpdate方法的頻率。但是並不能保證能夠在准確的時間去調用這個更新方法，我們建議這個更新的周期越大越好，從省電的角度來看，一個小時不要超過一次。你也應該允許用戶去配置這個調用的周期，例如有人需要每一刻鐘去更新證券的信息，有的人可能一天只更新四次。注意：如果到了更新的時候，設備正處於休眠期，那麼設備將會被喚醒去完成這次更新。如果你一個小時以內更新的頻率低於一次，那麼這將不會對你的電池造成什麼明顯的影響，如果你更新的十分頻繁，或者不需要在設備休眠的時候更新，那麼建議你使用鬧鐘來完成這個功能，在鬧鐘中你可以設定是否需要喚醒設備。你可以設定鬧鐘的類型為ELAPSED_REALTIME或者RTC,這將只在設備處於喚醒狀態進行更新。那麼在這種情況下，你可以設定updatePeriodMillis為0

initiaLayou屬性指定了app widget的布局文件。

configure屬性指定了當用戶創建一個app widget的時候需要啟動的activity,這個屬性允許用戶去設定app widget的屬性.。這一項是可選的。

4.創建App Widget的布局文件

必須定義一個在res/layout中定義一個布局文件，來作為app widget的初始化布局文件。你可以使用下面列表中出現的View對象來作為布局文件。

如果你屬性創建布局文件，那麼創建一個app widget的布局文件同樣是一個很簡單的事情，但是需要注意的事情是app widget的布局是基於RemoteViews的，這些並不是支持所有的布局文件，只有下面三種是被支持的：FrameLayout,LinearLayout和RelativeLayout，同時下面這七種Widget對象也是被支持的：AnalogClock,Button,Chronometer,ImageButton,ImageView,ProgressBar和TextView。

5.使用AppWidgetProvider class

AppWidgetProvider 類繼承了BroadcastReceiver，這樣方便於去處理App Widget廣播，AppWidgetProvider類只處理與App Widget相關的廣播，例如當app widget 發生以下的事件updated,deleted,endabled和disabled。當這些廣播事件發生以後，AppWidgetProvider會調用這些方法

onUpdate(Context context,AppWidgetManager,int [] widgetids) 這個方法會在updatePeriodMillis屬性定義的時間周期類調用，當用戶添加新的App Widget的時候，這個方法也會被調用。因此在這個方法裡面需要執行一些必要的設置，例如設定一個視圖的事件處理器或者啟動一個臨時的服務。但是，如果你為app widget添加了啟動的activity，那麼在用戶添加app widget的時候，這個方法不會被執行，但是在隨後的更新中，這個方法會被執行。在完成配置任務的activity完成配置的時候要執行一次更新。

onDeleted(Context context,int [] widgetsid)每當App Widget被刪除的時候調用

onEnabled(Context context)這個方法只會在第一次創建app widget的時候被調用，例如，當用戶創建了兩個app widget，這個方法只會在創建第一個app widget的時候被調用，如果你需要使用數據庫或者其他只需要只執行一次的設定，那麼你可以將它們放在這個方法裡面調用。當最後一個app widget實例被刪除的時候，這個方法會被調用。在這裡你可以完成一些必要的清理工作。

onReceive(Context context,Intent intent)這個方法在收到關於app widget的廣播之後並且在上面所有的方法調用之前被調用，實際上你並不需要自己去實現這個方法，因為在AppWidgetProvider提供的默認實現中，會根據系統的廣播來在上面的方法選擇一個調用。

在AppWidgetProvider所有的方法中最重要的是Onupdate方法，因為每次添加一個app widget的都會被調用，除非你為你的app widget配置了一個activity.如果你的app widget需要處理與用戶的交互事件，那麼你也許需要在這個方法中定義一個事件處理的handler，如果你的app widget不需要創建臨時性的文件或者其他需要在最後處理的任務，那麼你或許僅僅需要在onupdate中來定義自己業務處理邏輯，其他的方法空實現即可。例如，當你的app widget中包含一個button，當點擊button的時候，需要啟動一個activity，那麼下面的示例可以供你參考。

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這個AppWidgetProvider實現類僅僅定義了onupdate方法，在這個方法中我們定義了一個可以啟動activity的PendingIntent，我們點擊了注冊了setOnClickPendingIntent()方法的button時，會啟動我們定義的activity.需要注意的是，在這個方法裡面包含了對appwidgetids數組的遍歷，這個數組是當我們創建app widget的時候AppWidgetProvider為我們創建的。此外，當用戶創建了不止一個app
 widget的時候，這些app widget會全部同時的更新。但是針對更新的頻率我們只能定義一個updatePeriodMillis屬性。例如當我們設定更新周期為兩個小時一次，我們創建兩個app widget之間相隔了一個小時，那麼第二個被添加的app widget也會在第一個app widget 被添加兩個小時之後更新。第二個的更新周期會被忽略。

       注意：因為AppWidgetProvider是繼承與BroadcastReceiver,你的進程在這些方法返回之後並不能保證會繼續執行，如果你的進程需要進行耗時的操作，那麼請考慮一下在onupdate方法中啟動一個service，在這個service中，你可以考慮繼續進行你需要完成的工作而不需要擔心ANR



6.接收到的App Widget 廣播意圖
AppWidgetProvider是一個方便用來處理接收到的AppWidget 廣播的類。如果你需要直接接受到App Widget的廣播，那麼你可以實現你自己的BroadcastReceiver或者重寫onReceiver方法。下面這四種意圖是你需要關心的。
ACTION_APPWIDGET_UPDATE   ACTION_APPWIDGET_DELETED ACTION_APPWIDGET_ENABLED  ACTION_APPWIDGET_DISABLED



7.為app widget 添加啟動的activity
如果你想在用戶創建一個app widget的時候可以配置app widget的基本信息，你可以為app widget配置一個activity，用戶可以通過這個activity來配置widget 的更新頻率，大小，顏色或者其他功能性的設置。
這個配置性的Activity同樣需要在AndroidManifest.xml文件中進行聲明，但是這個activity需要對android.appwidget.action.APPWIDGET_CONFIGURE 進行過濾。如下面的示例

    
        
    


同樣需要在AppWidgetProviderInfo xml文件中定義這個activity的信息。示例如下：

類的名稱一定是全限定名稱，因為你可能引用了其他包的類。這些就是啟動activity所需要的。現在你需要的就是一個繼承了Activity的類，但是你還需要注意下面兩點。

①這個activity需要返回一個結果，這個結果中包含了intent傳遞過來的App Widget ID
        ②當app widget被創建的時候 onupdate方法不會被執行，因為在啟動activity的時候，系統不會發出 ACTION_APPWIDGET_UPDATE廣播，那麼當加載activity之後，activity需要主動去要求一次更新app widget。否則出了第一次會被跳過意外，後面的更新會被執行。
下面給出了配置activity實現。



8.通過activity更新app widget
    如果創建app widget的時候使用了activity，那麼在activity配置結束的時候應該主動要求更新一次app widget。可以通過AppWidgetManager來完成一次更新的請求。
下面是要求更新app widget的步驟。
①首先通過啟動Activity的intent 獲取App Widget id
 
Intent intent = getIntent();
Bundle extras = intent.getExtras();
if (extras != null) {
    mAppWidgetId = extras.getInt(
            AppWidgetManager.EXTRA_APPWIDGET_ID, 
            AppWidgetManager.INVALID_APPWIDGET_ID);
}
②完成用戶配置的設置。

③當配置完成以後，通過調用AppWidgetManager的getIntance(Context context)來得到AppWidgetManager的實例。

AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

④通過RemoteViews並且調用AppWidgetManager實例的updateAppWidget方法來完成更新。

RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
appWidgetManager.updateAppWidget(mAppWidgetId, views);
⑤最後創建一個返回的Intent


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




上面的翻譯來自於個人的理解，部分語言實在是不知道怎麼翻譯，希望大家多多指點。