Widgets are often displayed alongside both native and third-party widgets, so it's important that yours conform to design standards. This is particularly important because widgets are most often used on the home screen.

There are widget UI design guidelines for controlling both layout size and visual styling. The former is rigidly enforced while the latter is a guide only; both are summarized in the following sections. Additional detail can also be found on the Android Developers Widget Design Guidelines site at http://developer.android.com/guide/practices/ui_guidelines/widget_design.html

Minimum size in dp = (Cell count * 74dp) - 2dp

Because of security and performance considerations there are several restrictions on the layouts and Views available to you when you're constructing your widget UI.

In general, the following Views are unavailable for App Widget layouts and will result in a null pointer error (NPE) if used:

Currently, the layouts available are limited to:

The Views they contain are restricted to:

The Text Views and Image Views are particularly useful. Later in this chapter you'll see how to use the Image View in conjunction with the SelectionStateDrawable resource to create interactive widgets with little or no code.

Listing 10-1 shows a sample layout resource used to define the UI of an App Widget.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout
  xmlns:android="http://schemas.android.com/apk/res/android"
  android:orientation="horizontal"
  android:layout_width="fill_parent"
  android:layout_height="fill_parent"
  android:padding="10sp">

<ImageView
    android:id="@+id/widget_image"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:src="@drawable/icon"
  />
  <TextView
    android:id="@+id/widget_text"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:text="Text Goes Here"
  />
</LinearLayout>

To create a new Remote Views object you must pass the name of the calling application package, and the layout resource you plan to manipulate, into the constructor, as shown in Listing 10-5. Later in this section you'll learn how to use this Remote Views object to update the Views and layout of your widget.

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

To use Remote Views on widgets, call the static getInstance method to return an instance of the App Widget Manager and use it to find identifiers for each instance of a particular widget class, as in this continuation of Listing 10-5:

// Get the App Widget Manager.
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
// Retrieve the identifiers for each instance of your chosen widget.
ComponentName thisWidget = new ComponentName(context, MyAppWidget.class);
int[] appWidgetIds = appWidgetManager.getAppWidgetIds(thisWidget);

When you've finished making changes to a Remote Views object, apply those modifications to one or more widgets by calling the updateAppWidget method on the App Widget Manager, passing in either an individual widget ID or an array of identifiers:

appWidgetManager.updateAppWidget(appWidgetIds, views);

The standard pattern used to update widget UI is to iterate over the widget ID array as shown in Listing 10-6. This enables you to apply different UI values to each widget based on its configuration settings or UI requirements.

final int N = appWidgetIds.length;
// Iterate through each widget, creating a RemoteViews object and
// applying the modified RemoteViews to each widget.
for (int i = 0; i < N; i++) {
  int appWidgetId = appWidgetIds[i];
  // Create a Remove View
  RemoteViews views = new RemoteViews(context.getPackageName(),
                                      R.layout.my_widget_layout);

  // TODO Update the widget UI using the views object.

  // Notify the App Widget Manager to update the widget using
  // the modified remote view.
  appWidgetManager.updateAppWidget(appWidgetId, views);
}

The App Widget Provider simplifies your widget interactions by passing the App Widget Manager, and an array of matching App Widget IDs, as parameters into the onUpdate handler.

You can then follow the same pattern as shown above, without the need to obtain a reference to the App Widget Manager or find the identifier values for the affected widgets first as shown in Listing 10-7.

@Override
public void onUpdate(Context context,
                     AppWidgetManager appWidgetManager,
                     int[] appWidgetIds) {
  final int N = appWidgetIds.length;
  for (int i = 0; i < N; i++) {
    int appWidgetId = appWidgetIds[i];
    // Create a Remove View
    RemoteViews views = new RemoteViews(context.getPackageName(),
                                        R.layout.my_widget_layout);
    // TODO Update the UI.

    // Notify the App Widget Manager to update the widget using
    // the modified remote view.
    appWidgetManager.updateAppWidget(appWidgetId, views);
  }
}

Remote Views expose a variety of methods designed to provide access to the properties and methods available on Views in order for you to change their appearance.

The most versatile of these is a series of methods that lets you execute a target method name on a remotely hosted View. These methods support the passing of single-value parameters. Supported method signatures include a parameter for each primitive type, including Boolean, integer, and float, plus strings, bitmaps, and URI parameters.

Listing 10-8 shows examples of some of the method signatures supported.

// Set the image level for an ImageView.
views.setInt(R.id.widget_image_view, "setImageLevel", 2);
// Show the cursor of a TextView.
views.setBoolean(R.id.widget_text_view, "setCursorVisible", true);
// Assign a bitmap to an ImageButton.
views.setBitmap(R.id.widget_image_button, "setImageBitmap", myBitmap);

Remote Views also include a set of View-specific methods to set values applicable to a particular View class, including Text Views, Image Views, Progress Bars, and Chronometers.

Listing 10-9 shows examples of some of these specialist methods:

// Update a Text View
views.setTextViewText(R.id.widget_text_view, "Updated Text");
views.setTextColor(R.id.widget_text_view, Color.BLUE);
// Update an Image View
views.setImageViewBitmap(R.id.widget_image_view, myBitmap);
// Update a Progress Bar
views.setProgressBar(R.id.widget_progressbar, 100, 50, false);
// Update a Chronometer
views.setChronometer(.id.widget_chronometer,
SystemClock.elapsedRealtime(), null, true);

You can also set the visibility of any View hosted within Remote Views by calling setViewVisibility, as shown here:

views.setViewVisibility(R.id.widget_text_view, View.VISIBLE);

As described in the previous section, once you've made changes to a Remote Views object you must use the App Widget Manager to apply those changes to a particular widget, as shown here:

appWidgetManager.updateAppWidget(appWidgetId, views);

You can also add interactivity to your widgets using Remote Views, but reactions to user input are tightly restricted.

Because they run within the home-screen process, the widgets themselves inherit its permissions. As a result of these security implications widget interactivity is carefully controlled.

Widget interaction is generally limited to two possibilities:

It's notable that there is no supported technique for entering text directly into an App Widget.

If you need text input from your widget, best practice is to add a click listener that displays an Activity to accept the user data when a portion of the widget is clicked.

Intent intent = new Intent("com.paad.ACTION_WIDGET_CLICK");
PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent, 0);
views.setOnClickPendingIntent(R.id.my_text_view, pendingIntent);

<selector xmlns:android="http://schemas.android.com/apk/res/android">
  <item android:state_window_focused="false"
        android:drawable="@drawable/widget_bg_normal"/>
  <item android:state_focused="true"
        android:drawable="@drawable/widget_bg_selected"/>
  <item android:state_pressed="true"
        android:drawable="@drawable/widget_bg_pressed"/>
  <item android:drawable="@drawable/widget_bg_normal"/>
</selector>

The simplest, but potentially most resource-intensive, technique is to set the minimum update rate for a widget in the XML definition file, as shown in Listing 10-12, where the widget is updated once every hour:

<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider
  xmlns:android="http://schemas.android.com/apk/res/android"
  android:initialLayout="@layout/my_widget_layout"
  android:minWidth="146dp"
  android:minHeight="146dp"
  android:label="My App Widget"
  android:updatePeriodMillis="3600000"
/>

Setting this value will cause the device to broadcast an Intent requesting an update of your widget at the rate specified.

This technique should be used to define the absolute minimum rate at which your widget must be updated to remain useful. Generally the minimum expected update rate should be at least an hour, ideally not more than once or twice a day.

If your device requires more frequent updates, consider using one of the techniques described in the following sections to dynamically perform updates using either an event/Intent-driven model or a more efficient scheduled model using Alarms.

As widgets are implemented as Intent Receivers you can trigger updates and UI refreshes by registering Intent Filters for additional actions.

This is a dynamic approach to refreshing your widget that uses a more efficient event model rather than the potentially battery-draining method of specifying a short minimum refresh rate.

The XML snippet in Listing 10-13 assigns a new Intent Filter to the manifest entry of the widget defined earlier:

<receiver android:name=".MyAppWidget" android:label="My App Widget">
  <intent-filter>
    <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
  </intent-filter>
  <intent-filter>
    <action android:name="com.paad.chapter9.FORCE_WIDGET_UPDATE" />
  </intent-filter>
  <meta-data
    android:name="android.appwidget.provider"
    android:resource="@xml/my_app_widget_info"
  />
</receiver>

By updating the widget's onReceive method handler as shown in Listing 10-14, you can listen for this new Intent and use it to update your widget.

public static String FORCE_WIDGET_UPDATE =
"com.paad.chapter9.FORCE_WIDGET_UPDATE";

@Override
public void onReceive(Context context, Intent intent) {
  super.onReceive(context, intent);

  if (FORCE_WIDGET_UPDATE.equals(intent.getAction())) {
    // TODO Update widget UI.
  }
}

To trigger an update of your widget at any point in your application, you can broadcast an Intent using this action:

context.sendBroadcast(new Intent(FORCE_WIDGET_UPDATE));

This technique is particularly useful for reacting to system, user, or application events — like a data refresh, or a user action such as clicking buttons on the widget itself. You can also register for system event broadcasts such as changes to network connectivity, battery level, or screen brightness.

Alarms provide a middle-ground alternative to the polling and Intent-based techniques described so far.

Alarms, covered in detail in Chapter 9, provide a flexible way to schedule regular events within your application. Using alarms you can poll at regular intervals, using an Intent to trigger your updates.

Using Alarms to refresh your widgets is similar to using the Intent-driven model described earlier. Add a new Intent Filter to the manifest entry for your widget and override its onReceive method to identify the Intent that triggered it. Within your application, use the Alarm Manager to create an Alarm that fires an Intent with the registered action.

Alarms have an advantage over the minimum refresh rate, thanks to their flexibility.

Like the widgets' refresh rate, Alarms also have the ability to wake the device when they fire — making it equally important to take care to minimize battery use.

Alternatively, by using the RTC or ELAPSED_REALTIME modes when constructing your alarm, you can configure it to trigger after a minimum interval has elapsed, but only after the device has awakened:

alarmManager.setRepeating(AlarmManager.ELAPSED_REALTIME,
                          AlarmManager.INTERVAL_HOUR,
                          AlarmManager.INTERVAL_HOUR,
                          pi);

Using this technique will ensure your widget is up to date when visible, without draining the battery unnecessarily to update the widget when the screen is off.

If your widget does need to be updated even when the device is on standby, you can optimize this process with the inexact repeating option, shown here:

String alarmService = Context.ALARM_SERVICE;
AlarmManager alarmManager = (AlarmManager)getSystemService(alarmService);

Intent intent = new Intent(MyAppWidget.FORCE_WIDGET_UPDATE);
PendingIntent pi = PendingIntent.getBroadcast(this,
                                              0,
                                              intent,
                                              0);

alarmManager.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP,
                                 AlarmManager.INTERVAL_HALF_DAY,
                                 AlarmManager.INTERVAL_HALF_DAY,
                                 pi);

As described in Chapter 9, the inexact repeating Alarm will optimize the alarm triggers by phase-shifting all the alarms scheduled to occur at similar times. This ensures the device is only awakened once, rather than several times within a few minutes.

Any Content Provider can provide the data displayed within a Live Folder. Live Folders use a standard set of column names:

Figure 10-4. FIGURE 10-4

When displayed, a Live Folder will use these column names to extract data from your Content Provider for display.

Rather than renaming your Content Provider to suit the requirements of Live Folders, you should apply a projection that maps the required column names to columns used within your existing Content Provider, as shown in Listing 10-15.

final HashMap<String, String> liveFolderProjection =
  new HashMap<String, String>();
liveFolderProjection.put(LiveFolders._ID,
                         KEY_ID + " AS " +
                         LiveFolders._ID);
liveFolderProjection.put(LiveFolders.NAME,
                         KEY_NAME_COLUMN + " AS " +
                         LiveFolders.NAME);
liveFolderProjection.put(LiveFolders.DESCRIPTION,
                         KEY_DESCRIPTION_COLUMN + " AS " +
                         LiveFolders.DESCRIPTION);
liveFolderProjection.put(LiveFolders.IMAGE,
                         KEY_IMAGE_COLUMN + " AS " +
                         LiveFolders.IMAGE);

SQLiteQueryBuilder qb = new SQLiteQueryBuilder();
qb.setTables(MY_TABLES);
qb.setProjectionMap(LIVE_FOLDER_PROJECTION);

Only the ID and name columns are required; the image and description columns can be used or left unmapped as required.

The Live Folder itself is created with an Intent returned as a result from an Activity. The Intent's data property indicates the URI of the Content Provider supplying the data (with the appropriate projection applied), while a series of extras are used to configure settings such as the display mode, icon, and folder name.

Listing 10-16 shows the overridden onCreate method of an Activity used to create a Live Folder.

The Live Folder definition Intent is constructed and set as the Activity result, before the Activity is closed with a call to finish.

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  String action = getIntent().getAction();
  if (LiveFolders.ACTION_CREATE_LIVE_FOLDER.equals(action)) {
    Intent intent = new Intent();
    intent.setData(EarthquakeProvider.LIVE_FOLDER_URI);
    intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_BASE_INTENT,
                    new Intent(Intent.ACTION_VIEW,
                               EarthquakeProvider.CONTENT_URI));
    intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_DISPLAY_MODE,
                    LiveFolders.DISPLAY_MODE_LIST);
    intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_ICON,
                    Intent.ShortcutIconResource.fromContext(context,
                                                            R.drawable.icon));
    intent.putExtra(LiveFolders.EXTRA_LIVE_FOLDER_NAME, "Earthquakes");
    setResult(RESULT_OK, createLiveFolderIntent(this));
  }
  else
    setResult(RESULT_CANCELED);
  finish();
}

As well as the standard configuration values you can add a LiveFolders.EXTRA_LIVE_FOLDER_BASE_INTENT extra to specify a base Intent to fire when a Live Folder item is selected.

When an item is chosen the Live Folder will call showActivity, passing in an Intent that has the data parameter set to the Live Folder's base URI with the selected item's _id value appended.

When adding your Live Folder Activity to the application manifest you need to include an Intent Filter for the CREATE_LIVE_FOLDER action, as shown in Listing 10-17.

<activity android:name=".MyLiveFolder "
          android:label="My Live Folder">
  <intent-filter>
    <action android:name="android.intent.action.CREATE_LIVE_FOLDER"/>
  </intent-filter>
</activity>

To enable application search, you must create an Activity that will be used to initiate and display the search.

The first step is to create a new searchable metadata XML resource in the res/xml folder. This file, shown in Listing 10-18, specifies the authority of the Content Provider you will be performing the search on, and the action to fire if a suggested search result is clicked.

<searchable xmlns:android="http://schemas.android.com/apk/res/android"
  android:label="@string/app_name"
  android:searchSuggestAuthority="myauthority"
  android:searchSuggestIntentAction="android.intent.action.VIEW">
</searchable>

Next, you will need to create an Activity that will be used to display the search results. In many cases this will be a simple List View-based Activity, but it can use any user interface you require. As shown in Listing 10-19, include a <meta-data> tag that includes a name attribute that specifies android.app.searchable and a resource attribute that specifies the XML resource you created in Listing 10-18.

You must also include an Intent Filter registered for the android.intent.action.SEARCH action and the DEFAULT category.

<activity android:name=".EarthquakeSearch" android:label="Earthquake Search">
  <intent-filter>
    <action android:name="android.intent.action.SEARCH" />
    <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
  <meta-data
    android:name="android.app.searchable"
    android:resource="@xml/searchable"
  />
</activity>

The search query that caused this search result Activity to be displayed will be returned within the calling Intent using the SearchMananger.USER_QUERY extra as shown in the following:

String searchTerm = getIntent().getStringExtra(SearchManager.USER_QUERY);

It's good practice to use the same search results form for your entire application. To set an Activity as the default search results provider for an application you need to add a new <meta-data> tag to the <application> manifest node as shown in Listing 10-20.

Set the name attribute to android.app.default_searchable and specify your search Activity using the value attribute.

<meta-data
  android:name="android.app.default_searchable"
  android:value=".EarthquakeSearch"
/>

The search Activity described in the previous section can be used to initiate a search and display the results for an application. In order for it to have data to display you need to create (or modify) a Content Provider to handle search queries and return results.

To support the Android search framework you need to support specific query path URI values. Listing 10-21 shows a URI Matcher that compares a requested URI to the known search query path values.

private static int SEARCH = 1;

static {
  uriMatcher = new UriMatcher(UriMatcher.NO_MATCH);
  uriMatcher.addURI("com.paad.provider.earthquake", "earthquakes", QUAKES);
  uriMatcher.addURI("com.paad.provider.earthquake", "earthquakes/#", QUAKE_ID);
  uriMatcher.addURI("com.paad.provider.earthquake",
    SearchManager.SUGGEST_URI_PATH_QUERY, SEARCH);
  uriMatcher.addURI("com.paad.provider.earthquake",
    SearchManager.SUGGEST_URI_PATH_QUERY + "/*", SEARCH);
  uriMatcher.addURI("com.paad.provider.earthquake",
    SearchManager.SUGGEST_URI_PATH_SHORTCUT, SEARCH);
  uriMatcher.addURI("com.paad.provider.earthquake",
    SearchManager.SUGGEST_URI_PATH_SHORTCUT + "/*", SEARCH);
}

Use a similar URI Matcher pattern within your Content Provider to return the appropriate MIME type for search queries as shown in Listing 10-22. Search results should be returned as SearchManager.SUGGEST_MIME_TYPE in order to support live search suggestions.

@Override
public String getType(Uri uri) {
  switch (uriMatcher.match(uri)) {
    case QUAKES  : return "vnd.android.cursor.dir/vnd.paad.earthquake";
    case QUAKE_ID: return "vnd.android.cursor.item/vnd.paad.earthquake";
    case SEARCH  : return SearchManager.SUGGEST_MIME_TYPE;
    default: throw new IllegalArgumentException("Unsupported URI: " + uri);
  }
}

The URI Matcher can also be used within the query method. If an incoming search query is detected, find the search term by examining the last segment of the query URI.

uri.getPathSegments().get(1);

To return search results that can be displayed using the Android search framework you will need to create and apply a projection that assigns your column names to those supplied and supported by the Search Manager. The Search Manager class includes a number of static constants of the form SUGGEST_COLUMN_* that can be used in the projection.

There are two required columns, SUGGEST_COLUMN_TEXT_1 which displays the search result text and id_, which indicates the unique row ID.

Listing 10-23 shows the skeleton code for creating and applying a projection within a query that returns a Cursor suitable for search results.

private static final HashMap<String, String> SEARCH_PROJECTION_MAP;
static {
  SEARCH_PROJECTION_MAP = new HashMap<String, String>();
  SEARCH_PROJECTION_MAP.put(SearchManager.SUGGEST_COLUMN_TEXT_1,
                            KEY_SEARCH_COLUMN + " AS " +
                            SearchManager.SUGGEST_COLUMN_TEXT_1);
  SEARCH_PROJECTION_MAP.put("_id", KEY_ID + " AS " + "_id");
}

@Override
public Cursor query(Uri uri, String[] projection, String selection, String[]
                    selectionArgs, String sort) {
  SQLiteQueryBuilder qb = new SQLiteQueryBuilder();
  qb.setTables(MY_TABLE);

  switch (uriMatcher.match(uri)) {
    case SINGLE_ID:
      qb.appendWhere(KEY_ID + "=" + uri.getPathSegments().get(1));
      break;
    case SEARCH   :  qb.appendWhere(KEY_SEARCH_COLUMN + " LIKE "%" +
                                    uri.getPathSegments().get(1) + "%"");
                     qb.setProjectionMap(SEARCH_PROJECTION_MAP);
                     break;
    default       : break;
  }

  Cursor c = qb.query(MyDB,
                      projection,
                      selection, selectionArgs,
                      null, null, orderBy);

  return c;
}