diff options
author | kmccormick <kmccormick@google.com> | 2013-05-30 18:48:27 +0000 |
---|---|---|
committer | Android (Google) Code Review <android-gerrit@google.com> | 2013-05-30 18:48:27 +0000 |
commit | b3803855b0554879836c18b4157194b9c2061219 (patch) | |
tree | 3554c2e262c42e686482d0fcddc27e18d66cc58f | |
parent | e55ba43171cb46cc95aa90f83524c4751c7030ff (diff) | |
parent | 25072c7d7bfd912a38da60b6331b546b3087615f (diff) | |
download | frameworks_base-b3803855b0554879836c18b4157194b9c2061219.zip frameworks_base-b3803855b0554879836c18b4157194b9c2061219.tar.gz frameworks_base-b3803855b0554879836c18b4157194b9c2061219.tar.bz2 |
Merge "Doc change: document AppWidgetHost" into jb-mr1.1-docs
-rw-r--r-- | docs/html/guide/guide_toc.cs | 11 | ||||
-rw-r--r-- | docs/html/guide/topics/appwidgets/host.jd | 392 | ||||
-rw-r--r-- | docs/html/guide/topics/appwidgets/index.jd | 45 |
3 files changed, 429 insertions, 19 deletions
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index ff35d2e..5f9f530 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -76,9 +76,16 @@ <span class="en">Permissions</span> </a> </li> - <li><a href="<?cs var:toroot ?>guide/topics/appwidgets/index.html"> + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>guide/topics/appwidgets/index.html"> <span class="en">App Widgets</span> - </a></li> + </a></div> + <ul> + <li><a href="<?cs var:toroot ?>guide/topics/appwidgets/host.html"> + <span class="en">App Widget Host</span> + </a></li> + </ul> + </li> <li class="nav-section"> <div class="nav-section-header"><a href="<?cs var:toroot ?>guide/topics/manifest/manifest-intro.html"> <span class="en">Android Manifest</span> diff --git a/docs/html/guide/topics/appwidgets/host.jd b/docs/html/guide/topics/appwidgets/host.jd new file mode 100644 index 0000000..da7408f --- /dev/null +++ b/docs/html/guide/topics/appwidgets/host.jd @@ -0,0 +1,392 @@ +page.title=App Widget Host +page.tags="AppWidgetHost","home screen","launcher" +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#host-binding">Binding App Widgets</a> + <ol> + <li><a href="#binding-pre">Binding app widgets on Android 4.0 and lower</a></li> + <li><a href="#binding-41">Binding app widgets on Android 4.1 and higher</a></li> + </ol> + </li> + <li><a href="#host-state">Host Responsibilities</a> + <ol> + <li><a href="#30">Android 3.0</a></li> + <li><a href="#31">Android 3.1</a></li> + <li><a href="#40">Android 4.0</a></li> + <li><a href="#41">Android 4.1</li> + <li><a href="#42">Android 4.2</a></li> + </ol> + </li> + </ol> + </div> +</div> + + +<p>The Android Home screen available on most Android devices allows the user +to embed <a href="{@docRoot}guide/topics/appwidgets/index.html">app widgets</a> 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.</p> + +<p>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 +<a href="https://android.googlesource.com/platform/packages/apps/Launcher2/+/master/src/com/android/launcher2/Launcher.java"> +Launcher</a>. + + +<p>Here is an overview of key classes and concepts involved in implementing a custom +{@link android.appwidget.AppWidgetHost}:</p> +<ul> + <li><strong>App Widget Host</strong>— + 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.</li> + + <li><strong>App Widget ID</strong>— + 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 <a href="#binding">Binding app widgets</a>). +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. +</li> + + <li><strong>App Widget Host View</strong>— + {@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. </li> + <li><strong>Options Bundle</strong>— +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}.</p></li> +</ul> + +<h2 id="host-binding">Binding App Widgets</h2> + +<p>When a user adds an app widget to a host, a process called +<em>binding</em> occurs. <em>Binding</em> 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.</p> + +<h3 id="binding-pre">Binding app widgets on Android 4.0 and lower</h3> + +<p>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 +<a href="https://android.googlesource.com/platform/packages/apps/Launcher/+/master/src/com/android/launcher/Launcher.java">Launcher</a>. 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:</p> + +<pre> +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; + } + ... +}</pre> + +<p>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:</p> + +<pre>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; + } + } + ... + } +}</pre> + +<p>The method {@code addAppWidget()} checks to see if the app widget +needs to be configured before it's added:</p> + +<pre>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. + } +}</pre> + +<p>For more discussion of configuration, +see <a href="{@docRoot}guide/topics/appwidgets/index.html#Configuring">Creating an +App Widget Configuration Activity</a>.</p> + +<p>Once the app widget is ready, the next step is to do the +actual work of adding it to the workspace. The +<a href="https://android.googlesource.com/platform/packages/apps/Launcher/+/master/src/com/android/launcher/Launcher.java">original Launcher</a> uses a method called {@code completeAddAppWidget()} +to do this.</p> + +<h3 id="binding-41">Binding app widgets on Android 4.1 and higher</h3> + +<p>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:</p> + +<pre><uses-permission android:name="android.permission.BIND_APPWIDGET" /> +</pre> + + +<p>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:</p> + +<pre>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); +</pre> + +<p>The host also has to check whether the user added +an app widget that needs configuration. For more discussion of this topic, +see +<a href="{@docRoot}guide/topics/appwidgets/index.html#Configuring">Creating +an App Widget Configuration Activity</a>.</p> + +<h2 id="host-state">Host Responsibilities</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h2>What Version are You Targeting?</h2> + <p>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:</p> +<ul> +<li>Android 3.0 (API Level 11) introduces auto-advance behavior for widgets.</li> +<li>Android 3.1 (API Level 12) introduces the ability to resize widgets.</li> +<li>Android 4.0 (API Level 15) introduces a change in padding policy that +puts the responsibility on the +host to manage padding.</li> +<li>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.</li> +<li>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.</li> +</ul> +<p>If you are targeting earlier devices, refer to the original +<a href="https://android.googlesource.com/platform/packages/apps/Launcher/+/master/src/com/android/launcher/Launcher.java">Launcher</a> as an example. +</div> +</div> + +<p>Widget developers can specify a number of configuration settings +for widgets using the <a href="{@docRoot}guide/topics/appwidgets/index.html#MetaData"> +AppWidgetProviderInfo metadata</a>. +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.</p> + +<p>Regardless of the version of Android you are targeting, all hosts +have the following responsibilities:</p> + +<ul> +<li>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.</li> + +<li>When adding a widget, be sure to launch its configuration activity +if it exists, as described in +<a href="{@docRoot}guide/topics/appwidgets/index.html#UpdatingFromTheConfiguration"> +Updating the App Widget +from the Configuration Activity</a>. This is a necessary step for many app widgets before +they can be properly displayed.</li> + +<li>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.</li> + +</ul> + +<p>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.</p> + +<h3 id="30">Android 3.0</h3> + +<p>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).</p> + +<h3 id="31">Android 3.1</h3> + +<p>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}.</p> + +<p>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 <a href="https://android.googlesource.com/platform/packages/apps/Launcher2/+/master/src/com/android/launcher2/AppWidgetResizeFrame.java"> +{@code AppWidgetResizeFrame}</a> in {@code Launcher2}.</p> + + +<h3 id="40">Android 4.0</h3> + +<p>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.</p> + +<h3 id="41">Android 4.1</h3> + +<p>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.</p> + +<p>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).</p> + + +<h3 id="42">Android 4.2</h3> + +<p>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 <a href="#host-binding">Binding app widgets</a>.</p> + +<p>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.</p> + +<p>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 +<a href="{@docRoot}guide/topics/appwidgets/index.html#lockscreen"> +Enabling App Widgets on the Lockscreen</a>.</p> + + + + diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd index 774c66a..187f9ef 100644 --- a/docs/html/guide/topics/appwidgets/index.jd +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -22,15 +22,16 @@ Activity</a> <ol> <li><a href="#UpdatingFromTheConfiguration">Updating the App Widget from - the configuration Activity</a></li> + the Configuration Activity</a></li> </ol> </li> <li><a href="#preview">Setting a Preview Image</a></li> - <li><a href="#lockscreen">Enabling App Widgets on the Lockscreen + <li><a href="#lockscreen">Enabling App Widgets on the Lockscreen</a> <ol> - <li><a href="#lockscreen-sizing">Sizing guidelines</li> + <li><a href="#lockscreen-sizing">Sizing guidelines</a></li> </ol> </li> + <li><a href="#collections">Using App Widgets with Collections</a> <ol> <li><a href="#collection_sample">Sample application</a></li> @@ -66,7 +67,9 @@ the Music App Widget.</p> <img src="{@docRoot}images/appwidgets/appwidget.png" alt="" /> <p>This document describes how to publish an App Widget using an App Widget -provider.</p> +provider. For a discussion of creating your own {@link android.appwidget.AppWidgetHost} +to host app widgets, see <a href="{@docRoot}guide/topics/appwidgets/host.html"> +Implementing a Custom App Widget Host</a>.</p> <div class="note design"> <p><strong>Widget Design</strong></p> @@ -100,7 +103,7 @@ an optional and allows him or her to modify App Widget settings at create-time.</p> -<p>The following sections describe how to setup each of these components.</p> +<p>The following sections describe how to set up each of these components.</p> <h2 id="Manifest">Declaring an App Widget in the Manifest</h2> @@ -165,8 +168,8 @@ folder.</p> <pre> <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.</li> +<li>The <code>minResizeHeight</code> attribute 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 (see <code>resizeMode</code>). Introduced in Android 4.0.</li> + +<li>The <code> minResizeWidth </code> attribute 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 (see <code>resizeMode</code>). Introduced in Android 4.0.</li> + <li>The <code>widgetCategory</code> attribute 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_ <h2 id="collections">Using App Widgets with Collections</h2> -<p>Android 3.0 introduces App Widgets with collections. These kinds of App +<p>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 <a href="{@docRoot}guide/topics/providers/content-providers.html">content provider</a>. 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:”</p> <dl> @@ -900,15 +911,15 @@ how this is implemented, see </ul> <h3 id="implementing_collections">Implementing app widgets with collections</h3> -<p>To implement an App Widget with collections, you follow the same basic steps +<p>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.</p> <h4>Manifest for app widgets with collections</h4> <p> In addition to the requirements listed in <a href="#Manifest">Declaring an -App Widget in the Manifest</a>, to make it possible for App Widgets with +app widget in the Manifest</a>, 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.</p> @@ -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 { <h3 id="fresh">Keeping Collection Data Fresh</h3> -<p>The following figure illustrates the flow that occurs in an App Widget that +<p>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:</p> <img src="{@docRoot}images/appwidgets/appwidget_collections.png" alt="" /> -<p>One feature of App Widgets that use collections is the ability to provide +<p>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 |