Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 620986a: AI 147438: add app widget docs to dev guide

Browse Source 
Merge commit '620986a358c522178ddfc5c0088b2a5e1768e5ae' into donut

* commit '620986a358c522178ddfc5c0088b2a5e1768e5ae':
  AI 147438: add app widget docs to dev guide
This commit is contained in:
Scott Main
2009-04-28 21:54:07 -07:00
committed by The Android Open Source Project
parent 181634f080 620986a358
commit af3289e444
3 changed files with 164 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
core/java/android/appwidget/package.html
View File

@@ -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>&lt;receiver&gt;</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>&lt;intent-filter&gt;</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>&lt;meta-data&gt;</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 &gt;
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>

8
docs/html/guide/guide_toc.cs
View File

@@ -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>

154
docs/html/guide/topics/appwidgets/index.jd Normal file
View File

@@ -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 &raquo;</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>&lt;receiver&gt;</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>&lt;intent-filter&gt;</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>&lt;meta-data&gt;</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 &gt;
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>