Android allows applications to publish views to be embedded in other applications. These views are called gadgets, and are published by "gadget providers." The component that can contain gadgets is called a "gadget host."
Any application can publish gadgets. All an application needs to do to publish a gadget is to have a {@link android.content.BroadcastReceiver} that receives the {@link android.gadget.GadgetManager#ACTION_GADGET_UPDATE GadgetManager.ACTION_GADGET_UPDATE} intent, and provide some meta-data about the gadget. Android provides the {@link android.gadget.GadgetProvider} 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/gadgets/GadgetHostTest/AndroidManifest.xml GadgetProvider}
The <receiver> element has the following attributes:
android:name - which specifies the
{@link android.content.BroadcastReceiver} or {@link android.gadget.GadgetProvider}
class.android:label - which specifies the string resource that
will be shown by the gadget picker as the label.android:icon - which specifies the drawable resource that
will be shown by the gadget 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.gadget.GadgetManager#ACTION_GADGET_UPDATE GadgetManager.ACTION_GADGET_UPDATE} broadcast.
The gadget manager will send other broadcasts directly to your gadget provider as required.
It is only necessary to explicitly declare that you accept the {@link
android.gadget.GadgetManager#ACTION_GADGET_UPDATE GadgetManager.ACTION_GADGET_UPDATE} broadcast.
The <meta-data> element tells the gadget manager which xml resource to
read to find the {@link android.gadget.GadgetProviderInfo} for your gadget provider. It has the following
attributes:
android:name="android.gadget.provider" - identifies this meta-data
as the {@link android.gadget.GadgetProviderInfo} descriptor.android:resource - is the xml resource to use as that descriptor.
For a gadget, the values in the {@link android.gadget.GadgetProviderInfo} structure are supplied
in an XML resource. In the example above, the xml resource is referenced with
android:resource="@xml/gadget_info". That XML file would go in your application's
directory at res/xml/gadget_info.xml. Here is a simple example.
{@sample frameworks/base/tests/gadgets/GadgetHostTest/res/xml/gadget_info.xml GadgetProviderInfo}
The attributes are as documented in the {@link android.gadget.GadgetProviderInfo GagetInfo} class. (86400000 milliseconds means once per day)
The GadgetProvider class is the easiest way to handle the gadget provider intent broadcasts.
See the src/com/example/android/apis/gadget/ExampleGadgetProvider.java
sample class in ApiDemos for an example.
Keep in mind that since the the GadgetProvider 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.
Gadget hosts have the ability to start a configuration activity when a gadget is instantiated.
The activity should be declared as normal in AndroidManifest.xml, and it should be listed in
the GadgetProviderInfo XML file in the android:configure attribute.
The activity you specified will be launched with the {@link android.gadget.GadgetManager#ACTION_GADGET_CONFIGURE} action. See the documentation for that action for more info.
See the src/com/example/android/apis/gadget/ExampleGadgetConfigure.java
sample class in ApiDemos for an example.
{@link android.gadget.GadgetProvider} is just a convenience class. If you would like to receive the gadget broadcasts directly, you can. The four intents you need to care about are:
By way of example, the implementation of {@link android.gadget.GadgetProvider#onReceive} is quite simple:
{@sample frameworks/base/core/java/android/gadget/GadgetProvider.java onReceive}Gadget hosts are the containers in which gadgets can be placed. Most of the look and feel details are left up to the gadget hosts. For example, the home screen has one way of viewing gadgets, but the lock screen could also contain gadgets, and it would have a different way of adding, removing and otherwise managing gadgets.
For more information on implementing your own gadget host, see the {@link android.gadget.GadgetHost GadgetHost} class.