Problem

You want to send an email containing text or images from a view.

Solution

Pass the data to be emailed to the mail app as a parameter using an Intent.

Discussion

The steps for emailing text from a view are pretty straightforward:

1. Modify the AndroidManifest.xml file to allow for an internet connection so that email can be sent. This is shown in Example 4-1.

2. Create the visual presentation layer with an Email button that the user clicks. The layout is shown in Example 4-2, and the strings used to populate it are shown in Example 4-3.

3. Attach an OnClickListener to allow the email to be sent when the user clicks the Email button. The code for this is shown in Example 4-4.

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.examples"
    android:versionCode="1"
    android:versionName="1.0">

    <uses-permission
            android:name="android.permission.INTERNET" />

    <application
        android:icon="@drawable/icon"
        android:label="@string/app_name">
        <activity
            android:name=".Main"
            android:label="@string/app_name">
            <intent-filter>
                <action
                    android:name="android.intent.action.MAIN" />
                <category
                    android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

    </application>
</manifest>

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

    <Button
        android:id="@+id/emailButton"
        android:text="Email Text!"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content">
    </Button>

    <TextView
        android:id="@+id/text_to_email"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="@string/my_text" />

</LinearLayout>

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string
        name="hello">Hello World, Main!</string>
    <string
        name="app_name">EmailFromView</string>
    <string
        name="my_text">
        Lorem Ipsum is simply dummy text of the printing and typesetting industry.
        Lorem Ipsum has been the industry's standard dummy text ever since the 1500s,
        when an unknown printer took a galley of type and scrambled it to make a
        type specimen book. It has survived not only five centuries, but also the
        leap into electronic typesetting, remaining essentially unchanged. It was
        popularized in the 1960s with the release of Letraset sheets containing Lorem
        Ipsum passages, and more recently with desktop publishing software like
        Aldus PageMaker including versions of Lorem Ipsum.
</string>
</resources>

import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class Main extends Activity implements OnClickListener {
        private static final String TAG = "Main";
        private Button emailButton;

        /** Called when the Activity is first created. */
        @Override
        public void onCreate(Bundle savedInstanceState) {
                super.onCreate(savedInstanceState);

                // Set the view layer
                setContentView(R.layout.main);

                // Get reference to Email button
                this.emailButton = (Button) this.findViewById(R.id.emailButton);

                // Set the onClick event listener
                this.emailButton.setOnClickListener(this);

            }

        @Override
        public void onClick(View view) {
            if (view == this.emailButton) {
                Intent emailIntent = new Intent(Intent.ACTION_SEND);
                emailIntent.setType("text/html");
                emailIntent.putExtra(Intent.EXTRA_TITLE, "My Title");
                emailIntent.putExtra(Intent.EXTRA_SUBJECT, "My Subject");

                // Obtain reference to String and pass it to Intent
                emailIntent.putExtra(Intent.EXTRA_TEXT,
                    getString(R.string.my_text));
                startActivity(emailIntent);
            }
        }
    }

Source Download URL

The source code for this example is in the Android Cookbook repository, in the subdirectory EmailTextView (see “Getting and Using the Code Examples”).

Problem

You want to send an email with attachments.

Solution

Create an Intent, add extended data to specify the file you want to include, and start a new Activity to allow the user to send the email.

Discussion

The easiest way to send an email is to create an Intent of type ACTION_SEND:

Intent intent = new Intent(Intent.ACTION_SEND);
intent.putExtra(Intent.EXTRA_SUBJECT, "Test single attachment");
intent.putExtra(Intent.EXTRA_EMAIL, new String[]{recipient_address});
intent.putExtra(Intent.EXTRA_TEXT, "Mail with an attachment");

To attach a single file, we add some extended data to our Intent:

intent.putExtra(Intent.EXTRA_STREAM, Uri.fromFile(new File("/path/to/file")));
intent.setType("text/plain");

The MIME type can always be set as text/plain, but you may want to be more specific so that applications parsing your message will work properly. For instance, if you’re including a JPEG image you should write image/jpeg.

To send an email with multiple attachments, the procedure is slightly different, as shown in Example 4-5.

Intent intent = new Intent(Intent.ACTION_SEND_MULTIPLE);
intent.setType("text/plain");
intent.putExtra(Intent.EXTRA_SUBJECT, "Test multiple attachments");
intent.putExtra(Intent.EXTRA_TEXT, "Mail with multiple attachments");
intent.putExtra(Intent.EXTRA_EMAIL, new String[]{recipient_address});

ArrayList<Uri> uris = new ArrayList<Uri>();
uris.add(Uri.fromFile(new File("/path/to/first/file")));
uris.add(Uri.fromFile(new File("/path/to/second/file")));

intent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, uris);

First, you need to use Intent.ACTION_SEND_MULTIPLE, which has been available since Android 1.6. Second, you need to create an ArrayList with the URIs of the files you want to attach to the mail and call putParcelableArrayListExtra(). If you are sending different types of files you may want to use multipart/mixed as the MIME type.

Finally, in both cases, don’t forget to start the desired Activity with the following code:

startActivity(this, intent);

Which mail program will be used if there’s more than one on the device? If the user has previously made a choice that will be respected, but if the user hasn’t selected an application to handle this type of Intent a chooser will be launched.

The example in the source download shows both the single attachment and multiple attachment options, each connected to a Button with obvious labeling. The multiple attachment button looks like Figure 4-1 in my email client.

Figure 4-1. Email with multiple attachments

Source Download URL

The source code for this example is in the Android Cookbook repository, in the subdirectory EmailWithAttachments (see “Getting and Using the Code Examples”).

Problem

You need to pass some parameters into an Activity while launching it.

Solution

A quick solution is to use Intent.putExtra() to push the data. Then use getIntent().getExtras().getString() to retrieve it.

Discussion

Example 4-6 shows the code to push the data.

import android.content.Intent;
    ...

    Intent intent =
        new Intent(
            this,
            MyActivity.class );
    intent.putExtra( "paramName", "paramValue" );
    startActivity( intent );

This code might be inside the main Activity. MyActivity.class is the second Activity we want to launch and it must be explicitly included in your AndroidManifest.xml file:

<activity android:name=".MyActivity" />

Example 4-7 shows the code to pull the data in the target (receiving) Activity.

import android.os.Bundle;

    ...

    Bundle extras = getIntent().getExtras();
    if (extras != null) {
        String myParam = extras.getString("paramName");
    }
    else {
        //Oops!
    }

In this example, the code would be inside your main Activity.java file.

In addition to Strings, the Bundle (the “extras”) can contain several other types of data; see the documentation for Bundle for a complete list.

See Also

The blog post “Playing with Intents”, the developer documentation on Intent.putExtra().

Problem

Your main Activity needs to retrieve data from another Activity, sometimes informally called a “subactivity.”

Solution

Use startActivityForResult(), onActivityResult() in the main Activity, and setResult() in the subactivity.

Discussion

In this example, we return a string from a subactivity (MySubActivity) back to the main Activity (MyMainActivity). The first step is to “push” data from MyMainActivity via the Intent mechanism (see Example 4-8).

public class MyMainActivity extends Activity
{
    //For logging
    private static final String TAG = "MainActivity";

    //The request code is supposed to be unique
    public static final int MY_REQUEST_CODE = 123;

    @Override
    public void onCreate( Bundle savedInstanceState ) {
        ...
    }

    private void pushFxn() {
        Intent intent =
            new Intent(
                this,
                MySubActivity.class );

        startActivityForResult( intent, MY_REQUEST_CODE );
    }

    protected void onActivityResult(
            int requestCode,
            int resultCode,
            Intent pData) {
         if ( requestCode == MY_REQUEST_CODE ) {
             if (resultCode == Activity.RESULT_OK ) {
                 final String zData = pData.getExtras().getString
                     ( MySubActivity.EXTRA_STRING_NAME );

                 //Do something with our retrieved value

                 Log.v( TAG, "Retrieved Value zData is "+zData );
                 //Logcats "Retrieved Value zData is returnValueAsString"

             }
         }

     }
}

There will be a button with an event listener that calls the pushFxn() method; this starts the subactivity. In Example 4-8, the following occurs:

• The main Activity’s onActivityResult() method gets called after MySubActivity.finish().

• The retrieved value is technically an Intent, and so we could use it for more complex data (such as a URI to a Google contact). However, in Example 4-8, we are only interested in a string value via Intent.getExtras().

• The requestCode (MY_REQUEST_CODE) is supposed to be unique, and is used to differentiate among multiple outstanding subactivity calls.

The second major step is to “pull” data back from MySubActivity to MyMainActivity (see Example 4-9).

public class MySubActivity extends Activity
{
    public static final String EXTRA_STRING_NAME = "extraStringName";

    @Override
    public void onCreate( Bundle savedInstanceState ) {
        ...
    }


    private void returnValuesFxn() {
        Intent iData = new Intent();
        iData.putExtra(
            EXTRA_STRING_NAME,
            "returnValueAsString" );

        setResult(
            android.app.Activity.RESULT_OK,
            iData );

        //Returns us to the parent "MyMainActivity"
        finish();
    }
}

Again, something in the MySubActivity will call the returnValuesFxn() method in Example 4-9. Note the following:

• Once again, Intents are used as data (i.e., iData).

• setResult() requires a result code such as RESULT_OK.

• finish() essentially pushes the result from setResult().

• The data from MySubActivity doesn’t get “pulled” until we’re back on the other side with MyMainActivity, so arguably it is more similar to a second “push.”

• We don’t have to use a public static final String variable for our “extra” field name, but I chose to do so because I thought it was a good style.

See Also

Recipe 4.4, resultCode “gotcha”, startActivityForResultExample (under “Returning a Result from a Screen”); Activity.startActivityForResult().

Problem

You want part of your application to continue running in the background while the user switches to interact with other apps.

Solution

Create a Service class to do the background work; start the Service from your main application. Optionally provide a Notification icon to allow the user either to stop the running Service or to resume the main application.

Discussion

A Service class (android.app.Service) runs as part of the same process as your main application, but keeps running even if the user switches to another app or goes to the Home screen and starts up a new app.

As you know by now, Activity classes can be started either by an Intent that matches their content provider or by an Intent that mentions them by class name. The same is true for Services. This recipe focuses on starting a Service directly; Recipe 4.1 covers starting a Service implicitly. The following example is taken from JPSTrack, a GPS tracking program for Android. Once you start tracking, you don’t want the tracking to stop if you answer the phone or have to look at a map(!), so we made it into a Service. As shown in Example 4-10, the Service is started by the main Activity when you click the Start Tracking button, and is stopped by the Stop button. Note that this is so common that startService() and stopService() are built into the Activity class.

@Override
public void onCreate(Bundle savedInstanceState) {
    ...
    Intent theIntent = new Intent(this, TrackService.class);
    Button startButton = (Button) findViewById(R.id.startButton);
    startButton.setOnClickListener(new OnClickListener() {
            @Override
            public void onClick(View v) {
                startService(theIntent);
                Toast.makeText(Main.this, "Starting", Toast.LENGTH_LONG).show();
            }
    });
    Button stopButton = (Button) findViewById(R.id.stopButton);
    stopButton.setOnClickListener(new OnClickListener() {
            @Override
            public void onClick(View v) {
                stopService(theIntent);
                Toast.makeText(Main.this, "Stopped", Toast.LENGTH_LONG).show();
            }
    });
    ...
}

The TrackService class directly extends Service, so it has to implement the abstract onBind() method. This is not used when the class is started directly, so it can be a stub method. You will typically override at least the onStartCommand() and onUnbind() methods, to begin and end some Activity. Example 4-11 starts the GPS service sending us notifications that we save to disk, and we do want that to keep running, hence this Service class.

public class TrackService extends Service {
        private LocationManager mgr;
        private String preferredProvider;

        @Override
        public IBinder onBind(Intent intent) {
                return null;
        }

        @Override
        public int onStartCommand(Intent intent, int flags, int startId) {
                initGPS();      // Sets up the LocationManager mgr

                if (preferredProvider != null) {
                    mgr.requestLocationUpdates(preferredProvider, MIN_SECONDS * 1000,
                                    MIN_METRES, this);
                        return START_STICKY;
                }
                return START_NOT_STICKY;
        }

        @Override
        public boolean onUnbind(Intent intent) {
                mgr.removeUpdates(this);
                return super.onUnbind(intent);
        }

You may have noticed the different return values from onStartCommand(). If you return START_STICKY, Android will restart your Service if it gets terminated. If you return START_NOT_STICKY, the Service will not be restarted automatically. These values are discussed in more detail in the online documentation for the Service class. Remember to declare the Service subclass in the Application part of your AndroidManifest.xml:

<service android:enabled="true" android:name=".TrackService">

Problem

You want to create an Activity that receives a simple broadcast message sent by another Activity.

Solution

Set up a broadcast receiver, instantiate the message receiver object, and create an IntentFilter. Then register your receiver with an Activity that must receive the broadcast message.

Discussion

The code in Example 4-12 sets up the broadcast receiver, instantiates the message receiver object, and creates the IntentFilter.

// Instantiate message receiver object. You should
// create this class by extending android.content.BroadcastReceiver.
// The method onReceive() of this class will be called when broadcast is sent.
MyBroadcastMessageReceiver _bcReceiver = new MyBroadcastMessageReceiver();

// Create IntentFilter
IntentFilter filter = new IntentFilter(MyBroadcastMessageReceiver.class.getName());

// Register your receiver with your Activity, which must receive broadcast messages.
// Now whenever this type of message is generated somewhere in the system the
// _bcReceiver.onReceive() method will be called within main thread of myActivity.
myActivity.registerReceiver(_bcReceiver, filter);

The code in Example 4-13 shows how to publish the broadcast event.

Intent intent = new Intent(MyBroadcastMessageReceiver.class.getName());
intent.putExtra("some additional data", choice);
someActivity.sendBroadcast(intent);

Problem

You have a Service in your app and you want it to start after the phone reboots.

Solution

Listen to the Intent for boot events and start the Service when the event occurs.

Discussion

Whenever a platform boot is completed, an Intent is broadcast with the android.intent.action.BOOT_COMPLETED action. You need to register your application to receive this Intent, and to request permission for it. To do so, add the following code to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<application>
    <receiver android:name=".ServiceManager">
            <intent-filter>
                <action android:name="android.intent.action.BOOT_COMPLETED" />
            </intent-filter>
    </receiver>
...

For ServiceManager to be the broadcast receiver that receives the Intent for the boot event, the ServiceManager class would be coded as shown in Example 4-14.

public class ServiceManager extends BroadcastReceiver {

    Context mContext;
    private final String BOOT_ACTION = "android.intent.action.BOOT_COMPLETED";

    @Override
    public void onReceive(Context context, Intent intent) {
               // All registered broadcasts are received by this
        mContext = context;
        String action = intent.getAction();
        if (action.equalsIgnoreCase(BOOT_ACTION)) {
                        // Check for boot complete event & start your service
            startService();
        }
    }

    private void startService() {
        // Here, you will start your service
        Intent mServiceIntent = new Intent();
        mServiceIntent.setAction("com.bootservice.test.DataService");
        mContext.startService(mServiceIntent);
    }
}

Problem

You have an application that performs long tasks, and you don’t want your application to appear nonresponsive while these are ongoing.

Solution

By using threads, you can create an application that is responsive even when it is handling time-consuming operations.

Discussion

To make your application responsive while time-consuming operations are running on the Android OS you have a few options. If you already know Java, you know you can create a class that extends the Thread class and overrides the public void run() method and then call the start() method on that object to run the time-consuming process. If your class already extends another class, you can implement the Runnable interface. Another approach is to create your own class that extends Android’s AsyncTask class, but we will talk about AsyncTask in Recipe 4.10.

In the early days of Java and Android, we were taught about direct use of the Thread class. This pattern was coded as follows:

Thread thread = new Thread(new Runnable() {        // Deprecated, do not use!
    public void run() {
        getServerData();
    }
});
thread.start();

There are many issues around this usage of threads, but the biggest strike against it is the overhead of creating threads. For all but the simplest cases, it is now recommended to use thread pools, which have been in Java for half of its lifetime. Example 4-15 shows the pool-based implementation of this class.

public class NetworkConnection extends Activity {

    ExecutorService pool = Executors.newSingleThreadExecutor();

    /** Called when the Activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        pool.submit(new Runnable() {
            public void run() {
                getServerData();
            }
        });
   }
}

As you can see, when we start our Activity in the onCreate() method we create and submit a Runnable object. The Runnable method run() will be executed some time after we call the submit() method on the pool. From here you can call another method or a few other methods and operations that are time-consuming and that would otherwise block the main thread and make your application look unresponsive.

Often when we are done with the thread we get results that we want to present to the application user. If you try to update the GUI from the thread that you started (not the main thread) your application will crash. The Android UI is not thread safe—this was done deliberately, for performance reasons—so that if you try to change any UI component (even a single call to, e.g, someTextView.setText()) from a thread other than the main thread, your app will crash.

Of course, there are several ways to send data from background threads to the UI. One way is to use a Handler class; see Recipe 4.11. Alternatively, you can divide your code differently using AsyncTask (see Recipe 4.10).

Problem

You have to do some heavy processing, or load resources from the network, and you want to show the progress and results in the UI.

Solution

Use AsyncTask and ProgressDialog.

Discussion

As explained in the Processes and Threads” section of the Android Developers API Guides, you should never block the UI thread, or access the Android UI toolkit from outside the UI thread. Bad things will happen if you do.

You can run processes in the background and update the UI inside the UI thread (a.k.a. the main thread) in several ways, but using the AsyncTask class is very convenient and every Android developer should know how to do so.

The steps boil down to creating a class that extends AsyncTask. AsyncTask itself is abstract and has one abstract method, Result doInBackground(Params… params);. The AsyncTask simply creates a callable working thread in which your implementation of doInBackground() runs. Result and Params are two of the types we need to define in our class definition. The third is the Progress type, which we will talk about later.

Our first implementation will do everything in the background, showing the user a spinner in the title bar and updating the ListView once the processing is done. This is the typical use case, not interfering with the user’s task at hand and updating the UI when we have retrieved the result.

The second implementation will use a modal dialog to show the processing progressing in the background. In some cases we want to prevent the user from doing anything else when some processing takes place, and this is a good way to do just that.

We will create a UI that contains three Buttons and a ListView. The first button is to start our first refresh process. The second is for the other refresh process and the third is to clear the results in the ListView (see Example 4-16).

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical" android:layout_width="fill_parent"
    android:layout_height="fill_parent">
    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:orientation="horizontal" android:layout_width="fill_parent"
        android:layout_height="wrap_content">
        <Button android:text="Refresh 1" android:id="@+id/button1"
            android:layout_width="fill_parent" android:layout_height="wrap_content"
            android:layout_weight="1"></Button>
        <Button android:text="Refresh 2" android:id="@+id/button2"
            android:layout_width="fill_parent" android:layout_height="wrap_content"
            android:layout_weight="1"></Button>
        <Button android:text="Clear" android:id="@+id/button3"
            android:layout_width="fill_parent" android:layout_height="wrap_content"
            android:layout_weight="1"></Button>
    </LinearLayout>
    <ListView android:id="@+id/listView1" android:layout_height="fill_parent"
        android:layout_width="fill_parent"></ListView>
</LinearLayout>

We assign these UI elements to various fields in onCreate() and add some click listeners (see Example 4-17).

ListView mListView;
Button mClear;
Button mRefresh1;
Button mRefresh2;

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    mListView = (ListView) findViewById(R.id.listView1);
    mListView.setTextFilterEnabled(true);
    mListView.setOnItemClickListener(this);

    mRefresh1 = (Button) findViewById(R.id.button1);

    mClear = (Button) findViewById(R.id.button3);
    mClear.setOnClickListener(new OnClickListener() {
        @Override
        public void onClick(View v) {
            mListView.setAdapter(null);
        }
    });

}

public void onItemClick(AdapterView<?> parent, View view, int position, long id) {
    Datum datum = (Datum) mListView.getItemAtPosition(position);
    Uri uri = Uri.parse("http://androidcookbook.com/Recipe.seam?recipeId=" +
        datum.getId());
    Intent intent = new Intent(Intent.ACTION_VIEW, uri);
    this.startActivity(intent);
}

The following subsections describe two use cases: processing in the background and processing in the foreground.

Use case 1: Processing in the background

First we create an inner class that extends AsyncTask:

protected class LoadRecipesTask1 extends AsyncTask<String, Void, ArrayList<Datum>> {
...
}

As you can see, we must supply three types to the class definition. The first is the type of the parameter we will provide when starting this background task—in our case a String, containing a URL. The second type is used for progress updates (we will use this later). The third type is the type returned by our implementation of the doInBackground() method, and typically is something with which you can update a specific UI element (a ListView in our case).

Let’s implement the doInBackground() method:

@Override
protected ArrayList<Datum> doInBackground(String... urls) {
    ArrayList<Datum> datumList = new ArrayList<Datum>();
    try {
        datumList = parse(urls[0]);
    } catch (IOException e) {
        e.printStackTrace();
    } catch (XmlPullParserException e) {
        e.printStackTrace();
    }
    return datumList;
}

As you can see, this is pretty simple. The parse() method—which creates a list of Datum objects—is not shown as it’s related to a specific data format in one application. The result of the doInBackground() method is then passed as an argument to the onPostExecute() method in the same (inner) class. In this method we are allowed to update the UI elements in our layout, so we set the adapter of the ListView to show our result:

@Override
protected void onPostExecute(ArrayList<Datum> result) {
    mListView.setAdapter(new ArrayAdapter<Datum>(MainActivity.this,
        R.layout.list_item, result));
}

Now we need a way to start this task. We do this in mRefresh1’s onClickListener() by calling the execute(Params… params) method of AsyncTask (execute(String… urls) in our case):

mRefresh1.setOnClickListener(new OnClickListener() {

    @Override
    public void onClick(View v) {
        LoadRecipesTask1 mLoadRecipesTask = new LoadRecipesTask1();
        mLoadRecipesTask.execute(
            "http://androidcookbook.com/seam/resource/rest/recipe/list");
    }
});

Now, when we start the app it indeed retrieves the recipes and fills the ListView, but the user has no idea that something is happening in the background. In order to notify the user of ongoing activity, we can set the window state to “indefinite progress”; this displays a small progress animation in the top right of our app’s title bar. We request this feature by calling the following method in onCreate(): requestWindowFeature(Window.FEATURE_INDETERMINATE_PROGRESS). (Be aware that this feature is deprecated; we will show a better way to keep the user informed on progress in use case 2, next.)

Then we can start the progress animation by calling the set​ProgressBarIndeterminateVisibility(boolean visibility) method from within a new method in our inner class, the onPreExecute() method:

protected void onPreExecute() {
    MainActivity.this.setProgressBarIndeterminateVisibility(true);
}

We stop the spinning progress bar in our window title by calling the same method from within our onPostExecute() method, which will become:

protected void onPostExecute(ArrayList<Datum> result) {
    mListView.setAdapter(new ArrayAdapter<Datum>(MainActivity.this,
        R.layout.list_item, result));
    MainActivity.this.setProgressBarIndeterminateVisibility(false);
}

We’re done! Take your app for a spin (pun intended). See Figure 4-2.

Figure 4-2. The AsyncTask demo in action

As you can see, this is a nifty feature for creating a better user experience!

Use case 2: Processing in the foreground

In this example, we show a modal dialog to the user that displays the progress of loading the recipes in the background. Such a dialog is called a ProgressDialog. First we add it as a field to our Activity:

ProgressDialog mProgressDialog;

Then we add the onCreateDialog() method to be able to answer showDialog() calls and create our dialog:

protected Dialog onCreateDialog(int id) {
        switch (id) {
        case DIALOG_KEY:                                                       
            mProgressDialog = new ProgressDialog(this);
            mProgressDialog.setProgressStyle(ProgressDialog.STYLE_HORIZONTAL); 
            mProgressDialog.setMessage("Retrieving recipes...");               
            mProgressDialog.setCancelable(false);                              
            return mProgressDialog;
        }
        return null;
    }

We should handle the request and creation of all dialogs here. The DIALOG_KEY is an int constant with an arbitrary value (we used 0) to identify this dialog.

We set the progress style to STYLE_HORIZONTAL, which shows a horizontal progress bar. The default is STYLE_SPINNER.

We set our custom message, which is displayed above the progress bar.

By calling setCancelable() with the argument false we disable the Back button, making this dialog modal.

Our new implementation of AsyncTask is as shown in Example 4-18.

Example 4-18. The AsyncTask implementation

protected class LoadRecipesTask2 extends AsyncTask<String, Integer, ArrayList<Datum>>{

        @Override
        protected void onPreExecute() {
            mProgressDialog.show();                                               
        }

        @Override
        protected ArrayList<Datum> doInBackground(String... urls) {
            ArrayList<Datum> datumList = new ArrayList<Datum>();
            for (int i = 0; i < urls.length; i++) {                               
                try {
                    datumList = parse(urls[i]);
                    publishProgress((int) (((i+1) / (float) urls.length) * 100)); 
                } catch (IOException e) {
                    e.printStackTrace();
                } catch (XmlPullParserException e) {
                    e.printStackTrace();
                }
            }
            return datumList;
        }

        @Override
        protected void onProgressUpdate(Integer... values) {                      
            mProgressDialog.setProgress(values[0]);                               
        }

        @Override
        protected void onPostExecute(ArrayList<Datum> result) {
            mListView.setAdapter(new ArrayAdapter<Datum>(
                MainActivity.this, R.layout.list_item, result));
            mProgressDialog.dismiss();                                            
        }
    }

We see a couple of new things here:

Before we start our background process we show the modal dialog.

In our background process we loop through all the URLs, expecting to receive more than one. This will give us a good indication of our progress.

We can update the progress by calling publishProgress(). Notice that the argument is of type int, which will be auto-boxed to the second type defined in our class definition, Integer.

The call to publishProgress() will result in a call to onProgressUpdate(), which again has arguments of type Integer. You could, of course, use String or something else as the argument type by simply changing the second type in the inner class definition to String and, of course, in the call to publishProgress().

We use the first Integer to set the new progress value in our ProgressDialog.

We dismiss the dialog, which removes it.

Now we can bind this all together by implementing our onClickListener() for our second refresh button.:

mRefresh2.setOnClickListener(new OnClickListener() {

    @Override
    public void onClick(View v) {
        LoadRecipesTask2 mLoadRecipesTask = new LoadRecipesTask2();
        String url =
            "http://androidcookbook.com/seam/resource/rest/recipe/list";
        showDialog(DIALOG_KEY);                             
        mLoadRecipesTask.execute(url, url, url, url, url);  
    }
});

We show the dialog by calling showDialog() with the DIALOG_KEY argument, which will trigger our previously defined onCreateDialog() method.

We execute our new task with five URLs, simply to show a little bit of progress.

It will look something like Figure 4-3.

Figure 4-3. Retrieving recipes in the background

Implementing background tasks with AsyncTask is very simple and should be done for all long-running processes that also need to update your user interface.

See Also

The developer documentation on processes and threads.

Source Download URL

The source code for this project is in the Android Cookbook repository, in the subdirectory RecipeList (see “Getting and Using the Code Examples”).

Problem

You need to pass information or data from a Service or other background task to an Activity. Because Activities run on the UI thread, it is not safe to call them from a background thread.

Solution

You can write a nested class that extends Android’s Handler class, then override the handleMessage() method that will read messages from the thread queue. Pass this handler to the worker thread, usually via the worker class’s constructor; in the worker thread, post messages using the various obtainMessage() and sendMessage() methods. This will cause the Activity to be called in the handleMessage() method, but on the event thread so that you can safely update the GUI.

Discussion

There are many situations in which you must have a thread running in the background and send information to the main Activity’s UI thread. At the architectural level, you can take one of the following two approaches:

• Use Android’s AsyncTask class.

• Start a new thread.

Though using AsyncTask is very convenient, sometimes you really need to construct a worker thread by yourself. In such situations, you likely will need to send some information back to the Activity thread. Keep in mind that Android doesn’t allow other threads to modify any content of the main UI thread. Instead, you must wrap the data into messages and send the messages through the message queue.

To do this, you must first add an instance of the Handler class to, for example, your MapActivity instance (see Example 4-19).

public class MyMap extends MapActivity {
    .
    public Handler _handler = new Handler() {
        @Override
        public void handleMessage(Message msg) {
            Log.d(TAG, String.format("Handler.handleMessage(): msg=%s", msg));
            // This is where the main Activity thread receives messages
            // Put incoming message handling posted by other threads here
            super.handleMessage(msg);
        }

    };
.
}

Now, in the worker thread, post a message to the Activity’s main queue whenever you need to add the Handler class instance to your main Activity instance (see Example 4-20).

    /**
    * Performs background job
    */
    class MyThreadRunner implements Runnable {
        // @Override
        public void run() {
            while (!Thread.currentThread().isInterrupted()) {
                // Dummy message -- real implementation
                // will put some meaningful data in it
                Message msg = Message.obtain();
                msg.what = 999;
                MyMap.this._handler.sendMessage(msg);
                // Dummy code to simulate delay while working with remote server
                try {
                    Thread.sleep(5000);
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                }
            }
        }
    }