Declaring an App Widget in the Manifest

---

 

First, declare the AppWidgetProvider class in yourapplication'sAndroidManifest.xml file. For example:

 

Adding the AppWidgetProviderInfo Metadata

---

 

The AppWidgetProviderInfo defines the essential qualities of an App Widget, such as its minimum layout dimensions, its initiallayout resource,how often to update the App Widget, and (optionally) a configuration Activity tolaunch at create-time.Define the AppWidgetProviderInfo object in an XML resource using a single element and save it in the project'sres/xml/ folder.

For example:

The updatePeriodMillis attribute defines how often the AppWidget framework should request an update from theAppWidgetProvider by calling theonUpdate() callback method. The actual updateis not guaranteed to occur exactly on time with this value and we suggestupdating as infrequently as possible—perhaps no more than once an hour toconserve the battery. You might also allow the user to adjust the frequency in aconfiguration—some people might want a stock ticker to update every 15minutes, or maybe only four times a day.

Note: If the device is asleep when itis time for an update (as defined byupdatePeriodMillis), then the device willwake up in order to perform the update. If you don't update more than once per hour, thisprobably won't cause significant problems for the battery life.If, however, you needto update more frequently and/or you do not need to update while the device is asleep,then you can instead perform updates based on an alarm that will not wake the device. To doso, set an alarm with an Intent that your AppWidgetProvider receives, using theAlarmManager. Set the alarm type to eitherELAPSED_REALTIME orRTC, which will only deliver the alarm when the device is awake. Then setupdatePeriodMillis to zero (0).

 

Creating the App Widget Layout

---

 

You must define an initial layout for your App Widget in XML and save it inthe project'sres/layout/ directory. You can design your App Widget using theView objects listedbelow, but before you begin designing your App Widget, please read andunderstand theApp WidgetDesign Guidelines.

 

# of Cells
(Columns or Rows) Available Size (dp)
(minWidth or minHeight) 1 40dp 2 110dp 3 180dp 4 250dp … … n 70 × n − 30

 

 

 

Using the AppWidgetProvider Class

---

You must declare your AppWidgetProvider class implementation as abroadcast receiver using the element in the AndroidManifest (see Declaring an App Widget in the Manifest above).

 

The AppWidgetProvider class extendsBroadcastReceiver as a convenienceclass to handle the App Widget broadcasts. The AppWidgetProvider receives onlythe event broadcasts thatare relevant to the App Widget, such as when the App Widget is updated, deleted,enabled, and disabled.When these broadcast events occur, the AppWidgetProvider receives the followingmethod calls:

onUpdate()This is called to update the App Widget at intervals defined by theupdatePeriodMillis attribute in the AppWidgetProviderInfo (seeAdding the AppWidgetProviderInfo Metadata above). This method is also called when the user adds the App Widget, so it should perform the essential setup, such as define event handlers for Views and start a temporaryService, if necessary. However, if you have declared aconfiguration Activity,this method is not called when the user adds theApp Widget, but is called for the subsequent updates. It is the responsibility of the configuration Activity to perform the first update when configuration isdone. (SeeCreating an App Widget ConfigurationActivity below.)