From 620986a358c522178ddfc5c0088b2a5e1768e5ae Mon Sep 17 00:00:00 2001 From: Scott Main <> Date: Wed, 22 Apr 2009 18:58:13 -0700 Subject: [PATCH] AI 147438: add app widget docs to dev guide move app widget docs out of the package description BUG=1790234 Automated import of CL 147438 --- core/java/android/appwidget/package.html | 114 +-------------- docs/html/guide/guide_toc.cs | 8 +- docs/html/guide/topics/appwidgets/index.jd | 154 +++++++++++++++++++++ 3 files changed, 164 insertions(+), 112 deletions(-) create mode 100644 docs/html/guide/topics/appwidgets/index.jd diff --git a/core/java/android/appwidget/package.html b/core/java/android/appwidget/package.html index b6cd9c74d02ef..2b85bd5a41a4e 100644 --- a/core/java/android/appwidget/package.html +++ b/core/java/android/appwidget/package.html @@ -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."

-

AppWidget Providers

- -

AppWidget Hosts

+

For more information, see the +AppWidgets +documentation in the Dev Guide.

{@more}

AppWidget Providers

-

-Any application can publish widgets. All an application needs to do to publish a widget is +

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

Declaring a widget in the AndroidManifest

- -

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

- -

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

- - -

Adding the {@link android.appwidget.AppWidgetProviderInfo AppWidgetProviderInfo} meta-data

- -

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

Using the {@link android.appwidget.AppWidgetProvider AppWidgetProvider} class

- -

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

AppWidget Configuration UI

- -

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

AppWidget Broadcast Intents

- -

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

AppWidget Hosts

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.

For more information on implementing your own widget host, see the {@link android.appwidget.AppWidgetHost AppWidgetHost} class.

+ diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 3c9b7c27bbcd8..a5fdae957c5c8 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -19,11 +19,13 @@ @@ -37,7 +39,6 @@
  • Intents and Intent Filters
  • Data Storage
  • Content Providers
    • -
  • Security and Permissions
    • @@ -94,6 +95,7 @@ --> +
  • AppWidgets
    • diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd new file mode 100644 index 0000000000000..f6d481ae882ee --- /dev/null +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -0,0 +1,154 @@ +page.title=AppWidgets +@jd:body + +
    +
    +

    Key classes

    +
      +
    1. {@link android.appwidget.AppWidgetProvider}
      2. +
    2. {@link android.appwidget.AppWidgetHost}
      3. +
    +

    In this document

    +
      +
    1. AppWidget Providers +
        +
      1. Declaring a widget in the AndroidManifest
        2. +
      2. Adding the AppWidgetProviderInfo meta-data
        3. +
      3. Using the AppWidgetProvider class
        4. +
      4. AppWidget Configuration UI
        5. +
      5. AppWidget Broadcast Intents
        6. +
      +
      2. +
    2. AppWidget Hosts
      3. +
    + +

    See also

    +
      +
    1. Introducing + home screen widgets and the AppWidget framework »
      2. +
    +
    +
    + +

    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."

    + + + + +

    AppWidget Providers

    +

    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. + + +

    Declaring a widget in the AndroidManifest

    + +

    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: +

    + +

    +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.
      • +
    + + +

    Adding the AppWidgetProviderInfo meta-data

    + +

    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} class. + + +

    Using the AppWidgetProvider class

    + +

    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. + + + +

    AppWidget Configuration UI

    + +

    +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. + + + +

    AppWidget Broadcast Intents

    + +

    {@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: +

      +
    • {@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE}
      • +
    • {@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DELETED}
      • +
    • {@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_ENABLED}
      • +
    • {@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DISABLED}
      • +
    + +

    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} + + +

    AppWidget Hosts

    + +

    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.