KevinDion.com

Introducing FuelTrack for Android

Kevin Dion — Sat, 26 Feb 2011 19:20:11 +0000

I just launched my first (official) app in the Android market – FuelTrack! Basically, it’s an app that tracks your fuel purchases and uses that data to give you lots of information about your fuel consumption, spending, and efficiency! There are plenty of details and more information on the apps page, so check it out!

Custom XML Attributes For Your Custom Android Widgets

Kevin Dion — Fri, 28 Jan 2011 03:16:36 +0000

In the last part of my Custom UI Tutorial, commenter Knut asked:

Is there an easy way to declare the listener in XML (similar to the android:onClick=”onMyButtonClick” in the stock controls)?

This is a great question, and in answering his question, I’ll go ahead and show you how to create other custom attributes you can put in the XML for your custom widgets. The goal will be something like this in your layouts:


	custom:myText="Something"
	custom:fancyColors="true"
	custom:onAction="myDoSomething"
	/>

We have a custom View called MyCustomWidget, and along with the standard android: attributes, we have a few of our own: myText="Something", fancyColors="true", and onAction="doSomething". Presumably, these would map to attributes we already have for our custom widget which we could set in code, but we want a shortcut to set them from XML.

Step 1: attrs.xml

The first step to enable us to use our custom xml attributes is to define them for the android system. To do this, you need to create a new xml file under res/values/ and call it attrs.xml:

The first thing you see inside the requisite resources tag is a declare-styleable tag, with name="MyCustomWidget". This lets android know what it is we want to add our attributes to (the Java class name). As far as I know you can only do this with your own widgets – I don’t think you can put, say, declare-styleable name="EditText" (not that I could think of why you would want to, but still). Next, we have out custom attributes in attr tags. The name= value is what we want to use in our xml, and the format= is the type of attribute. There are a number of different types, including string, integer, float, dimension, boolean, float, resource, enum, and color. There may be one or two more, but I’m having a hard time finding where they are defined.

Step 2: Add logic to read in XML attributes to your custom widget

Now that we have a way to pass in attributes from XML to our widget, we need to read them in. This code will go in the constructors that get passed an AttributeSet, since that is what contains the XML attributes. To read the values in the XML, you need to first create a TypedArray from the AttributeSet, then use that to read the values:

TypedArray a = context.obtainStyledAttributes(attrs,
	R.styleable.MyCustomWidget);

final int N = a.getIndexCount();
for (int i = 0; i < N; ++i)
{
	int attr = a.getIndex(i);
	switch (attr)
	{
		case R.styleable.MyCustomWidget_myText:
			String myText = a.getString(attr);
			//...do something with myText...
			break;
		case R.styleable.MyCustomWidget_fancyColors:
			boolean fancyColors = a.getBoolean(attr, false);
			//...do something with fancyColors...
			break;
		case R.styleable.MyCustomWidget_onAction:
			String onAction = a.getString(attr);
			//...we'll setup the callback in a bit...
			break;
	}
}
a.recycle();

The first call to obtainStyledAttributes passes in the AttributeSet we get in the constructor, and we also pass in R.styleable.MyCustomWidget, which tells the system to just return those attributes we defined in our attrs.xml. Next, we simply loop over each of the attributes we get, then perform a switch on the index, which is really just an int we can tie back to the name in attrs.xml. The convention for the attribute ‘name’ or ‘index’ or whatever you want to call it is just:

R.styleable.ClassName_attributeName

Thus R.styleable.MyCustomWidget_myText, R.styleable.MyCustomWidget_fancyColors, etc. An alternative way to read out the values is

TypedArray a = context.obtainStyledAttributes(attrs,
	R.styleable.MyCustomWidget);

String myText = a.getString(R.styleable.MyCustomWidget_myText);
//...do something with myText...

boolean fancyColors = a.getBoolean(R.styleable.MyCustomWidget_fancyColors, false);
//...do something with fancyColors...

But I like the switch method because then we only try to read the attributes that were present in the XML. It may not be a big deal if you only have one or two attributes, but if you have a lot, it could save processing time to only read available attributes. Plus that is how Google does it in View…so until I have a firmer grasp of best practices in android than the creators, I’ll try to use their conventions.

Also, note this doesn’t really show you how to use an XML attribute as a callback, but we’ll see that later.

Step 3: Add the attributes to the XML

The final step is to add our new custom attributes to the layout XML:

The important line is the additional xmlns in the root element, right after xmlns:android. The url you pass as the argument is "http://schemas.android.com/apk/res/your.package.namespace". Note also that you can use anything after xmlns:, in this example I used custom, but you could use app, mine, foobar, whatever (well not whatever, but you get the idea). Just make sure you use the same prefix when you use your custom attributes in your widget.

And that’s it! You now have the ability to define and use your own custom XML attributes in your layouts.

Using a custom attribute for a callback

So, the original question is how you can setup a custom XML attribute to use as a method callback, like android:onClick="myMethod" for the stock controls. As we saw above, the first step is to simply define our desired attribute to accept a string (the method name we will call), but once we’ve read it in, what do we do? At first, I had no idea – but fortunately, Android already does this, and it is open source. So, it was simply a matter of tracking down where in the source code android deals with the onClick setting, and we can use that as a guide for how to handle our custom callback.

I finally found the relevant code in android.view.View. It is in the section of the constructor where it is reading the passed in attributes, dealing specifically with R.styleable.View_onClick. As of API 9 (2.3), you can see the code here. I won’t reproduce the whole thing here, since the case logic is pretty complicated. But, I will do my best to strip down the logic to pseudocode, so I can try to explain it, and you can follow along (with the actual source is best).

case R.styleable.View_onClick:
	if (context.isRestricted()) {
		throw IllegalStateException();
	}

	final String handlerName = a.getString(attr);
	if (handlerName != null) {
		setOnClickListener(new OnClickListener() {
			private Method mHandler;

			public void onClick(View v) {
				if (mHandler == null) {
					try {
						mHandler = getContext().getClass().getMethod(handlerName, View.class);
					} catch (NoSuchMethodException e) {
						throw IllegalStateException();
					}
				}

				try {
					mHandler.invoke(getContext(), View.this);
				} catch (IllegalAccessException e) {
					throw IllegalStateException();
				} catch (InvocationTargetException e) {
					throw IllegalStateException();
				}
			}
		});
	}
	break;

The first thing the code does is to check if the context (passed into the constructor) is restricted, and if so throws an exception. Otherwise, setOnClickListener is called, with an anonymous created OnClickListener. You would obviously replace this with your own listener set method and class.

The next important bit of code is when a Method is retrieved from the Context‘s Class (usually our Activity), with the name we passed into the xml attribute. The View.class parameter passed to getMethod is passed because the onClick methos takes a View as an argument. So if your callback method had no arguments, you wouldn’t pass a second argument into getMethod.

Finally, the Method is invoked, once again passing in the View as an argument. The code above is not really valid, and it’s missing a lot of information in the exception methods you wouldn;t want to take out in your own code.

But anyways, that’s how you would use your own custom xml attribute to define a callback you can set in xml!

Android Bitmap Blending – Color Channels

Kevin Dion — Tue, 18 Jan 2011 02:22:48 +0000

I recently was doing some investigation into doing image blending in android, and came across the quite powerful built-in capabilities of Paint. I was wondering if it was possible to combine several grayscale images into a color image, using the grayscale images as the color channels. If you are familiar with Photoshop or other graphics-editing programs, you are probably familiar with the concept of color channels, and how they are combined to create a color image. For this example, we will re-create the following image from its separated color channels:

The original image. Original by Steve Berger Photography via flikr

Separating the image

To start off with, I separated the image into its three color channel images: red, green, and blue.

Red

Green

Blue

Quick primer on color channels

“But wait,” you ask, “why are these color channels in black and white?”. A good question. As you may or may not know, digital images are generally represented by and presented with three colors of light – red, green, and blue (RGB). Each pixel in the image is comprised of three values representing the intensity of the red, green, and blue ‘parts’ of the pixel. The grayscale color channel images simply separate the red, green, or blue part of each pixel’s color and present them separately. The red channel image is very light (almost white) on the parrot’s body, since it is very red, but the green and blue channel images are almost black in that area. Using the right techniques, we can re-combine these images into the original, full-color version.

The Code

In order to ‘build’ our full color image from the individual channels, we start with the following code

private Bitmap getARGBImage()
{
	BitmapFactory.Options opt = new BitmapFactory.Options();
	opt.inPreferredConfig = Config.ARGB_8888;

	Bitmap red = BitmapFactory.decodeResource(getResources(),
			R.drawable.red, opt);
	Bitmap green = BitmapFactory.decodeResource(getResources(),
			R.drawable.green, opt);
	Bitmap blue = BitmapFactory.decodeResource(getResources(),
			R.drawable.blue, opt);

	int width = red.getWidth();
	int height = red.getHeight();

	Bitmap result = Bitmap.createBitmap(width, height, Config.ARGB_8888);
	result.eraseColor(Color.BLACK);

	// We will do more here...

	return result;
}

In this initial setup code, we create a BitmapFactory.Options object, which we use to read in our channel images. We tell it that we want to ise a configuration of ARGB_8888, and that is important. Any time you want to do image blending or color manipulation, you need to make sure you are in ARGB_8888 mode, not in RGB_565 mode. Up until 2.3, android will usully default to RGB_565 mode unless you explicitly tell it to do otherwise in order to save memory. The next bit of the code just reads in our channel images and creates a new, blank (black-filled) image that we will use to build our full-color image. If you were to build and run a project where you put the returned Bitmap from this function into an ImageView (go ahead, I’ll wait…), you would just get a black image. Adding this next bit of code will change that (replace the comment above)

Paint redP = new Paint();
redP.setShader(new BitmapShader(red, TileMode.CLAMP, TileMode.CLAMP));
redP.setColorFilter(new PorterDuffColorFilter(Color.RED, Mode.MULTIPLY));
redP.setXfermode(new PorterDuffXfermode(Mode.SCREEN));

Paint greenP = new Paint();
greenP.setShader(new BitmapShader(green, TileMode.CLAMP,TileMode.CLAMP));
greenP.setColorFilter(new PorterDuffColorFilter(Color.GREEN,Mode.MULTIPLY));
greenP.setXfermode(new PorterDuffXfermode(Mode.SCREEN));

Paint blueP = new Paint();
blueP.setShader(new BitmapShader(blue, TileMode.CLAMP, TileMode.CLAMP));
blueP.setColorFilter(new PorterDuffColorFilter(Color.BLUE,Mode.MULTIPLY));
blueP.setXfermode(new PorterDuffXfermode(Mode.SCREEN));

Canvas c = new Canvas(result);
c.drawRect(0, 0, width, height, redP);
c.drawRect(0, 0, width, height, greenP);
c.drawRect(0, 0, width, height, blueP);

It looks a lot more complicated than it actually is. I’ll walk through the red paint, since the process is almost exactly the same for each channel. The first thing we do is create a Paint object to hold our blending information. Next, we set the Shader of the Paint to a BitmapShader, passing in our red channel image. Now our Paint will draw the image.

Paint redP = new Paint();
redP.setShader(new BitmapShader(red, TileMode.CLAMP, TileMode.CLAMP));

Next, we set the ColorFilter of the paint, and we use a PorterDuffColorFilter with a mode of Multiply. We also pass in Color.Red to the ColorFilter. What this bit of code accomplishes is to turn our black and white image into a black and red image. The Multiply algorithm multiplies the values of each pixel (in this case, the shader image and pure red), leaving black areas black and generally darkening other areas. Since the white areas of the channel image really mean increased levels of red in the full color image, we make that translation here.

redP.setColorFilter(new PorterDuffColorFilter(Color.RED, Mode.MULTIPLY));

Finally, we set the Xfermode of the Paint to a PorterDuffXfermode, using the Screen algorithm this time. With the Screen algorithm, black areas become transparent, and light areas are generally lightened.

redP.setXfermode(new PorterDuffXfermode(Mode.SCREEN));

There are lots of build-in capabilities you can get by using PorterDuffColorFilters and PorterDuffXfermodes, but the various modes and operations they perform is a bit more math than I want to cover here. But if you find yourself needing to do basic blending or alpha manipulation, check out the documentation.

The last two paints for green and blue are exactly the same as the red paint, except for the color used in the ColorFilter. Now, if you were to run, you would get the original, full-color image as output!

Adding Alpha

The last trick I will show you is how to take a grayscale image and use it as an alpha (transparency) channel for your image. The image we will use is below.

Alpha - grayscale and fully opaque

The white area will stay opaque and the black area will be transparent.

In order for us to use this as the alpha channel for our image, we need it to have transparency where we want it. Unfortunately, it is fully opaque right now. Fortunately, we can change that fairly quickly. Right now, we have the data we want in the alpha channel in the rgb channels. So, to move that data where we want it, all we have to do is perform a bitwise shift on the value for each pixel, moving the red value into the alpha value. We can do this because android stores ARGB values as AARRGGBB (hex), so the red channel data is offset by 8 bits from the alpha. Also, since in a (true) grayscale image, the values at any given pixel for red, green, or blue will be the same, we can ignore the green and blue channels. Also, in a grayscale image, white will have a value of 255, and black a value of zero. An alpha value of 255 means opaque and 0 means transparent. So all we have to do is pull out the int pixel values for our grayscale image, shift them left, and we now have our proper alpha channel.

Bitmap alpha = Bitmap.createBitmap(width, height, Config.ARGB_8888);
int[] alphaPix = new int[width * height];
alphaGray.getPixels(alphaPix, 0, width, 0, 0, width, height);

int count = width * height;
for (int i = 0; i < count; ++i)
{
	alphaPix[i] = alphaPix[i] << 8;
}
alpha.setPixels(alphaPix, 0, width, 0, 0, width, height);

Paint alphaP = new Paint();
alphaP.setAntiAlias(true);
alphaP.setXfermode(new PorterDuffXfermode(Mode.DST_IN));

c.drawBitmap(alpha, 0, 0, alphaP);

We use a PorterDuffXfermode of DST_IN because that takes the alpha channel from the image we give it, but the color from whatever was there before – just what we want. The final code looks like this:

private Bitmap getARGBImage()
{
	BitmapFactory.Options opt = new BitmapFactory.Options();
	opt.inPreferredConfig = Config.ARGB_8888;

	Bitmap red = BitmapFactory.decodeResource(getResources(),
			R.drawable.red, opt);
	Bitmap green = BitmapFactory.decodeResource(getResources(),
			R.drawable.green, opt);
	Bitmap blue = BitmapFactory.decodeResource(getResources(),
			R.drawable.blue, opt);
	Bitmap alphaGray = BitmapFactory.decodeResource(getResources(),
			R.drawable.alpha, opt);

	int width = red.getWidth();
	int height = red.getHeight();

	Bitmap result = Bitmap.createBitmap(width, height, Config.ARGB_8888);
	result.eraseColor(Color.BLACK);

	Paint redP = new Paint();
	redP.setShader(new BitmapShader(red, TileMode.CLAMP, TileMode.CLAMP));
	redP.setColorFilter(new PorterDuffColorFilter(Color.RED, Mode.MULTIPLY));
	redP.setXfermode(new PorterDuffXfermode(Mode.SCREEN));

	Paint greenP = new Paint();
	greenP.setShader(new BitmapShader(green, TileMode.CLAMP,TileMode.CLAMP));
	greenP.setColorFilter(new PorterDuffColorFilter(Color.GREEN,Mode.MULTIPLY));
	greenP.setXfermode(new PorterDuffXfermode(Mode.SCREEN));

	Paint blueP = new Paint();
	blueP.setShader(new BitmapShader(blue, TileMode.CLAMP, TileMode.CLAMP));
	blueP.setColorFilter(new PorterDuffColorFilter(Color.BLUE,Mode.MULTIPLY));
	blueP.setXfermode(new PorterDuffXfermode(Mode.SCREEN));

	Canvas c = new Canvas(result);
	c.drawRect(0, 0, width, height, redP);
	c.drawRect(0, 0, width, height, greenP);
	c.drawRect(0, 0, width, height, blueP);

	Bitmap alpha = Bitmap.createBitmap(width, height, Config.ARGB_8888);
	int[] alphaPix = new int[width * height];
	alphaGray.getPixels(alphaPix, 0, width, 0, 0, width, height);

	int count = width * height;
	for (int i = 0; i < count; ++i)
	{
		alphaPix[i] = alphaPix[i] << 8;
	}
	alpha.setPixels(alphaPix, 0, width, 0, 0, width, height);

	Paint alphaP = new Paint();
	alphaP.setAntiAlias(true);
	alphaP.setXfermode(new PorterDuffXfermode(Mode.DST_IN));

	c.drawBitmap(alpha, 0, 0, alphaP);

	red.recycle();
	green.recycle();
	blue.recycle();
	alphaGray.recycle();
	alpha.recycle();

	return result;
}

Now just run, and marvel at your sweet new macaw with a palm frond mohawk.

The final result

Android UI Tutorial – Odometer Part III: Building the Odometer

Kevin Dion — Thu, 30 Dec 2010 00:36:57 +0000

[This is the third part of the tutortial so far. If you haven't already, check out Part 1 and Part 2 to get up to speed on where we are. You can also grab the source code we ended up with at the end of Part 2 to follow along.]

Odometer Tutorial

Part I: First Steps
Part II: Touch Input and Scrolling Numbers
Part III: Compound Widgets and Fixing Bugs « You are here

Creating the Odometer Widget

Now that we have our single digit spinner, we can create the actual odometer. Create a new class in the project, and name it Odometer. Instead of View, subclass from TableLayout. We will use the existing capabilities of TableLayout to automatically divide our widget into equal pieces for each spinner.

Odometer class creation

To define how our widget will display, we will use an xml layout file. Use the Android XML file wizard to add a new layout file as shown below.

Odometer layout file creation

Name the file widget_odometer.xml, and make sure to change the root element to TableLayout. Since this is going to be the catch-all layout for the widget, don’t select any qualifiers from the list. Once the file is created, open up the xml view (if it opens in the graphical view), and add the following to the element:

We now have the definition for a single row of 6 OdometerSpinners. The android:stretchColumns="*" tells the layout to size each of the columns (our spinners) the same. This saves us from needing to do that ourselves. We also set ids for each spinner, with names that help us keep track of which spinner is which digit (1s place, 10s place, etc).

Next, we need to tell our Odometer to use this layout file to draw itself. In the Odometer class, add an initialize() method like we did for OdometerSpinner where we can do our initialization independently regardless of which constructor is called. Add the following code:

private static final int NUM_DIGITS = 6;
private OdometerSpinner[] mDigitSpinners;
//...
private void initialize()
{
	mDigitSpinners = new OdometerSpinner[NUM_DIGITS];
	
	// Inflate the view from the layout resource.
	String infService = Context.LAYOUT_INFLATER_SERVICE;
	LayoutInflater li;
	li = (LayoutInflater)getContext().getSystemService(infService);
	li.inflate(R.layout.widget_odometer, this, true);
	
	mDigitSpinners[0] = (OdometerSpinner) 
		findViewById(R.id.widget_odometer_spinner_1);
	mDigitSpinners[1] = (OdometerSpinner) 
		findViewById(R.id.widget_odometer_spinner_10);
	mDigitSpinners[2] = (OdometerSpinner) 
		findViewById(R.id.widget_odometer_spinner_100);
	mDigitSpinners[3] = (OdometerSpinner) 
		findViewById(R.id.widget_odometer_spinner_1k);
	mDigitSpinners[4] = (OdometerSpinner) 
		findViewById(R.id.widget_odometer_spinner_10k);
	mDigitSpinners[5] = (OdometerSpinner) 
		findViewById(R.id.widget_odometer_spinner_100k);
	
}

The first thing we do is to use a LayoutInflater to ‘inflate’ the Odometer into the xml file we created. If you want to learn more about what exactly LayoutInflater does or other options you can use with it, check out LayoutInflater at Android Developers. The other thing we do in initialize() is to get references to each of the spinners and store them in an array so we can use them later.

Next, we need to change the main Activity layout so that instead of the single OdometerSpinner, we see our Odometer. In main.xml, remove the TextView with the ‘hello, world’ message and change OdometerSpinner to Odometer. The layout should now look like this:

Now, run the app and see our great new Odometer!

Or maybe not – things don’t look too good.

Our Odometer needs work

It looks a little better if you rotate the screen (Ctrl+F12 in the emulator), but the numbers in the spinners are way too big. You can still drag numbers up and down to change them, however – so at least that is good.

The numbers are more visible in landscape

Measurement and Sizing

In order for our view to draw and size properly, we need more robust logic than we have currently. At the moment, we are filling up the screen with the odometer (set with aandroid:layout_height="fill_parent" in the element in main.xml), but we probably don’t really want a tall and skinny odometer. What we really want is for the widest widget possible, and then let the Odometer determine how tall it should be based on that. Change main.xml to this:

Now if you ran the app, you wouldn’t see anything because android is relying on our code to know how tall to make the widget, but since we haven’t done anything with that it has a height of 0. So let’s fix that.

OdometerSpinner

In OdometerSpinner, we are going to add some logic to onMeasure() so our spinners get sized correctly.

public static final float IDEAL_ASPECT_RATIO = 1.5f;
//...
protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec)
{
	super.onMeasure(widthMeasureSpec, heightMeasureSpec);
	
	// get width and height size and mode
	int wSpec = MeasureSpec.getSize(widthMeasureSpec);
	int wMode = MeasureSpec.getMode(widthMeasureSpec);
	
	int hSpec = MeasureSpec.getSize(heightMeasureSpec);
	int hMode = MeasureSpec.getMode(heightMeasureSpec);
	
	int width = wSpec;
	int height = hSpec;
	
	// ideal height for the number display
	int idealHeight = (int) (wSpec * IDEAL_ASPECT_RATIO);
	
	if(idealHeight < hSpec)
	{
		height = idealHeight;
	}
	
	setMeasuredDimension(width, height);
}

The two arguments passed to onMeasure are encoded ints that contain both size and ‘mode’ information. To get the useful values, we need to call MeasureSpec.getSize() and MeasureSpec.getMode() on the passed width and height ints. The mode for height and width will be one of UNSPECIFIED, AT_LEAST, or EXACTLY, which lets us know how our parent wants us to size ourselves – at most n pixels, exactly n pixels, or unspecified (where the view can be any size it wants).

In this simple example, we don’t worry about the mode – we know that in our app we are constrained by width and need to set our height – but in an actual production widget you would want to account for the possible combinations of modes. For instance, how should our spinner calculate its size if it has to be short but can be as wide as it wants? But we won’t worry about that, because by setting all of our widgets to layout_width="fill_parent" in the layouts we get the end result we want (but in a somewhat ‘hacked’ manner).

In our new onMeasure(), we use a pre-defined aspect ratio we want to have for our spinner to calculate what our ideal height would be based on the width we are passed. Then, if that ideal height is less than the height we are passed, we use that one instead. This will fix the super tall numbers problem. Feel free to experiment with different values for the the aspect ratio, but I have found 1.5-1.6 to be pretty good for the default font android uses.

Odometer

We also need to add an implementation for onMeasure() to Odometer, so that it knows how tall to make itself.

protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec)
{
	super.onMeasure(widthMeasureSpec, heightMeasureSpec);
	
	// get width and height size and mode
	int wSpec = MeasureSpec.getSize(widthMeasureSpec);
	int wMode = MeasureSpec.getMode(widthMeasureSpec);
	
	int hSpec = MeasureSpec.getSize(heightMeasureSpec);
	int hMode = MeasureSpec.getMode(heightMeasureSpec);
	
	// calculate max height from width
	float contentHeight = ((float)wSpec / NUM_DIGITS) 
			* OdometerSpinner.IDEAL_ASPECT_RATIO;
	
	int maxHeight = (int)Math.ceil(contentHeight);
	
	int width = wSpec;
	int height = hSpec;
	
	if(maxHeight < hSpec)
	{
		height = maxHeight;
	}
	
	setMeasuredDimension(width, height);
}

Nothing too complex here, we do the same calculation based on the aspect ratio, only we use 1/6th the width passed to us, since that is the value the spinners will be getting for their width.

Now, if we run our app, we get a much better looking odometer.

The Odometer now sizes correctly for portrait view

Landscape gives us a larger widget

Much better! However, as you rotated the screen from portrait to landscape and moved the digits around, you probably noticed that every time you rotate the screen, all of the spinners reset to zero! This is due to the fact that every time the configuration of the device changes (such as going from portrait to landscape), the Activity is actually destroyed and restarted.

From the Activity documentation:

If the configuration of the device (as defined by the Resources.Configuration class) changes, then anything displaying a user interface will need to update to match that configuration. Because Activity is the primary mechanism for interacting with the user, it includes special support for handling configuration changes.

Unless you specify otherwise, a configuration change (such as a change in screen orientation, language, input devices, etc) will cause your current activity to be destroyed, going through the normal activity lifecycle process of onPause(), onStop(), and onDestroy() as appropriate.

Every time you rotate the screen, the app is killed and restarted – so all of the digits go back to zero (the initial default value).

Handling Activity Lifecycle Events

In order to maintain the value of the odometer when the screen orientation is changed (or when the user leaves the app and comes back), we will use some of the provided methods of Activity to store the value of the odometer before it is destroyed by the configuration change process, and then reading that value back and setting the odometer value accordingly. Of course, in order to do this we need to have a way to read and set the value of our Odometer.

Getting and Setting the value of OdometerSpinner

OdometerSpinner already has a method to set the digit in setCurrentDigit(int), so we just need to add a way to read the value to store later. So let’s go ahead and add one:

public int getCurrentDigit()
{
	return mCurrentDigit;
}

Nice and simple.

Get and Set in Odometer

Now we need to add code to get and set the value of the odometer.[Thanks to commenter Ted Hopp for giving me a better way to get and set the value of the individual spinners!]

private int mCurrentValue;
//...
public int getValue()
{
	int value = 0;
		
	for(int i = NUM_DIGITS - 1; i >= 0; --i)
	{
		value = 10 * value + mDigitSpinners[i].getCurrentDigit();
	}
	
	mCurrentValue = value;
	
	return mCurrentValue;
}

public void setValue(int value)
{
	for(int i = 0; i < NUM_DIGITS; ++i)
	{
		mDigitSpinners[i].setCurrentDigit(value % 10);
		value /= 10;
	}
}

In the get method, we read the value of each spinner and multiply it by the proper factor based on its position, adding the results to get the value represented by the whole. It is important that in initialize() you stored the spinners in increasing place order, so that the digit in the ones place it at index zero in the array – otherwise you will get incorrect values from this get call.

The set method is mostly the inverse of the get method, taking in the desired value and parsing out each digit. I didn’t put in a range check because in this case the only way to set the value is through the odometer itself (so no out of range data), but in a more widely used widget you would probably want to put some sort of check here.

Saving and Reading State

Now that we have a way to get and set the odometer value, let’s add the code in the main activity to handle the lifecycle. Add a class member for the Odometer, and add an override of onSaveInstanceState(Bundle), which is where we will add our code to store the value of the odometer. We will read the saved value in onCreate().

private static final String KEY_VALUE = "com.kdion.tutorial.odometer.OdometerValue";

private Odometer mOdometer;

private int mOdometerValue;
//...
public void onCreate(Bundle savedInstanceState)
{
	super.onCreate(savedInstanceState);
	setContentView(R.layout.main);
	
	mOdometer = (Odometer) findViewById(R.id.odometer);
	
	if(savedInstanceState != null)
	{
		mOdometerValue = savedInstanceState.getInt(KEY_VALUE);
		mOdometer.setValue(mOdometerValue);
	}
}

protected void onSaveInstanceState(Bundle outState)
{
	super.onSaveInstanceState(outState);
	
	mOdometerValue = mOdometer.getValue();
	outState.putInt(KEY_VALUE, mOdometerValue);
}

We create a unique string key that we will use to store our data – in this case I used “com.kdion.tutorial.odometer.OdometerValue“, following the Java namespace format – but you could use any string you wish. In onSaveInstanceState(), we read the odometer value, then put that value in the Bundle we are passed. From the Android Docs for saveInstanceState(Bundle):

Called to retrieve per-instance state from an activity before being killed so that the state can be restored in onCreate(Bundle) or onRestoreInstanceState(Bundle) (the Bundle populated by this method will be passed to both)

So the Bundle we saved our odometer value to in onSaveInstanceState() is passed to the onCreate() method when it is being used to continue execution of our app (like when the screen orientation changes). So we read the vale from the Bundle, and use it to set the odometer’s value. If there is not a value stored in the bundle (such as if this were a clean run of the app where there was no previous state), we don’t do anything.

There are a lot of different methods that you can (and should) use to save and restore your app’s state that deal with the Activity lifecycle. They all have slightly different uses and times they are better to be used over others. If you aren’t really familiar with the Activity lifecycle, it is a really good idea to read up on it in the Android Docs. There is a lot of great information there.

Now, run the app and see how you can rotate the screen and the numbers will persist!

Adding Change Listeners

One thing that our current code limits us in is that we don’t know when the value of the odometer changes. If we were using this as part of a group of widgets that depended on having an up-to-date value from the odometer, it would fail with our current widget. To demonstrate this (before we fix it), add a TextView to the main activity layout (main.xml – I added it after/below the odometer, but you could do it above if you really wanted to):

In addition, change the code in the main activity to show the odometer value in the TextView:

private TextView mValueDisplay;
//...
public void onCreate(Bundle savedInstanceState)
{
	super.onCreate(savedInstanceState);
	setContentView(R.layout.main);
	
	mOdometer = (Odometer) findViewById(R.id.odometer);
	mValueDisplay = (TextView) findViewById(R.id.main_valuedisplay);
	
	if(savedInstanceState != null)
	{
		mOdometerValue = savedInstanceState.getInt(KEY_VALUE);
		mOdometer.setValue(mOdometerValue);
	}
	updateOdometerValue();
}

private void updateOdometerValue()
{
	mOdometerValue = mOdometer.getValue();
	
	String text = String.format("%06d", mOdometerValue);
	mValueDisplay.setText(text);
}

We format the value of the odometer (the “%06d“) to be zero-padded so that it will look more like what the odometer shows. You can also add a call to updateOdometerValue() in onSaveInstanceState() if you wish, but since that code isn’t called until our activity is getting destroyed we won’t see the change anyways. Now run the app, and see that as you change the numbers of the odometer, the text view doesn’t update its display until you rotate the screen. This happens because we only read the odometer value in onSaveInstanceState() – so our activity is only updated when we destroy it!

As you change the Odometer, the value displayed below does not change

In order for our activity to keep the TextView updated with the latest odometer value, it needs to know when that value has changed. The value of the odometer changes when any of its digits changes, so we need to know when any of the OdometerSpinners is changed. Add the following code to OdometerSpinner:

public class OdometerSpinner extends View
{
	private OnDigitChangeListener mDigitChangeListener;
	//...
	public void setCurrentDigit(int digit)
	{
		int newVal = digit;
		
		if(newVal < 0)
			newVal = 0;
		if(newVal > 9)
			newVal = 9;
		
		int old = mCurrentDigit;
		mCurrentDigit = newVal;
		
		if(mCurrentDigit != old && mDigitChangeListener != null)
			mDigitChangeListener.onDigitChange(this, mCurrentDigit);
		
		//...
	}
	//...
	public void setOnDigitChangeListener(OnDigitChangeListener listener)
	{
		mDigitChangeListener = listener;
	}
	//...
	public interface OnDigitChangeListener
	{
		abstract void onDigitChange(OdometerSpinner sender, int newDigit);
	}
}

First (last bit of code), we add a public interface defining how our Listener will be called – note that it is inside the OdometerSpinner class! We also add a member variable to store a listener (dealing with multiple/chained listeners is beyond the scope of this tutorial), and a method to set the listener. FInally, within the setCurrentDigit() method, we check that the current digit has changed, and if so call the listener method.

Next, we need to add essentially the same things to Odometer, but also listen for the spinner changes:

public class Odometer extends TableLayout
{
	private OnValueChangeListener mValueChangeListener;
	//...
	private void initialize()
	{
		//...
		
		for(OdometerSpinner s : mDigitSpinners)
		{
			s.setOnDigitChangeListener(new OdometerSpinner.OnDigitChangeListener()
			{
				public void onDigitChange(OdometerSpinner s, int newDigit)
				{
					updateValue();
				}
			});
		}
	}
	
	private void updateValue()
	{
		int value = 0;
		
		for(int i = NUM_DIGITS - 1; i >= 0; --i)
		{
			value = 10 * value + mDigitSpinners[i].getCurrentDigit();
		}
		
		int old = mCurrentValue;
		mCurrentValue = value;
		
		if(old != mCurrentValue && mValueChangeListener != null)
			mValueChangeListener.onValueChange(this, mCurrentValue);
	}
	
	public void setValue(int value)
	{
		for(int i = 0; i < NUM_DIGITS; ++i)
		{
			mDigitSpinners[i].setCurrentDigit(value % 10);
			value /= 10;
		}
	}
		
	public int getValue()
	{	
		return mCurrentValue;
	}
	
	public void setOnValueChangeListener(OnValueChangeListener listener)
	{
		mValueChangeListener = listener;
	}
	//...
	public interface OnValueChangeListener
	{
		abstract void onValueChange(Odometer sender, int newValue);
	}
}

[Commenter Ted Hopp pointed out that we could avoid allocating a new listener for each separate spinner by having Odometer implement OnDigitChangeListener. Another way would be to create a single member for the Listener and pass that one instance to each spinner. I find myself leaning toward that since it doesn't then expose the DigitChangeListener interface to the outside world.]

Again, we defined a public interface for other classes to use to listen for our value changes, as well as a method to set our listener. We also set the listener for each of the spinners in the odometer, and update our value whenever one does. Note that the code to read the value from the spinners was moved from the getValue() method to the new updateValue() method. Finally, if the value of the odometer is changed (either through updating based on a spinner change or from setValue), we call our listener.

Finally, we need to setup the change listener in our main activity to listen for changes to the odometer value:

public void onCreate(Bundle savedInstanceState)
{
	super.onCreate(savedInstanceState);
	setContentView(R.layout.main);
	
	mOdometer = (Odometer) findViewById(R.id.odometer);
	mValueDisplay = (TextView) findViewById(R.id.main_valuedisplay);
	
	mOdometer.setOnValueChangeListener(new Odometer.OnValueChangeListener()
	{
		@Override
		public void onValueChange(Odometer sender, int newValue)
		{
			updateOdometerValue();
		}
	});
	
	if(savedInstanceState != null)
	{
		mOdometerValue = savedInstanceState.getInt(KEY_VALUE);
		mOdometer.setValue(mOdometerValue);
	}
	updateOdometerValue();
}

We simply call our updateOdometerValue() method, which reads the current odometer value and set the TextView. Now, when you run, you should see that as you change the odometer, the value displayed below also changes.

As you change the value on the Odometer, the value below updates correctly

One final bug we will deal with in this tutorial is best seen in portrait mode. If you drag a number too far without lifting your finger, you will quickly pass the single additional digit we draw either above or below in the spinner. Because of this, you won’t see any more digits in the spinner until you lift your finger and drag again.

If you drag too far, there aren't any more numbers

To fix this, we need to make some changes to OdometerSpinner. Rather than drawing even more numbers (and thus tracking where to draw them, etc), we will simply check during the drag event if the number has been dragged enough to count as a digit change. We will use the height of the spinner as the threshold, since that is how far apart the digits are spaced. When a number is dragged that far, we will change the value of the spinner, which will reset the above and below numbers, allowing for additional dragging. The change we need to make looks like this:

public boolean onTouchEvent(MotionEvent event)
{
	//... ACTION_DOWN ...
	else if(action == MotionEvent.ACTION_MOVE)
	{
		float currentY = event.getY();
		
		float delta = mTouchLastY - currentY;
		mTouchLastY = currentY;
		
		mDigitY -= delta;
		mDigitAboveY -= delta;
		mDigitBelowY -= delta;
		
		// calculate the overall delta (beginning to now)
		float totalDelta = mTouchStartY - currentY;
		
		// If we have scrolled an entire number, change numbers while 
		// keeping the scroll
		if(Math.abs(totalDelta) > mHeight )
		{
			// need to either increase or decrease value
			float postDelta = Math.abs(totalDelta) - mHeight;
			
			if(totalDelta > 0)
			{
				// go DOWN a number
				setCurrentDigit(mDigitBelow);
				mTouchStartY -= mHeight;
				
				mDigitY -= postDelta;
				mDigitBelowY -= postDelta;
				mDigitAboveY -= postDelta;
			}
			else
			{
				// go UP a number
				setCurrentDigit(mDigitAbove);
				mTouchStartY += mHeight;
				
				mDigitY += postDelta;
				mDigitBelowY += postDelta;
				mDigitAboveY += postDelta;
			}
		}
		
		invalidate();
		
		return true;
	}
	//... ACTION_UP ...
}

The first part of the code is the same as before, but now, after we have moved the digits, we check the total drag distance. If we have dragged the equivalent of one digit (the height of the spinner), we can go ahead and change the number appropriately. Depending on the sign of the total delta, we either increment or decrement the number. When we call setCurrentDigit(), it centers each digit. Since we wait until the next digit would be centered anyways to change, that is what we want.

However, it is possible that our code won’t get called exactly when the total scroll delta is equal to the height. In that case, we need to then offset each digit by the difference between the height and how far we actually scrolled so there isn’t any stutter during the drag. Note that we also offset mTouchStartY by the height so that the code in ACTION_UP behaves correctly once a digit has been passed. If we didn’t ‘reset’ the start y-value, whenever the user dragged past a number or two and released, the digit would increment/decrement even if there was a digit perfectly centered.

Now, you can run the app and see that as you continue to scroll, not only do numbers continue to appear, but as you pass digits the value is also continually updated!

That concludes this tutorial – there are a number of ways this widget can be improved, both in appearance and in functionality. You could add a way for the numbers to automatically animate a scroll to a value when set programmatically, or make it look more realistic with better background graphics and shadows.

Source

Grab the source for the completed Part 3 here. (ZIP)

Odometer Tutorial

Part I: First Steps
Part II: Touch Input and Scrolling Numbers
Part III: Compound Widgets and Fixing Bugs « You are here

Android UI Tutorial – Odometer Part II: Completing the Spinner

Kevin Dion — Mon, 27 Dec 2010 16:53:16 +0000

[This is the second part in a three-part tutorial for creating an odometer widget in android. If you haven't already, check out Part 1 to get up to speed on where we are. You can also grab the source code we ended up with at the end of Part 1 to follow along.]

Odometer Tutorial

Part I: First Steps
Part II: Touch Input and Scrolling Numbers « You are here
Part III: Compound Widgets and Fixing Bugs

Adding Interactivity

Now that we have the basic display for our widget down, it is time to make it interactive by working with touch events. But before we do that, there is a small change we need to make that will make moving forward easier.

A Numbers Game

Up to this point, we have been treating the digit we are displaying as just a string. Since we were only drawing that one digit, and it wasn’t changing, it wasn’t a big deal – but now that we are going to be changing our numbers, we should change how we deal with the digit internally. We will still store the string version of the current digit to keep from having to convert it every time we draw, but now we will add an int to store the numeric value as well. We will also add a method, setCurrentDigit(int), that will take in an int value and set the int and string values as appropriate.

private int mCurrentDigit;
//...
public void setCurrentDigit(int digit)
{
	/*
	 *  Basic range limiting - in a production widget,
	 *  you might want to throw an exception if the number passed
	 *  if less than 0 or greater than 9
	 */
	int newVal = digit;

	if(newVal < 0)
		newVal = 0;
	if(newVal > 9)
		newVal = 9;

	mCurrentDigit = newVal;
	mDigitString = String.valueOf(mCurrentDigit);

	setDigitYValues();
	invalidate();
}

The new function setCurrentDigit() does some basic range checking so that we only deal with single-digit, non-negative numbers, but in a production environment, you would want to add some additional handling of these conditions so that you aren’t producing unexpected behavior (hey! i set the spinner to show -42! What’s up?). We set the digit value and the string representation, and then we call some new functions, setDigitYValues() and invalidate(). We will implement setDigitYValues() in a bit, but invalidate() is a method provided us by View, and it tells the system to redraw our widget. Since we changed the number we want to draw, we should probably make sure it gets shown, right?

private void setDigitYValues()
{
	mDigitY = findCenterY(mCurrentDigit);
}

private float findCenterY(int digit)
{
	String text = String.valueOf(digit);
	Rect bounds = new Rect();
	mDigitPaint.getTextBounds(text, 0, text.length(), bounds);

	int textHeight = Math.abs(bounds.height());

	float result = mHeight - ((mHeight - textHeight) / 2);

	return result;
}

You will also need to add the two methods above, which sets the correct Y value for the digit we want to draw. The logic now in findCenterY() was previously in onSizeChanged(), so you will also need to remove that, and just replace it with a call to setDigitYValues(). The last thing to do is to get rid of the old digit initialization in initialize(), and change it to call setCurrentDigit(). It should look something like this:

private void initialize()
{
	//... other code here ...
	setCurrentDigit(4);
}
protected void onSizeChanged(int w, int h, int oldw, int oldh)
{
	//... other code here ...
	mDigitX = mWidth / 2;

	setDigitYValues();
}

Now, if we run our app, we can see the new number displayed – and see that it does still work!

New Dig(it)s

Touch Me, Feel Me

Now that we have our handling for the current digit better setup, we can start changing it. Rather than trying to get perfect touch interactivity right off the bat, we will take small steps that gradually get us closer to having that scrolling interaction we are looking for. The first thing we will do is allow the user to ‘tap’ the spinner to increment the digit that is displayed.

To handle user touch input, we need to override onTouchEvent(). This method is called when there is a touch motion event within our View, such as the user touching the screen, moving their finger around, or lifting up the finger. There are many different ‘Actions’ that we can handle, and we determine which Action the passed in MotionEvent encompasses by calling MotionEvent.getAction(). onTouchEvent() also returns a bool, which should be true if the event passed was handled by our code, or false if not.

The two actions we will handle right now will be ACTION_DOWN and ACTION_UP, which correspond to the user putting a finger down on the screen over our View, and lifting that finger up, respectively. We don’t want to do anything when the user touches their finger down, so we just return true. When the user lifts their finger, however, we want to increment the number we display (wrapping after 9), so we change the current digit when that event occurs.

public boolean onTouchEvent(MotionEvent event)
{
	// Pull out the Action value from the event for processing
	int action = event.getAction();

	if(action == MotionEvent.ACTION_DOWN)
	{
		return true;
	}
	else if(action == MotionEvent.ACTION_UP)
	{
		int newValue = mCurrentDigit + 1;

		if(newValue > 9)
			newValue = 0;

		setCurrentDigit(newValue);

		return true;
	}
	return false;
}

If we run our app now, you can tap the spinner to increment the number (click in the emulator).

Touch to increment

Such a Drag

Now that we have some basic touch interaction, let’s add the next layer – dragging the digit. Now, if you drag your finger around the screen, the number doesn’t move, it just changes when you lift your finger. We want the user to drag the number up and down to change it, so we need to add that. To begin with, we will add some handling of the ACTION_MOVE action in onTouchEvent(), so that we can move the digit up or down.

We first add two new variables to OdometerSpinner, to store the Y value of where the user started the drag, and another to store the last y-value of the drag. Then, we set those in ACTION_DOWN, and handle changing the digit y-value based on where the user’s finger is while they drag it around.

public boolean onTouchEvent(MotionEvent event)
{
	// Pull out the Action value from the event for processing
	int action = event.getAction();

	if(action == MotionEvent.ACTION_DOWN)
	{
		mTouchStartY = event.getY();
		mTouchLastY = mTouchStartY;

		return true;
	}
	else if(action == MotionEvent.ACTION_MOVE)
	{
		float currentY = event.getY();

		float delta = mTouchLastY - currentY;
		mTouchLastY = currentY;

		mDigitY -= delta;

		invalidate();

		return true;
	}
	//... ACTION_UP...
}

We also call invalidate() during the drag to redraw the View with the new location of the digit. If you run the app at this point, you will see that you can drag the digit up and down, and it moves around like you would expect. When you lift your finger, the number also increments.

Dragging the digit

There are still improvements to be made, however. Regardless of which direction you drag the number, it only increases in value – and it also increases even if you tap without moving the number very much.

In order to tell if we should increase, decrease, or not change the digit we display, we need to add some conditional logic to the ACTION_UP handler. When the user lifts their finger, we compare the current y-value of their finger to the initial position (which we saved in ACTION_DOWN), and if it is above where they started, they have dragged the number up, so we should decrement the digit. If the y-value is below the starting point, we increment. We also check that the change in y (how far the user dragged) is above a certain threshold (in this case, one third the height of the spinner), or else we don’t change the value at all. Remember, because of how the graphics coordinate system is set up, higher y-values go down, so a negative delta means the user dragged down, so we increase the number (confused yet? It all makes sense, I promise!).

public boolean onTouchEvent(MotionEvent event)
{
	// ... ACTION_DOWN and ACTION_MOVE ...
	else if(action == MotionEvent.ACTION_UP)
	{
		float currentY = event.getY();

		// delta: negative means a down 'scroll'
		float deltaY = mTouchStartY - currentY;

		int newValue = mCurrentDigit;

		if(Math.abs(deltaY) > (mHeight / 3) )
		{
			// higher numbers are 'above' the current, so a scroll down
			// _increases_ the value
			if(deltaY < 0)
			{
				++newValue;
				if(newValue > 9)
					newValue = 0;
			}
			else
			{
				--newValue;
				if(newValue < 0)
					newValue = 9;
			}
		}

		setCurrentDigit(newValue);

		return true;
	}
	return false;
}

Also note that we call setCurrentDigit() even if we didn’t change the value of the digit we are displaying, because it resets the position of the digit to the center of the screen, which we want to happen regardless of whether the number we are displaying changed or not. Run the app and see how much more intuitive changing the number is now. Simply drag up to decrease, and drag down to increase.

Drawing More Numbers

In a real Odometer, as a number is changing, you can see both the current value and the next, since the numbers are usually fairly close together vertically. Right now the user can’t see what the next number is until they lift their finger, so until they change the number a few times, they don’t know what result their action will have. What we need to do is display the numbers above and below the current number as the user drags it up or down.

In OdometerSpinner, add new variables for storing the two new digits – above and below- remembering that we track their integer value, string representation, and y-position. Next, in setCurrentDigit(), set the values of the above and below digits based on the current digit.

private int mDigitAbove;
private int mDigitBelow;
private float mDigitAboveY;
private float mDigitBelowY;
private String mDigitAboveString;
private String mDigitBelowString;
//...
public void setCurrentDigit(int digit)
{
	// Basic range limiting
	int newVal = digit;
	
	if(newVal < 0)
		newVal = 0;
	if(newVal > 9)
		newVal = 9;
	
	mCurrentDigit = newVal;
	
	// Digit above - greater
	mDigitAbove = mCurrentDigit + 1;
	
	if(mDigitAbove > 9)
		mDigitAbove = 0;
	
	// digit below - lower
	mDigitBelow = mCurrentDigit - 1;
	
	if(mDigitBelow < 0)
		mDigitBelow = 9;

	mDigitString = String.valueOf(mCurrentDigit);
	mDigitAboveString = String.valueOf(mDigitAbove);
	mDigitBelowString = String.valueOf(mDigitBelow);
	
	setDigitYValues();
	invalidate();
}

We also need to calculate the starting y-values for our above and below digits, so add them to setDigitYValues(). We also need to draw our new digits, so add them to onDraw().

private void setDigitYValues()
{
	mDigitY = findCenterY(mCurrentDigit);
	mDigitAboveY = findCenterY(mDigitAbove) - mHeight;
	mDigitBelowY = mHeight + findCenterY(mDigitBelow);
}
//...
protected void onDraw(Canvas canvas)
{
	super.onDraw(canvas);
	
	mBGGrad.draw(canvas);
	
	canvas.drawText(mDigitString, mDigitX, mDigitY, mDigitPaint);

	canvas.drawText(mDigitAboveString, mDigitX, mDigitAboveY, mDigitPaint);
	canvas.drawText(mDigitBelowString, mDigitX, mDigitBelowY, mDigitPaint);
}

Finally, in the ACTION_MOVE handling, change the y-values for the above and below digits along with the current digit so they scroll into view as the current digit leaves. We can also now change the code in ACTION_UP to change to the above or below digit instead of doing the calculations there.

public boolean onTouchEvent(MotionEvent event)
{
	// Pull out the Action value from the event for processing
	int action = event.getAction();
	
	if(action == MotionEvent.ACTION_DOWN)
	{
		mTouchStartY = event.getY();
		mTouchLastY = mTouchStartY;
		
		return true;
	}
	else if(action == MotionEvent.ACTION_MOVE)
	{
		float currentY = event.getY();
		
		float delta = mTouchLastY - currentY;
		mTouchLastY = currentY;
		
		mDigitY -= delta;
		mDigitAboveY -= delta;
		mDigitBelowY -= delta;
		
		invalidate();
		
		return true;
	}
	else if(action == MotionEvent.ACTION_UP)
	{
		float currentY = event.getY();
		
		// delta: negative means a down 'scroll'
		float deltaY = mTouchStartY - currentY;
		
		int newValue = mCurrentDigit;
		
		if(Math.abs(deltaY) > (mHeight / 3) )
		{
			// higher numbers are 'above' the current, so a scroll down 
			// _increases_ the value
			if(deltaY < 0)
			{
				newValue = mDigitAbove;
			}
			else
			{
				newValue = mDigitBelow;
			}
		}
		
		setCurrentDigit(newValue);
		
		return true;
	}
	return false;
}

Run the app and play around with it – it should work much like you would expect a spinner to work. You can drag the number up or down to change it, and the new number will scroll into view before being set.

Showing multiple digits

Source

Grab the source for the completed Part II here. (ZIP)

In part 3 of the tutorial, we will combine multiple spinners into an odometer, and handle some final cleanup.

Odometer Tutorial

Part I: First Steps
Part II: Touch Input and Scrolling Numbers « You are here
Part III: Compound Widgets and Fixing Bugs

Custom UI Elements in Android: Odometer Tutorial Part I

Kevin Dion — Sat, 25 Dec 2010 19:43:05 +0000

Introduction

This series of tutorials will provide an introduction to creating custom user interface elements in Android. By the end, you will have a complete custom widget that will allow input of numbers as if on an odometer. The user will slide the digits up and down, and change the digits.

This first part of the tutorial will get our test project created, and start building out the basic element of our odometer – a single-digit spinner.

Odometer Tutorial

Part I: First Steps « You are here
Part II: Touch Input and Scrolling Numbers
Part III: Compound Widgets and Fixing Bugs

Odometer Tutorial Part I: First Steps

In this first step tutorial, we will get the foundation laid for our Odometer widget, and get through drawing the single-digit spinner, but we won’t get to interactivity yet.

Creating the Project

The first step is to create a new Android project in Eclipse. I used the following values:

Project Name: OdometerTutorial
Build Target: 2.1
Application Name: Odometer
Package Name: com.kdion.tutorial.odometer
Create Activity: OdometerTutorialMain
min sdk: 7

Project Settings

(Special Note: if you look at the settings in the image, you will see that I mis-typed ‘tutorial’ as ‘turotial’ in the Package name. This came back to bite me later, so I had to fix it after I took this screenshot. Don’t make the same mistake as me!)

You can use whatever values you wish for these, but just be aware that my code is based on using these values so if you use different values (say, for the Package Name), your code will need to change accordingly.

With your newly created project, go ahead and run it to make sure everything is playing nice with the emulator (or your dev phone)

Running the new project

OdometerSpinner

To begin our custom widget creation, we will first create the building blocks for the odometer. Our first class, OdometerSpinner, will represent a single digit in the final odometer. In case you aren’t familiar with the old non-digital odometers, each digit is on its own wheel/spinner that goes from 0 to 9 and wraps at 10. So as you are driving along, the digits on a spinner go …8-9-0-1… When a spinner goes from 9 to 0, the next spinner increments as well, but we won’t be implementing that behavior, since it would be a pain to input numbers if our widget worked that way. Also, be aware that I use the term ‘Spinner’ in a different context than the standard Android ‘Spinner’ UI class, which is more of a drop-down (or at least that’s how I think of it).

Create the OdometerSpinner class

Add a new class to your project, using the settings shown in the image below. You want to inherit from View, and I go ahead and have it auto-generate the default constructors for me, as well as any abstract methods (although there aren’t any when inheriting form View). I also have ‘Generate comments’ checked, although you don’t have to. The important thing is to make a class names ‘OdometerSpinner’ that subclasses android.view.View.

Creation settings for OdometerClass

Once you create the class, you will see that there are three different constructors generated for you, looking something like this:

public OdometerSpinner(Context context)
{
    super(context);
}

public OdometerSpinner(Context context, AttributeSet attrs)
{
    super(context, attrs);
}

public OdometerSpinner(Context context, AttributeSet attrs, int defStyle)
{
    super(context, attrs, defStyle);
}

These are the three View constructors, and it is important you override them all in your custom classes. The first constructor is the one called when you create the class in code. The second and third come into play when your custom View is created from an xml file. The AttributeSet passed is the set of xml attributes defined – the defStyle in the third constructor has to do with applying a custom theme – I have never used it myself, but I figure it is best to override the constructor just in case.

onMeasure() and onDraw()

The next methods you will need to override in OdometerSpinner are onMeasure and onDraw. So go ahead and add them through Source > Override/Implement Methods… and select onMeasure(int, int) and onDraw(Canvas). It is recommended that you override these methods whenever you are making your own custom View, so while we won’t do much with them right now, we’ll go ahead and get them in place. They should look something like this (comments are mine):

protected void onDraw(Canvas canvas)
{
    super.onDraw(canvas);

    // TODO draw stuff
}

protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec)
{
    super.onMeasure(widthMeasureSpec, heightMeasureSpec);

    // MAKE SURE you call super.onMeasure(int, int) here!!!
    // At least until we implement our own measuring logic
}

Adding OdometerSpinner to the Activity

The next step is to add the OdometerSpinner to our Activity’s layout so we can see it when we run. Open up main.xml in the layout/ folder and add OdometerSpinner so it looks like this:

Your syntax for OdometerSpinner might not be ‘com.kdion.tutorial.odometer.OdometerSpinner‘, just change the package path to whatever you are using for your package. The important thing to note is to set the layout_width and layout_height to fill_parent (this has to do with not overriding the logic in onMeasure(), so until we put logic in there leave the width and height as fill_parent). I also just kept the default TextView with the “Hello, World!” message for grins, but you don’t have to.

Now, go ahead and run your app once again…but wait! Nothing shows up for our spinner! It is still there, we just haven’t yet drawn anything – so it is invisible. We will start drawing next.

Drawing the Background

The first thing we will do for drawing the background is to simply draw a solid rectangle to represent our OdometerSpinner. The simplest way to do this is to add the following drawing commands to OdometerSpinner’s onDraw() method:

protected void onDraw(Canvas canvas)
{
	super.onDraw(canvas);

	int width = getMeasuredWidth();
	int height = getMeasuredHeight();

	Paint p = new Paint();
	p.setColor(Color.GREEN);

	canvas.drawRect(0, 0, width, height, p);
}

First, we get the width and height of our View by calling getMeasuredWidth() and getMeasuredHeight(). Next, we create a Paint object and set it a green color. Finally, we call drawRect() on the Canvas object passed to us. The first two zeros passed as arguments to the drawRect() function define the top left corner of the rectangle (if you are unfamiliar with computer graphics, the coordinate system used by most drawing packages has the origin at the top left corner of the screen, with increasing X-values going to the right and increasing Y-values going down).

Now, if we run our app, we see that there is now a nice big green rectangle taking up most of the screen.

Running our app with a green background

Improving the drawing

Before we move on to changing up the background to look more like an odometer, we need to change how we are drawing the background. As we have the code now, we query the width and height of our View, create a Paint object, and draw the rectangle. This is horribly inefficient, since onDraw() might be getting called many times a second (at least once we start having scrolling numbers and such). So what we need to do is move as much of the overhead as possible out of onDraw(). To do that, we will add new class member variables for the width, height, background rectangle, and background paint. In general, it is considered ‘best practice’ in Android to move things to class members rather than re-calculate within the methods every time they are called. So, add the following variables to the OdometerSpinner class:

public class OdometerSpinner extends View
{
	private float mWidth;
	private float mHeight;
	
	private RectF mBGRect;
	
	private Paint mBGPaint;
	//...

Now that we have those new variables, we need to initialize the Paint and RectF when the class is instantiated. So add the following initialize() method to OdometerSpinner, and add calls to initialize() in each of the 3 constructors.

private void initialize()
{
	mBGRect = new RectF();
	
	mBGPaint = new Paint(Paint.ANTI_ALIAS_FLAG);
	mBGPaint.setColor(Color.GREEN);
}

Now that we have the Paint saved in our class, we need to store the width and height of our widget. Instead of measuring the width and height every time we draw, we really only need to change our stored measurements when the size of the View changes. And wouldn’t you know it, there is a method you can override in View that is called every time the size changes – onSizeChanged(). Add an override for onSizeChanged in OdometerSpinner and put the following in it:

protected void onSizeChanged(int w, int h, int oldw, int oldh)
{
	super.onSizeChanged(w, h, oldw, oldh);
	
	mWidth = w;
	mHeight = h;
	
	mBGRect.set(0, 0, w, h);
}

Here we set the width and height, and resize our saved rectangle to the new size – now we don’t need to perform the cumbersome recalculation every time we draw. Now just change the onDraw() code:

protected void onDraw(Canvas canvas)
{
	super.onDraw(canvas);
	
	canvas.drawRect(mBGRect, mBGPaint);
}

Much nicer, isn’t it? You can go ahead and run and see that there is stil that big green screen.

Drawing Gradients

Now it is time to get rid of that bright green and replace it with a more realistic-looking gradient for the background. Using a gradient for the background will give us the illusion of depth on out spinner and make it look like we are showing part of a round object – just what we want.

At the top of OdometerSpinner, add a new member variable for this GradientDrawable, and add its initialization in initialize(). You can remove the Paint and RectF we were using before. Also, add the resizing logic in onSizeChanged(), and draw the gradient in onDraw().

private GradientDrawable mBGGrad;
//...
private void initialize()
{
	mBGGrad = new GradientDrawable(GradientDrawable.Orientation.TOP_BOTTOM, 
				new int[] { 0xFF000000, 0xFFAAAAAA, 0xFF000000 });
}
//...
protected void onSizeChanged(int w, int h, int oldw, int oldh)
{
	super.onSizeChanged(w, h, oldw, oldh);
	
	mWidth = w;
	mHeight = h;

        mBGGrad.setBounds(0, 0, w, h);
}
//...
protected void onDraw(Canvas canvas)
{
	super.onDraw(canvas);
	
	mBGGrad.draw(canvas);
}

In initialize() we create a new GradientDrawable, setting the direction to go from top to bottom. We also pass in an array of ints, which are the ordered colors we want in the gradient. We tell the gradient to have black at the top, fade to a medium gray in the middle, and back to black. The format of the ints we pass is 0xAARRGGBB, where AA is the alpha channel, and RR, GG, and BB are the red, green, and blue channels, respectively.

In onSizeChanged(), we tell the gradient its new dimensions. In onDraw(), we tell it to draw itself on the canvas. Now when you run the app, you should get a nice vertical gradient as shown below.

Our OdometerSpinner with the gradient background

Throwing Numbers Around

Now that we have a nice looking background, we need to have our odometer actually display some numbers. Rather than worry about all of the logic for changing numbers, having the values wrap, and so on – for now, we’ll just draw a single, hard-coded digit.

Canvas has a nice method to draw a string, so we will need a String to hold the text representation of our digit (again, rather than convert int to String in every onDraw() call, we store it as a separate variable). We will also need a Paint to control how the text looks, so we will add those variables. We will initialize them along with our other class members in initialize(), then draw them in onDraw().

private String mDigitString;
private Paint mDigitPaint;
//...
private void initialize()
{
	mBGGrad = new GradientDrawable(GradientDrawable.Orientation.TOP_BOTTOM, 
			new int[] { 0xFF000000, 0xFFAAAAAA, 0xFF000000 });

	mDigitString = "8";
	
	mDigitPaint = new Paint(Paint.ANTI_ALIAS_FLAG);
	mDigitPaint.setColor(Color.WHITE);
	mDigitPaint.setTextAlign(Align.CENTER);
}	
//...
protected void onDraw(Canvas canvas)
{
	super.onDraw(canvas);
	
	mBGGrad.draw(canvas);
	
	float digitX = mWidth / 2;
	float digitY = mHeight / 2;
	
	canvas.drawText(mDigitString, digitX, digitY, mDigitPaint);
}

I went ahead and used 8 as the digit we will display for now, since it is pretty easy to tell if it is centered on the screen when it is displayed. We also set up the Paint we use to draw the digit, telling it to center the text and color it white. In onDraw(), we draw the digit string in the center of the OdometerSpinner with the appropriate Paint. Running our app at this point gives us the following:

Drawing a tiny number

Sizing

As you can see, the text is very tiny, because Android by uses the default text size for the Paint since we did not specify a size. Since the size we want the digits to be will depend on the size of the spinner itself, we can put the following line of code in the onSizeChanged() call to set a proper text size.

protected void onSizeChanged(int w, int h, int oldw, int oldh)
{
	//... other code here...
	mDigitPaint.setTextSize(h);
}

This sets the text height to be the height of the spinner, which should fill up the spinner with the digit, which is what we want. Running now gives us this:

Big number, bad placement

Placement

The text is now big enough, but it is not placed correctly. In onDraw(), when we passed the Y-value to draw as mHeight/2, that actually specifies the bottom of the text. We can pass mWidth/2 for the X-value and get it centered horizontally because Paint has a text alignment that we set as CENTER. In order to get our text centered vertically, we are going to have to perform a bit more calculation, measuring how tall the text we want to display is, and using that measurement to calculate where we need to place it to get it perfectly centered. Unfortunately, every digit (0-9) might have different heights, so we don’t want to use a single, hard-coded value. Fortunately, there are some built-in functions we can use to get the exact height of what we want to draw. Add two new variables, mDigitX and mDigitY to store the location we want to draw the digit, and add the following code to onSizeChanged() and onDraw()

private float mDigitX;
private float mDigitY;
//...
protected void onSizeChanged(int w, int h, int oldw, int oldh)
{
	super.onSizeChanged(w, h, oldw, oldh);
	
	mWidth = w;
	mHeight = h;
	
	mBGGrad.setBounds(0, 0, w, h);
	
	mDigitPaint.setTextSize(h);
	
	Rect bounds = new Rect();
	mDigitPaint.getTextBounds(mDigitString, 0, 1, bounds);
	
	int textHeight = Math.abs(bounds.height());
	
	mDigitX = mWidth / 2;
	mDigitY = mHeight - ((mHeight - textHeight) / 2);
}
//...
protected void onDraw(Canvas canvas)
{
	super.onDraw(canvas);
	
	mBGGrad.draw(canvas);
	
	canvas.drawText(mDigitString, mDigitX, mDigitY, mDigitPaint);
}

In onSizeChanged(), we use getTextBounds() to measure the smallest rectangle that would fit around mDigitString (characters 0 to 1), putting those dimensions in the rectangle bounds. Then, we use the height of that rectangle (taking the absolute value since it isn’t guaranteed to be positive, and a negative number would mess with our calculations) to calculate exactly where to place the digit when we draw it. With the appropriate changes to the arguments in onDraw(), we now get the following when we run our app:

Correctly placed, correctly sized number

That is all for Part I of this tutorial, in Part II we will add touch interaction and the ability to change numbers with our spinner.

Source

Here is the source code for Part I. (.zip file, Right-click > Save As…)

Odometer Tutorial

Part I: First Steps « You are here
Part II: Touch Input and Scrolling Numbers
Part III: Compound Widgets and Fixing Bugs

Diving Boynton Beach

Kevin Dion — Tue, 26 Oct 2010 23:52:35 +0000

This past Saturday I went diving down in Boynton Beach with the great guys at American Divers. I just got a new camera and couldn’t wait to try it out underwater! We did a three-tank dive at a few reefs, and actually ended up doing somewhat of a reverse dive profile with a really short dive first, with a longer second and third dive (depths for all were around 45-50 ft). But it worked out well, since the best reef by far was the last – with a lot of cool wildlife! Saw 3-4 turtles, a couple of rays, and a good number of bugs (lobster). Even saw my first eel! All in all it was a reminder of why I love diving so much – and a reminder that I really should get my nitrox cert…

Europe Photos Added

Kevin Dion — Wed, 06 Oct 2010 01:41:11 +0000

I have put up a bunch of photos from my trip last summer to Europe. Destinations include Germany, Austria, Italy, and Switzerland. Few images have meaningful titles or details yet, but check them out anyways!

Photos

Presenting: SAAZenheimer Uberweizenbock Label

Kevin Dion — Thu, 30 Sep 2010 01:13:22 +0000

This is the label I did up for the commemorative beer made specially for the 16th Commander SAAZ Interplanetary Homebrew Blastoff. The name: SAAZenheimer Uberweizenbock – a traditional style weizenbock brewed especially for the 2010 Interplanetary Homebrew Blastoff. SAAZ, of course, stands for the Space Coast Associates for the Advancement of Zymurgy – in other words the local homebrew club. Every year they host the Interplanetary Homebrew Blastoff, which is a national beer and mead competition.

I wanted to make a label that had a traditional feel, with blackletter styling and old-world flair. I also wanted it to have a good amount of extra detail since in the past they (SAAZ) have printed out the labels in letter size and given them as raffle prizes.

TED a Day

Kevin Dion — Thu, 23 Sep 2010 15:56:55 +0000

I absolutely Love TED. I think it might just be one of the greatest things on the web, and should be required viewing in every school. In fact, I could see an entire class devoted to watching and discussing TED talks. The variety of topics and level of prestige the presenters have is amazing, and just being exposed to the amazing work in a domain you are unfamiliar with is extremely beneficial, regardless of what you do.

I have known of TED for a while, when one of my friends would send me a a link to a particularly inspiring or engaging talk. Oddly, any time someone shares a TED talk, the comment usually goes something like this: “OMG you have to see this! it is AMAZING!”. And invariably, it was amazing, inspiring, and all of those other adjectives. What I did not realize until just a few days ago, however, was just how many talks there are – I didn’t realize that TED has been going on for decades, and they have an extensive back-catalog of archived videos (more than 700 to date). That is a lot of potential inspiration!

So in an effort to continue expanding my mind, I have decided to watch every single TED talk. While this may seem like a monstrous endeavor, I have found that at the very least over the last few days it has only taken a small change in my daily routine to knock out at least one talk a day, and usually a few more. At the moment I am working chronologically forward, going through the TED events starting from the earliest (1984) to the present.

So here’s to expanding my mind.