Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit af3289e4 authored by Scott Main's avatar Scott Main Committed by The Android Open Source Project
Browse files

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

Merge commit '620986a3' into donut

* commit '620986a3':
  AI 147438: add app widget docs to dev guide
parents 181634f0 620986a3

core/java/android/appwidget/package.html

+5 −109
Original line number Diff line number Diff line
@@ -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>

docs/html/guide/guide_toc.cs

+5 −3
Original line number Diff line number Diff line
@@ -19,11 +19,13 @@ 
          <ul>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/declaring-layout.html">Declaring Layout</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html">Creating Menus</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/layout-objects.html">Common Layout Objects</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/binding.html">Binding to Data with AdapterView</a></li>

     <!--       <li><a href="<?cs var:toroot ?>guide/topics/ui/dialogs.html">Creating Dialogs</a></li>  -->

            <li><a href="<?cs var:toroot ?>guide/topics/ui/ui-events.html">Handling UI Events</a></li>

     <!--       <li><a href="<?cs var:toroot ?>guide/topics/ui/notifiers/index.html">Notifying the User</a></li> -->

            <li><a href="<?cs var:toroot ?>guide/topics/ui/themes.html">Applying Styles and Themes</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/custom-components.html">Building Custom Components</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/binding.html">Binding to Data with AdapterView</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/layout-objects.html">Common Layout Objects</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/how-android-draws.html">How Android Draws Views</a></li>

          </ul>

      </li>
@@ -37,7 +39,6 @@ 
      <li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html">Intents and Intent Filters</a></li>

      <li><a href="<?cs var:toroot ?>guide/topics/data/data-storage.html">Data Storage</a></li>

      <li><a href="<?cs var:toroot ?>guide/topics/providers/content-providers.html">Content Providers</a></li>

<!--  <li><a style="color:gray;">Notifications</a></li> -->

      <li><a href="<?cs var:toroot ?>guide/topics/security/security.html">Security and Permissions</a></li>

<!--  <li><a style="color:gray;">Processes and Threads</a></li> -->

<!--  <li><a style="color:gray;">Interprocess Communication</a></li> -->
@@ -94,6 +95,7 @@ 
          </ul>

      </li> -->

<!--  <li><a style="color:gray;">Localization</a></li>  -->

      <li><a href="<?cs var:toroot ?>guide/topics/appwidgets/index.html">AppWidgets</a></li>

    </ul>

</li>

docs/html/guide/topics/appwidgets/index.jd

0 → 100644
+154 −0
Original line number Diff line number Diff line 
page.title=AppWidgets

@jd:body



<div id="qv-wrapper">

  <div id="qv">

    <h2>Key classes</h2>

    <ol>

      <li>{@link android.appwidget.AppWidgetProvider}</li>

      <li>{@link android.appwidget.AppWidgetHost}</li>

    </ol>

    <h2>In this document</h2>

    <ol>

      <li><a href="#Providers">AppWidget Providers</a>

        <ol>

          <li><a href="#provider_manifest">Declaring a widget in the AndroidManifest</a></li>

          <li><a href="#provider_meta_data">Adding the AppWidgetProviderInfo meta-data</a></li>

          <li><a href="#provider_AppWidgetProvider">Using the AppWidgetProvider class</a></li>

          <li><a href="#provider_configuration">AppWidget Configuration UI</a></li>

          <li><a href="#provider_broadcasts">AppWidget Broadcast Intents</a></li>

        </ol>

      </li>

      <li><a href="#Hosts">AppWidget Hosts</a></li>

    </ol>



    <h2>See also</h2>

    <ol>

      <li><a href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html">Introducing

      home screen widgets and the AppWidget framework &raquo;</a></li>

    </ol>

  </div>

</div>



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









<h2 id="Providers">AppWidget Providers</h2>

<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 id="provider_manifest">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 id="provider_meta_data">Adding the 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} class.





<h3 id="provider_AppWidgetProvider">Using the 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 id="provider_configuration">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 id="provider_broadcasts">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 id="Hosts">AppWidget Hosts</h2>



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

<p>For more information on implementing your own widget host, see the

{@link android.appwidget.AppWidgetHost AppWidgetHost} class.</p>