The first thing that we need to do is switch to release 13 of the support library. As this is a maven project, this is achieved via the POM, but if you are not using maven you’ll need to remove the existing library and re-import release 13.

The first thing that we need to do is alter our main layout and wrap it in a DrawerLayout (from the support library) and then add a new ListView to contain the navigation list:

<android.support.v4.widget.DrawerLayout 
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/drawer_layout"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity" >

    <FrameLayout
        android:id="@+id/main"
        android:layout_width="match_parent"
        android:layout_height="match_parent" >
    </FrameLayout>

    <ListView
        android:id="@+id/drawer"
        android:layout_width="240dp"
        android:layout_height="match_parent"
        android:layout_gravity="start"
        android:background="#FFF"
        android:choiceMode="singleChoice" />

</android.support.v4.widget.DrawerLayout>

Next we need to change our MainActivity to attach the Adapter to the ListView instead of the existing Spinner:

@Override
protected void onCreate(Bundle savedInstanceState)
{
	super.onCreate(savedInstanceState);
	setContentView(R.layout.activity_main);
	final String[] names = 
		getResources().getStringArray(R.array.nav_names);
	final String[] classes = 
		getResources().getStringArray(R.array.nav_classes);
	ArrayAdapter<String> adapter = 
		new ArrayAdapter<String>(
			getActionBar().getThemedContext(), 
			android.R.layout.simple_list_item_1, names);

	final DrawerLayout drawer = 
		(DrawerLayout)findViewById(R.id.drawer_layout);
	final ListView navList = 
		(ListView) findViewById(R.id.drawer);
	navList.setAdapter(adapter);
	navList.setOnItemClickListener(new OnItemClickListener()
	{

		@Override
		public void onItemClick(AdapterView<?> parent, 
				View view, final int pos, long id)
		{
			drawer.setDrawerListener( 
				new DrawerLayout.SimpleDrawerListener()
			{
				@Override
				public void onDrawerClosed(View drawerView)
				{
					super.onDrawerClosed(drawerView);
					FragmentTransaction tx = 
						getSupportFragmentManager()
							.beginTransaction();
					tx.replace(R.id.main, 
						Fragment.instantiate(
							MainActivity.this, 
							classes[pos]));
					tx.commit();
				}
			});
			drawer.closeDrawer(navList);
		}
	});

	FragmentTransaction tx = 
		getSupportFragmentManager().beginTransaction();
	tx.replace(R.id.main,
		Fragment.instantiate(MainActivity.this, classes[0]));
	tx.commit();
}

First we need to use a different layout for each item as this is now a ListView and not a Spinner. Next we find our DrawerLayout and ListView controls from the layout and set the Adapter to the ListView. Then we handle click events on our ListView – whenever an item is clicked, we close the drawer, wait for it to complete using a DrawerListener, and switch the Fragment once the drawer has closed. The reason for waiting for the drawer to close is to prevent stuttering during the drawer closing animation if we try and switch the Fragment at the same time. Alternatively we could switch the Fragment first, and then close the drawer, but for simplicity in this example we’ll wait for the drawer to close.

Finally we need to set set the default Fragment. The reason for this is that when we were using the Spinner, a default selection in the Spinner would be made which would trigger our OnNavigationListener to create the appropriate Fragment. In this new navigation model there is no initial event so we have to load the default Fragment manually.

That’s enough to get a basic Navigation Drawer working. If we swipe from the left hand edge of the screen our Navigation Drawer appears, and we can select the different examples:

In the next article in this series we’ll look at how we can connect the Navigation Drawer up the the app icon in our ActionBar to show and hide it.

The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License

A PagerAdapter is responsible for creating the content for each page within a ViewPager. It takes two main forms: When creating or inflating a standard View hierarchy the standard PagerAdapter is used, but when each page is a Fragment we can use FragmentPagerAdapter instead. Let’s start with the former:

private static String[] titles = new String[]
{ 
	"Page 1", "Page 2", "Page 3", "Page 4", "Page 5"
};

private class MyPagerAdapter extends PagerAdapter
{
	@Override
	public int getCount()
	{
		return titles.length;
	}

	@Override
	public boolean isViewFromObject(View view, 
		Object object)
	{
		return view.equals(object);
	}

	@Override
	public Object instantiateItem(ViewGroup container, 
		int position)
	{
		TextView text = new TextView(getActivity());
		text.setText(titles[position]);
		container.addView(text);
		return text;
		}

	@Override
	public void destroyItem(ViewGroup container, 
		int position, Object object)
	{
		if (object instanceof View)
		{
			container.removeView((View) object);
		}
	}
		
	@Override
	public CharSequence getPageTitle(int position)
	{
		return titles[position];
	}
}

This is pretty much as simple as we can get it. The view that is created is a simple TextView and we set the text to the value of the appropriate string from the titles array. In the instantiateItem() method we could, just as easily, use a LayoutInflator to inflate a layout from XML and then find the controls to bind to. We could also create or inflate different layouts depending on the position. But the basic principle in that getCount() returns the number of pages to display, instantiateItem() gets called to create the individual layouts, destroyItem() gets called to remove the layouts, and getPageTitle() returns the title to use in a PagerTabStrip or PagerTitleStrip (for more information on PagerTabString see this article).

To create Fragment instead of a View hierarchy, we first need to create a Fragment class:

public static class MyFragment extends Fragment
{		
	private static final String TAG = "MyFragment";
	public MyFragment()
	{
		super();
	}
		
	@Override
	public View onCreateView(LayoutInflater inflater, 
		ViewGroup container,
		Bundle savedInstanceState)
	{
		View view = inflater.inflate(R.layout.page, 
			container, false);
		View text = view.findViewById(android.R.id.text1);
		if(text != null && text instanceof TextView)
		{
			((TextView)text).setText(
				titles[getArguments().getInt("position")]);
			}
		return view;
	}
				
	@Override
	public void onAttach(Activity activity)
	{
		super.onAttach(activity);
		Log.d(TAG, "Attached " + 
			getArguments().getInt("position"));
	}
		
	@Override
	public void onDetach()
	{
		Log.d(TAG, "Detached " + 
			getArguments().getInt("position"));
		super.onDetach();
	}
}

Our Fragment class, MyFragment, creates a layout identical to the one used in the previous example, only in this case it inflates it from XML instead of creating the View objects programatically. Either approach is fine, just chose whichever suits the task that you’re trying to perform best – I’ve simply included both forms here to show that it can be done. The overrides of the onAttach() and onDetach() methods simply add a little logging to show when the instances of this class become attached and detached from an Activity (the reasons for adding this will become obvious later on).

The Adapter itself is actually simpler than the previous PagerAdapter example because we don’t need to worry about the destroyItem() method this time:

private class MyFragmentPagerAdapter 
	extends FragmentPagerAdapter
{
	public MyFragmentPagerAdapter(FragmentManager fm)
	{
		super(fm);
	}

	@Override
	public Fragment getItem(int position)
	{
		Bundle args = new Bundle();
		args.putInt("position", position);
		return Fragment.instantiate(getActivity(), 
			MyFragment.class.getName(), args);
	}

	@Override
	public int getCount()
	{
		return titles.length;
	}
		
	@Override
	public CharSequence getPageTitle(int position)
	{
		return titles[position];
	}
}

The important thing to remember here is that we can actually instantiate different kinds of Fragment for different positions. It is the role of the Adapter to create the correct instance for each position. This implementation is actually much cleaner than the first example because it clearly splits the responsibilities in to different objects. The Fragment instance represents the view for an individual page, and the Adapter is responsible for creating the separate instances.

There is one further thing that is important, although I stated that there were two types of PagerAdapter, there are actually three because there are two variants of FragmentPagerAdapter: FragmentPagerAdapter (as we have used here) and FragmentStatePagerAdapter. The difference between the two is that FragmentPagerAdpater will create views and hold them in memory for the lifecycle of the Adapter, whereas FragmentStatePagerAdapter can destroy individual Fragments when they are not visible. This makes FragmentPagerAdapter suitable when you have a small number of static page Fragments that aren’t particularly memory hungry; but FragmentStatePagerAdapter is better if you have a large number of pages, or some or all of the individual page Fragments are particularly memory hungry.

You can actually switch between the two by simply changing the base class that MyFragmentPagerAdapter subclasses. If you try this and check the logs, you’ll see that when using FragmentPagerAdapter, each of the views gets attached to the Activity once when it is first viewed, but they all remain attached no matter how much you page between the different pages in the ViewPager. On the other hand if you switch to FragmentStatePagerAdapter you’ll see that each time you switch pages, views will become attached to the Activity while others become detached.

If we run this, we can see two ViewPagers which look and behave identically, but have rather different implementations:

That brings us to the end of this series on Adapters. PagerAdapters are somewhat different to the other types of Adapter that we’ve looked at in this series, but many of the underlying principles are the same. Getting our Adapters right is an important part of getting our UI to behave in a smooth manner, and therefore improving the overall user experience.

The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License

As this series focuses on Adapters, I’m not going to provide a tutorial on SQLite databases and ContentProviders. For some useful information on these topics, please refer to Lars Vogel’s excellent tutorial. Grokking Android’s Wolfram Rittmeyer has also written some useful tutorials on this topic.

For our example, I have set up a simple database and ContentProvider. The database contains two columns: The obligatory ID column, and a column containing arbitrary text. We’ll simply store a set of numbers in text form (i.e. “One”, “Two”, “Three”, etc). To keep things simple, the database has been limited to the numbers 1-20. I won’t include this code in the article, but it’s available in the source if you want to look at it.

Before we dive in to the code, it’s worth looking at a fundamental shift in the recommended usage of CursorAdapters which occurred in API 11 Honeycomb 3.0. Prior to that the accepted usage was to use the FLAG_AUTO_REQUERY flag which would cause the Cursor to be re-retrieved when it detected a change to the database. The only problem with this is that the database queries are performed on the UI thread which can make your UI laggy or, in extreme cases, present the user with the dreaded “Application Not Responding” dialog. Looking at the Javadocs for CursorAdapter the suggestion is to use CursorLoader instead, but doesn’t give much more information. So we’ll implement things using a CursorLoader to see how to do this.

In actual fact, using a CursorLoader is simplicity itself, and it does a surprising amount for us. We used a Loader in the previous article, but this time we’ll implement our LoaderCallback in our ListFragment instead of in our ViewHolder as we don’t need a ViewHolder in this case:

public class CursorAdapterFragment 
	extends ListFragment 
	implements LoaderCallbacks<Cursor>
{
	private static final String[] columns =
	{ 
		CounterHelper.COLUMN_ID, 
		CounterHelper.COLUMN_TEXT 
	};
	
	private static final int[] controlIds =
	{ 
		android.R.id.text1, 
		android.R.id.text2 
	};

	@Override
	public View onCreateView(LayoutInflater inflater, 
		ViewGroup container,
		Bundle savedInstanceState)
	{
		setHasOptionsMenu(true);
		return inflater.inflate(R.layout.listview, 
			container, false);
	}

	@Override
	public void onActivityCreated(Bundle savedInstanceState)
	{
		super.onActivityCreated(savedInstanceState);
		getLoaderManager().restartLoader(0, null, this);
	}

	@Override
	public Loader<Cursor> onCreateLoader(int id, Bundle args)
	{
		Loader<Cursor> loader = null;
		if (id == 0)
		{
			loader = new CursorLoader(getActivity(),
				CounterContentProvider.CONTENT_URI,
				CounterContentProvider.PROJECTION, 
				null, null,
				CounterHelper.COLUMN_ID + " ASC");
		}
		return loader;
	}

	@Override
	public void onLoadFinished(Loader<Cursor> loader, 
		Cursor cursor)
	{
		ListAdapter adapter = getListAdapter();
		if (adapter == null || 
			!(adapter instanceof CursorAdapter))
		{
			adapter = new SimpleCursorAdapter(getActivity(),
				android.R.layout.simple_list_item_2, 
				cursor, columns, controlIds, 0);
			getActivity().invalidateOptionsMenu();
			setListAdapter(adapter);
		}
		else
		{
			((CursorAdapter) adapter).swapCursor(cursor);
		}
	}

	@Override
	public void onLoaderReset(Loader<Cursor> loader)
	{
	}
	@Override
	public void onCreateOptionsMenu(Menu menu, 
		MenuInflater inflater)
	{
		inflater.inflate(R.menu.cursor, menu);
	}

	@Override
	public void onPrepareOptionsMenu(Menu menu)
	{
		MenuItem item = menu.findItem(R.id.add);
		if (item != null)
		{
			item.setEnabled(getListAdapter() != null ? 
				getListAdapter().getCount() < 
				CounterHelper.MAX_ROWS : false);
		}
		super.onPrepareOptionsMenu(menu);
	}

	@Override
	public boolean onOptionsItemSelected(final MenuItem item)
	{
		if (item.getItemId() == R.id.add)
		{
			int count = getListAdapter().getCount();
			if(count < CounterHelper.MAX_ROWS)
			{
				item.setEnabled(false);
				AsyncQueryHandler queryHandler = 
					new AsyncQueryHandler(
						getActivity().getContentResolver())
				{
					@Override
					protected void onInsertComplete(int token, 
							Object cookie,
							Uri uri)
					{
						getActivity().invalidateOptionsMenu();
						super.onInsertComplete(token, 
								cookie, uri);
					}
				};
				ContentValues values = new ContentValues();
				values.put(CounterHelper.COLUMN_TEXT,
						CounterHelper.NUMBERS[count]);
				queryHandler.startInsert(0, null, 
						CounterContentProvider.CONTENT_URI, 
						values);
			}
			else
			{
				getActivity().invalidateOptionsMenu();
			}
		}
		return super.onOptionsItemSelected(item);
	}
}

In our onActivityCreated() method we kick off the Loader and it is in the onCreateLoader() method where we actually create our CursorLoader using some constants defined in the ContentProvider. We’re actually using the stock CursorLoader and we don’t have to subclass it because it actually does an awful lot for us, as we’ll explore in a while.

In our onLoadFinished() method we check whether a CursorAdapter already exists for the ListView and create one, if necessary. The Adapter that we’re using is a SimpleCursorAdapter which work in a similar way to the SimpleAdapter that we looked at in part 2 of this series. It allows us to map columns in our database to controls in the layout rather than the Map that we used in SimpleAdapter.

The remainder of the code is just adding a simple menu which adds a new item to the database which allows us to see quite what the relatively simple CursorLoader & Adapter are actually doing for us.

If we run this we’ll see an empty list, but if we click the add button a few times, we’ll see items automatically appear in the list:

None of the code that we’ve added detects the data changing, and the reason that it’s happening is because the CursorLoader does it for us. When we first ran the CursorLoader it registered a ContentObserver on the data so it is automatically run again (on a background thread, of course) whenever the data changes. You can see this happening if you set a breakpoint in the onLoadFinished() method and hit the “Add” button.

We also don’t need to worry about cleaning things up because the CursorLoader is tied to the Activity lifecycle so will be properly cleaned up when our Activity goes out of scope.

All in all we get a lot of functionality for just a few lines of code.

Apologies that this article has focused a little more on CursorLoader than CursorAdpater (and this is, after all a series on Adapters), but the Adapter itself is pretty straightforward if you already understand how SimpleAdapter works, and the implementation is made even easier when we use a CursorLoader instead of acquiring a Cursor directly from the ContentResolver. Of course the CursorLoader pattern is applicable wherever you use Cursors and is not limited solely to CursorAdapters.

In the next article we’ll have a look at how we use Adapters to populate ViewPagers.

The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License

Actually adding images to the list item is easy enough, but we’ll compound the problems we face by not only loading images (which is an expensive operation), but also retrieving them from the cloud (another expensive operation). Neither of these operations should be performed in our getView() method, or indeed on the UI thread. To demonstrate this we’ll create a ListView which loads all of the emoticon icons from the Android AOSP source on github.

First we create an item layout which contains an ImageView:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:gravity="left|center_vertical"
    android:minHeight="?android:attr/listPreferredItemHeightSmall"
    android:paddingEnd="?android:attr/listPreferredItemPaddingEnd"
    android:paddingStart="?android:attr/listPreferredItemPaddingStart" >

    <TextView
        android:id="@android:id/text1"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:textIsSelectable="false" />

    <ImageView
        android:id="@android:id/icon"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_below="@android:id/text1"
        android:visibility="gone" />

    <ProgressBar
        android:id="@android:id/progress"
        style="@android:style/Widget.ProgressBar.Small"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_below="@android:id/text1"
        android:indeterminate="true" 
        android:minWidth="@dimen/image_size"
        android:minHeight="@dimen/image_size"/>

</RelativeLayout>

We’re also preempting something that we’ll require later on – a ProgressBar to display in place of the image while we’re loading it.

Our Adapter is pretty similar to what we’ve used previously, we’re just overriding getView() and doing the same view recycling and caching that we’ve done previously:

public class ArrayAdapterImageFragment extends ListFragment
{
	public static final String TAG = 
		"ArrayAdapterImageFragment";
	private static final List<String> items = 
		new ArrayList<String>();

	private class ItemAdapter extends ArrayAdapter<String>
	{

		public ItemAdapter(Context context)
		{
			super(context, 
				android.R.layout.simple_list_item_2, items);
		}

		@Override
		public View getView(int position, View convertView, 
			ViewGroup parent)
		{
			View view = convertView;
			ArrayAdapterImageViewHolder holder = null;
			if (view == null)
			{
				view = LayoutInflater.from(getContext())
					.inflate(R.layout.image_item, parent, false);
				TextView text = (TextView) view
					.findViewById(android.R.id.text1);
				ImageView image = (ImageView) view
					.findViewById(android.R.id.icon);
				ProgressBar progress = (ProgressBar) view
					.findViewById(android.R.id.progress);
				view.setTag(new ArrayAdapterImageViewHolder(
					getContext(), text, image, progress));
			}
			if (holder == null && view != null)
			{
				Object tag = view.getTag();
				if (tag instanceof ArrayAdapterImageViewHolder)
				{
					holder = 
						(ArrayAdapterImageViewHolder) tag;
				}
			}
			String item = getItem(position);
			if (item != null && holder != null)
			{
				holder.setName(item);
			}
			return view;
		}
	}

	static
	{
		items.add("emo_im_angel");
		items.add("emo_im_cool");
		items.add("emo_im_embarrassed");
		items.add("emo_im_foot_in_mouth");
		items.add("emo_im_happy");
		items.add("emo_im_kissing");
		items.add("emo_im_laughing");
		items.add("emo_im_lips_are_sealed");
		items.add("emo_im_money_mouth");
		items.add("emo_im_sad");
		items.add("emo_im_surprised");
		items.add("emo_im_tongue_sticking_out");
		items.add("emo_im_undecided");
		items.add("emo_im_winking");
		items.add("emo_im_wtf");
		items.add("emo_im_yelling");
	}

	@Override
	public View onCreateView(LayoutInflater inflater, 
		ViewGroup container, 
		Bundle savedInstanceState)
	{
		return inflater.inflate(R.layout.listview, 
			container, false);
	}

	@Override
	public void onActivityCreated(Bundle savedInstanceState)
	{
		super.onActivityCreated(savedInstanceState);
		ListAdapter adapter = new ItemAdapter(getActivity());
		setListAdapter(adapter);
	}

}

One thing to note is that we’re not even attempting to bind anything to the ImageView control within our getView() method – we’re going to do this in a Loader to keep the heavy image download and decoding operations outside of our getView() method, and off of the UI thread. For a fuller discussion of this, please refer to the series on Background Tasks.

First let’s look at the ViewHolder, which does rather more than the simple state holder that we used previously:

public class ArrayAdapterImageViewHolder 
		implements LoaderCallbacks<Bitmap>
{
	private static final String TAG = 
		ArrayAdapterImageFragment.TAG;

	private static int nextLoaderId = 0;
	private final int loaderId;
	private final Bundle bundle = new Bundle();
	private final Context context;
	private String name = null;
	public final TextView text;
	public final ImageView image;
	public final ProgressBar progress;

	public ArrayAdapterImageViewHolder(Context context, 
		TextView text, ImageView image, ProgressBar progress)
	{
		this.context = context;
		this.text = text;
		this.image = image;
		this.progress = progress;
		this.loaderId = nextLoaderId++;
	}

	@Override
	public Loader<Bitmap> onCreateLoader(int id, Bundle args)
	{
		return new ArrayAdapterImageLoader(
			context, args.getString("name"));
	}

	@Override
	public void onLoadFinished(
		Loader<Bitmap> loader, 
		Bitmap bitmap)
	{
		if(bitmap != null)
		{
			image.setImageBitmap(bitmap);
		}
		image.setVisibility(View.VISIBLE);
		progress.setVisibility(View.GONE);
	}

	@Override
	public void onLoaderReset(Loader<Bitmap> loader)
	{
		loader.abandon();
	}
	
	public void setName(String name)
	{
		text.setText(name);
		image.setVisibility(View.GONE);
		progress.setVisibility(View.VISIBLE);
		if(!name.equals(this.name) 
			&& context instanceof FragmentActivity)
		{
			bundle.putString("name", name);
			((FragmentActivity)context)
				.getSupportLoaderManager()
				.restartLoader(loaderId, bundle, this);
			Log.d(TAG, "Restarting loader: " + 
				loaderId + " : " + name);
		}
	}

}

The first thing to note is that this class implements our LoaderCallbacks interface, so this will handle the work which needs to be performed to set the Loader running, and also update the UI components (which needs to be performed on the UI thread) once the Loader‘ background operation is complete.

The entry point is the setName() method. This is called from our getView(), so needs to be really efficient. It sets the text in our TextViewProgressBar, hide the ImageView, and then restart the Loader (which will create it, if necessary). It is worth noting that we try and keep object creation to an absolute minimum – as these are expensive operations – so we reuse the Loader wherever possible, and also reuse the Bundle object that we use to pass parameters to our Loader.

The final component is the Loader implementation itself:

public class ArrayAdapterImageLoader 
	extends AsyncTaskLoader<Bitmap>
{
	private static final String TAG = 
		ArrayAdapterImageFragment.TAG;

	private static String density = null;

	private final String name;
	private boolean cancelled = false;

	public ArrayAdapterImageLoader(Context context, 
		String name)
	{
		super(context);
		this.name = name;
		if (density == null)
		{
			DisplayMetrics dm = 
				context.getResources().getDisplayMetrics();
			switch (dm.densityDpi)
			{
			case DisplayMetrics.DENSITY_LOW:
				density = "ldpi";
				break;
			case DisplayMetrics.DENSITY_MEDIUM:
				density = "mdpi";
				break;
			case DisplayMetrics.DENSITY_HIGH:
				density = "hdpi";
				break;
			case DisplayMetrics.DENSITY_XHIGH:
				density = "xhdpi";
				break;
			default:
				density = "mdpi";
				break;
			}
		}
	}

	@Override
	public Bitmap loadInBackground()
	{
		URL url = null;
		Bitmap bitmap = null;
		HttpURLConnection http = null;
		try
		{
			url = new URL(getContext().getString(
				R.string.image_base_url, density, name));
			URLConnection conn = url.openConnection();
			if(conn instanceof HttpURLConnection)
			{
				http = (HttpURLConnection)conn;
				if(http.getResponseCode() == 
						HttpURLConnection.HTTP_OK 
					&& http.getContentType()
						.startsWith("image"))
				{
					bitmap = BitmapFactory.decodeStream(
						http.getInputStream());
				}
			}
		}
		catch (Exception e)
		{
			Log.e(TAG, "Error loading image", e);
		}
		finally
		{
			if(http != null)
			{
				http.disconnect();
			}
		}
		return cancelled ? null : bitmap;
	}
	
	@Override
	protected void onStartLoading()
	{
		super.onStartLoading();
		forceLoad();
	}
	
	@Override
	protected void onAbandon()
	{
		super.onAbandon();
		cancelled = true;
	}

}

What we’re doing here is determining the device pixel density so that we can get the correct image for our device. Note that only ldpi, mdpi, hdpi, and xhdpi versions of these images are provided on AOSP, so we only support these.

We then load the image from github by constructing the URL, loading the content and decoding it to create a Bitmap object (all rather expensive operations) within the loadInBackground() method.

If we run this we see he following:

However, you’ll have to try it out for yourself to see how the ListView scrolling stays smooth.

It is worth pointing out that the code in this article is designed to demonstrate how to keep your ListView scrolling smooth, and your UI responsive, so I have tried to keep the code as simple as possible so that it is clear that the expensive operations are performed in the correct place. However, there are some omissions which should be addressed if you were to attempt to use it in a real app:

1. The handling of pixel densities for which assets do not exist is a little crude (i.e. xxhdpi defaults to mdpi)
2. There is no handling of network resources that are not found or not available
3. There is no detection of whether a network connection is available
4. Currently the images get pulled from the network each time they are loaded. An image cache would improve the user experience considerably

In the next article we’ll look at binding a ListView to a SQLite database.

The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License

In principle, replacing the SimpleAdapter with an ArrayAdapter is relatively simple. We create a class to hold the data for each item:

private static class Item
{
	public final String line1;
	public final String line2;
		
	public Item(String line1, String line2)
	{
		this.line1 = line1;
		this.line2 = line2;
	}
}

We can then use an ArrayAdapter instead of the ArrayAdapter that we used previously. The only problem here is that ArrayAdapter has no implicit knowledge of our Item class, so we need to perform the actual data binding ourselves. We do this by creating our own ArrayAdapter implementation and overriding the getView() method:

public class ArrayAdapterObjectFragment 
	extends ListFragment
{
	private static final List<Item> items = 
		new ArrayList<Item>();

	private static class Item
	{
		public final String line1;
		public final String line2;
		
		public Item(String line1, String line2)
		{
			this.line1 = line1;
			this.line2 = line2;
		}
	}
		
	private class ItemAdapter extends ArrayAdapter<Item>
	{

		public ItemAdapter(Context context)
		{
			super(context, 
				android.R.layout.simple_list_item_2, 
				items);
		}
		
		@Override
		public View getView(int position, 
			View convertView, 
			ViewGroup parent)
		{
			/* This implementation is very 
			 * inefficient and should not be used
			 * as is.
			 */
			Item item = getItem(position);
			View view = LayoutInflater.from(
				getContext()).inflate(
					android.R.layout.simple_list_item_2, 
					parent, false);
			((TextView)view.findViewById(android.R.id.text1))
				.setText(item.line1);
			((TextView)view.findViewById(android.R.id.text2))
				.setText(item.line2);
			return view;
		}
	}
	
	static
	{
		items.add(new Item("Title One", "Subtitle One"));
		items.add(new Item("Title Two", "Subtitle Two"));
		items.add(new Item("Title Three", "Subtitle Three"));
		items.add(new Item("Title Four", "Subtitle Four"));
		items.add(new Item("Title Five", "Subtitle Five"));
	}
	
	@Override
	public View onCreateView(LayoutInflater inflater, 
		ViewGroup container, Bundle savedInstanceState)
	{
		return inflater.inflate(R.layout.listview, 
			container, false);
	}
	
	@Override
	public void onActivityCreated(Bundle savedInstanceState)
	{
		super.onActivityCreated(savedInstanceState);
		ListAdapter adapter = new ItemAdapter(getActivity());
		setListAdapter(adapter);
	}
}

Hopefully this should be fairly understandable, and it does precisely what we require:

However, there is a problem with this, as you may be able to guess from the comment in the getView() implementation. To understand the problem, we have to consider how ListView works, particularly when we are scrolling through a list. Each time an item in the ListView comes in to view when scrolling, getView() will be called. Our getView() implementation is performing two quite expensive operations: layout inflation, and finding views within the layout.

Layout inflation is expensive because it requires the parsing of XML and the creation of a number of object instances representing the controls within the XML.

Finding views is expensive because it requires traversal of the view hierarchy in order to find the control that we’re interested in.

The net result of having these expensive operations within our getView() method is that the scrolling of our ListView will not be smooth. This will be compounded because the items going out of view will need to be garbage collected by the VM in order to free up the memory that will be necessary to create new objects during view inflation, and garbage collection is also an expensive operation.

Fortunately the Adapter framework gives us a mechanism for recycling our item layouts. When items go out of view, their layouts will be recycled and they will be passed in to our getView() method in the convertView argument. So we can perform a null check on this, and only inflate the view if we have to:

@Override
public View getView(int position, 
	View convertView, 
	ViewGroup parent)
{
	/* This implementation is better
	 * than before but still 
	 * inefficient and should not be used
	 * as is.
	 */
	Item item = getItem(position);
	View view = convertView;
        if(view == null)
	{
		LayoutInflater.from(
			getContext()).inflate(
			android.R.layout.simple_list_item_2, 
			parent, false);
	}
	((TextView)view.findViewById(android.R.id.text1))
		.setText(item.line1);
	((TextView)view.findViewById(android.R.id.text2))
		.setText(item.line2);
	return view;
}

This will optimise performance quite considerably but we’re still performing these expensive findViewById() calls each time getView() is called. Now that we are re-using our layouts, the actual TextView objects that we’re binding to are also being reused so we can cache them. We can do this by using a View Holder pattern where we create a new object containing references to our controls and attach this to the parent layout:

public static class ViewHolder 
{
	public final TextView text1;
	public final TextView text2;
		
	public ViewHolder(TextView text1, TextView text2)
	{
		this.text1 = text1;
		this.text2 = text2;
	}
}

@Override
public View getView(int position, 
	View convertView, 
	ViewGroup parent)
{
	View view = convertView;
	ViewHolder holder = null;
	if(view == null)
	{
		view = LayoutInflater.from(
			getContext()).inflate(
				android.R.layout.simple_list_item_2, 
				parent, false);
		TextView text1 = 
			(TextView)view.findViewById(android.R.id.text1);
		TextView text2 = 
			(TextView)view.findViewById(android.R.id.text2);
		view.setTag(new ViewHolder(text1, text2));
	}
	if(holder == null && view != null)
	{
		Object tag = view.getTag();
		if(tag instanceof ViewHolder)
		{
			holder = (ViewHolder)tag;
		}
	}
	Item item = getItem(position);
	if(item != null && holder != null)
	{
		holder.text1.setText(item.line1);
		holder.text2.setText(item.line2);
	}
	return view;
}

Now we only perform the layout inflation and findViewById() calls when we absolutely have to, thus keeping the code in getView() much more efficient. You should always avoid expensive calls such as filesystem and network operations in the getView() method.

In the next article we’ll have a look at how we can bind images to an ImageView within our item layout without making expensive calls in getView().

The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License

Previously we created a fragment named ListViewFragment which is currently empty, save for inflating a simple layout containing a single ListView. To populate this ListView we use an Adapter. Let’s start by doing something really simple, and very similar to how we connected up our List Navigation Spinner: Use an ArrayAdapter:

public class ListViewFragment extends ListFragment
{
	private static final String[] items = new String[] {
		"One", "Two", "Three", "Four", "Five"
	};
	
	@Override
	public View onCreateView(LayoutInflater inflater, 
		ViewGroup container, Bundle savedInstanceState)
	{
		return inflater.inflate(R.layout.listview, 
			container, false);
	}
	
	@Override
	public void onActivityCreated(Bundle savedInstanceState)
	{
		super.onActivityCreated(savedInstanceState);
		ListAdapter adapter = new ArrayAdapter<String>(
			getActivity(), 
			android.R.layout.simple_list_item_1, items);
		setListAdapter(adapter);
	}
}

We’ve used a static String array, and a different layout, but essentially this is exactly the same as we did with the Navigation Spinner. This demonstrates how the Adapter is completely decoupled from the control that it is binds to. ArrayAdapter extends BaseAdapter which implements both ListAdapter and SpinnerAdapter interfaces which means that it can be used to populate either of these controls.

This gives us the following:

So what if we want to do something slightly more complex. If we want to use android.R.layout.simple_list_item_2 instead of the previous layout, it includes two TextView objects which we need to bind to. Using the ArrayAdapter as before will not work because we now have to bind two controls, so we’ll use a SimpleAdapter instead:

public class SimpleAdapterFragment extends ListFragment
{
	private static final List<Map<String,String>> items = 
		new ArrayList<Map<String,String>>();
	private static final String[] keys = 
		{ "line1", "line2" };
	private static final int[] controlIds = 
		{ android.R.id.text1, 
		android.R.id.text2 };
	
	static
	{
		Map<String, String> map = 
			new HashMap<String, String>();
		map.put("line1", "Title One");
		map.put("line2", "Subtitle One");
		items.add(map);
		map = new HashMap<String, String>();
		map.put("line1", "Title Two");
		map.put("line2", "Subtitle Two");
		items.add(map);
		map = new HashMap<String, String>();
		map.put("line1", "Title Three");
		map.put("line2", "Subtitle Three");
		items.add(map);
		map = new HashMap<String, String>();
		map.put("line1", "Title Four");
		map.put("line2", "Subtitle Four");
		items.add(map);
		map = new HashMap<String, String>();
		map.put("line1", "Title Five");
		map.put("line2", "Subtitle Five");
		items.add(map);
	}
	
	@Override
	public View onCreateView(LayoutInflater inflater, 
		ViewGroup container, 
		Bundle savedInstanceState)
	{
		return inflater.inflate(R.layout.listview, 
			container, false);
	}
	
	@Override
	public void onActivityCreated(Bundle savedInstanceState)
	{
		super.onActivityCreated(savedInstanceState);
		ListAdapter adapter = new SimpleAdapter(
			getActivity(), 
			items, 
			android.R.layout.simple_list_item_2, 
			keys, 
			controlIds );
		setListAdapter(adapter);
	}
}

Despite it’s name, SimpleAdapter is actually a little more complex than the very basic ArrayAdapter implementation that we used before. However, it is actually a pretty simple way of binding multiple controls within each item in our ListView.

It works by storing the data that we want to bind to the control within a List of Maps. Each item in the List represents a single item in the ListView, and the Map contains the values which get assigned to the different controls. The two TextViews in the layout have ids of android.R.id.text1 and android.R.id.text2 and we need to map these values to the controls. This is done using two arrays, keys contains a list of keys used in the Map, and controlIds contains a list of control ids. SimpleAdapter will bind the controls to their respective Map values:

controlId[i].setText(map.get(keys[i]));

This gives us the following:

So we’ve seen how we can use ArrayAdapter to perform the simplest of bindings, and then SimpleAdapter to perform something very slightly more complex. Actually we can also use ArrayAdapter to perform this second kind of binding, but there are some optimisations that we need to be aware of before we do so. In the next article we’ll look at this.

The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License

To understand what Adapters do, let’s think about a simple ListView. The ListView itself is a container for a number of items, and the data for these items may come from vastly different sources. For example one ListView may contain a list of static items which never change throughout the entire lifespan of the app, whereas another ListView may contain a list of items from a SQLite database. In order to keep ListView agnostic about the source of the data for its items an abstraction layer exists, and this is the Adapter. So the role of the Adapter is to keep the control (in this case the ListView) decoupled from the data that it requires to create its child elements.

Part of the flexibility of the Adapter architecture is that polymorphism is used to provide abstraction from the data source. Up until now we’ve only referred to Adapters in that abstract form, but in practise we’ll need to use a concrete Adapter implementation depending on the nature of the data and where it is sourced from. As far as our ListView is concerned the Adapter is simply a ListAdapter, but we can actually provide any concrete Adapter implemenation that we like provided it implements the ListAdapter interface.

An example would help here. We’ll put together a simple app which will allow us to demonstrate various Adapter implementations and uses, and we’ll use List Navigation in the ActionBar to enable us to switch between different fragments. We’re going to focus purely on the Adapter here, but if you require further information on List Navigation then take a look here.

Arguably the simplest for of Adapter that we can use is one which maps to simple, static values:

@Override
protected void onCreate(Bundle savedInstanceState)
{
	super.onCreate(savedInstanceState);
	setContentView(R.layout.activity_main);
	final String[] names = getResources()
		.getStringArray(R.array.nav_names);
	final String[] classes = getResources()
		.getStringArray(R.array.nav_classes);
	getActionBar().setNavigationMode(
		ActionBar.NAVIGATION_MODE_LIST);

	ArrayAdapter<String> adapter = 
		new ArrayAdapter<String>(
			getActionBar().getThemedContext(), 
			android.R.layout.simple_spinner_item, names);
	adapter.setDropDownViewResource(
		android.R.layout.simple_spinner_dropdown_item);

	getActionBar().setListNavigationCallbacks(adapter, 
		new OnNavigationListener()
	{
		@Override
		public boolean onNavigationItemSelected(
			int itemPosition, long itemId)
		{
			FragmentTransaction tx = 
				getSupportFragmentManager()
				.beginTransaction();
			tx.replace(R.id.main, 
				Fragment.instantiate(MainActivity.this, 
					classes[itemPosition]));
			tx.commit();
			return true;
		}
	});
}

All we are doing here is loading a String array from resources, and we build an ArrayAdapter from that.

ArrayAdapter is a generic class which provides an Adapter based upon a simple array of objects. In our case we’re wrapping a String array which we obtain from resources. The constructor that we’re using takes 3 parameters: The context in which the Adapter will be used, a layout to use (in this case we’re using a standard layout from the OS), and the array of objects to use.

What goes on under the bonnet is that ArrayAdapter will create a new layout (actually this is not strictly true, but we’ll return to this in a later article) for each item in the list objects, each layout will be inflated from the resource ID that we provided. It will then look for a TextView with the id “android:id/text1″ (which exists in the layout – see here for proof) and set the text value of that text view to the value of the item in the list. In our case the items are all String values, but for other object classes ArrayAdapter will use the value returned by the toString() method.

To get this to work add a couple of String arrays to our resources (and define a class names ListViewFragment, which you can see in the source, but which we won’t discuss here):

<?xml version="1.0" encoding="utf-8"?>
<resources>

    <string-array name="nav_names">
        <item>ListView</item>
    </string-array>


    <string-array name="nav_classes">
        <item>com.stylingandroid.adapters.ListViewFragment</item>
    </string-array>

</resources>

If we run this we can see that our navigation list gets populated accordingly:

Update: As per Jake Wharton’s comments, the source code has been updated accordingly. Thanks, Jake!

In the next article we’ll take this a little further and show some alternative approaches that we can use. The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License

Creating text filled with a gradient is actually really easy, although it’s not immediately obvious how to do it in the same was as simply changing the text colour. The trick is to use a Shader, or more specifically a LinearGradient (which extends Shader), to do all of the work for us.

The constructor for LinearGradient that we’ll use takes seven arguments, although there is also a more complex form which allows for multiple colour steps to be defined. The first four of these represent the start x & y and end x & y coordinates of the line along which the gradient will be drawn (this effectively controls the direction of the gradient). The next two arguments represent the start and end colours of the gradient, and the final argument dictates how areas outside of the rectangle defined in the first four arguments will be drawn.

So how do we go about applying this? In its simplest form, we can get a reference to a standard TextView object, and set the Shader on it’s Paint object:

Shader myShader = new LinearGradient( 
    0, 0, 0, 100, 
    Color.WHITE, Color.BLACK, 
    Shader.TileMode.CLAMP );
textview.getPaint().setShader( myShader );

The TileMode that we’re using means that the colour of areas outside of the rectangle (0, 0) – (0, 100) will match the colour of the closest edge of that rectangle – i.e. extending the colour of the edges of the rectangle.

While this will certainly work, it does suffer from the small drawback that the gradient will need to be static dimensions which are completely detached from the size of the text within the TextView. So what if we want the dimensions of the gradient to actually match our text? We simply need to extend TextView.

Now the obvious thought is to extend TextView and simply override onDraw() to create a new LinearGradient which matches the dimensions of the textView control each time the control is drawn. However this is rather inefficient because it means instantiating a Shader object each time onDraw is called. Object instantiation is a rather expensive business and should be avoided at all costs in your onDraw method. If you perform object instantiation in your onDraw you’ll find that your frame rates suffer badly as a result.

So if we don’t do it in onDraw, then where should we do it? The answer is quite obvious when we think about how often we actually need to create a new LinearGradient: only when the size of the TextView changes. Therefore, the most efficient place to do this is actually in onLayout:

public class GradientTextView extends TextView
{
    public GradientTextView( Context context )
    {
        super( context, null, -1 );
    }
    public GradientTextView( Context context, 
        AttributeSet attrs )
    {
        super( context, attrs, -1 );
    }
    public GradientTextView( Context context, 
        AttributeSet attrs, int defStyle )
    {
        super( context, attrs, defStyle );
    }

    @Override
    protected void onLayout( boolean changed, 
        int left, int top, int right, int bottom )
    {
        super.onLayout( changed, left, top, right, bottom );
        if(changed)
        {
            getPaint().setShader( new LinearGradient( 
                0, 0, 0, getHeight(), 
                Color.WHITE, Color.BLACK, 
                Shader.TileMode.CLAMP ) );
        }
    }
}

So, whenever the layout changes we create and set a new LinearGradient based on the height of the TextView.

Running this gives us the following:

This same technique can be used to apply different kinds of gradients (LinearGradient, RadialGradient, SweepGradient), filling text with a bitmap (BitmapShader), or even combining shaders (ComposeShader). The more adventurous can even create their own custom shaders!

While we’ve only covered a really simple example here, we have covered a very useful technique which is pretty easy to implement, and can give us some impressive results.

The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License

Previously we got everything written with the exception of an method named updateImage(), so let’s look at that:

private void updateImage()
{
    if ( foreground != null && background != null )
    {
        float[] transform =
            { red, 0, 0, 0, 0, 
              0, green, 0, 0, 0, 
              0, 0, blue, 0, 0, 
              0, 0, 0, 1.0f, 0 };
        ColorFilter cf = 
            new ColorMatrixColorFilter( transform );
        image.setImageBitmap( 
            combineImages( background, foreground, cf ) );
    }
}

public Bitmap combineImages( Bitmap bgd, Bitmap fg, 
    ColorFilter filter )
{
    Bitmap cs;

    int width = bgd.getWidth() > fg.getWidth() 
        ? bgd.getWidth() : fg.getWidth();
    int height = bgd.getHeight() > fg.getHeight() 
        ? bgd.getHeight() : fg.getHeight();

    cs = Bitmap.createBitmap( width, height, 
        Bitmap.Config.ARGB_8888 );

    Canvas comboImage = new Canvas( cs );
    comboImage.drawBitmap( bgd, new Matrix(), null );
    paint.setColorFilter( filter );
    comboImage.drawBitmap( fg, new Matrix(), paint );

    return cs;
}

There’s not actually much code there, but it requires a little bit of explanation. If we focus on combineImages to start with, what we are doing is creating a new Bitmap which is maximum width and height of our background and foreground images. Then we’re creating a Canvas based upon that Bitmap. Then we draw our background image on the Canvas at position 0,0 and we then draw the foreground image on top of this at position 0,0 using a Paint object on which we’ve set a ColorFilter. We’ll come back to the ColorFilter in a moment but for now let’s just assume that it applies the appropriate colour as we draw the foreground image.

The Bitmap containing this combined image can then be applied to our ImageView object. So the combining of the images is pretty straightforward, but this ColorFilter requires some further explanation.

If we look at the creation of the ColorFilter it looks pretty scary. The constructor takes an array of 20 float values:

float[] transform =
    { red, 0, 0, 0, 0, 
      0, green, 0, 0, 0, 
      0, 0, blue, 0, 0, 
      0, 0, 0, 1.0f, 0 };
ColorFilter cf = new ColorMatrixColorFilter( transform );

It becomes a little less daunting if we break this down in to 4 groups of 5 floats. Each group corresponds to one of the 4 colour channels: red, green, blue, and alpha (transparency). Each of the values in each group represents part of the calculation to determine the new value for that colour channel for that pixel.

Let’s break it down a little further. If we have the following matrix:

{
a, b, c, d, e,
f, g, h, i, j,
k, l, m, n, o,
p, q, r, s, t
}

and we apply this to an arbitrary colour represented by four values to represent the red, green, blue, and alpha components:

[ R, G, B, A ]

The resulting colour will be made up of four new red, green, blue, and alpha components. Each of these is based upon a quite simple calculation. Let’s consider the new red value first, which is calculated as follows:

R' = R*a + G*b + B*c + A*d + e

So the new red value can be influenced by *any* of the existing colour channel values, which can be really useful for doing things like inverting the colours of an image. In our case, we use the following values:

a = red (the value from our red SeekBar)
b = 0
c = 0
d = 0
e = 0

So the calculation can be simplified to:

R' = R*a
G' = G*g
B' = B*m

So if we think about our mask image, all of the pixels were either white or transparent. When the matrix is applied to a white pixel (which has 0xFF red component) from the mask, the new red value will be used. The green and blue values will be calculated in the same way, and for this reason it is important that the “on” pixels in our mask are white because the output values will depend on the green and blue components of the mask pixel.

But what about those transparent pixels from the mask, how does that work? When the transform applied to the alpha channel the alpha channel part of the matrix will be used:

p = 0
q = 0
r = 0
s = 1.0
t = 0

So the calculation is:

A' = A*s

This is actually an identity transformation where the value output will match the value input. So in our case where the mask pixel is transparent, the output will be transparent (i.e. the background image will show through) and where the mask pixel is opaque the foreground image will overwrite the background image.

For the sake of clarity, our mask only contains fully opaque or fully transparent pixels. However by using varying levels of transparency we can allow parts of the background image to show through.

If we look at what this does to our app we can see that our colour is now applied to the image:

Specifying a light colour demonstrates that the border of the background image is showing through our colourised mask:

That concludes this short series of articles, but we’ve barely scratched the surface of what a colour matrix transform can do but, suffice it to say, they are extremely powerful!

The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License

When the requirement first became apparent, the graphic designer had provided an image in which the afre that needed to change colour was a simple rectangle, so my initial thought was to simply use a canvas to draw a filled rectangle on top of the bitmap. While this would have certainly worked, it would have been made more complex by having to adapt the dimensions of the rectangle based upon different screen densities, and subtle differences in the image assets provided for mdpi, hdpi, xhdpi etc. The graphic designer then started working on some alternative assets where there was a non-uniform shape which needed the colour applying, and this new non-uniform shape would be difficult to mimic accurately by drawing directly to a canvas.

The solution which sprang to mind was to use a mask in much the same way as you would in and image manipulation package whereby you create a mask corresponding to the areas that you want to apply the colour to, and apply the appropriate colour to these areas.

So, let’s begin by setting up an basic Android 4.2 project with a package name of com.stylingandroid.dynamicicon, and a main activity named DynamicIconActivity. Next we’ll create a layout in res/layout/main.xml consisting of three SeekBars corresponding to the red, green, and blue components of the colour that we wish to apply, as well as an ImageView to hold the image that will be our dynamic icon:

<GridLayout xmlns:android="http://schemas.android.com/apk/res/android"
            xmlns:tools="http://schemas.android.com/tools"
            android:id="@+id/GridLayout1"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:columnCount="2"
            android:padding="8dp"
            tools:context=".MainActivity">

    <TextView
            android:layout_gravity="right|center_vertical"
            android:text="@string/red"/>

    <SeekBar
            android:id="@+id/redSeek"
            android:layout_gravity="center_vertical|fill_horizontal"
            android:paddingTop="4dp"
            android:paddingBottom="4dp"
            android:layout_marginLeft="8dp"/>

    <TextView
            android:layout_gravity="right|center_vertical"
            android:text="@string/green"/>

    <SeekBar
            android:id="@+id/greenSeek"
            android:layout_gravity="center_vertical|fill_horizontal"
            android:paddingTop="4dp"
            android:paddingBottom="4dp"
            android:layout_marginLeft="8dp"/>

    <TextView
            android:layout_gravity="right|center_vertical"
            android:text="@string/blue"/>

    <SeekBar
            android:id="@+id/blueSeek"
            android:layout_gravity="center_vertical|fill_horizontal"
            android:paddingTop="4dp"
            android:paddingBottom="4dp"
            android:layout_marginLeft="8dp"/>

    <ImageView
            android:id="@+id/image"
            android:layout_columnSpan="2"
            android:layout_gravity="center"
            android:contentDescription="@string/drawable_holder"
            android:minWidth="40dp"/>

</GridLayout>

There are some string definitions required also in res/values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>

    <string name="app_name">Dynamic Icon</string>
    <string name="red">Red</string>
    <string name="green">Green</string>
    <string name="blue">Blue</string>
    <string name="drawable_holder">Drawable Holder</string>

</resources>

This is all pretty standard stuff, so we won’t go in to details.

The next thing that we need to look at is the image that we want to transform. As a simple example, I’ll use one of the standard menu icons within Android: ic_menu_play_clip and the mask that corresponds to the areas that we intend to fill with colour:

Although it is difficult to determine by comparing the two images, the mask corresponds to the area inside the dark border on the left hand image. This means that the dark border will always be drawn, but we’ll control the colour inside that border.

The key advantage of this approach is that the mask can be any shape that the graphic designer wants. As long as he provides an appropriate mask, we can apply it. Also this still works when we have different image drawables for different pixel densities because we can have a separate mask for each, as well.

For the sake of simplicity, I’ve only included xhdpi versions in the example project as I am only targeting my Galaxy Nexus for screen shots. However in a production app, you would provide more coverage for different screen densities.

Next we need to add some basci wiring to our Activity:

    private float red = 1.0f;
    private float green = 1.0f;
    private float blue = 1.0f;

    private ImageView image = null;
    private Bitmap background = null;
    private Bitmap foreground = null;

    private Paint paint = new Paint();

    @Override
    protected void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        background = BitmapFactory.decodeResource( getResources(), R.drawable.ic_menu_play_clip );
        foreground = BitmapFactory.decodeResource(getResources(), R.drawable.ic_menu_play_clip_mask);
        SeekBar redSeek = (SeekBar) findViewById(R.id.redSeek);
        SeekBar greenSeek = (SeekBar) findViewById(R.id.greenSeek);
        SeekBar blueSeek = (SeekBar) findViewById(R.id.blueSeek);
        image = (ImageView) findViewById(R.id.image);

        image.setBackgroundColor( Color.WHITE );
        image.setImageResource( R.drawable.ic_menu_play_clip );

        redSeek.setMax(0xFF);
        redSeek.setProgress(0xFF);
        redSeek.setOnSeekBarChangeListener(new SeekBar.OnSeekBarChangeListener()
        {

            @Override
            public void onStopTrackingTouch(SeekBar arg0)
            {
            }

            @Override
            public void onStartTrackingTouch(SeekBar arg0)
            {
            }

            @Override
            public void onProgressChanged(SeekBar arg0, int pos, boolean arg2)
            {
                red = (float) pos / (float) 0xFF;
                updateImage();
            }
        });
        .
        .
        .
        updateImage();
    }
}

For the sake of brevity I have removed pretty much duplicate code for the OnSeekBarChangeListener implementation for the green and blue SeekBars. So what we have is three SeekBars which will each update a respective colour value when the position changes.

If we run this we can see the basic test app, but nothing yet happens when we move the SeekBars:

Note how the dark border makes the icon visible when it is displayed on top of a white background.

So we have our basic test app in place, but we don’t yet have an implementation for the updateImage() method which is going to perform the transformation of our image. In the concluding article in this series we’ll look at this code.

The source code for this article is available here.

© 2013, Mark Allison. All rights reserved. This article originally appeared on Styling Android.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License