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属性，并说明它是否支持水平和/或垂直大小调整。在Androi