Android API Guides --- App Widget Host

Android API Guides --- App Widget Host
Application Widget host
Android available on most Android devices ?? The oid home screen allows users to embed application gadgets for quick access to content. If you are building a home replacement or similar application, you can also allow users to embed application components by implementing AppWidgetHost. This is not something that most applications do not need to do, but if you are creating your own host, it is very important to understand the implicit consent of hosts under contractual obligations.

This document focuses on the responsibility for customizing AppWidgetHost. For how to implement an AppWidgetHost example, see the source code for the Android Main Screen startup.

Here is an overview of key classes and concepts involved in customizing AppWidgetHost:

The AppWidgetHost of the application's Widget HOST provides applications that use the AppWidget service, such as the home screen, and you want to embed the app Widget in its UI for interaction. An AppWidgetHost must have an ID, which is unique in the host's own package. This ID is persistent across all hosts. This ID usually specifies a hard-coded value in the application.
Application gadgets ID-each application plug-in instance is assigned a unique ID at the combined time (see bindAppWidgetIdIfAllowed () for details about binding application widgets ). The unique ID is obtained by using the allocateAppWidgetId () host. This ID spans the plug-in, that is, lifetime persistence until it is deleted from the host. The status of any specific host (such as the size and location of the widget) should be persistent by the notice package and associated with the application's micro-component ID.
AppWidgetHostView can be regarded as a frame for the widget host of an application. This plug-in is packaged to display it whenever needed. Each widget of the application plug-in is allocated to AppWidgetHostView by the host inflation time.
Option ?? Bundle-This AppWidgetHost uses the option Bundle to convey information to the description about how AppWidgetProvider is displaying a microware (for example, a size range, and whether the screen is locked or the main screen on the widget ). This information allows how and where the custom Widget content and appearance are displayed based on AppWidgetProvider. You can use updateAppWidgetOptions () and updateAppWidgetSize () to modify the package of the application widget. These two methods trigger a callback to AppWidgetProvider.
Combined with application gadgets


When a user plug-in an application to the host, a binding process occurs. Combination refers to a specific application microware ID, which is associated with a specific host and a specific AppWidgetProvider. What version of Android does it depend on to achieve this goal ?? Oid runs on your application in different ways.


Integrate app gadgets in Android 4.0 and lower

When running Android 4.0 and lower devices, users can select a widget to add application parts through system activities. This implicitly checks permissions, that is, by adding application widgets, users are implicitly granted permissions to add your application widgets to the host. Here is an example taken from the original starter in this method. In this clip, an event handler calls startActivityForResult () in the Request Code REQUEST_PICK_APPWIDGET that responds to user operations:

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;
  }
  ...
}
When the system activity ends, it returns the result of your activity with the gadget selected by the user. In the following example, the activity adds an application widget response by calling the advertisement 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;
        }
    }
    ...
  }
}
This method adds AppWidget () to check if the application widget requires it to be configured before adding:
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.
  }
}
For a detailed discussion of configuration, see Creating an application widget configuration activity.
Once the gadget is ready, the next step is to do the actual work of adding it to the workspace. The original launch method used is called Full AppWidget () to do this.
Combine gadgets in Android4.1 and higher
Equipped with Android 4.1 added API for a more streamlined binding process. These APIs also make it possible to bind a host to provide a custom UI. To use this improved method, your application must declare the BIND_APPWIDGET permission in its manifest:
However, this is only the first step. At runtime, the user must explicitly grant permissions to your application to enable it to add widgets to the host. To test whether your application has permission to add gadgets, you can use bindAppWidgetIdIfAllowed () method. If bindAppWidgetIdIfAllowed () returns false, your application must display a dialog box prompting the user to grant permission ("Allow" or "Always Allow" to cover all future app gadget additions). This code provides an example of how to display the dialog box:
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);
The host must also check whether the user adds that an application component needs to be configured. For more discussion on this topic, see Create an application widget configuration activity.
Moderator duties
What version are you targeting?
The method you use to implement your host should depend on what Android version your goal is. Many of the features described in this section are introduced in version 3.0 or later. E.g:
Android 3.0 (API level 11) introduces the behavior of widget auto-advancement.
Android 3.1 (API level 12) introduced the ability to adjust components.
Android 4.0 (API level 15) is introduced to introduce the responsibility for managing changes to the fill policy on the host.
Android 4.1 (API level 16) adds an API that allows widget suppliers to obtain more detailed information about the environment in which their control instances are hosted.
Android 4.2 (API level 17) introduced the option package and bindAppWidgetIdIfAllowed () method. A lock screen widget has also been introduced.
If you target early equipment, refer to the original boot as an example.
Plug-in developers can specify some configuration settings for widgets using AppWidgetProviderInfo metadata. These configuration options, discussed in more detail below, can be retrieved from the AppWidgetProviderInfo object host associated with the widget provider.
Regardless of your target Android version, all hosts have the following responsibilities:
When adding widgets, you must assign the part ID as described above. You must also ensure that when a widget is deleted from the host, you can call deleteAppWidgetId () to release the widget ID.
When adding widgets, you can be sure if there is a rollout configuration activity, such as updating the application widget description from the configuration activity. This is a necessary step before many widgets can be displayed correctly.
Each application widget specifies the minimum width and height of dps, such as AppWidgetProviderInfo to define metadata (using android: minWidth and android: minHeight). Make sure the widget has at least so many dps layouts. For example, many hosts align grid icons and widgets. In this case, by default, the host should use the minimum number of application components added that satisfy the minWidth and minHeight constraints.
In addition to the requirements listed above, the specific version of the platform introduces new responsibility functions placed on the host. These will be described in the following sections.
Android 3.0
Android 3.0 (API level 11) introduced a small tool that specifies the ability to autoAdvanceViewId (). This view ID should point to an instance that can advance, such as StackView or AdapterViewFlipper. This indicates that the host should call this view ahead of time () to consider the appropriate host (considering whether it makes sense to advance the widget, for example, the host may not want it if it advances one widget on another page, or if the screen is shut down).
Android version 3.1
Android 3.1 (API level 12) introduced the ability to adjust components. A widget can specify that it is resizable using Android: in the AppWidgetProviderInfo meta resizeMode attribute, and indicate whether it supports horizontal and / or vertical resizing. Introduced in Android 4.0 (API level 14), the widget can also specify a robot: minResizeWidth and / or Android: minResizeHeight.
It is the responsibility of the host, which causes the plugin to be adjusted horizontally and / or vertically, as specified by the plugin. This shows that it can be resized and arbitrarily large, but it should not be smaller than the size specified by Android: minResizeWidth and android: minResizeHeight. For an example implementation, see launcher2 in AppWidgetResizeFrame.
Android 4.0
Android 4.0 (API level 15) is introduced to introduce the responsibility for managing changes to the fill policy on the host. As of 4.0, the application widget no longer includes its own fill. Instead, the system adds and populates each component based on the characteristics of the current screen. This results in a more uniform, consistent presentation of the grid parts. To help the host application widget, the platform provides the method getDefaultPaddingForWidget application (). The application can call this method when calculating the number of cells assigned to the widget to get the system-defined padding and interpret it.
Equipped with Android 4.1
Android 4.1 (API level 16) adds an API that allows widget suppliers to obtain more detailed information about the environment in which their control instances are hosted. Specifically, the host hints to the widget provider about the size of the widget being displayed. It is the responsibility of the host to provide this size of information.
The host provides this information through updateAppWidgetSize (). The size is specified as the minimum and maximum width / height in the DPS. The reason for a range (rather than a fixed size) is because the width and height of a small window can change with the orientation. You do n’t want the host to have to update all its rotating parts, as this may cause serious system slowness. These values should be placed from the previous plug-in update, the plug-in is resized any time, any time the launch dilation is used for the component at a given boot at the first time (as the value does not span startup duration).
Android version 4.2
Added ability to select Android 4.2 (API level 17) specified when bundling. This is the ideal way to specify the application plug-in options, including size, because it gives the AppWidgetProvider the option to directly access the data at the first update. This can be achieved by using the method bindAppWidgetIdIfAllowed (). For more discussion on this topic, please refer to Read the binding application parts.
Android 4.2 also introduces lock screen widgets. When the host is on the widget on the lock screen, the host must specify this information in the application widget option package (AppWidgetProvider can use this information to style in an appropriate way). To specify a widget as a lock screen plugin, use updateAppWidgetOptions () and include OPTION_APPWIDGET_HOST_CATEGORY in the field with value WIDGET_CATEGORY_KEYGUARD. This option defaults to WIDGET_CATEGORY_HOME_SCREEN, so there is no explicit requirement to set the main screen host for this work.
Please make sure that your host only adds application widgets, suitable for your application, for example, if your host is the home screen, make sure that android: in the AppWidgetProviderInfo meta widgetCategory attribute includes the flag WIDGET_CATEGORY_HOME_SCREEN. Similarly, for the lock screen, make sure that the field includes the flag WIDGET_CATEGORY_KEYGUARD. For more discussion on this topic, see widgets for lock screen-enabled applications.