Instant Android Fragmentation Management How-to

To better understand about the compatibility package, it's helpful to know a bit about Android's history.

The Android platform was born in 2003, as the product of a company which at first was known as Android Inc. and which was acquired by Google in 2005. Its direct competitors were and are still today the iOS platform by Apple and the RIM, know as Blackberry. Technically speaking, its core is an operating system using a Linux Kernel, aimed to be installed on devices with very different hardware (mainly mobile devices, but today it is also used in general embedded systems like, for example, the game console OUYA that features a modified version of Android 4.0).

Like any software that has been around for a while, many changes happened to the functionality and many versions came out, each with a name of a dessert:

Like in many other software projects, the names, as well as the themes, are in alphabetical order (another project that follows this approach is the Ubuntu distribution).

The API level written in the parenthesis is the main point about this compatibility package. Each version of software introduces or removes features and bugs. In its lifetime, an operating system such as Android aims to add more fantastic innovations while avoiding breaking pre-installed applications in older versions, but also aims to make available to these older versions the same features with a process technically called backporting.

For more information about the API levels, carefully read the official documentation available at http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels.

All that you will read in the following sections is thought to address these problems, using backporting; in particular, to specifically address the backward compatibility issues with version 3.0 of the Android operating system—the version named Honeycomb.

Version 3.0 was first intended to be installed on tablets, and in general, on devices with large screens. Android is a platform that from the beginning was intended to be used on devices with very different characteristics (think a system where an application must be usable on VGA screens, with or without physical keyboards, with a camera, and so on); with the release of 3.0, all this was improved with specific APIs thought to extend and make developing applications easier, and also to create new patterns with the graphical user interface.

The more important innovation was the introduction of the Fragment class. Earlier, the only main class in developing the Android applications was Activity, a class that provides the user with a screen in order to accomplish a specific task, but that was too coarse grain and not re-usable enough to be used in the applications with large screens such as a tablet. With the introduction of the Fragment class to be used as the basic block, it is now possible to create responsive mobile design; that is, producing content adapting to the context and optimizing the block's placement, using reflowing or a combination of each Fragment inside the main Activity.

These are concepts inspired by the so called responsive web design, where developers build web pages that adapt to the viewport's size; the preeminent book about this argument is Responsive Web Design, Ethan Marcotte.

If all this seems a bit complicated, allow me to make a simple example using a real application. The following image is the composition of two screenshots of the same application (Google Play, the Android Market) with two different screen resolutions; you can see how the information about the developer and the information about the application is placed side by side on the tablet version, where as in the phone version they are just shown one below the other.

It's not the only possibility to create a so-called multi-paned layout; you can stretch, compress, stack, or expand the Fragment depending on your plan. On the Android's site, it's available as a guide worth following—in the design section of the site. It is available at http://developer.android.com/design/patterns/multi-pane-layouts.html.

Another important element introduced in Google's platform is the UI pattern named ActionBar—a piece of interface at the top of an application where the more important menu's buttons are visualized in order to be easily accessible.

Also a new contextual menu is available in the action bar. When, for example, one or more items in a list are selected (such as, the Gmail application), the appearance of the bar changes and shows new buttons related to the actions available for the selected items.

For sake of completeness, let me list other new capabilities introduced with Honeycomb (as previously said, look into the official documentation for a better understanding of them):

Not all the things listed here are backported with the Support Library. In particular, there is no official way to implement the new animation framework in a backward compatible way (libraries that do this do exist though).

Unfortunately, the Support Library does not support all these features of previous versions of the OS. Most notably, the official Google Support Library does not support the action bar.

Fortunately, for Android developers, there is an open-source project called ActionBarSherlock, which does a fantastic job of bringing the ActionBar API back to Android 1.6 (API level 4). We will discuss more on this in the ActionBar section.

When we create the two possible layouts of the Fragments, we choose the landscape and portrait orientation as a switch, but this is not completely the correct approach.

We know well how it is possible to provide various versions of the same resource (layouts, images, and so on) by placing it in a directory whose name is appended with some specific qualifiers that identify the configuration under which the resources must be used (in the previous case, layout-land has been used as the directory's name to indicate as configuration to the device in landscape orientation). The qualifiers can be mixed together, but only in a specific order.

From API level 13 (that is, version 3.2), two new qualifiers are available:

With these qualifiers, it is also possible to use the extended layout on devices that have, for example, the screen width on portrait mode large enough to contain it. If we decide that the switch happens at 600 dp of screen width, we can place our extended layout XML file into a directory named res/layout-w600dp/.

Another trick useful in cases like these is the use of <include> and <merge> tags into your layout. In this way, we can create only one specific layout file and reference it from another if we think it must be equal. If we want to use res/layout-w600dp/main.xml as our real extended layout, we can reference it from res/layout-land/main.xml with the following piece of code:

<?xml version="1.0" encoding="utf-8"?>
<merge>
  <include layout="@layout/skeleton_extended"/>
</merge>

Here we have renamed it to skeleton_extended.xml, the multi-paned layout.

The final words are about managing themes and making them as version-independent as possible. If, for example, we want to use a light theme (the default one is dark) and in particular the Holo theme (a particular theme included in all Android OS starting from Honeycomb that is a compatibility requirement for Android devices running Android 4.0 and forward) with devices with an API level equal or greater than 11, we need to declare our custom theme. Create two directories, one with the path res/values/ and the other named res/values-v11/.

In the first, create the styles.xml file with the following content:

<resources>
    <style
            name="AppTheme"
            parent="android:Theme.Light" />
</resources>

In the other instead write the following content:

<resources>
    <style
            name="AppTheme"
            parent="android:Theme.Holo.Light" />
</resources>

Finally insert the following code line in the AndroidManifest.xml file as an attribute of the <application> tag:

android:theme="@style/AppTheme"

It's important to note that these considerations don't help the backward compatibility directly, but they avoid the loss of possibilities offered from new devices.

Starting with the Honeycomb version, the way the menu is managed is also different. Because of ActionBar, now it's possible to present some menu options on it so that it becomes easily accessible. The ratio to be used in choosing the options to place in the ActionBar should follow the FIT scheme—Frequent, Important, or Typical.

So the method used for building the menu, that is, OnCreateOptionsMenu(), is called—when an action bar is present—at Activity start (on pre-Honeycomb devices, this function is activated only by pressing the menu button). For example, we can define a simple menu with two options in it, into a file at the res/menu/main.xml path.

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@+id/menu_new"
          android:title="New"
          android:showAsAction="ifRoom"/>
    <item android:id="@+id/help"
          android:title="Help" />
</menu>

Since we have indicated the ifRoom value in the showAsAction attribute, this option will be inserted to the right side of the ActionBar (in case there are more options with the same value set, only those that fit into the action bar will be displayed, the others will be shown normally by the menu button).

In pre-Honeycomb devices without ActionBar, all the options will appear normally with the usual menu buttons.

Since the Fragments are components at application level and not at UI level, it's possible to instance these without associating layout elements to them.

We do this programmatically with the add(fragment, tag) function.

This is available with an instance of FragmentTransaction. The tag parameter is a normal string (do not confuse this parameter with the tags used in the View class) that can then be used to find the Fragment with the findFragmentByTag() function.

If you are wondering why you would want to use a Fragment with no UI, keep in mind that in this way Fragments are not destroyed when the UI is recreated (such as during orientation changes).

Since the devil is in the detail, it is important to understand the role of the variables in the <uses-sdk> tag used in AndroidManifest.xml, which expresses the application's compatibility with one or more versions of the Android platform.

As the meaning of minSdkVersion is rather obvious, let me quote an excerpt from the documentation of targetSdkVersion:

In our case, we want to create applications installable from devices with API level 4, and in particular, we want to use capabilities introduced with Honeycomb (that is, API level 11), so finally the AndroidManifest.xml file must contain the following content:

    <uses-sdk
        android:minSdkVersion="4"
        android:targetSdkVersion="11" />

For the Eclipse users, it's possible to set these values initially from the Android projects creation wizard:

The targetSdkVersion is Build SDK as set in the shown dialog.

The maxSdkVersion must be set manually.

As you can clearly see in the code, there is a special type of Fragment, a ListFragment, which is a fragment that displays a list of items by binding them to a data source and exposes event handlers when the user selects an item.

Support Library also provides the backward compatible implementation of the FragmentDialog class used to display, obviously, dialog windows. In the documentation, it is explained as follows:

Let's write some example code in order to show how this is supposed to work:

Obviously this is a very simple example and much more could be said, but it's left as an exercise for the reader (as, for example, how to embed a dialog into an Activity).

Not all the possible problems can be addressed with the Support Library, so it is necessary to learn some ways to manage the different availability of features between versions.

One solution could be the creation of different APKs, one for each particular version of Android, and uploading each one separately on the Android market; this is not particularly smart, since it causes a lot of code duplication and is maintainability hell.

A better solution is to create branches in the interested code, using an if statement and checking for VERSION_CODES. This is accessible from the android.os.Build package and it presents an enumeration of all versions of Android. To be able to check for the actual version at runtime, the SDK_INT field must be used in the android.os.Build.VERSION package.

At the end, we should write some code similar to the following:

if (android.os.Build.VERSION.SDK_INT => android.os.Build.VERSION_CODES.HONECOMB) {
   // ...
} else if (android.os.Build.VERSION.SDK_INT =>
android.os.Build.VERSION_CODES.GINGERBREAD){
     // ...
}

A more sophisticated approach would be to use the resource system in order to set appropriate Boolean variables with values of interest. Suppose we create two values files, one with the path res/values/bools.xml and with the following content:

<?xml version="1.0" encoding="utf-8"?>
<resources>
   <bool name="isHoneycomb">false</bool>
</resources>

The other at the path res/values-v11/bools.xml with the following content:

<?xml version="1.0" encoding="utf-8"?>
<resources>
   <bool name="isHoneycomb">true</bool>
</resources>

Inside the code, the isHoneycomb variable can be referenced with a simple piece of code, as shown as follows:

Resource r = getResources();
boolean isHoneycomb = r.getBoolean(R.bool.isHoneycomb)

This can be used directly in the code.

Under the hood, an Android application is not a unique block of instructions executed one after the other, but is composed of multiple pipelines of execution. The main concepts here are the process and thread. When an application is started, the operating system creates a process (technically a Linux process) and each component is associated to this process.

Together with the process, a thread of execution named main is also created. This is a very important thread because it is in charge of dispatching events to the appropriate user interface elements and receiving events from them. This thread is also called UI Thread.

It's important to note that the system does not create a separate thread for each element, but instead uses the same UI thread for all of them. This can be dangerous for the responsiveness of your application, since if you perform an intensive or time expensive operation, this will block the entire UI. All Android developers fight against the ANR (Application Not Responding) message that is presented when the UI is not responsive for more than 5 seconds.

Following Android's documentation, there are only two rules to follow to avoid the ANR:

These two rules can seem simple, but there are some particulars that have to be clear. First of all, let me show you the simplest way to create a new thread, using the class named Thread.

This class implements the Runnable interface defined with a single method called run(); when an instance of a Thread calls its own method start(), it launches in the background the instructions defined in the run() method. Nothing new for everyone with experience in Java programming; this is plain Java, so it is completely available in all API levels.

For example, if we want to create a simple task that sleeps for 5 seconds, without blocking the UI, we can use the following piece of code:

new Thread(new Runnable() {
  public void run() {
    this.sleep(5000);
  }
}).start();

All is clear, but in a general case, we would like to interact with the UI, in order to update a progress bar, to show an error, or to change the appearance of a UI element; using an example from Android's documentation, we are tempted to write a piece of code where we update an ImageView by using a remote PNG:

public void onClick(View v) {

  new Thread(new Runnable() {

    public void run() {

      Bitmap b = loadImageFromNetwork("http://example.com/image.png");

      mImageView.setImageBitmap(b);
    }

  }).start();

}

All seems ok, but when running this code, it results in an infamous exception appearing in the application's log:

This is because setImageBitmap() is executed in the thread created by us and not in the UI thread, violating the second rule expressed above (this is not allowed since the UI thread is not thread-safe, that is, it is not assured that concurrent access to an element doesn't cause problems).

Before we solve this problem, let me show you the innermost structures introduced by the Android system to manage threads—the Looper and Handler classes.

An instance of the first class is simply used to run a message loop in a thread that will be handled by an instance of the second class. On the other hand, a Handler instance manages message instances between threads, but its context of execution is the thread where it was initially defined.

In order to understand, it's better to write a complex example involving two threads communicating with messages. Suppose we have a generic Activity class, and inside its onCreate() method, we define two threads communicating after every 5 seconds:

  new Thread(new Runnable() {
    @Override
    public void run() {
      Looper.prepare();

      mFirstHandler = new Handler() {
        @Override
        public void handleMessage(Message message) {
          android.util.Log.i(TAG, (String)message.obj);
        }
      };

      Looper.loop();
    }
  }).start();

    new Thread(new Runnable() {
    @Override
    public void run() {
      int cycle = 0;
      while (true) {
        try {
          Thread.sleep(5000);

          Message msg = mFirstHandler.obtainMessage();

          msg.obj = "Hi thread we are at " + cycle;
          mFirstHandler.sendMessage(msg);

          cycle++;
        } catch (java.lang.InterruptedException error) {
          android.util.Log.i(TAG, "error: " + error.getMessage());
        }
      }
    }
  }).start();

This is how it appears in Eclipse's thread panel when the code is running:

The more fascinating thing is that there is also a possibility to queue the Runnable classes to be executed in the original thread of the Handler class. Instead of sendMessage(), it is possible to use mFirstHandler.post() with a Runnable class's definition as the argument.

The fundamental point to remember in order to use these classes is to call Looper.prepare() and Looper.loop() in the run() method of the thread and the code related to the Handler class in between—that's all.

The only thread that has yet a Looper defined is the UI Thread that makes some methods available in order to post the Runnable class instance in it.

Now, back to the earlier problem, let me explain how to solve it using the Runnable class; we can post the updating UI code by using a utility method available to any View, such as the View.post(Runnable) method.

Now, we can substitute the line causing the problem with the following code:

            mImageView.post(new Runnable() {
                public void run() {
                    mImageView.setImageBitmap(bitmap);
                }
            });

Looper and Handler are important since they are at the core of the system, and more importantly, they have been available since API level 1, making them good resources for writing the Android applications.

Another important class, available since API level 3, is AsyncTask. If you have worked on an application using background threads, it is probable that you have used it since it is intended for this purpose; to facilitate the managing of the threads, and to avoid all the headache and the error-prone code of the Looper and Handler classes.

Its definition is particular. It uses generics; that is, there are some parameters indicated with Params, Progress, and Result that identify the signature of some functions used internally to manage threads.

In particular, AsyncTask has four methods as follows:

All but the doInBackground() function are executed in the UI thread, so it's important to remember not to perform time-consuming work in them.

If we want to replicate the code that downloads a remote PNG and updates an ImageView with it, we should write something, as shown in the following code snippet:

class PNGUpdate extends AsyncTask<URL, Integer, Long> {
  Bitmap mBitmap;
  ImageView mImageView;

  public PNGUpdate(ImageView iv) {
    mImageView = iv;
  }

  protected Long doInBackground(URL... urls) {
   int count = urls.length;
    for (int i = 0; i < count; i++) {
      mBitmap = loadImageFromNetwork(urls[i]);
    }

    return 0;
  }

  protected void onPostExecute(Long result) {
    mImageView.setImageBitmap(mBitmap);
  }
}

For where we will want to call it, we have to insert a line, such as the following:

new PNGUpdate(myImageView).execute(pngURL)

What you may have noted is that in the initial steps, when we defined our Loader, we subclassed a class named AsyncTaskLoader. It is simply a Loader with an AsyncTask inside; the only difference here is that it doesn't get three parameters in its definition, but only one since it's not supposed by a Loader to return information about the status of an operation (for example, no progress bar is shown).

A final note from the documentation about the serial/parallel execution of threads:

The initial instructions about writing a Loader have used the simple AsyncTaskLoader that simplifies a lot for the life of a developer, creating for you the correct subdivision between background threads and UI threads.

This is important, mainly since it avoids wasting your time with little errors, and more importantly, makes the code more modular, avoiding the need of reinventing the wheel. However, now we are to reinvent the wheel in order to understand how to correctly manage the Loader classes with your applications.

The Loader is intended to be used with dynamic data, where it is important to be notified for updates in order to refresh the related element of the UI; in order to notify our loader that the underlying data is changed, we'll implement a class named RSSObservable that controls that the XML (representing the RSS) is different from the previous version. It's important to note that this is a proof of concept and is not intended to be used in the real world. Both the Loader and the Observable classes download the RSS, causing the drain of the battery (and in some case, you will be billed for the bandwidth).

Once you read this code, try to compare it with the original implementation of the AsyncTaskLoader class that you can find in Android's source code in the file frameworks/base/core/java/android/content/AsyncTaskLoader.java. Obviously, we are not going to implement all the things that you can find there.

So let's implement our custom Loader:

The more cumbersome part is understanding the underlying flow of the Loader. First of all, there are three states in which it can exist. Those are as follows:

Each of these states can be reached from the others.

Since all happens asynchronously, it's possible that a notification of data update can reach the Loader instance when the state is different from STARTED; this explains the various checks present in the code.

One thing introduced in the preceding code snippet, not mentioned in the AsyncTaskLoader example, is the Observer/Observable design pattern. The first is defined as an interface and the second as a class, both in the java.util package (and both have been available from API level 1, so do not cause compatibility issues). The observer receives notification of updates by the update() method, whereas the observable registers some observers (by the addObserver() method) to be notified (by the notifyObservers() method) when a change occurs.

From the start, the Android platform has made available a Back button with which one can step back during the navigation between activity and applications. To allow a more structured navigation, the Up button was introduced to permit a user to create a new task from an activity that does not belong to the original task that created it (it's not completely true, since if the original application is the same, no tasks are created).

For example, we start a news reader and then we choose a specific news item that we want to share with our friends by sending it via e-mail; in order to do so, we launch an Email application that is started in the same task of the news reader. If the Email application has an Up button, clicking on it will start a new task with the home Activity of the Email application.

What we obtain with the Up button is a hierarchical navigation inside the active application. Obviously, the Up button should not be present in the main Activity because there is no upward navigation there.

In order to enable the Up button in our code, simply activate it by using the following code line:

actionbarinstance.setDisplayHomeAsUpEnabled(true);

We can now write the code that will handle the click on the icon on the left-hand side of the ActionBar. This code is as follows:

@Override
public boolean onOptionsItemSelected(MenuItem item) {
  switch (item.getItemId()) {

    case android.R.id.home:

    Intent intent = new Intent(this, MyOwnActivity.class);
    intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
    startActivity(intent);

    return true;

    default:
    return super.onOptionsItemSelected(item);

  }
}

Remember only that the Up button is represented on the ActionBar with a widget having android.R.id.home as an identifier.

Another UI pattern from the ActionBar is the action view. It is possible to associate a particular widget to an action item. A widget here is, a visual element that can be expanded to occupy all the available space of the ActionBar; in the following code, we will implement a fake search entry—initially on the ActionBar there is only the Search button:

After selecting this element, it will appear expanded, as shown in the following screenshot:

This example mimics the example from the Android documentation where the SearchView class is used instead. This class is not available with ActionBarSherlock, but is planned to be included (maybe) in future releases.

For further information about this issue, please follow the discussion on the github project page at https://github.com/JakeWharton/ActionBarSherlock/issues/70.

An extension to the concept of action view is the action provider—a widget that not only controls its appearance, but also extends its controls. An action provider available with the Android framework is ShareActionProvider that allows us to easily share the contents showing a menu with some share target in it.

Since we are interested in maintaining backward compatibility using ActionBarSherlock, here are the steps necessary to implement this:

In the following screenshot, you can see how the menu item appears:

The necessity to make simple and quick actions on specific elements such as list items (for example, removing a contact) or copying some selected text into the clipboard, makes the employ of the contextual action bar useful. The appearance of the bar changes so that it can show the specific menu item for the action desired.

Now, let's see how to add a contextual action bar with two action items to your application:

The following screenshot shows how the contextual menu will appear:

Remember that the OK button (the button at the very left of the bar) simply dismisses the contextual action bar and the system adds it for you.

The obvious extension of this mechanism is the possibility to select multiple elements and to act on it. This exists and it possibly started from Honeycomb, using the MultiChoiceModeListener interface that belongs to the AbsListView class. The only problem is that it is not available with ActionBarSherlock, so as hinted from the original Android documentation, it is better to fall back to a floating contextual menu.

Let's explain how to create a more interesting visual layout for your application, for example, one UI pattern that we see all the time is the "swipey-tabs" one, used in the Android Market.

This UI pattern allows the user to switch between sections of the application, simply swiping left/right and having the title on the tab following the swipe motion (for more technical information about this design, I advise you to read the post from an Android Market designer at http://www.pushing-pixels.org/2011/08/11/android-tips-and-tricks-swipey-tabs.html).

In order to do this, we need to download another library from the web page of its project, located at http://viewpagerindicator.com/.

The steps required to add this library to our project are the same as those shown at the start of this section. Only keep in mind that the path to the library is where you have extracted it.

Now, we are ready to add ViewPageIndicator to your application:

What we obtain is an application where the various Fragments served from the ViewPager class are inserted, one for each tab, and the TitlePagerIndicator class furnishes us with a visual effect when the transition between tabs happens. The following screenshot shows how the tab part appears in our application (obviously, it is not possible to show the animation on paper):