diff options
| -rw-r--r-- | core/java/android/appwidget/package.html | 114 | ||||
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 8 | ||||
| -rw-r--r-- | docs/html/guide/topics/appwidgets/index.jd | 154 |
3 files changed, 164 insertions, 112 deletions
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 @@ widgets, but the lock screen could also contain widgets, and it would have a dif 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> |