index.jd revision a055e5ea1d87a958cc2c0ea82fe7026b205578b9
1page.title=AppWidgets 2@jd:body 3 4<div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>Key classes</h2> 7 <ol> 8 <li>{@link android.appwidget.AppWidgetProvider}</li> 9 <li>{@link android.appwidget.AppWidgetHost}</li> 10 </ol> 11 <h2>In this document</h2> 12 <ol> 13 <li><a href="#Providers">AppWidget Providers</a> 14 <ol> 15 <li><a href="#provider_manifest">Declaring a widget in the AndroidManifest</a></li> 16 <li><a href="#provider_meta_data">Adding the AppWidgetProviderInfo meta-data</a></li> 17 <li><a href="#provider_AppWidgetProvider">Using the AppWidgetProvider class</a></li> 18 <li><a href="#provider_configuration">AppWidget Configuration UI</a></li> 19 <li><a href="#provider_broadcasts">AppWidget Broadcast Intents</a></li> 20 </ol> 21 </li> 22 <li><a href="#Hosts">AppWidget Hosts</a></li> 23 </ol> 24 25 <h2>See also</h2> 26 <ol> 27 <li><a href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html">Introducing 28 home screen widgets and the AppWidget framework »</a></li> 29 </ol> 30 </div> 31</div> 32 33<p>AppWidgets are miniature application views that can be embedded in other applications 34(e.g., the Home). These views are called "widgets" and you can publish one with 35an "AppWidget provider." An application component that is able to hold other widgets is 36called an "AppWidget host."</p> 37 38 39 40 41<h2 id="Providers">AppWidget Providers</h2> 42<p>Any application can publish widgets. All an application needs to do to publish a widget is 43to have a {@link android.content.BroadcastReceiver} that receives the {@link 44android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} intent, 45and provide some meta-data about the widget. Android provides the 46{@link android.appwidget.AppWidgetProvider} class, which extends BroadcastReceiver, as a convenience 47class to aid in handling the broadcasts. 48 49 50<h3 id="provider_manifest">Declaring a widget in the AndroidManifest</h3> 51 52<p>First, declare the {@link android.content.BroadcastReceiver} in your application's 53<code>AndroidManifest.xml</code> file. 54 55{@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/AndroidManifest.xml AppWidgetProvider} 56 57<p> 58The <code><receiver></code> element has the following attributes: 59<ul> 60 <li><code>android:name</code> - specifies the 61 {@link android.content.BroadcastReceiver} or {@link android.appwidget.AppWidgetProvider} 62 class.</li> 63 <li><code>android:label</code> - specifies the string resource that 64 will be shown by the widget picker as the label.</li> 65 <li><code>android:icon</code> - specifies the drawable resource that 66 will be shown by the widget picker as the icon.</li> 67</ul> 68 69<p> 70The <code><intent-filter> element tells the {@link android.content.pm.PackageManager} 71that this {@link android.content.BroadcastReceiver} receives the {@link 72android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} broadcast. 73The widget manager will send other broadcasts directly to your widget provider as required. 74It is only necessary to explicitly declare that you accept the {@link 75android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} broadcast. 76 77<p> 78The <code><meta-data></code> element tells the widget manager which xml resource to 79read to find the {@link android.appwidget.AppWidgetProviderInfo} for your widget provider. It has the following 80attributes: 81<ul> 82 <li><code>android:name="android.appwidget.provider"</code> - identifies this meta-data 83 as the {@link android.appwidget.AppWidgetProviderInfo} descriptor.</li> 84 <li><code>android:resource</code> - is the xml resource to use as that descriptor.</li> 85</ul> 86 87 88<h3 id="provider_meta_data">Adding the AppWidgetProviderInfo meta-data</h3> 89 90<p>For a widget, the values in the {@link android.appwidget.AppWidgetProviderInfo} structure are supplied 91in an XML resource. In the example above, the xml resource is referenced with 92<code>android:resource="@xml/appwidget_info"</code>. That XML file would go in your application's 93directory at <code>res/xml/appwidget_info.xml</code>. Here is a simple example. 94 95{@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/res/xml/appwidget_info.xml AppWidgetProviderInfo} 96 97<p>The attributes are as documented in the 98{@link android.appwidget.AppWidgetProviderInfo} class. 99 100 101<h3 id="provider_AppWidgetProvider">Using the AppWidgetProvider class</h3> 102 103<p>The AppWidgetProvider class is the easiest way to handle the widget provider intent broadcasts. 104See the <code>src/com/example/android/apis/appwidget/ExampleAppWidgetProvider.java</code> 105sample class in ApiDemos for an example. 106 107<p class="note">Keep in mind that since the the AppWidgetProvider is a BroadcastReceiver, 108your process is not guaranteed to keep running after the callback methods return. See 109<a href="../../../guide/topics/fundamentals.html#broadlife">Application Fundamentals > 110Broadcast Receiver Lifecycle</a> for more information. 111 112 113 114<h3 id="provider_configuration">AppWidget Configuration UI</h3> 115 116<p> 117Widget hosts have the ability to start a configuration activity when a widget is instantiated. 118The activity should be declared as normal in AndroidManifest.xml, and it should be listed in 119the AppWidgetProviderInfo XML file in the <code>android:configure</code> attribute. 120 121<p>The activity you specified will be launched with the {@link 122android.appwidget.AppWidgetManager#ACTION_APPWIDGET_CONFIGURE} action. See the documentation for that 123action for more info. 124 125<p>See the <code>src/com/example/android/apis/appwidget/ExampleAppWidgetConfigure.java</code> 126sample class in ApiDemos for an example. 127 128 129 130<h3 id="provider_broadcasts">AppWidget Broadcast Intents</h3> 131 132<p>{@link android.appwidget.AppWidgetProvider} is just a convenience class. If you would like 133to receive the widget broadcasts directly, you can. The four intents you need to care about are: 134<ul> 135 <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE}</li> 136 <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DELETED}</li> 137 <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_ENABLED}</li> 138 <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DISABLED}</li> 139</ul> 140 141<p>By way of example, the implementation of 142{@link android.appwidget.AppWidgetProvider#onReceive} is quite simple:</p> 143 144{@sample frameworks/base/core/java/android/appwidget/AppWidgetProvider.java onReceive} 145 146 147<h2 id="Hosts">AppWidget Hosts</h2> 148 149<p>Widget hosts are the containers in which widgets can be placed. Most of the look and feel 150details are left up to the widget hosts. For example, the home screen has one way of viewing 151widgets, but the lock screen could also contain widgets, and it would have a different way of 152adding, removing and otherwise managing widgets.</p> 153<p>For more information on implementing your own widget host, see the 154{@link android.appwidget.AppWidgetHost AppWidgetHost} class.</p> 155