Handling Application Logic inside an AppWidgetProvider

After the pending intent has started your AppWidgetProvider, you need to perform some logic on behalf of the calling application (in this case, the Home screen application). In the following sections, I show you how to perform time-sensitive work on behalf of the caller.

Before I hop into the code, it's best to understand how the work will be done in the AppWidgetProvider. Due to the nature of remote processes and how resource-intensive they can be, it's best to do all work inside a background service. I will be performing the changing of the brightness mode via a background service.

Understanding the IntentService

Why should you use a background service for such a trivial task as changing the device brightness mode? Well, it has to do with avoiding Application Not Responding (ANR) errors.

Any code that executes for too long without responding to the Android system is subject to the ANR error. App widgets are especially vulnerable to ANR errors because they are executing code in a remote process — they execute across process boundaries that can take time to set up, execute, and tear down — the entire process is very CPU-, memory-, and battery-intensive. The Android system watches app widgets to ensure that they do not take too long to execute. If they do take an extended period of time to execute, the calling application (the Home screen) locks up and the device is unusable. Therefore, the Android platform wants to make sure that you're never capable of making the device unresponsive for more than a couple of seconds.

Because app widgets are very expensive in regard to CPU and memory, it's really hard to judge whether an app widget will cause an ANR error. If the device is not doing any other expensive tasks, the app widget would probably work just fine. However, if the device is in the middle of one or many expensive CPU operations, the app widget could take too long to respond — causing an ANR error. This unknown CPU state is a dangerous variation to introduce to your app widget. Therefore, to get around it, move the work of the app widget into a space where it can take as long as it needs to complete, a space that in turn will not affect the Home screen application — in other words, a background service. (You're using a background service called an IntentService for this app.) Unlike most background services, which are long-running, an IntentService uses the work queue processor pattern that handles each intent in turn using a worker thread, and it stops when it runs out of work. In laymen's terms, the IntentService simply takes the work given to it, runs it as a background service, and then stops the background service when no more work needs to be done.

Implementing the AppWidgetProvider and IntentService

In your AppWidgetProvider class, type the code in Listing 8-3 into your code editor.

Listing 8-3: The Full AppWidget Implementation

public class AppWidget extends AppWidgetProvider {

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

         if (intent.getAction()==null) {
             context.startService(new Intent(context, ToggleService.class));  →7
             Intent i = new Intent(context, ToggleActivity.class);            →8
             i.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK);                     →9
             i.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);                       →10

             context.startActivity(i);                                        →12
            } else {
                super.onReceive(context, intent);                             →14
            }
        }

       public static class ToggleService extends IntentService {              →18

           public ToggleService() {
               super(“AppWidget$ToggleService”);                              →21
           }

           @Override
        protected void onHandleIntent(Intent intent) {                        →25
             ComponentName me=new ComponentName(this, AppWidget.class);       →26
             AppWidgetManager mgr=AppWidgetManager.getInstance(this);         →27
             mgr.updateAppWidget(me, buildUpdate(this));                      →28

        }

        private RemoteViews buildUpdate(Context context) {                    →32
            RemoteViews updateViews=new
                RemoteViews(context.getPackageName(),R.layout.widget);        →34

            int currentBrightness =
               BrightnessHelper.getCurrentBrightness(ToggleService.this);     →37
            if(currentBrightness > 51) {                                      →38
                // Dim it to 20 %. 20% of 255 is 51
              updateViews.setImageViewResource(R.id.brightnessState,
                  R.drawable.night);                                          →41
            } else {
                // Push it back to full brightness
                  updateViews.setImageViewResource(R.id.brightnessState,
                  R.drawable.sun);                                            →45
            }

            Intent i=new Intent(this, AppWidget.class);                       →48
            PendingIntent pi = PendingIntent.getBroadcast(context, 0, i,0);   →49
            updateViews.setOnClickPendingIntent(R.id.brightnessState,pi);     →50

            return updateViews;
        }
    }
}

The following list briefly explains what each major section of code does:

Adding the ToggleActivity to Help Adjust Current Window Brightness

In Listing 8-3 you were introduced to the ToggleActivity. The ToggleActivity has one function — to act as an invisible courier that does work, kind of like a ninja on a midnight mission! The ToggleActivity checks the current screen brightness and then, depending upon the current state of that brightness, updates the current window parameters with the new screen brightness in order to get the brightness to change. You want this activity to start, do its work so fast that no one notices, and then close. You do not want the user to view the Activity — they should not notice a new activity starting. Therefore, you will hide the title bar of the activity. When you register this activity later in the chapter in the AndroidManifest.xml file, you will inform the Android system to make the background of the activity transparent, effectively hiding any known trace that the activity is actually running.

Why does this step need to be done in an activity? Why can't it be done in a service? Because you need access to the currently running window in order to get access to the current window/screen brightness. A background service runs in the background, so it has no window. Because the widget is running in a remote process, Linux security won't let you have access to that window. Therefore, you have to start a new activity (one hidden from the user), so you can gain access to the window in order to change the current brightness.

To set up your activity, add a new class with the name of ToggleActivity.java to the src/ folder. Replace the contents of this file with what is shown in Listing 8-4.

Listing 8-4: The ToggleActivity.java

public class ToggleActivity extends Activity {

     @Override
     public void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            requestWindowFeature(Window.FEATURE_NO_TITLE);            →6

            int currentBrightness =
                         BrightnessHelper.getCurrentBrightness(this); →9

            if(currentBrightness > 51) {                              →11
                // Dim it to 20 %. 20% of 255 is 51
                BrightnessHelper.setCurrentBrightness(this, 51);
            } else {
                // Push it back to full brightness
                BrightnessHelper.setCurrentBrightness(this, 255);
            }

            // Wait for 1000 milliseconds (1 second) for the brightness
            // change to start, then quit.
            final Timer t = new Timer();                              →21
            t.schedule(new TimerTask() {                              →22

                @Override
                public void run() {                                   →25
                    finish();                                         →26
                    t.cancel();                                       →27
                }
           }, 1000);                                                  →29
    }
}

In the following list, I explain each major area of the code:

You've written the code to implement the widget as well as to update the screen brightness in the settings as well as on the screen. Now you need to work with the metadata of the widget and add the new components to the AndroidManifest.xml.

Working with the app widget's metadata

Now that the code is written to handle the updating of the app widget, you may be wondering how to get the app widget to show up on the Widgets menu so that you can install it. This fairly simple process requires that you add a single XML file to your project. This XML file describes some basic metadata about the app widget so that the Android platform can determine how to lay out the app widget onto the Home screen. Here's how you do this:

1. In your project, right-click the res directory and choose NewNew Folder.
2. For the folder name, type xml and click Finish.
3. Right-click the new res/xml folder, choose New, and then choose Android XML File.
4. In the New Android XML File Wizard, type widget_provider.xml for the filename.
5. The file type will be of the type AppWidgetProvider. Select that radio button and then click Finish.
6. After the file opens, open the XML editor and type the following into the widget_provider.xml file:

   <?xml version=“1.0” encoding=“utf-8”?>
   <appwidget-provider xmlns:android=“http://schemas.android.com/apk/res/android”
              android:minWidth=“79px”
              android:minHeight=“79px”
              android:updatePeriodMillis=“0”
              android:initialLayout=“@layout/widget”
   />

The minWidth and minHeight properties are used for setting the very minimum space that the view will take on the Home screen. These values could be larger if you want.

The updatePeriodMillis property defines how often the app widget should attempt to update itself. In the case of the Screen Brightness Toggle application, you do not want this to happen — the only time the brightness should change is if the user initiates it. Therefore, this value is set to 0 seconds. If you were to set this to 180000 milliseconds — 30 minutes then every 30 minutes, the app would update itself through sending an intent that executes the onUpdate() method call in the AppWidgetProvider (if you have implemented that method).

The initialLayout property identifies what the app widget will look like when the app widget is first added to the Home screen before any work takes place. Note that it may take a couple of seconds (or longer) for the app widget to initialize and update your app widget's RemoteView object by calling the onReceive() method.

An example of a longer delay is if you had an app widget that checked Twitter for status updates. If the network is slow, the initialLayout would be shown until updates were received from Twitter. Therefore, if you foresee this becoming an issue, inform the user in the initialLayout that information is loading. Therefore, the user is kept aware of what is happening when the app widget is initially loaded to the Home screen. You can do this by providing a TextView with the contents of ”Loading …” while the AppWidgetProvider does its work.

At this point, you can install the Screen Brightness Toggle application, long-press the Home screen, and choose the Widgets category; now you should see the Screen Brightness Toggle present. The metadata that you just defined is what made this happen. The icon defaults to the application icon. However, the app widget would throw an exception if you attempted to add it to the Home screen. This mistake is fairly common: I forgot to let the AndroidManifest.xml file know about my new IntentService and BroadcastReceiver. If the AndroidManifest.xml does not know about these new items, exceptions will be thrown because the application context has no idea where to find them. You solve this problem next.

Registering your new components with the manifest

Anytime you add an Activity, Service, or BroadcastReceiver (as well as other items) to your application, you need to register them with the application manifest file. The application manifest presents vital information to the Android platform, namely, the components of the application. The Activity, Service, and BroadcastReceiver objects that are not registered in the application manifest will not be recognized by the system and will not be able to be run. Therefore, if you added the app widget to your Home screen, you would have it crash because your AppWidgetProvider is a BroadcastReceiver, and the code in the receiver is using a service that is also not registered in the manifest.

To add your AppWidgetProvider and IntentService to your application manifest file, open the AndroidManifest.xml file and type the code shown in Listing 8-5 into the already-existing file. Bolded lines are the newly added lines for the new components.

Listing 8-5: An Updated AndroidManifest.xml File with New Components Registered

<?xml version=“1.0” encoding=“utf-8”?>
<manifest xmlns:android=“http://schemas.android.com/apk/res/android”
    package=“com.dummies.android.screeenbrightnesstoggle”
    android:versionCode=“1” android:versionName=“1.0”>
    <uses-permission android:name=“android.permission.WRITE_SETTINGS”></uses-permission>
    <application android:icon=“@drawable/icon” android:label=“@string/app_name”>
        <activity android:name=“.MainActivity” android:label=“@string/app_name”>
            <intent-filter>
                <action android:name=“android.intent.action.MAIN” />
                <category android:name=“android.intent.category.LAUNCHER” />
            </intent-filter>
        </activity>

        <activity android:name=
           “com.dummies.android.screeenbrightnesstoggle.ToggleActivity”                     →14
            android:theme=“@android:style/Theme.Translucent” />                             →15
     <receiver android:name=
        “com.dummies.android.screeenbrightnesstoggle.AppWidget”                             →17
        android:label=“@string/app_name” android:icon=“@drawable/icon”
        android:previewImage=“@drawable/night”>                                             →19
<intent-filter>
<action android:name=“android.appwidget.action.APPWIDGET_UPDATE” />
                                                                                            →22
</intent-filter>
<meta-data android:name=“android.appwidget.provider”
android:resource=“@xml/widget_provider” />
                                                                                            →26
</receiver>
<service     android:name=
                                                                                            →28
“com.dummies.android.screeenbrightnesstoggle.AppWidget$ToggleService” />

    </application>
    <uses-sdk android:minSdkVersion=“11” />
</manifest>

The following is a brief explanation of what each section does:

At this point, your application is ready to be installed and tested. To install the application, choose RunRun or press Ctrl+F11. Your application should now show up on the emulator. Return to the Home screen by pressing the Home key. You can now add the app widget you recently created to your Home screen.