In this document
+ +The Android Home screen available on most Android devices allows the user +to embed app widgets for quick +access to content. If you're building a Home replacement or a similar app, +you can also allow the user to embed app widgets by implementing an +{@link android.appwidget.AppWidgetHost}. +This is not something that most apps will ever need to do, but if you are +creating your own host, it's important to understand the contractual obligations +a host implicitly agrees to.
+ +This document focuses on the responsibilities involved in implementing a custom +{@link android.appwidget.AppWidgetHost}. For an example of how to implement an +{@link android.appwidget.AppWidgetHost}, see the source code for the +Android Home screen + +Launcher. + + +
Here is an overview of key classes and concepts involved in implementing a custom +{@link android.appwidget.AppWidgetHost}:
+-
+
- App Widget Host— + The {@link android.appwidget.AppWidgetHost} provides the interaction +with the AppWidget service for apps, like the home screen, that want to embed +app widgets in their UI. An {@link android.appwidget.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. + +
- App Widget ID— + Each app widget instance is assigned a unique ID at the time of binding +(see {@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed bindAppWidgetIdIfAllowed()}, +discussed in more detail in Binding app widgets). +The unique ID is obtained by the host using {@link android.appwidget.AppWidgetHost#allocateAppWidgetId() allocateAppWidgetId()}. This ID is persistent across the lifetime of the widget, +that is, until it is deleted from the host. Any host-specific state (such as the +size and location of the widget) should be persisted by the hosting package and +associated with the app widget ID. + + +
- App Widget Host View— + {@link android.appwidget.AppWidgetHostView} can be thought of as a frame +that the widget is wrapped in whenever it needs to be displayed. An app widget +is assigned to an {@link android.appwidget.AppWidgetHostView} every time the +widget is inflated by the host. +
- Options Bundle— +The {@link android.appwidget.AppWidgetHost} uses the options bundle to communicate +information to the {@link android.appwidget.AppWidgetProvider} about how the +widget is being displayed (for example, size range, and whether the widget is on +a lockscreen or the home screen). This information allows the +{@link android.appwidget.AppWidgetProvider} to tailor the widget's contents +and appearance based on how and where it is displayed. +You use +{@link android.appwidget.AppWidgetHostView#updateAppWidgetOptions(android.os.Bundle) updateAppWidgetOptions()} +and +{@link android.appwidget.AppWidgetHostView#updateAppWidgetSize updateAppWidgetSize()} + +to modify an app widget's +bundle. Both of these methods trigger a callback to the +{@link android.appwidget.AppWidgetProvider}. +
Binding App Widgets
+ +When a user adds an app widget to a host, a process called +binding occurs. Binding refers to associating +a particular app widget ID to a specific host and to a specific +{@link android.appwidget.AppWidgetProvider}. There are different +ways of achieving this, depending on what version of Android your +app is running on.
+ +Binding app widgets on Android 4.0 and lower
+ +On devices running Android version 4.0 and lower, users add app widgets +via a system activity that allows users to select a widget. This implicitly +does a permission check—that is, by adding the app widget, the user is +implicitly granting permission to your app to add app widgets to the host. +Here is an example that illustrates +this approach, taken from the original +Launcher. In this snippet, an event handler invokes +{@link android.app.Activity#startActivityForResult(android.content.Intent,int) startActivityForResult()} +with the request code {@code REQUEST_PICK_APPWIDGET} in response to a +user action:
+ +
+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 finishes, it returns a result with the user's chosen +app widget to your activity. In the following example, the activity responds +by calling {@code addAppWidget()} to add the app widget:
+ +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;
+ }
+ }
+ ...
+ }
+}
+
+The method {@code addAppWidget()} checks to see if the app widget +needs to be configured before it's added:
+ +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 more discussion of configuration, +see Creating an +App Widget Configuration Activity.
+ +Once the app widget is ready, the next step is to do the +actual work of adding it to the workspace. The +original Launcher uses a method called {@code completeAddAppWidget()} +to do this.
+ +Binding app widgets on Android 4.1 and higher
+ +Android 4.1 adds APIs for a more streamlined binding process. +These APIs also make it possible for a host to provide a custom UI for +binding. To use this improved process, your app must declare the +{@link android.Manifest.permission#BIND_APPWIDGET} permission in its manifest:
+ +<uses-permission android:name="android.permission.BIND_APPWIDGET" /> ++ + +
But this is just the first step. At runtime the user must +explicitly grant permission to your app to allow it to add app widgets +to the host. To test whether your app has permission to add the widget, +you use the +{@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed bindAppWidgetIdIfAllowed()} +method. +If {@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed bindAppWidgetIdIfAllowed()} +returns {@code false}, your app must display a dialog prompting the +user to grant permission +("allow" or "always allow," to cover all future app widget additions). +This snippet gives an example of how to display the dialog:
+ +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 also has to check whether the user added +an app widget that needs configuration. For more discussion of this topic, +see +Creating +an App Widget Configuration Activity.
+ +Host Responsibilities
+ +What Version are You Targeting?
+The approach you use in implementing your host should depend on what Android version +you're targeting. Many of the features described in this section were introduced +in 3.0 or later. For example:
+-
+
- Android 3.0 (API Level 11) introduces auto-advance behavior for widgets. +
- Android 3.1 (API Level 12) introduces the ability to resize widgets. +
- Android 4.0 (API Level 15) introduces a change in padding policy that +puts the responsibility on the +host to manage padding. +
- Android 4.1 (API Level 16) adds an API that allows the widget provider +to get more detailed information about the environment in which its +widget instances are being hosted. +
- Android 4.2 (API Level 17) introduces the options bundle and the +{@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed(int,android.content.ComponentName,android.os.Bundle) bindAppWidgetIdIfAllowed()} +method. It also introduces lockscreen widgets. +
If you are targeting earlier devices, refer to the original +Launcher as an example. +
Widget developers can specify a number of configuration settings +for widgets using the +AppWidgetProviderInfo metadata. +These configuration options, discussed in more detail below, can be +retrieved by the host from the {@link android.appwidget.AppWidgetProviderInfo} +object associated with a widget provider.
+ +Regardless of the version of Android you are targeting, all hosts +have the following responsibilities:
+ +-
+
- When adding a widget, you must allocate the widget ID as described above. +You must also make sure that when a widget is removed from the host, you call {@link android.appwidget.AppWidgetHost#deleteAppWidgetId deleteAppWidgetId()} +to deallocate the widget ID. + +
- When adding a widget, be sure to launch its configuration activity +if it exists, as described in + +Updating the App Widget +from the Configuration Activity. This is a necessary step for many app widgets before +they can be properly displayed. + +
- Every app widget specifies a minimum width and height in dps, as defined in the {@link android.appwidget.AppWidgetProviderInfo} metadata +(using {@link android.appwidget.AppWidgetProviderInfo#minWidth android:minWidth} and +{@link android.appwidget.AppWidgetProviderInfo#minHeight android:minHeight}). +Make sure that the widget is laid out with at least this many dps. +For example, many hosts align icons and widgets in a grid. In this scenario, +by default the host should add the app widget using the minimum number of +cells that satisfy the {@code minWidth} and {@code minHeight} constraints. + +
In addition to the requirements listed above, specific platform +versions introduce features that place new responsibilities on the +host. These are described in the following sections.
+ +Android 3.0
+ +Android 3.0 (API Level 11) introduces the ability for a widget to specify {@link android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId autoAdvanceViewId()}. +This view ID should point to an instance of an +{@link android.widget.Advanceable}, such as {@link android.widget.StackView} +or {@link android.widget.AdapterViewFlipper}. This indicates that the host +should call {@link android.widget.Advanceable#advance advance()} on this +view at an interval deemed appropriate by the host (taking into account whether +it makes sense to advance the widget—for example, the host probably +wouldn't want to advance a widget if it were on another page, or +if the screen were turned off).
+ +Android 3.1
+ +Android 3.1 (API Level 12) introduces the ability to resize widgets. +A widget can specify that it is resizable using the +{@link android.appwidget.AppWidgetProviderInfo#resizeMode android:resizeMode} +attribute in the {@link android.appwidget.AppWidgetProviderInfo} +metadata, and indicate whether it supports horizontal and/or +vertical resizing. Introduced in Android 4.0 (API Level 14), the widget can also specify a +{@link android.appwidget.AppWidgetProviderInfo#minResizeWidth android:minResizeWidth} +and/or {@link android.appwidget.AppWidgetProviderInfo#minResizeHeight android:minResizeHeight}.
+ +It is the host’s responsibility to make it possible for the +widget to be resized horizontally and/or vertically, as specified +by the widget. A widget that specifies that it is resizable can be +resized arbitrarily large, but should not be resized smaller than +the values specified by {@link +android.appwidget.AppWidgetProviderInfo#minResizeWidth android:minResizeWidth} +and {@link +android.appwidget.AppWidgetProviderInfo#minResizeHeight android:minResizeHeight}. +For a sample implementation, see +{@code AppWidgetResizeFrame} in {@code Launcher2}.
+ + +Android 4.0
+ +Android 4.0 (API Level 15) introduces a change in padding policy that +puts the responsibility on the host to manage padding. As of 4.0, app +widgets no longer include their own padding. Instead, the system adds +padding for each widget, based the characteristics of the current screen. +This leads to a more uniform, consistent presentation of widgets in a grid. +To assist applications that host app widgets, the platform provides +the method +{@link android.appwidget.AppWidgetHostView#getDefaultPaddingForWidget getDefaultPaddingForWidget()}. +Applications can call this method to get the system-defined padding +and account for it when computing the number of cells to allocate to the widget.
+ +Android 4.1
+ +Android 4.1 (API Level 16) adds an API that allows the widget provider +to get more detailed information about the environment in which its +widget instances are being hosted. Specifically, the host hints to the +widget provider about the size at which the widget is being displayed. +It is the host’s responsibility to provide this size information.
+ +The host provides this information via +{@link android.appwidget.AppWidgetHostView#updateAppWidgetSize updateAppWidgetSize()}. +The size is specified as a minimum and maximum width/height in dps. +The reason that a range is specified (as opposed to a fixed size) +is because the width and height of a widget may change with orientation. +You don’t want the host to have to update all of its widgets on rotation, +as this could cause serious system slowdown. These values should be +updated once upon the widget being placed, any time the widget is resized, +and any time the launcher inflates the widget for the first time in a +given boot (as the values aren’t persisted across boot).
+ + +Android 4.2
+ +Android 4.2 (API Level 17) adds the ability for the options bundle +to be specified at bind time. This is the ideal way to specify app +widget options, including size, as it gives the {@link +android.appwidget.AppWidgetProvider} immediate access to the options +data on the first update. This can be achieved by using the method {@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed(int,android.content.ComponentName,android.os.Bundle) bindAppWidgetIdIfAllowed()}. For more discussion of this topic, +see Binding app widgets.
+ +Android 4.2 also introduces lockscreen widgets. When hosting widgets +on the lockscreen, the host must specify this information within the app +widget options bundle (the {@link +android.appwidget.AppWidgetProvider} can use this information to style +the widget appropriately). To designate a widget as a lockscreen widget, use {@link android.appwidget.AppWidgetHostView#updateAppWidgetOptions updateAppWidgetOptions()} +and include the field +{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_HOST_CATEGORY} +with the value {@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_KEYGUARD}. +This option defaults to +{@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_HOME_SCREEN}, +so it is not explicitly required to set this for a home screen host.
+ +Make sure that your host adds only app widgets that are appropriate +for your app—for example, if your host is a home screen, ensure +that the +{@link android.appwidget.AppWidgetProviderInfo#widgetCategory android:widgetCategory} +attribute in the +{@link android.appwidget.AppWidgetProviderInfo} metadata includes +the flag {@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_HOME_SCREEN}. +Similarly, for the lockscreen, ensure that field includes the flag {@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_KEYGUARD}. For more +discussion of this topic, see + +Enabling App Widgets on the Lockscreen.
+ + + + diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd index 774c66a9c0224..187f9efb95058 100644 --- a/docs/html/guide/topics/appwidgets/index.jd +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -22,15 +22,16 @@ Activity- Updating the App Widget from - the configuration Activity + the Configuration Activity
- Sample application @@ -66,7 +67,9 @@ the Music App Widget.
- The
minResizeHeightattribute specifies the minimum height (in dps) to which +the widget can be resized. This field has no effect if it is greater than {@code minHeight} or if +vertical resizing isn't enabled (seeresizeMode). Introduced in Android 4.0.
+
+ - The
minResizeWidthattribute specifies the minimum width (in dps) to which +the widget can be resized. This field has no effect if it is greater than {@code minWidth} or if +horizontal resizing isn't enabled (seeresizeMode). Introduced in Android 4.0.
+
- The
widgetCategoryattribute declares whether your App Widget can be displayed on the home screen, the lock screen (keyguard), or both. Values for this attribute include "home_screen" and "keyguard". A widget that is displayed on both needs to ensure that it follows the design guidelines for both widget classes. For more @@ -788,12 +799,12 @@ int baseLayout = isKeyguard ? R.layout.keyguard_widget_layout : R.layout.widget_Using App Widgets with Collections
-Android 3.0 introduces App Widgets with collections. These kinds of App +
Android 3.0 introduces app widgets with collections. These kinds of App Widgets use the {@link android.widget.RemoteViewsService} to display collections that are backed by remote data, such as from a content provider. The data provided by the {@link android.widget.RemoteViewsService} -is presented in the App Widget using one of the following view types, which +is presented in the app widget using one of the following view types, which we’ll refer to as “collection views:”
-
@@ -900,15 +911,15 @@ how this is implemented, see
Implementing app widgets with collections
-To implement an App Widget with collections, you follow the same basic steps +
To implement an app widget with collections, you follow the same basic steps you would use to implement any app widget. The following sections describe the -additional steps you need to perform to implement an App Widget with +additional steps you need to perform to implement an app widget with collections.
Manifest for app widgets with collections
In addition to the requirements listed in Declaring an -App Widget in the Manifest, to make it possible for App Widgets with +app widget in the Manifest, to make it possible for app widgets with collections to bind to your {@link android.widget.RemoteViewsService}, you must declare the service in your manifest file with the permission {@link android.Manifest.permission#BIND_REMOTEVIEWS}. This prevents other applications @@ -987,7 +998,7 @@ android.widget.RemoteViewsService} can then return your implementation of {@link android.widget.RemoteViewsService.RemoteViewsFactory RemoteViewsFactory}, and the widget can serve up the appropriate data. When you call this method, you must pass an intent that points to your implementation of {@link -android.widget.RemoteViewsService} and the App Widget ID that specifies the app +android.widget.RemoteViewsService} and the app widget ID that specifies the app widget to update.
@@ -1009,7 +1020,7 @@ int[] appWidgetIds) { // Add the app widget ID to the intent extras. intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]); intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME))); - // Instantiate the RemoteViews object for the App Widget layout. + // Instantiate the RemoteViews object for the app widget layout. RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout); // Set up the RemoteViews object to use a RemoteViews adapter. // This adapter connects @@ -1367,15 +1378,15 @@ class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {Keeping Collection Data Fresh
-The following figure illustrates the flow that occurs in an App Widget that +
The following figure illustrates the flow that occurs in an app widget that uses -collections when updates occur. It shows how the App Widget code interacts with +collections when updates occur. It shows how the app widget code interacts with the {@link android.widget.RemoteViewsService.RemoteViewsFactory RemoteViewsFactory}, and how you can trigger updates:
-One feature of App Widgets that use collections is the ability to provide +
One feature of app widgets that use collections is the ability to provide users with up-to-date content. For example, consider the Android 3.0 Gmail app widget, which provides users with a snapshot of their inbox. To make this possible, you need to be able to trigger your {@link
This document describes how to publish an App Widget using an App Widget -provider.
+provider. For a discussion of creating your own {@link android.appwidget.AppWidgetHost} +to host app widgets, see +Implementing a Custom App Widget Host.Widget Design
@@ -100,7 +103,7 @@ an optional and allows him or her to modify App Widget settings at create-time. -The following sections describe how to setup each of these components.
+The following sections describe how to set up each of these components.
Declaring an App Widget in the Manifest
@@ -165,8 +168,8 @@ folder.
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
- android:minWidth="294dp"
- android:minHeight="72dp"
+ android:minWidth="40dp"
+ android:minHeight="40dp"
android:updatePeriodMillis="86400000"
android:previewImage="@drawable/preview"
android:initialLayout="@layout/example_appwidget"
@@ -270,6 +273,14 @@ handles to change the size on the layout grid. Values for the
To declare a widget as resizeable horizontally and vertically, supply the value
"horizontal|vertical". Introduced in Android 3.1.
+