Android allows applications to publish views to be embedded in other applications. These views are called widgets, and are published by "AppWidget providers." The component that can contain widgets is called a "AppWidget host."
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.
First, declare the {@link android.content.BroadcastReceiver} in your application's
AndroidManifest.xml file.
{@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/AndroidManifest.xml AppWidgetProvider}
The <receiver> element has the following attributes:
android:name - which specifies the
{@link android.content.BroadcastReceiver} or {@link android.appwidget.AppWidgetProvider}
class.android:label - which specifies the string resource that
will be shown by the widget picker as the label.android:icon - which specifies the drawable resource that
will be shown by the widget picker as the icon.
The <intent-filter> 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.
The <meta-data> 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:
android:name="android.appwidget.provider" - identifies this meta-data
as the {@link android.appwidget.AppWidgetProviderInfo} descriptor.android:resource - is the xml resource to use as that descriptor.
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
android:resource="@xml/appwidget_info". That XML file would go in your application's
directory at res/xml/appwidget_info.xml. Here is a simple example.
{@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/res/xml/appwidget_info.xml AppWidgetProviderInfo}
The attributes are as documented in the {@link android.appwidget.AppWidgetProviderInfo GagetInfo} class. (86400000 milliseconds means once per day)
The AppWidgetProvider class is the easiest way to handle the widget provider intent broadcasts.
See the src/com/example/android/apis/appwidget/ExampleAppWidgetProvider.java
sample class in ApiDemos for an example.
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 Application Fundamentals > Broadcast Receiver Lifecycle for more information.
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 android:configure attribute.
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.
See the src/com/example/android/apis/appwidget/ExampleAppWidgetConfigure.java
sample class in ApiDemos for an example.
{@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:
By way of example, the implementation of {@link android.appwidget.AppWidgetProvider#onReceive} is quite simple:
{@sample frameworks/base/core/java/android/appwidget/AppWidgetProvider.java onReceive}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.
For more information on implementing your own widget host, see the {@link android.appwidget.AppWidgetHost AppWidgetHost} class.