Merge "Doc change: document AppWidgetHost" into jb-mr1.1-docs

3 files changed, 429 insertions, 19 deletions

diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index ff35d2e21341..5f9f53000a06 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 000000000000..da7408f96aa2
--- /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>&mdash;  
+    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>&mdash;
+    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>&mdash;  
+    {@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>&mdash;
+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&mdash;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 {
+    ...
+    &#64;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>&lt;uses-permission android:name="android.permission.BIND_APPWIDGET" /&gt;
+</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&mdash;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&mdash;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 774c66a9c022..187f9efb9505 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>
 &lt;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