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

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

Browse Source 
Merge commit 'af3289e4448971b38ae4e95269401452dbc6077e'

* commit 'af3289e4448971b38ae4e95269401452dbc6077e':
  AI 147438: add app widget docs to dev guide
This commit is contained in:
Scott Main
2009-04-29 13:35:39 -07:00
committed by The Android Open Source Project
parent 3d31904115 af3289e444
commit 64b786f159
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>