AI 147438: add app widget docs to dev guide
move app widget docs out of the package description
BUG=1790234
Automated import of CL 147438
diff --git a/core/java/android/appwidget/package.html b/core/java/android/appwidget/package.html
index b6cd9c7..2b85bd5 100644
--- a/core/java/android/appwidget/package.html
+++ b/core/java/android/appwidget/package.html
@@ -3,127 +3,22 @@
views are called widgets, and are published by "AppWidget providers." The component that can
contain widgets is called a "AppWidget host."
</p>
-<h3><a href="package-descr.html#providers">AppWidget Providers</a></h3>
-<ul>
- <li><a href="package-descr.html#provider_manifest">Declaring a widget in the AndroidManifest</a></li>
- <li><a href="package-descr.html#provider_meta_data">Adding the AppWidgetProviderInfo meta-data</a></li>
- <li><a href="package-descr.html#provider_AppWidgetProvider">Using the AppWidgetProvider class</a></li>
- <li><a href="package-descr.html#provider_configuration">AppWidget Configuration UI</a></li>
- <li><a href="package-descr.html#provider_broadcasts">AppWidget Broadcast Intents</a></li>
-</ul>
-<h3><a href="package-descr.html#">AppWidget Hosts</a></h3>
+<p>For more information, see the
+<a href="{@docRoot}guide/topics/appwidgets/index.html">AppWidgets</a>
+documentation in the Dev Guide.</p>
{@more}
<h2><a name="providers"></a>AppWidget Providers</h2>
-<p>
-Any application can publish widgets. All an application needs to do to publish a widget is
+<p>Any application can publish widgets. All an application needs to do to publish a widget is
to have a {@link android.content.BroadcastReceiver} that receives the {@link
android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} intent,
and provide some meta-data about the widget. Android provides the
{@link android.appwidget.AppWidgetProvider} class, which extends BroadcastReceiver, as a convenience
class to aid in handling the broadcasts.
-<h3><a name="provider_manifest"></a>Declaring a widget in the AndroidManifest</h3>
-
-<p>
-First, declare the {@link android.content.BroadcastReceiver} in your application's
-<code>AndroidManifest.xml</code> file.
-
-{@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/AndroidManifest.xml AppWidgetProvider}
-
-<p>
-The <b><code><receiver></b> element has the following attributes:
-<ul>
- <li><b><code>android:name</code> -</b> which specifies the
- {@link android.content.BroadcastReceiver} or {@link android.appwidget.AppWidgetProvider}
- class.</li>
- <li><b><code>android:label</code> -</b> which specifies the string resource that
- will be shown by the widget picker as the label.</li>
- <li><b><code>android:icon</code> -</b> which specifies the drawable resource that
- will be shown by the widget picker as the icon.</li>
-</ul>
-
-<p>
-The <b><code><intent-filter></b> element tells the {@link android.content.pm.PackageManager}
-that this {@link android.content.BroadcastReceiver} receives the {@link
-android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} broadcast.
-The widget manager will send other broadcasts directly to your widget provider as required.
-It is only necessary to explicitly declare that you accept the {@link
-android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} broadcast.
-
-<p>
-The <b><code><meta-data></code></b> element tells the widget manager which xml resource to
-read to find the {@link android.appwidget.AppWidgetProviderInfo} for your widget provider. It has the following
-attributes:
-<ul>
- <li><b><code>android:name="android.appwidget.provider"</code> -</b> identifies this meta-data
- as the {@link android.appwidget.AppWidgetProviderInfo} descriptor.</li>
- <li><b><code>android:resource</code> -</b> is the xml resource to use as that descriptor.</li>
-</ul>
-
-
-<h3><a name="provider_meta_data"></a>Adding the {@link android.appwidget.AppWidgetProviderInfo AppWidgetProviderInfo} meta-data</h3>
-
-<p>
-For a widget, the values in the {@link android.appwidget.AppWidgetProviderInfo} structure are supplied
-in an XML resource. In the example above, the xml resource is referenced with
-<code>android:resource="@xml/appwidget_info"</code>. That XML file would go in your application's
-directory at <code>res/xml/appwidget_info.xml</code>. Here is a simple example.
-
-{@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/res/xml/appwidget_info.xml AppWidgetProviderInfo}
-
-<p>
-The attributes are as documented in the {@link android.appwidget.AppWidgetProviderInfo GagetInfo} class. (86400000 milliseconds means once per day)
-
-
-<h3><a name="provider_AppWidgetProvider"></a>Using the {@link android.appwidget.AppWidgetProvider AppWidgetProvider} class</h3>
-
-<p>The AppWidgetProvider class is the easiest way to handle the widget provider intent broadcasts.
-See the <code>src/com/example/android/apis/appwidget/ExampleAppWidgetProvider.java</code>
-sample class in ApiDemos for an example.
-
-<p class="note">Keep in mind that since the the AppWidgetProvider is a BroadcastReceiver,
-your process is not guaranteed to keep running after the callback methods return. See
-<a href="../../../guide/topics/fundamentals.html#broadlife">Application Fundamentals >
-Broadcast Receiver Lifecycle</a> for more information.
-
-
-
-<h3><a name="provider_configuration"></a>AppWidget Configuration UI</h3>
-
-<p>
-Widget hosts have the ability to start a configuration activity when a widget is instantiated.
-The activity should be declared as normal in AndroidManifest.xml, and it should be listed in
-the AppWidgetProviderInfo XML file in the <code>android:configure</code> attribute.
-
-<p>The activity you specified will be launched with the {@link
-android.appwidget.AppWidgetManager#ACTION_APPWIDGET_CONFIGURE} action. See the documentation for that
-action for more info.
-
-<p>See the <code>src/com/example/android/apis/appwidget/ExampleAppWidgetConfigure.java</code>
-sample class in ApiDemos for an example.
-
-
-
-<h3><a name="providers_broadcasts"></a>AppWidget Broadcast Intents</h3>
-
-<p>{@link android.appwidget.AppWidgetProvider} is just a convenience class. If you would like
-to receive the widget broadcasts directly, you can. The four intents you need to care about are:
-<ul>
- <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE}</li>
- <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DELETED}</li>
- <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_ENABLED}</li>
- <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DISABLED}</li>
-</ul>
-
-<p>By way of example, the implementation of
-{@link android.appwidget.AppWidgetProvider#onReceive} is quite simple:</p>
-
-{@sample frameworks/base/core/java/android/appwidget/AppWidgetProvider.java onReceive}
-
<h2>AppWidget Hosts</h3>
<p>Widget hosts are the containers in which widgets can be placed. Most of the look and feel
@@ -132,5 +27,6 @@
adding, removing and otherwise managing widgets.</p>
<p>For more information on implementing your own widget host, see the
{@link android.appwidget.AppWidgetHost AppWidgetHost} class.</p>
+
</body>
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index 3c9b7c2..a5fdae9 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -19,11 +19,13 @@
<ul>
<li><a href="<?cs var:toroot ?>guide/topics/ui/declaring-layout.html">Declaring Layout</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html">Creating Menus</a></li>
- <li><a href="<?cs var:toroot ?>guide/topics/ui/layout-objects.html">Common Layout Objects</a></li>
- <li><a href="<?cs var:toroot ?>guide/topics/ui/binding.html">Binding to Data with AdapterView</a></li>
+ <!-- <li><a href="<?cs var:toroot ?>guide/topics/ui/dialogs.html">Creating Dialogs</a></li> -->
<li><a href="<?cs var:toroot ?>guide/topics/ui/ui-events.html">Handling UI Events</a></li>
+ <!-- <li><a href="<?cs var:toroot ?>guide/topics/ui/notifiers/index.html">Notifying the User</a></li> -->
<li><a href="<?cs var:toroot ?>guide/topics/ui/themes.html">Applying Styles and Themes</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/ui/custom-components.html">Building Custom Components</a></li>
+ <li><a href="<?cs var:toroot ?>guide/topics/ui/binding.html">Binding to Data with AdapterView</a></li>
+ <li><a href="<?cs var:toroot ?>guide/topics/ui/layout-objects.html">Common Layout Objects</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/ui/how-android-draws.html">How Android Draws Views</a></li>
</ul>
</li>
@@ -37,7 +39,6 @@
<li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html">Intents and Intent Filters</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/data/data-storage.html">Data Storage</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/providers/content-providers.html">Content Providers</a></li>
-<!-- <li><a style="color:gray;">Notifications</a></li> -->
<li><a href="<?cs var:toroot ?>guide/topics/security/security.html">Security and Permissions</a></li>
<!-- <li><a style="color:gray;">Processes and Threads</a></li> -->
<!-- <li><a style="color:gray;">Interprocess Communication</a></li> -->
@@ -94,6 +95,7 @@
</ul>
</li> -->
<!-- <li><a style="color:gray;">Localization</a></li> -->
+ <li><a href="<?cs var:toroot ?>guide/topics/appwidgets/index.html">AppWidgets</a></li>
</ul>
</li>
diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd
new file mode 100644
index 0000000..f6d481a
--- /dev/null
+++ b/docs/html/guide/topics/appwidgets/index.jd
@@ -0,0 +1,154 @@
+page.title=AppWidgets
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>Key classes</h2>
+ <ol>
+ <li>{@link android.appwidget.AppWidgetProvider}</li>
+ <li>{@link android.appwidget.AppWidgetHost}</li>
+ </ol>
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#Providers">AppWidget Providers</a>
+ <ol>
+ <li><a href="#provider_manifest">Declaring a widget in the AndroidManifest</a></li>
+ <li><a href="#provider_meta_data">Adding the AppWidgetProviderInfo meta-data</a></li>
+ <li><a href="#provider_AppWidgetProvider">Using the AppWidgetProvider class</a></li>
+ <li><a href="#provider_configuration">AppWidget Configuration UI</a></li>
+ <li><a href="#provider_broadcasts">AppWidget Broadcast Intents</a></li>
+ </ol>
+ </li>
+ <li><a href="#Hosts">AppWidget Hosts</a></li>
+ </ol>
+
+ <h2>See also</h2>
+ <ol>
+ <li><a href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html">Introducing
+ home screen widgets and the AppWidget framework »</a></li>
+ </ol>
+ </div>
+</div>
+
+<p>AppWidgets are miniature application views that can be embedded in other applications
+(e.g., the Home). These views are called "widgets" and you can publish one with
+an "AppWidget provider." An application component that is able to hold other widgets is
+called an "AppWidget host."</p>
+
+
+
+
+<h2 id="Providers">AppWidget Providers</h2>
+<p>Any application can publish widgets. All an application needs to do to publish a widget is
+to have a {@link android.content.BroadcastReceiver} that receives the {@link
+android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} intent,
+and provide some meta-data about the widget. Android provides the
+{@link android.appwidget.AppWidgetProvider} class, which extends BroadcastReceiver, as a convenience
+class to aid in handling the broadcasts.
+
+
+<h3 id="provider_manifest">Declaring a widget in the AndroidManifest</h3>
+
+<p>First, declare the {@link android.content.BroadcastReceiver} in your application's
+<code>AndroidManifest.xml</code> file.
+
+{@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/AndroidManifest.xml AppWidgetProvider}
+
+<p>
+The <b><code><receiver></b> element has the following attributes:
+<ul>
+ <li><b><code>android:name</code> -</b> which specifies the
+ {@link android.content.BroadcastReceiver} or {@link android.appwidget.AppWidgetProvider}
+ class.</li>
+ <li><b><code>android:label</code> -</b> which specifies the string resource that
+ will be shown by the widget picker as the label.</li>
+ <li><b><code>android:icon</code> -</b> which specifies the drawable resource that
+ will be shown by the widget picker as the icon.</li>
+</ul>
+
+<p>
+The <b><code><intent-filter></b> element tells the {@link android.content.pm.PackageManager}
+that this {@link android.content.BroadcastReceiver} receives the {@link
+android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} broadcast.
+The widget manager will send other broadcasts directly to your widget provider as required.
+It is only necessary to explicitly declare that you accept the {@link
+android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} broadcast.
+
+<p>
+The <b><code><meta-data></code></b> element tells the widget manager which xml resource to
+read to find the {@link android.appwidget.AppWidgetProviderInfo} for your widget provider. It has the following
+attributes:
+<ul>
+ <li><b><code>android:name="android.appwidget.provider"</code> -</b> identifies this meta-data
+ as the {@link android.appwidget.AppWidgetProviderInfo} descriptor.</li>
+ <li><b><code>android:resource</code> -</b> is the xml resource to use as that descriptor.</li>
+</ul>
+
+
+<h3 id="provider_meta_data">Adding the AppWidgetProviderInfo meta-data</h3>
+
+<p>For a widget, the values in the {@link android.appwidget.AppWidgetProviderInfo} structure are supplied
+in an XML resource. In the example above, the xml resource is referenced with
+<code>android:resource="@xml/appwidget_info"</code>. That XML file would go in your application's
+directory at <code>res/xml/appwidget_info.xml</code>. Here is a simple example.
+
+{@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/res/xml/appwidget_info.xml AppWidgetProviderInfo}
+
+<p>The attributes are as documented in the
+{@link android.appwidget.AppWidgetProviderInfo} class.
+
+
+<h3 id="provider_AppWidgetProvider">Using the AppWidgetProvider class</h3>
+
+<p>The AppWidgetProvider class is the easiest way to handle the widget provider intent broadcasts.
+See the <code>src/com/example/android/apis/appwidget/ExampleAppWidgetProvider.java</code>
+sample class in ApiDemos for an example.
+
+<p class="note">Keep in mind that since the the AppWidgetProvider is a BroadcastReceiver,
+your process is not guaranteed to keep running after the callback methods return. See
+<a href="../../../guide/topics/fundamentals.html#broadlife">Application Fundamentals >
+Broadcast Receiver Lifecycle</a> for more information.
+
+
+
+<h3 id="provider_configuration">AppWidget Configuration UI</h3>
+
+<p>
+Widget hosts have the ability to start a configuration activity when a widget is instantiated.
+The activity should be declared as normal in AndroidManifest.xml, and it should be listed in
+the AppWidgetProviderInfo XML file in the <code>android:configure</code> attribute.
+
+<p>The activity you specified will be launched with the {@link
+android.appwidget.AppWidgetManager#ACTION_APPWIDGET_CONFIGURE} action. See the documentation for that
+action for more info.
+
+<p>See the <code>src/com/example/android/apis/appwidget/ExampleAppWidgetConfigure.java</code>
+sample class in ApiDemos for an example.
+
+
+
+<h3 id="provider_broadcasts">AppWidget Broadcast Intents</h3>
+
+<p>{@link android.appwidget.AppWidgetProvider} is just a convenience class. If you would like
+to receive the widget broadcasts directly, you can. The four intents you need to care about are:
+<ul>
+ <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE}</li>
+ <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DELETED}</li>
+ <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_ENABLED}</li>
+ <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DISABLED}</li>
+</ul>
+
+<p>By way of example, the implementation of
+{@link android.appwidget.AppWidgetProvider#onReceive} is quite simple:</p>
+
+{@sample frameworks/base/core/java/android/appwidget/AppWidgetProvider.java onReceive}
+
+
+<h2 id="Hosts">AppWidget Hosts</h2>
+
+<p>Widget hosts are the containers in which widgets can be placed. Most of the look and feel
+details are left up to the widget hosts. For example, the home screen has one way of viewing
+widgets, but the lock screen could also contain widgets, and it would have a different way of
+adding, removing and otherwise managing widgets.</p>
+<p>For more information on implementing your own widget host, see the
+{@link android.appwidget.AppWidgetHost AppWidgetHost} class.</p>