Android API Guides---App Widget Host

Android API Guides---App Widget Host

應用的Widget主機
大多數Android設備上可用的Andr??oid主屏幕允許用戶嵌入應用小工具，以便快速訪問的內容。如果你正在構建一個家庭更換或類似的應用程序，也可以允許用戶通過實現AppWidgetHost嵌入應用程序部件。這不是大多數應用程序都不會需要做的事情，但如果你正在創建您自己的主機，它了解合同義務的主機隱含同意是非常重要的。

本文件的重點參與實施定制AppWidgetHost的責任。對於如何實現一個AppWidgetHost示例，請參見為Android主屏幕啟動的源代碼。

這裡是參與實施定制AppWidgetHost關鍵類和概念的概述：

應用的Widget HOST-的AppWidgetHost提供與AppWidget服務的應用程序，如主屏幕，希望嵌入應用小部件在其UI交互。一個AppWidgetHost必須有一個ID，它是主機自己的包中是唯一的。此ID在跨越主機的所有使用持久性。該ID通常是在應用程序中指定一個硬編碼值。
應用小工具ID-每個應用插件實例是在結合的時間分配了一個唯一的ID（見bindAppWidgetIdIfAllowed（），更詳細地在裝訂應用程序窗口小部件所討論的）。唯一ID是通過使用allocateAppWidgetId（）主機獲得。該ID是橫跨插件，即的壽命持久，直到它從主機中刪除。任何特定的主機的狀態（例如大小和小部件的位置）應當由主機包被持久並與該應用微件ID相關聯。
應用程式的widget主機取景AppWidgetHostView可以被認為是一幀，該插件是包裹在每當需要將其顯示出來。應用程式插件每小部件是由主機充氣時間分配給AppWidgetHostView。
選項??Bundle-該AppWidgetHost使用選項束將信息傳達給所述AppWidgetProvider如何正在顯示微件（例如，尺寸范圍，以及是否該窗口小部件上的鎖定屏幕或主屏幕）。該信息允許AppWidgetProvider的基礎上如何以及在哪裡顯示定制Widget的內容和外觀。您可以使用updateAppWidgetOptions（）和updateAppWidgetSize（）來修改應用程序widget的包。這兩種方法觸發一個回調至AppWidgetProvider。
結合應用小工具


當用戶將某個應用插件到主機時，發生所謂的裝訂處理。結合是指一種特定的應用微件ID，以一個特定的主機和一個特定AppWidgetProvider相關聯。有實現這一目標，取決於什麼版本的Andr??oid您的應用程序上運行的不同方式。


在Android 4.0和更低的結合應用小工具

在運行Android 4.0版和更低的設備，用戶通過系統的活動，允許用戶選擇一個小部件添加應用程序部件。這含蓄地做了權限檢查，也就是說，通過將應用程序窗口小部件，用戶被隱性授予權限，以您的應用程序小部件添加到主機。這裡是示出該方法中，從原來的啟動器所采取的示例。在這個片段中，一個事件處理程序調用startActivityForResult（）在響應用戶操作的請求代碼REQUEST_PICK_APPWIDGET：

private static final int REQUEST_CREATE_APPWIDGET = 5;
private static final int REQUEST_PICK_APPWIDGET = 9;
...
public void onClick(DialogInterface dialog, int which) {
  switch (which) {
  ...
    case AddAdapter.ITEM_APPWIDGET: {
      ...
      int appWidgetId = 
          Launcher.this.mAppWidgetHost.allocateAppWidgetId();
      Intent pickIntent = 
          new Intent(AppWidgetManager.ACTION_APPWIDGET_PICK);
      pickIntent.putExtra
          (AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
      ...
      startActivityForResult(pickIntent, REQUEST_PICK_APPWIDGET);
      break;
  }
  ...
}

當系統活動結束時，它返回與用戶選擇的應用小工具，你的活動的結果。在下面的例子中，該活動通過調用廣告AppWidget（）添加應用程序部件響應：

public final class Launcher extends Activity 
    implements View.OnClickListener, OnLongClickListener {
  ...
  @Override
  protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    mWaitingForResult = false;

    if (resultCode == RESULT_OK && mAddItemCellInfo != null) {
      switch (requestCode) {
        ...
        case REQUEST_PICK_APPWIDGET:
          addAppWidget(data);
          break;
        case REQUEST_CREATE_APPWIDGET:
          completeAddAppWidget(data, mAddItemCellInfo, !mDesktopLocked);
          break;
        }
    } 
    ...
  }
}

該方法添加AppWidget（）檢查是否應用程序部件需要它添加之前配置：

void addAppWidget(Intent data) {
  int appWidgetId = data.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, -1);

  String customWidget = data.getStringExtra(EXTRA_CUSTOM_WIDGET);
  AppWidgetProviderInfo appWidget = 
      mAppWidgetManager.getAppWidgetInfo(appWidgetId);

  if (appWidget.configure != null) {
    // Launch over to configure widget, if needed.
    Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_CONFIGURE);
    intent.setComponent(appWidget.configure);
    intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
    startActivityForResult(intent, REQUEST_CREATE_APPWIDGET);
  } else {
    // Otherwise, finish adding the widget.
  }
}

有關配置的詳細討論，請參閱創建應用程序窗口小部件配置活動。
一旦應用小工具已准備就緒，下一步就是做它添加到工作區的實際工作。原來發射使用的方法稱為完全加AppWidget（）來做到這一點。
在Android4.1及更高的結合應用小工具
搭載Android 4.1增加了API，用於一個更精簡的綁定過程。這些API也有可能使一台主機綁定提供自定義UI。要使用此改進方法，您的應用程序必須申報在其清單中BIND_APPWIDGET權限：

但是，這僅僅是第一步。在運行時，用戶必須明確授予權限，您的應用程序，使其能夠應用小部件添加到主機。要測試你的應用程序是否有權限新增的小工具，可以使用bindAppWidgetIdIfAllowed（）方法。如果bindAppWidgetIdIfAllowed（）返回false，您的應用程序必須顯示一個對話框，提示用戶授予權限（“允許”或“總是允許”，以涵蓋所有未來的應用小工具添加）。這段代碼提供了如何顯示對話框的例子：

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle discussed above
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

主機也必須檢查用戶是否補充說，需要配置一個應用程序部件。有關此主題的更多討論，請參閱創建應用程序窗口小部件配置活動。
主持人職責
什麼版本你定位？
您實現您的主機使用的方法應該取決於你的目標是什麼Android版本。許多本節所述的功能在3.0或更高版本進行了介紹。例如：
Android 3.0的（API等級11）介紹了小部件自動推進的行為。
Android的3.1（API等級12）引入了調整部件的能力。
搭載Android 4.0（API等級15）引入該把責任在主機上管理填充填充政策的改變。
搭載Android 4.1（API等級16）增加了一個API，允許小部件供應商，以獲取有關在其控件實例被托管環境的更多詳細信息。
Android的4.2（API等級17）推出期權包和bindAppWidgetIdIfAllowed（）方法。還引入了鎖屏小部件。
如果你的目標早期設備，參考原始啟動作為一個例子。
插件開發者可以指定使用AppWidgetProviderInfo元數據窗口小部件的一些配置設置。這些配置選項，在下面更詳細討論的，可以通過從與小窗口提供者關聯的AppWidgetProviderInfo對象主機進行檢索。
無論你的目標了Android版本，所有主機具有以下職責：
當添加窗口小部件，則必須按照上述分配部件ID。您還必須確保當一個小部件從主機中刪除，你可以調用deleteAppWidgetId（）來釋放小部件ID。
當添加窗口小部件，可以肯定如果存在推出配置活動，如從配置活動更新應用程序窗口小部件描述。這是許多應用小部件的必要步驟可以正確顯示前。
每一個應用程序窗口小部件指定的dps的最小寬度和高度，如AppWidgetProviderInfo定義元數據（采用了android：了minWidth和android：了minHeight）。確保小部件至少有這麼多的dps布局。例如，許多主機對齊柵格圖標和窗口小部件。在這種情況下，在默認情況下，主機應使用滿足了minWidth和了minHeight約束單元的最小數量添加的應用部件。
除了上面列出的要求，具體版本的平台引入放置在主機上新的責任功能。這些將在以下各節中描述。
Android 3.0的
Android 3.0的（API等級11）介紹了一個小工具，指定autoAdvanceViewId（）的能力。此視圖ID應指向一個可前進，如StackView或AdapterViewFlipper的一個實例。這表明主機應該呼吁這種觀點提前（）的間隔認為適當的主機（考慮到是否有意義推進小部件，例如，主機可能不希望，如果它提前一個小部件是另一個頁上，或如果屏幕被關閉）。
Android版3.1
Android的3.1（API等級12）引入了調整部件的能力。一個小部件可以指定它使用Android是可調整大小：在AppWidgetProviderInfo元resizeMode屬性，並說明它是否支持水平和/或垂直大小調整。在Android 4.0的（API級別14）介紹，小部件也可以指定一個機器人：minResizeWidth和/或Android：minResizeHeight。
它是主機的責任，這使該插件被水平和/或垂直地調整，由插件規定的。這說明它是可以調整大小可以調整任意大，但不應該比大小由Android規定值小的部件：minResizeWidth和android：minResizeHeight。有關示例實現，請參閱AppWidgetResizeFrame中的launcher2。
Android 4.0的
搭載Android 4.0（API等級15）引入該把責任在主機上管理填充填充政策的改變。作為4.0，應用小部件不再包括自己的填充。相反，系統添加填充每個部件，基於當前屏幕的特性。這導致一個更均勻，在網格部件的一致呈現。為了幫助該主機的應用程序窗口小部件，該平台提供的方法getDefaultPaddingForWidget應用程序（）。計算細胞的數量分配給widget時應用程序可以調用此方法來獲取系統定義的填充和解釋它。
搭載Android 4.1
搭載Android 4.1（API等級16）增加了一個API，允許小部件供應商，以獲取有關在其控件實例被托管環境的更多詳細信息。具體地，主機暗示至約在正被顯示的窗口小部件的尺寸小窗口提供者。這是主機的責任提供這種規模的信息。
主機通過updateAppWidgetSize提供該信息（）。的大小指定為在DPS的最小和最大寬度/高度。一個范圍（而不是一個固定的大小）的原因是因為一個小窗口的寬度和高度可以與取向發生變化。你不希望主機必須更新其所有的旋轉部件，因為這可能會導致嚴重的系統運行緩慢。這些值應從前的插件來更新被放置，所述插件被調整大小的任何時間，任何時間發射膨脹用於在給定引導在第一時間（作為值不跨越啟動持續）的部件。
Android 4.2版
對於選擇在捆綁綁定時指定的Andr??oid 4.2（API等級17）增加的能力。這是指定的應用程序插件選項，包括大小的理想方法，因為它給了AppWidgetProvider直接訪問數據的選項在第一次更新。這可以通過使用該方法bindAppWidgetIdIfAllowed（）來實現。有關此主題的更多討論，請參閱綁定應用程序部件。
Android 4.2版還引入了鎖屏小部件。當主機在鎖定屏幕上的小部件，主機必須指定應用程序窗口小部件選項包內該信息（AppWidgetProvider可以使用這些信息來適當方式進行樣式設置）。要指定一個widget作為鎖屏插件，使用updateAppWidgetOptions（），並包括與價值WIDGET_CATEGORY_KEYGUARD領域OPTION_APPWIDGET_HOST_CATEGORY。此選項默認為WIDGET_CATEGORY_HOME_SCREEN，所以也沒有明確要求，設置本作的主屏幕主機。
請確保您的主機只增加了應用小工具，適合你的應用程序，例如，如果你的主機是主屏幕，確保了android：在AppWidgetProviderInfo元widgetCategory屬性包括旗WIDGET_CATEGORY_HOME_SCREEN。同樣，對於鎖屏，確保字段包括標志WIDGET_CATEGORY_KEYGUARD。有關此主題的更多討論，請參閱鎖屏啟用應用程序的窗口小部件。