Android has a ScaleGestureDetector since API level 8 (Android 2.2). From this point on the first Android devices with multitouch screens appeared. This was great, and the ScaleGestureDetector too ofcourse.

What’s a mistery to me however, is why this is the only multitouch gesture detector that is in the API! Why isn’t there something like a RotateGestureDetector to find out rotations between two (or more) fingers… Is it one of the issues in the patent war between Apple and Google? I don’t know, but I want to be able to use it anyway… so I built this small extendable framework and I’ll explain in this article how you can use it in your Android apps! Now hope I won’t get sued for building the obvious :shock:!

Why I built this small framework

When I googled for solutions to read out rotations between two fingers on the screen, I found many solutions from people dealing with the same situation, but all not so much Object Oriented (no interfaces, abstract classes, etc) and therefor more difficult to reuse and extend.

Also, I imagine that someday (when the patent wars are over ;)) Google will add something like a RotationGestureDetector to the API in the same way the ScaleGestureDetector is working already. At that point I would like to only change the import statement and not my whole activity implementation (no guarantees here ;)). This is why I wanted to build this structure of gesture detectors. You can download (zip) or clone the framework, including an example Android app, right here from Github. Import it in your Eclipse workspace and off you go.

How to use Android’s ScaleGestureDetector

Let’s start with a tutorial on how to use the ScaleGestureDetector in your Activity…

Basic structure

In your Activity class you implement the android.view.View.OnTouchListener which makes you implement the onTouch(...) method. This way the Android system is able to inform the class any android.view.MotionEvent is happening.

public class TouchActivity extends Activity implements OnTouchListener {

	public void onCreate(Bundle savedInstanceState) {
		// Init stuff here
		...
	}

	public boolean onTouch(View v, MotionEvent event) {
		// Handle touch events here
		...
	}

	...
}

Now it is possible for you to read out the multitouch events in the onTouch(...) method and handle everything… but trust me, you’ll end up with a clutter of code which will be hard for you or your collegues to maintain! Also, the android.view.ScaleGestureDetector is here already for you to use anyway if you’re targeting API level 8 or higher, which you probably are at the time you are reading this article! Let’s delegate the eventhandling to the ScaleGestureDetector!

public class TouchActivity extends Activity implements OnTouchListener {

	private ScaleGestureDetector mScaleDetector;

	public void onCreate(Bundle savedInstanceState) {
		mScaleDetector = new ScaleGestureDetector(getApplicationContext(), new ScaleListener());
		...
	}

	public boolean onTouch(View v, MotionEvent event) {
		mScaleDetector.onTouchEvent(event);
	}

	...
}

Ofcourse first we have to create an instance of the ScaleGestureDetector in the onCreate(...) method. Via the local variable mScaleDetector we delegate the MotionEvent to the mScaleDetector.onTouchEvent(event). Great! Now the ScaleGestureDetector can figure out for us if scaling is performed. It’s of our sleaves!… Oh wait, how do we handle a user’s scale action than, just so we can do something with it in our Activity?

Handling events with a Listener

Maybe you’ve noticed the initialisation of the ScaleListener when we inited our ScaleGestureDetector. This listener is our way to know when a scale event has happened and what scaling information is available. Let’s implement this ScaleListener now as a private inner class:

public class TouchActivity extends Activity implements OnTouchListener
	...

	private class ScaleListener extends ScaleGestureDetector.SimpleOnScaleGestureListener {
		@Override
		public boolean onScale(ScaleGestureDetector detector) {
			mScaleSpan = detector.getCurrentSpan(); // average distance between fingers
			return true;
		}
	}

}

The ScaleListener class is an implementation of ScaleGestureDetector’s inner interface SimpleOnScaleGestureListener. This way the ScaleGestureDetector ‘knows’ how to call our implementation when a scale event happened. In the onScale(...) method, we can read out the data we need from the given ScaleGestureDetector.

Using the scale data

Since the ScaleListener is an inner class, we can use the same local variables as in our Activity class to store our results for later use. This could be your action rendering something… you guessed… scaled on the screen ;). A good place for this could be the onTouch(...) method again.

public class TouchActivity extends Activity implements OnTouchListener

	private float mScaleSpan = 1.0f;
	private ScaleGestureDetector mScaleDetector;

	...

	public boolean onTouch(View v, MotionEvent event) {
                mScaleDetector.onTouchEvent(event);

		// ScaleDetector handled event at this point.
		// Perform your magic with mScaleSpan now!
		...

		return true; // indicate event was handled
	}

	private class ScaleListener extends ScaleGestureDetector.SimpleOnScaleGestureListener {
		@Override
		public boolean onScale(ScaleGestureDetector detector) {
			mScaleSpan = detector.getCurrentSpan(); // average distance between fingers
			return true; // indicate event was handled
		}
	}

}

Preserving state between gestures

Now, detector.getCurrentSpan() always returns the distance between two finger touches. This means that if for example you want to scale a photo on the screen, you can’t scale it with multiple scale gestures following up eachother. The user must scale the photo in one gesture! That’s not the usability we want to offer in this case. We want to preserve the previous scale state so the user can ‘add’ additional scaling to it. This is something you can change in the listener. We can use the ScaleGestureDetector.getScaleFactor() here. And to preserve the state, use *= instead of =.

public class TouchActivity extends Activity implements OnTouchListener

	private float mScaleFactor = 1.0f;
	...

	private class ScaleListener extends ScaleGestureDetector.SimpleOnScaleGestureListener {
		@Override
		public boolean onScale(ScaleGestureDetector detector) {
			mScaleFactor *= detector.getScaleFactor(); // scale change since previous event
			return true; // indicate event was handled
		}
	}

}

Almeros’s multitouch gesture detectors

OK, now you know how you can setup your activity in an Object Oriented way with the standard multitouch gesture detector in the Android API. The gesture detectors I introduce can be used in the same way. I’ll start by explaining what the two different gesture detectors detect ;). Also, note that these multitouch gesture detectors are still working with more than two fingers on the screen!

RotateGestureDetector

Two fingers on the screen represent a line between them. In a previous (first) onRotate event an angle was determined towards the normal. In the current event the RotateGestureDetector is able to determine the angle difference between the previous and the current event’s lines.

Only when two fingers are on screen, this angle can be determined ofcourse, so only then the listener will receive a call to the onRotate(...) method. At this point you can read out the current angle difference.

Same as above with the ScaleGestureDetector, we want to preserve the rotation state so a user can rotate (an image) with multiple progressing rotation gestures. Use -= instead of using =.

public class TouchActivity extends Activity implements OnTouchListener {

    private float mRotationDegrees = 0.f;
	...

	private class RotateListener extends RotateGestureDetector.SimpleOnRotateGestureListener {
		@Override
		public boolean onRotate(RotateGestureDetector detector) {
			mRotationDegrees -= detector.getRotationDegreesDelta();
			return true;
		}
	}	

	...
}

MoveGestureDetector

This one is actually more a convenience gesture detector. You could do very well without this one but to keep your code clear, more general and Object Oriented I think this one deserves its spot in the framework.

And again… to preserve the moved state between multiple gestures we use a delta distance from the previous event till the current one. If you don’t want that, you can use MoveGestureDetector.getFocusX() and MoveGestureDetector.getFocusY().

public class TouchActivity extends Activity implements OnTouchListener {

    private float mFocusX = 0.f;
	private float mFocusY = 0.f;
	...

	private class MoveListener extends MoveGestureDetector.SimpleOnMoveGestureListener {
		@Override
		public boolean onMove(MoveGestureDetector detector) {
			PointF d = detector.getFocusDelta();
			mFocusX += d.x;
			mFocusY += d.y;		

			// mFocusX = detector.getFocusX();
			// mFocusY = detector.getFocusY();
			return true;
		}
	}	

	...
}

All together now… To-geee-ther!

Yes you may sing along ;). You can combine all these gesture detectors to give a user total control over the object on his/her screen.

...
import com.almeros.android.multitouch.gesturedetectors.MoveGestureDetector;
import com.almeros.android.multitouch.gesturedetectors.RotateGestureDetector;

public class TouchActivity extends Activity implements OnTouchListener {
	...

    private float mScaleFactor = 1.0f;
    private float mRotationDegrees = 0.f;
    private float mFocusX = 0.f;
    private float mFocusY = 0.f;  

    private ScaleGestureDetector mScaleDetector;
    private RotateGestureDetector mRotateDetector;
    private MoveGestureDetector mMoveDetector;

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

		// Setup Gesture Detectors
		mScaleDetector = new ScaleGestureDetector(getApplicationContext(), new ScaleListener());
		mRotateDetector = new RotateGestureDetector(getApplicationContext(), new RotateListener());
		mMoveDetector = new MoveGestureDetector(getApplicationContext(), new MoveListener());
	}

	public boolean onTouch(View v, MotionEvent event) {
	        mScaleDetector.onTouchEvent(event);
        	mRotateDetector.onTouchEvent(event);
	        mMoveDetector.onTouchEvent(event);

        	// Mmmmmhhhagic!!!
        	//  with: mScaleFactor, mRotationDegrees, mFocusX and mFocusY 
		...

		return true; // indicate event was handled
	}

	private class ScaleListener extends ScaleGestureDetector.SimpleOnScaleGestureListener {
		@Override
		public boolean onScale(ScaleGestureDetector detector) {
			mScaleFactor *= detector.getScaleFactor(); // scale change since previous event
			return true;
		}
	}

	private class RotateListener extends RotateGestureDetector.SimpleOnRotateGestureListener {
		@Override
		public boolean onRotate(RotateGestureDetector detector) {
			mRotationDegrees -= detector.getRotationDegreesDelta();
			return true;
		}
	}	

	private class MoveListener extends MoveGestureDetector.SimpleOnMoveGestureListener {
		@Override
		public boolean onMove(MoveGestureDetector detector) {
			PointF d = detector.getFocusDelta();
			mFocusX += d.x;
			mFocusY += d.y;		

			return true;
		}
	}		

}

Extending the framework with your own GestureDetectors

In the next article I’m going to write, I’ll explain how this framework is now built up and how you can extend it. I’ll also place the code with a simple test application in Github so you can all send me pull requests with your extentions!

I hope you like my efforts and I hope you enjoyed reading this tutorial. Cheers to multitouch on Android!