Creating an App Widget Configuration Activity

If you would like the user to configure settings when he or she adds a new App Widget, you can create an App Widget configuration Activity. This Activity will be automatically launched by the App Widget host and allows the user to configure available settings for the App Widget at create-time, such as the App Widget color, size, update period or other functionality settings.

Also, the Activity must be declared in the AppWidgetProviderlnfo XML file, with the android:configure attribute (see Adding the AppWidgetProvierlnfo Metadata above). For example, the configuration Activity can be declared like this:

<appwidget-provider xmlns:android=""

android:configure="" ... >


Notice that the Activity is declared with a fully-qualified namespace, because it will be referenced from outside your package scope.

That's all you need to get started with a configuration Activity. Now all you need is the actual Activity. There are, however, two important things to remember when you implement the Activity:

• The App Widget host calls the configuration Activity and the configuration Activity should always return a result. The result should include the App Widget ID passed by the Intent that launched the Activity (saved in the Intent extras as EXTRA APPWIDGET ID).

• The onUpdate() method will not be called when the App Widget is created (the system will not send the ACTION_APPWIDGET_UPDATE broadcast when a configuration Activity is launched). It is the responsibility of the configuration Activity to request an update from the AppWidgetManager when the App Widget is first created. However, onUpdateQ will be called for subsequent updates—it is only skipped the first time.

See the code snippets in the following section for an example of how to return a result from the configuration and update the App Widget.

The configuration Activity should be declared as a normal Activity in the Android manifest file. However, it will be launched by the App Widget host with the ACTION APPWIDGET CONFIGUREaction, so the Activity needs to accept this Intent. For example:

<activity android:name=".ExampleAppWidgetConfigure"> <intent-filter>

<action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" /> </intent-filter> </activity>

Updating the App Widget from the configuration Activity

When an App Widget uses a configuration Activity, it is the responsibility of the Activity to update the App Widget when configuration is complete. You can do so by requesting an update directly from the AppWidgetManager.

Here's a summary of the procedure to properly update the App Widget and close the configuration Activity: 1. First, get the App Widget ID from the Intent that launched the Activity:

2. Perform your App Widget configuration.

3. When the configuration is complete, get an instance of the AppWidgetManager by calling getInstance(Context):

AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

4. Update the App Widget with a RemoteViews layout by calling updateAppWidget(int, RemoteViews):

RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example appwidget);

appWidgetManager.updateAppWidget(mAppWidgetId, views);

5. Finally, create the return Intent, set it with the Activity result, and finish the Activity:

Intent resultValue = new Intent();

resultValue.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, mAppWidgetId);

setResult(RESULT_OK, resultValue);

Tip: When your configuration Activity first opens, set the Activity result to RESULT_CANCELED. This way, if the user backs-out of the Activity before reaching the end, the App Widget host is notified that the configuration was cancelled and the App Widget will not be added.

See the sample class in ApiDemos for an example.

Intent intent = getIntent(); Bundle extras = intent.getExtras(); if (extras != null) {

mAppWidgetId = extras.getInt(


Was this article helpful?

+1 0

Post a comment