A pinch-to-zoom code example

Now that we’ve looked at some of the basics of implementing pinch-to-zoom, let’s examine a pinch-to-zoom listener class named PinchZoomListener that puts those basics into action. The PinchZoomListener class is part of a project which you can download and use to build the application.

Download the pinch-to-zoom sample project (0.66 MB)

Remember that the application can recognize and process pinch-to-zoom gestures in Xperia™ X10 only if you install the pinch-to-zoom support in the device.

Implementing the OnTouchListener interface

The first thing to notice about PinchZoomListener is that it implements the View.OnTouchListener interface. This is indicated in the class definition, as shown below.

public class PinchZoomListener implements View.OnTouchListener {

    …

{

By implementing the View.OnTouchListener interface, PinchZoomListener is invoked when a user touches the screen.

Registering the listener

Remember that the listener needs to be registered by an activity. In the application, it is registered in an activity class, TutorialZoomActivity4, as follows:

import com.sonyericsson.zoom.ImageZoomView;
import com.sonyericsson.zoom.PinchZoomListener;
import android.view.View;

public class TutorialZoomActivity4 extends Activity {

private ImageZoomView mZoomView;
private PinchZoomListener mPinchZoomListener;

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

         mPinchZoomListener = new PinchZoomListener(getApplicationContext());
         mZoomView.setOnTouchListener(mPinchZoomListener);
         …
      }

Notice the use of the ImageZoomView class. This class provides a View that is capable of drawing an image at different zoom levels. The ImageZoomControl class is explained in Android one finger zoom tutorial- Part 1 that was published earlier in this blog.

If you’re familiar with the one finger zoom sample project that accompanies the Android one finger zoom tutorial, you’ll notice that the pinch-to-zoom sample is architected quite similarly to the one finger zoom application. The major difference is the addition of the PinchZoomListener.

Defining listener modes

The next thing to notice in PinchZoomListener is that it defines three listener modes, each indicating a touch state. Here is the definition:

private enum Mode {
    UNDEFINED, PAN, PINCHZOOM
}

private Mode mMode = Mode.UNDEFINED;

The three listener mode constants and their meanings are:

• PAN. Indicates that the user touched the screen and moved his or her finger over the view.
• PINCHZOOM. Indicates that the user touched the screen with a second finger while continuing to touch the screen with the first finger.
• UNDEFINED. Indicates that the state is not PAN or PINCHZOOM. The user may or may not be touching the screen. Initially the listener sets the state to UNDEFINED.

Handling gestures

The core of the processing is focused on handling user gestures. Recall from Part 1 of the tutorial that the handler uses the onTouch() method in the View.OnTouchListener interface to process touch events. Here is part of the definition of the onTouch() method in PinchZoomListener.

private VelocityTracker mVelocityTracker;
public boolean onTouch(View v, MotionEvent event) {
    final int action = event.getAction() & MotionEvent.ACTION_MASK;
    final float x = event.getX();
    final float y = event.getY();
if (mVelocityTracker == null) {
    mVelocityTracker = VelocityTracker.obtain();
   }
        mVelocityTracker.addMovement(event);
   …
 }

The onTouch() method uses the getAction() method to get the action from the MotionEvent object for the touch event. To get the action code, the onTouch() method performs a bitwise AND operation on the retrieved action and the ACTION_MASK constant. Then the method gets the X and Y coordinates of the touched position on the screen.

Notice the use of the VelocityTracker class. A VelocityTracker object will be used to track the velocity of the touch events.

Handling ACTION_DOWN events

After getting the action-related information from the MotionEvent object, your application needs to handle the action. Here is how the listener processes an ACTION_DOWN event, that is, when the user touches the screen with one finger:

switch (action) {
    case MotionEvent.ACTION_DOWN:
        mZoomControl.stopFling();
        mDownX = x;
        mDownY = y;
        mX = x;
        mY = y;
        break;

As its name implies, mZoomControl controls zooming in the application. It is assigned a DynamicZoomControl object that is provided in the setZoomControl() method of the application, as shown below.

public void setZoomControl(DynamicZoomControl control) {
    mZoomControl = control;
}

The DynamicZoomControl class is fully explained in Android one finger zoom tutorial – Part 4, published earlier in this blog. The stopFling() method of DynamicZoomControl stops the animation associated with a fling gesture. A fling gesture means that the user dragged an object across the screen and then removed his or her finger from the screen. This result is an animation in which the object continues to move but slows over time. The ACTION_DOWN event invokes stopFling() to stop processing the fling gesture. This handles the situation where the user made a fling gesture before retouching the screen.

The mX and mY variables are used to record the X and Y coordinates, respectively, of the current touch on the screen. The mDownX and mDownY variables are used to record the X and Y coordinates, respectively, of the previous touch on the screen. The four variables are set to the coordinate values for the current ACTION_DOWN event.

Handling ACTION_POINTER_DOWN events

Now let’s look at the code in PinchZoomListener that processes an ACTION_POINTER_DOWN event.

case MotionEvent.ACTION_POINTER_DOWN:
    if (event.getPointerCount() > 1) {
        oldDist = spacing(event);
        if (oldDist > 10f) {
            midPoint(mMidPoint, event);
            mMode = Mode.PINCHZOOM;
        }
    }
    break;

In this case, the user should have two fingers touching the screen. If so, the listener calculates the distance between the two fingers using a spacing() method, as follows.

private float spacing(MotionEvent event) {
    float x = event.getX(0) - event.getX(1);
    float y = event.getY(0) - event.getY(1);
    return FloatMath.sqrt(x * x + y * y);

You might wonder why the distance between the fingers is tested, that is, if(oldDist > 10f) {…}. The test is needed because the support in Android for multi-touch events such as pinch-to-zoom is still not optimal (see Limitations below). For example, sometimes Android incorrectly reports that two fingers are touching in almost the same position. To guard against anomalous situations such as this, the listener ignores events where the distance between the two fingers is less than a certain threshold (in this case 10f). If the distance is greater than the threshold, the listener finds the midpoint of the distance using a midPoint() method, as shown below. The midpoint will be used as the center point of the zoom.

private void midPoint(PointF point, MotionEvent event) {
        float x = event.getX(0) + event.getX(1);
        float y = event.getY(0) + event.getY(1);
        point.set(x / 2, y / 2);

With the two fingers now touching the screen, the listener sets the mode to PINCHZOOM.

Handling ACTION_MOVE events

Next, let’s look at the code in PinchZoomListener that handles an ACTION_MOVE event, where the user moves a finger across the screen.

case MotionEvent.ACTION_MOVE:
    final float dx = (x - mX) / v.getWidth();
    final float dy = (y - mY) / v.getHeight();

    if (mMode == Mode.PAN) {
        mZoomControl.pan(-dx, -dy);
    } else if (mMode == Mode.PINCHZOOM) {
        float newDist = spacing(event);
        if (newDist > 10f) {
            final float scale = newDist / oldDist;
            final float xx = mMidPoint.x / v.getWidth();
            final float yy = mMidPoint.y / v.getHeight();
            mZoomControl.zoom(scale, xx, yy);
            oldDist = newDist;
        }
    } else {
        final float scrollX = mDownX - x;
        final float scrollY = mDownY - y;

        final float dist =
            (float)Math.sqrt(scrollX * scrollX + scrollY * scrollY);

        if (dist >= mScaledTouchSlop ){
            mMode = Mode.PAN;
        }
    }

    mX = x;
    mY = y;
    break;

Here, the listener determines if the action is part of a pan gesture or a pinch-to-zoom gesture. In either case, it uses the dynamic zoom control to handle the gesture. The zoom action is handled by the zoom() method in the DynamicZoomControl class. The method performs its actions based on the scale of the zoom, an invariant X coordinate position, and an invariant Y coordinate position. The scale of the zoom and the invariant coordinates are defined as follows:

Here, the term invariant means the zoom method ensures that the coordinate value does not change during the course of the zoom.

Notice that the listener ignores the event if the mode is PINCHZOOM and the distance between the points is less than the space threshold. Again, this is to protect against anomalous results.

If the node is not PAN or PINCHZOOM, the listener tests to see if the move distance exceeds the distance at which the movement is considered scrolling in pixels. The listener sets the threshold from the current context using the getScaledTouchSlop() method. Here is the call to getScaledTouchSlop() in the listener.

private final int mScaledTouchSlop;

public PinchZoomListener(Context context) {
    mScaledTouchSlop = ViewConfiguration.get(context).getScaledTouchSlop();
    …
}

If the move distance does exceed the threshold, the listener sets the mode to PAN.

Handling ACTION_POINTER_UP events

The next event type to examine is ACTION_POINTER_UP, the case where the user releases one finger while continuing to touch the screen with the other finger. Here is the code that handles that case.

case MotionEvent.ACTION_POINTER_UP:
    if(event.getPointerCount() > 1 &&  mMode == Mode.PINCHZOOM){
       panAfterPinchTimeout = System.currentTimeMillis() + 100;
    }
    mMode = Mode.UNDEFINED;
    break;

There is no zoom processing to perform for this event, so the listener simply sets a timeout threshold that it will use if the user subsequently pans across the screen. It then sets the mode to UNDEFINED.

Handling ACTION_UP events

Last, here is the way the ACTION_UP event is handled in the PinchZoomListener.

case MotionEvent.ACTION_UP:
    if (mMode == Mode.PAN) {
        final long now = System.currentTimeMillis();
        if(panAfterPinchTimeout < now){
           mVelocityTracker.computeCurrentVelocity(1000,
                  mScaledMaximumFlingVelocity);
           mZoomControl.startFling(
                  -mVelocityTracker.getXVelocity() / v.getWidth(),
                  -mVelocityTracker.getYVelocity() / v.getHeight());
        }
        } else if(mMode != Mode.PINCHZOOM) {
                  mZoomControl.startFling(0, 0);
        }
        mVelocityTracker.recycle();
        mVelocityTracker = null;

The ACTION_UP event covers the situation where the user has one finger touching the screen and then removes it from the screen. If the user was panning across the screen before removing the finger, the listener checks to see that timeout threshold wasn’t reached. If the threshold wasn’t reached, the listener starts a fling animation by calling the startFling() method of the Dynamic ZoomControl object.

When it makes the call to startFling(), the listener specifies the velocity in the X and Y dimensions. These velocities are used by the method in calculating the physics of the animation. If the mode is not PAN or PINCHZOOM, the listener simply releases control by calling the startFling() method and specifying 0 for the velocities in the X and Y dimensions.

Limitations

Xperia™ X10 is not yet fully optimized for multi-touch. There are some cases where a pinch-to-zoom gesture generates unusual behavior. For example, a user might not see the expected zoom in or zoom out in the field of view if he or she crosses the X or Y axis during a pinch-to-zoom gesture. For instance, the zoom in or zoom out might appear jumpy, as illustrated below.

In addition, a user might not see a smooth zoom in or zoom out movement if his or her fingers are aligned along the X or Y axis, as illustrated below.

Note too that the all points addressable screen in the Xperia™ X10 consists of an intersection matrix of row and column sense elements, as illustrated below.

This arrangement is termed dual layer.

The dual layer hardware registers the touch position of a finger in terms of a row and column. For two fingers, it registers two rows and two columns. However, the hardware does not necessarily distinguish which finger is touching the screen at the registered row and column. Also, the hardware does not necessarily distinguish which recorded value represents the row and which the column. As a result, when two fingers touch the screen, as in a pinch-to-zoom gesture, there are four possibilities of how the combined event is registered.

Suppose, for example, that the first finger (let’s call it finger A) touches the screen at row 1 column 1, and the second finger (let’s call it finger B) touches the screen at row 3 column 6, as shown in the following image.

The hardware might register the fingers in any of the following four ways:

• Finger A at row 1 and column 1 and finger B at row 3 column 6.
• Finger A at row 3 column 6 and finger B at row 1 column 1.
• Finger A at row 3 column 1 and finger B at row 1 column 6.
• Finger A at row 1 column 6 and finger B at row 3 column 1.

This type of axis flipping is also a general problem reported about the multi-touch support in Android 2.1.

Beyond the axis flipping problem, Android 2.1 sometimes records touches by multiple fingers as one finger touch or as multiple fingers touching at almost the same position. So it’s important to check for anomalous results where you can, as the PinchZoomListener in this tutorial does. Recall that the PinchZoomListener tests whether the distance between the two fingers is below a specified distance (10f), and if that distance is below the threshold, the listener ignores the touch event.

If you’re interested in testing your Xperia™ X10 device for multi-touch, you can use the MultiTouch Visualizer 2 application, which you can find in Android Market.

More information

• How to take advantage of the pinch-to-zoom feature in your Xperia™ 10 apps – Part 1>>>
• Learn more about Visualizer 2 in AndroidMarket>>>
• Learn more about Android development on Developer World>>>
• See Xperia™ X10 on the consumer website>>>

Recently Sony Ericsson rolled out an update to the Android™2.1 operating system in its Xperia™ X10 phones. One of the important new features in the update is support for a multi-touch gesture called pinch-to-zoom. In this first part of a two-part tutorial, you will learn how to take advantage of the pinch-to-zoom feature in your apps. In the second part of the tutorial, you’ll examine a code example that uses the pinch-to-zoom feature.

The pinch-to-zoom feature allows users to zoom in and get a closer, more detailed view of a display, or zoom out and get a wider field of view. For example, in the side-by-side image below, the image on the left shows a display zoomed out for a wider field of view. The image on the right shows the display zoomed in for a closer view.

The pinch-to-zoom feature lets users zoom out for a wider field of view, or zoom in for a closer view.

Although not initially available in the Android 2.1 support in Xperia™ X10, pinch-to-zoom is now available as an over-the-air (OTA) enhancement. Note however that Xperia™ X10 is not yet fully optimized for multi-touch. There are some cases where a pinch-to-zoom gesture generates unusual behavior. For more information, see the Limitations section in Part 2 of the tutorial.

You can take advantage of the pinch-to-zoom feature in applications that you develop for Xperia™ X10. Two applications that are packaged with Xperia™ X10 already take advantage of the feature: the web browser and Google Maps. There are also other applications that make use of this feature, such as Angry Birds.

Below is a video that demonstrates the pinch-to-zoom feature in Xperia™ X10.

Providing pinch-to-zoom capability in your Xperia™ X10 application

Your Xperia™ X10 application needs to do the following to provide pinch-to-zoom capability:

• Detect that the user has made a pinch-to-zoom gesture, such as moving two fingers across the screen. This is further explained below in Detecting and getting information about the gesture.
• Get information about the gesture, such as what the action was and when it took place. This is further explained below in Detecting and getting information about the gesture.
• Process the gesture, that is, respond to the user’s action, as appropriate. This is further explained below in Processing the gesture.

Detecting and getting information about the gesture

When a user touches the screen, Android creates an Android™ MotionEvent object to record information about the touch event, such as the action the user performed and the time when the user performed it. Your application needs to access the object in order to detect a pinch-to-zoom gesture and get information about it. This requires the application to first import the MotionEvent class as follows:

import android.view.MotionEvent;

Processing the gesture

To process the gesture, you create a callback handler. You can use the callback handler to take actions such as get information about a pinch-to-zoom gesture. However, first you need to register the callback handler using the setOnTouchListener() method of the Android View class, as shown in the following code snippet.

import android.view.View;
import android.view.View.OnTouchListener;
…
view.setOnTouchListener(onTouchListener);

The parameter to view.setOnTouchListener represented by onTouchListener is the callback handler, that is, the touch listener that you want to register. The callback handler is attached to a specific view. Touch events that are posted to that view are processed by the associated callback handler.

The callback handler must implement Android’s View.OnTouchListener interface and use the onTouch() method defined in the interface to process the touch events. When you call the onTouch() method, you need to supply as parameters a View object and a MotionEvent object, as shown below.

public class MyPinchZoom extends Activity implements OnTouchListener {

   public boolean onTouch(View v, MotionEvent event) {
      // Process touch events
   }

}

A user starts a pinch-to-zoom gesture by touching the screen with one finger. This event is represented in the MotionEvent object by the constant ACTION_DOWN. When the user touches the screen with a second finger while continuing to touch the screen with the first finger, that event is recorded in the MotionEvent object by the constant ACTION_POINTER_DOWN. Other constants represent other actions taken during the pinch-to-zoom gesture. Here are the set of action-related constants for the pinch-to-zoom gesture:

After you register the callback handler, you can use it to call methods on the MotionEvent object to get information about a pinch-to-zoom related event. For example, the getAction() method returns the type of action performed: up down, move , or cancel. The following code snippet shows a call to the getAction() method.

// Process touch events
      int action = event.getAction();

The lowest 8 bits of the action returned by getAction() represent the action code. To access the action code, you can perform a bitwise AND operation (using the & operator). The two operands of the AND operation are the result returned by getAction() and the MotionEvent constant, ACTION_MASK. The ACTION_MASK constant is a bit mask of the part of the action code that represents the action itself. The following line of code performs a bitwise AND operation on the action returned by getAction() and the ACTION_MASK constant.

int actionCode = action & MotionEvent.ACTION_MASK;

You can get the number of pointers (fingers) associated with the event by calling the getPointerCount() method of the MotionEvent object, as shown below.

int pCount = event.getPointerCount();

You can also retrieve the X and Y coordinates associated with the touch event by calling the getX() and getY() methods of the MotionEvent object, respectively. Here is an example that retrieves first the X coordinate and then the Y coordinate.

float xcoord = event.getX;
float ycoord = event.getY;

By identifying a pointer index as a parameter to getX() and getY(), you can retrieve the X and Y coordinates of a specific pointer. The following example shows how to get the X coordinate and Y coordinate of the first pointer.

Float  xcoord = event.getX(0);   //Get the X coordinate for the first
                                 // pointer
Float  ycoord = event.getY(1);   //Get the Y coordinate for the second
                                 // pointer

More information

• How to take advantage of the pinch-to-zoom feature in your Xperia™ X10 apps – Part 2>>>
• Learn more about Android development on Developer World>>>
• See Xperia™ 10 on the consumer website>>>

Read Johan’s tutorial here.

Based on PhoneGap’s open source framework, WebSDK Packager is a great tool for someone who has great expertise with HTML CSS and JavaScript and is adept at creating web applications, but is not familiar with the complexities of the mobile environment. WebSDK Packager allows Android™ developers to create mobile web applications by packaging their web components inside a native shell for Android. For Symbian developers, WebSDK Packager uses the PhoneGap API with web runtime (WRT) widgets. This truly enables developers to write code once and deploy on multiple platforms. With support of this tool on Windows and Mac OS platforms, developers can use the tool on their preferred platform.

For those not familiar with PhoneGap, it is an open source development framework for building cross-platform mobile apps that run on different mobile platforms including Android, Symbian, iPhone®, iPad®, Palm® and BlackBerry®. The PhoneGap open source code has been downloaded more than 250,000 times and there are thousands of PhoneGap-based apps in various platform stores. We also welcome the recent announcement by Symbian to integrate PhoneGap library in their web extensions package.

Sony Ericsson supports cross-platform web development and sees this as an important enabler for developers to create exciting new services across web and mobile. Sony Ericsson announced support for PhoneGap framework in 2009 and our WebSDK Packager as part of a broader approach to simplifying the application and services development on mobile devices for developers.

Additionally, we will begin referring to Sony Ericsson’s WebSDK as a “Packager”, which aligns with the true functionality of the product – a complete tool for developers to build, simulate and package their application’s web components into a single native shell.

For developers, Sony Ericsson has put together an add-on for the Android™ SDK, including the splash screen, backgrounds, an Xperia™ X10 skin and some other stuff. Find out more on the Developer World web site.

[Download] One Finger Zoom sample project – Part 4 (220kb)

In this part we’ll focus on introducing dynamic behavior to our zoom such as fling and bounce by animating the zoom state. Dynamic behavior adds a lot in terms of looks, feedback and usability.

Dynamics

To implement dynamic behavior we’re going to subclass the Dynamics class introduced in the final part of the list tutorial. Make sure to read through that tutorial if you want to know more about the Dynamics base class.

The Dynamics class is useful for applying dynamic behavior to a value, the class itself holds a position and a velocity and functionality for setting min and max positions. When subclassing Dynamics we must implement the onUpdate(int) method that is responsible for updating the state. This gives us control over the dynamic behavior and in our Dynamics sub-class we’ll implement basic friction and spring physics to handle fling and edge bounce. If you want to know more about spring physics then this is a nice place to start.

Let start by defining the necessary attributes for our dynamic behavior. The friction factor will be used to decelerate the fling animation when we are inside the pan limits, and the stiffness and damping factor will be used to simulate a spring pulling the zoom window back to the content if we are outside of the pan limits. To simplify setting up the physics we let the user specify a damping ratio which we then internally recalculate to the damping factor we use in our calculations. Damping ratio is easy to use, basically a value of less than 1 makes the animation overshoot while a value of 1 or more doesn’t. Here you can learn more about damping.
[java]
public class SpringDynamics extends Dynamics {

private float mFriction;
private float mStiffness;
private float mDamping;

public void setFriction(float friction) {
mFriction = friction;
}

public void setSpring(float stiffness, float dampingRatio) {
mStiffness = stiffness;
mDamping = dampingRatio * 2 * (float)Math.sqrt(stiffness);
}
[/java]
Next we’ll implement the onUpdate() method which is responsible for updating the position and velocity of the Dynamics object. The input parameter, dt, is the number of milliseconds passed since the method was previously called. (By the way: dt stands for delta time. Delta is commonly used in mathematics and denotes change and thus: dt = change in time.)

To implement friction and spring physics we need to numerically solve the equations of motion. To do this we’ll use Euler integration. Although it has low accuracy and is prone to instability it works fine in a simple case like this. Here you can read more about numerical integration.
[java]
@Override
protected void onUpdate(int dt) {
final float fdt = dt / 1000f;
final float a = calculateAcceleration();
mPosition += mVelocity * fdt + .5f * a * fdt * fdt;
mVelocity += a * fdt;
}[/java]
Our algorithm requires us to be able to calculate the acceleration at the current position which we’ll do by using spring physics if we’re outside of the pan limits. If we are inside of the pan limits we’ll calculate the acceleration caused by friction as the product of the friction coefficient and the current velocity.
[java]
private float calculateAcceleration() {
float acceleration;

final float distanceFromSnap = getDistanceFromSnap();
if (distanceFromSnap != 0) {
acceleration = distanceFromSnap * mStiffness – mDamping * mVelocity;
} else {
acceleration = -mFriction * mVelocity;
}

return acceleration;
}
[/java]

A dynamic zoom control

Once we have the SpringDynamics implementation down we can improve our zoom control. As you might remember from the previous tutorials the zoom control is responsible for imposing limits and other similar logic. Let’s introduce our new SpringDynamics class to the zoom control by creating one of them for each dimension and setting fitting friction and spring coefficients.
[java]
private final SpringDynamics mPanDynamicsX = new SpringDynamics();
private final SpringDynamics mPanDynamicsY = new SpringDynamics();

public DynamicZoomControl() {
mPanDynamicsX.setFriction(2f);
mPanDynamicsY.setFriction(2f);
mPanDynamicsX.setSpring(50f, 1f);
mPanDynamicsY.setSpring(50f, 1f);
}
[/java]
Next, as we no longer will have hard limits on the pan but instead a spring pulling behavior when we are outside the pan limits, we need to modify the pan method:
[java]
private static final float PAN_OUTSIDE_SNAP_FACTOR = .4f;
private float mPanMinX;
private float mPanMaxX;
private float mPanMinY;
private float mPanMaxY;

public void pan(float dx, float dy) {
final float aspectQuotient = mAspectQuotient.get();

dx /= mState.getZoomX(aspectQuotient);
dy /= mState.getZoomY(aspectQuotient);

if (mState.getPanX() > mPanMaxX && dx > 0 || mState.getPanX() < mPanMinX && dx < 0) {
dx *= PAN_OUTSIDE_SNAP_FACTOR;
}
if (mState.getPanY() > mPanMaxY && dy > 0 || mState.getPanY() < mPanMinY && dy < 0) {
dy *= PAN_OUTSIDE_SNAP_FACTOR;
}

final float newPanX = mState.getPanX() + dx;
final float newPanY = mState.getPanY() + dy;

mState.setPanX(newPanX);
mState.setPanY(newPanY);

mState.notifyObservers();
}
[/java]
We will no longer limit the pan by clamping it inside bounds when the user is panning around. Instead we’ll impose a penalty factor when panning outside the bounds giving the user clear visible feedback and a sense of struggling. This also means we’ll no longer need the limitPan() method we used in the previous tutorials. However, we still need to calculate the pan limits so we can do the pull back animation. We’ll replace the limitPan() method with a new method, updatePanLimits(), that calculates the pan limits depending on the zoom level, and then call that method every time the zoom level changes:
[java]
private void updatePanLimits() {
final float aspectQuotient = mAspectQuotient.get();

final float zoomX = mState.getZoomX(aspectQuotient);
final float zoomY = mState.getZoomY(aspectQuotient);

mPanMinX = .5f – getMaxPanDelta(zoomX);
mPanMaxX = .5f + getMaxPanDelta(zoomX);
mPanMinY = .5f – getMaxPanDelta(zoomY);
mPanMaxY = .5f + getMaxPanDelta(zoomY);
}
[/java]
Next we’ll add functionality for starting a fling which will be called when the user lifts his or her finger from the screen after panning.
[java]
private final Handler mHandler = new Handler();

public void startFling(float vx, float vy) {
final float aspectQuotient = mAspectQuotient.get();
final long now = SystemClock.uptimeMillis();

mPanDynamicsX.setState(mState.getPanX(), vx / mState.getZoomX(aspectQuotient), now);
mPanDynamicsY.setState(mState.getPanY(), vy / mState.getZoomY(aspectQuotient), now);

mPanDynamicsX.setMinPosition(mPanMinX);
mPanDynamicsX.setMaxPosition(mPanMaxX);
mPanDynamicsY.setMinPosition(mPanMinY);
mPanDynamicsY.setMaxPosition(mPanMaxY);

mHandler.post(mUpdateRunnable);
}
[/java]
In the startFling() method we prepare the dynamics objects for taking over control of the pan, setting to it the current pan and velocity values as well as the current time. We also set the min and max values of the dynamics object to the current pan limits. Finally we post a runnable that is responsible for updating and animating the zoom state.
[java]
private static final float REST_VELOCITY_TOLERANCE = 0.004f;
private static final float REST_POSITION_TOLERANCE = 0.01f;
private static final int FPS = 50;

private final Runnable mUpdateRunnable = new Runnable() {
public void run() {
final long startTime = SystemClock.uptimeMillis();
mPanDynamicsX.update(startTime);
mPanDynamicsY.update(startTime);
final boolean isAtRest = mPanDynamicsX.isAtRest(REST_VELOCITY_TOLERANCE, REST_POSITION_TOLERANCE) && mPanDynamicsY.isAtRest(REST_VELOCITY_TOLERANCE, REST_POSITION_TOLERANCE);
mState.setPanX(mPanDynamicsX.getPosition());
mState.setPanY(mPanDynamicsY.getPosition());

if (!isAtRest) {
final long stopTime = SystemClock.uptimeMillis();
mHandler.postDelayed(mUpdateRunnable, 1000 / FPS – (stopTime – startTime));
}

mState.notifyObservers();
}
};
[/java]
In the runnable that is posted for animating the pan values we update the dynamics objects and then we set the updated pan values to the ZoomState. Then we check if the animation should go on or by checking if the the dynamics objects are both at rest. If the dynamics objects are not at rest we post this runnable again using a delay calculated to try to meet a chosen FPS. Finally we notify observers of the ZoomState object that it’s been changed, ultimately causing the zoom view to invalidate.

Lastly our dynamic zoom control will need a method for stopping the fling that will be used when the user puts his or her finger down on the screen again after making a fling. Since our fling animation uses a runnable posted on a handler we simply remove the runnable from the handler, thus no longer triggering the automatic zoom state updates and effectively stopping the animation.
[java]
public void stopFling() {
mHandler.removeCallbacks(mUpdateRunnable);
}
[/java]

Utilizing our new tools

Alright, so we have implemented dynamic behavior to our zoom control, now lets start using the new methods we created so we can start flinging and bouncing around! To do this we will build on our OnTouchListener implementation and make sure the onTouch method calls our new methods in all the correct places.

The startFling method we declared above takes two velocity parameters, one for each dimension, and luckily the Android platform has just the right tools for calculating the velocity of a fling motion. The onTouch method is will use VelocityTracker for tracking the velocity of motion events by simply adding the events to the tracker object:
[java]
private VelocityTracker mVelocityTracker;

public boolean onTouch(View v, MotionEvent event) {
final int action = event.getAction();
final float x = event.getX();
final float y = event.getY();

if (mVelocityTracker == null) {
mVelocityTracker = VelocityTracker.obtain();
}
mVelocityTracker.addMovement(event);
[/java]
The handling of down events will be largely unchanged with the exception of the call to the stopFling() method on the zoom control, stopping any current animation when the user puts his or her finger back on the screen:
[java]
switch (action) {
case MotionEvent.ACTION_DOWN:
mZoomControl.stopFling();
v.postDelayed(mLongPressRunnable, mLongPressTimeout);
mDownX = x;
mDownY = y;
mX = x;
mY = y;
break;
[/java]
The handling of move events is unchanged since the previous part of the tutorial so lets skip ahead to the handling of up events. Here we will use the velocity tracker for calculating the velocity of the fling event if we were panning around. If we were not panning but instead perhaps zooming or simply in an undefined state, for example if the user has done a quick tap on the screen, we’ll start a fling without velocity. Even if we don’t give the fling any initial velocity it is important that we start it since the pan values might be outside of the limits which makes the springs physics accelerate the pan values, pulling them back within limits.
[java]
case MotionEvent.ACTION_UP:
if (mMode == Mode.PAN) {
mVelocityTracker.computeCurrentVelocity(1000, mScaledMaximumFlingVelocity);
mZoomControl.startFling(-mVelocityTracker.getXVelocity() / v.getWidth(), -mVelocityTracker.getYVelocity() / v.getHeight());
} else {
mZoomControl.startFling(0, 0);
}
mVelocityTracker.recycle();
mVelocityTracker = null;
v.removeCallbacks(mLongPressRunnable);
mMode = Mode.UNDEFINED;
break;

default:
mVelocityTracker.recycle();
mVelocityTracker = null;
v.removeCallbacks(mLongPressRunnable);
mMode = Mode.UNDEFINED;
break;

}

return true;
}
[/java]
Note that the fling uses the negative of the calculated velocities similar to how the negative of the dx and dy values are used in the part of the switch statement that handles move events.

And with that, we’re done! We now have a dynamic zoom with a nicely separated software architecture, and while this is where this tutorial series will end I hope it can be the start of experiments and projects for some of you. In this tutorial series we’ve limited ourselves to zooming in images, but the code can be used to zoom in any application. To do this you need to write your own View subclass and implement the drawing in this view to honor the values you get from ZoomState.

Please feel free to share your zoom experiences, and don’t hesitate to ask any questions.

Good luck!

More info on X8 and the Q3 update to Android 2.1 for X10 and X10 mini/pro can be found on our sister blog, the Sony Ericsson Product Blog

Don’t forget to go to Android Market and download Sony Ericsson Tutorials, the app that collects all sample apps in this and other Sony Ericsson tutorials. Get the QR-code for the app here. Below is a link to the source code of part 3, prepared for you to set up your own project in e.g. Eclipse.

[Download] One Finger Zoom sample project – Part 3 (215kb)

This tutorial part will focus on introducing a new way of interacting with the zoom, a new input paradigm as our designers would say. In the previous tutorial we laid the ground for exactly this when we created a new class for controlling the zoom state. Separating the state control from the input control handled by an OnTouchListener implementation.

Besides being nice for easier code overview this separation is great for us in at least two other ways:

First it it is very useful for trying out different way of controlling the zoom, something I had great use for in the X10 mini project. Here at Sony Ericsson we have the privilege of working with several great and driven designers wanting to test out every idea for controlling the zoom you can think of. Being able to easily switch between variants meant we could evaluate several good designs before settling.

Secondly it means we can easily have different ways of controlling the zoom on different devices. Multiple screen support is something you should always think of when designing for android. For small devices like the X10 mini one handed touch is very useful, while larger screens will be operated with two hands most of the time, one hand holding the phone and another free to touch the screen.

Implementing a new paradigm

As you might remember, the zoom control in the previous tutorial parts had options menu alternatives for switching between pan and zoom mode. Having menu alternatives such as these are usually not a good idea as in many Android applications the options menu is already overflowing. Also you don’t want navigation more than one click away.

Our new input paradigm will be similar to the one on the X10 mini. We’ll use long press to enter zoom mode and vertical touch dragging for zooming in and out. Pan will be left unchanged, activated simply by dragging.

We’ll start the implementation of a new listener by modifying the BasicZoomListener class we’ve built on so far, removing all references to the ControlType enum and renaming the class to LongPressZoomListener. Then we create a new constructor for the listener.

[java]
private final int mScaledTouchSlop;
private final int mLongPressTimeout;

public LongPressZoomListener(Context context) {
mLongPressTimeout = ViewConfiguration.getLongPressTimeout();
mScaledTouchSlop = ViewConfiguration.get(context).getScaledTouchSlop();
}
[/java]

To implement long press we need to define the long press timeout, that is the duration before a press turns into a long press. We also need to define the touch slop, that is the amount touch can wander before we decide it’s a drag event rather than a long press. As luck might have it the system defines good default values we can use for this. The touch slop value is even screen size dependent.

To implement the long touch logic we first need to define a flag for holding the classification of the current touch event. The classification mode have three states, undefined means the touch hasn’t been classified yet and can become either pan or zoom. Pan means the user has started dragging and has entered pan mode while zoom means the user has made a long press and entered zoom mode where vertical touch movement zooms in or out.

[java]
private enum Mode {
UNDEFINED, PAN, ZOOM
}

private Mode mMode = Mode.UNDEFINED;
[/java]

Next up we will re-implement the onTouch callback method to classify long press and drag and interpret these as either zoom or pan.

[java]
private final Runnable mLongPressRunnable = new Runnable() {
public void run() {
mMode = Mode.ZOOM;
}
};

public boolean onTouch(View v, MotionEvent event) {
final int action = event.getAction();
final float x = event.getX();
final float y = event.getY();

switch (action) {
case MotionEvent.ACTION_DOWN:
v.postDelayed(mLongPressRunnable, mLongPressTimeout);
mDownX = x;
mDownY = y;
mX = x;
mY = y;
break;
[/java]

Starting with the action down event, this is largely unchanged from our previous tutorials with the exception of posting a runnable on the view handler. This runnable, called mLongPressRunnable, is posted with a delay meaning it will run once the delay time has passed, in this case when the long press duration has passed. The runnable simply sets the mode to zoom mode, meaning once the long press duration has passed we’ll enter zoom mode.

[java]
case MotionEvent.ACTION_MOVE: {
final float dx = (x – mX) / v.getWidth();
final float dy = (y – mY) / v.getHeight();

if (mMode == Mode.ZOOM) {
mZoomControl.zoom(
(float)Math.pow(20, -dy),
mDownX / v.getWidth(),
mDownY / v.getHeight());
} else if (mMode == Mode.PAN) {
mZoomControl.pan(-dx, -dy);
} else {
final float scrollX = mDownX – x;
final float scrollY = mDownY – y;

final float dist = (float)
Math.sqrt(scrollX * scrollX + scrollY * scrollY);

if (dist >= mScaledTouchSlop) {
v.removeCallbacks(mLongPressRunnable);
mMode = Mode.PAN;
}
}

mX = x;
mY = y;
break;
}
[/java]

The action move event handling code is also similar to what we had in the previous tutorials. What’s new is the else block where we check if the the touch has wandered far enough to be classified as a drag. This is done by calculating the distance from the touch down location using the Pythagorean theorem and comparing it to the touch slop we got for the view configuration. If the touch has wandered far enough we set the pan mode flag and we remove the mLongPressRunnable from the view callback queue, making sure we don’t enter zoom mode after the long press timeout duration has passed.

[java]
default:
v.removeCallbacks(mLongPressRunnable);
mMode = Mode.UNDEFINED;
break;

}

return true;
}
[/java]

Finally we add support for handling the remaining touch events, such as action up and action cancel. In these cases we remove the long press callback and reset the mode flag, putting the component back into default state.

Tactile feedback

Now we have implemented a nicer input paradigm, making it easy and swift to zoom and pan. It is however it’s a bit confusing to the user that no indication is given when they enter zoom or pan mode. To fix this we’ll use tactile feedback, giving the user a quick vibration when entering zoom mode.

Using the vibrator on Android devices is easy. We get access to the vibrator service through the context we get in the constructor like this.

[java]
private final Vibrator mVibrator;

public LongPressZoomListener(Context context) {
mLongPressTimeout = ViewConfiguration.getLongPressTimeout();
mScaledTouchSlop = ViewConfiguration.get(context).getScaledTouchSlop();
mVibrator = (Vibrator)context.getSystemService(“vibrator”);
}
[/java]

Then we modify our runnable to give a quick vibration when entering zoom mode, 50 ms gives a nice and short feedback.

[java]
private static final long VIBRATE_TIME = 50;

private final Runnable mLongPressRunnable = new Runnable() {
public void run() {
mMode = Mode.ZOOM;
mVibrator.vibrate(VIBRATE_TIME);
}
};
[/java]

This is all the java code required for tactile feedback, however if you try to run this you’ll get an exception due to the application not having permission to use the vibrator service. This is easily remedied by adding the line below in the manifest.

[xml]
<uses-permission android:name=”android.permission.VIBRATE” />
[/xml]

And we’re done! Our zoom is starting to feel quite nice and useful, we’ve got a nice input paradigm and a zoom that behaves reasonably. This is the perfect time for you readers to try out your own take on a input paradigm if you want to, or maybe you’ve got ideas on how to improve the one we’ve just implemented.

Next up we’ll implement a very nice addition to our zoom, fling and bounce. Currently a downside with the zoom is that it feels stiff and panning far requires a lot of dragging. This will all change in the next tutorial where we introduce a more dynamic behavior.

Until then, good luck!

Don’t forget to go to Android Market and download Sony Ericsson Tutorials, the app that collects all sample apps in this and other Sony Ericsson tutorials.

In this part of the tutorial we will build on the zoom application we started in part 1. As you might remember, in part 1 we finished with a zoom application that didn’t have any limits, we could zoom and pan into the void and back. In this tutorial we will introduce limits and we will also make sure that the pan always follows the finger as one would expect, as we in part 1 could see panning following the finger differently depending on the current zoom level. Below is a link to the source code for step 2 and the video showing what you will learn in the one finger zoom tutorial series.

[Download] One Finger Zoom sample project – Part 2 (218kb)

The aspect quotient

Remember this picture from part 1?

Images illustrating how the zoom state works, the dashed gray area represents what is shown in the view and the patterned area represents the content. On the left: Zoom is 1, pan-x and pan-y are both 0.5, in this state the image fits the screen perfectly. In the middle: Zoom is 2, pan-x and pan-y are still both 0.5, less content is now shown on the screen but will be scaled up. To the right: Zoom is 3, pan-x is 0.7 and pan-y is 0.833, we now see less of the image, only the top right corner, scaled up.

In the rightmost image we’re at the top right pan limit, this means the maximum pan values are 0.7 and 0.833 on the x- and y-axis respectively when the zoom level is 3. The actual limits are dependent on the level of zoom in that particular dimension, and the level of zoom in a particular dimension depends on the aspect quotient (quotient between content aspect ratio and view aspect ratio, refer to part 1 for more explanation). And to make a long story short, in order to apply limits to the pan, as well as making pan follow the finger correctly, we need the aspect quotient.

Currently though, from part 1, our aspect quotient is only available in the ImageZoomView. So first let us change this and create an object that holds the aspect quotient and extends Observable as a means of easily notifying whom ever wishes to observe.

[java]
public class AspectQuotient extends Observable {

private float mAspectQuotient;

public float get() {
return mAspectQuotient;
}

public void updateAspectQuotient(float viewWidth, float viewHeight, float contentWidth,
float contentHeight) {
final float aspectQuotient = (contentWidth / contentHeight) / (viewWidth / viewHeight);

if (aspectQuotient != mAspectQuotient) {
mAspectQuotient = aspectQuotient;
setChanged();
}
}
}
[/java]

Pretty straight forward, the calculations are the same as in part 1 and just as the ZoomState observable we leave it up to the client updating the aspect quotient to notify observers. The next step is to update ImageZoomView to hold a AspectQuotient object (as opposed to just a float as in part 1), and give others access to it. Of course we also need to update the code that currently modifies the aspect quotient, but I’ll leave code like this out of the tutorial as it’s straightforward and just re-factors existing functionality. Please see the code in the project linked below for reference.

Enforcing limits and following fingers

Alright, so now we’re able to access the aspect quotient that we need for implementing limits and follow finger through a neat and tidy Observable. The next step is to add the actual code that does these things, but where?

Currently the responsibility for modifying the ZoomState lies with the OnTouchListener, while we could add the functionality here I am reluctant too as I want the OnTouchListener implementation to be responsible for the touch paradigm used and not the specifics on how the ZoomState is controlled. For example, I want to easily be able to implement an OnTouchListener for multi-touch, and when I do I don’t want to update or even duplicate the functionality that applies limits, or as we’ll see in later parts, animates a state.

Another idea would be to add the functionality to the ZoomState, but I want the ZoomState to be simple, it’s responsibility is to provide an interface for accessing the state and getting callbacks when it changes.

So, the way to implement the new functionality is through a new class that sits in between the OnTouchListener implementation and the ZoomState. Let’s call this new class BasicZoomControl, as we’ll implement a first and quite basic component for controlling the ZoomState. And let’s start with creating the skeleton of this class, we know we need access to the aspect quotient and we want a callback when this changes where we enforce limits, we also know we will be controlling a zoom state so lets add that and a get method for access.

[java]
public class BasicZoomControl implements Observer {

private AspectQuotient mAspectQuotient;

private final ZoomState mState = new ZoomState();

public ZoomState getZoomState() {
return mState;
}

public void setAspectQuotient(AspectQuotient aspectQuotient) {
if (mAspectQuotient != null) {
mAspectQuotient.deleteObserver(this);
}

mAspectQuotient = aspectQuotient;
mAspectQuotient.addObserver(this);
}

public void update(Observable observable, Object data) {
limitZoom();
limitPan();
}

}
[/java]

Secondly we want methods for applying zoom and pan and apply the logics needed to keep within limits, have pan follow finger and also we’ll be making the content under the coordinate of the touch down event invariant during zooming, meaning we can zoom into specific parts of the content and not just the current center.

[java]
public void zoom(float f, float x, float y) {
final float aspectQuotient = mAspectQuotient.get();

final float prevZoomX = mState.getZoomX(aspectQuotient);
final float prevZoomY = mState.getZoomY(aspectQuotient);

mState.setZoom(mState.getZoom() * f);
limitZoom();

final float newZoomX = mState.getZoomX(aspectQuotient);
final float newZoomY = mState.getZoomY(aspectQuotient);

mState.setPanX(mState.getPanX() + (x – .5f) * (1f / prevZoomX – 1f / newZoomX));
mState.setPanY(mState.getPanY() + (y – .5f) * (1f / prevZoomY – 1f / newZoomY));

limitPan();

mState.notifyObservers();
}

public void pan(float dx, float dy) {
final float aspectQuotient = mAspectQuotient.get();

mState.setPanX(mState.getPanX() + dx / mState.getZoomX(aspectQuotient));
mState.setPanY(mState.getPanY() + dy / mState.getZoomY(aspectQuotient));

limitPan();

mState.notifyObservers();
}
[/java]

The zoom method takes a zoom factor and the position of the touch down event as parameters and then updates the state of both the zoom level and the pan position. By storing the previous zoom levels it is possible to calculate new pan parameters that satisfies keeping the down coordinate invariant when zooming. The pan method is similar to how panning was done in part 1 but now the dx and dy values are divided by the level of zoom in the respective coordinate, doing this makes pan follow the finger as we now take the zoom level in consideration. Finally we need to implement the methods that limit the zoom and pan values:

[java]
private static final float MIN_ZOOM = 1;

private static final float MAX_ZOOM = 16;

private void limitZoom() {
if (mState.getZoom() < MIN_ZOOM) {
mState.setZoom(MIN_ZOOM);
} else if (mState.getZoom() > MAX_ZOOM) {
mState.setZoom(MAX_ZOOM);
}
}

private float getMaxPanDelta(float zoom) {
return Math.max(0f, .5f * ((zoom – 1) / zoom));
}

private void limitPan() {
final float aspectQuotient = mAspectQuotient.get();

final float zoomX = mState.getZoomX(aspectQuotient);
final float zoomY = mState.getZoomY(aspectQuotient);

final float panMinX = .5f – getMaxPanDelta(zoomX);
final float panMaxX = .5f + getMaxPanDelta(zoomX);
final float panMinY = .5f – getMaxPanDelta(zoomY);
final float panMaxY = .5f + getMaxPanDelta(zoomY);

if (mState.getPanX() < panMinX) {
mState.setPanX(panMinX);
}
if (mState.getPanX() > panMaxX) {
mState.setPanX(panMaxX);
}
if (mState.getPanY() < panMinY) {
mState.setPanY(panMinY);
}
if (mState.getPanY() > panMaxY) {
mState.setPanY(panMaxY);
}
}
[/java]

Limiting the zoom is quite straightforward, we use 1 (within screen bounds) and 16 (quite a lot of zoom, more than enough for most images on most screens) and simply clamp the value. For the pan we do the same but the problem with pan is that the limits change based on the level of zoom we’re currently at. For example, at a zoom level of 1 we don’t want the user to be able to pan at all (as the content fits the view perfectly).

Stringing it all together

Alright, we’re almost done with part 2 of the zoom tutorial. What’s left is adapting the Activity and the OnTouchListener implementations to the new solutions. This means changing so that the OnTouchListener implementation doesn’t manipulate the ZoomState directly but instead calls methods in BasicZoomControl, and setting it all up correctly in the Activity implementation. Please check out the project link below if you want to know the specifics of this code, or even better if you want to start playing around with the code on your own!

Now we have a zoom that works good, we’ve fixed the blemishes from part 1 but we’ve got some work left to make it really useful. First thing that comes in my mind is the input method, changing mode in the options menu is a poor choice. Because of this we’ll look into implementing a new OnTouchListener and a new input paradigm in the next tutorial.

[Download] One Finger Zoom sample project – Part 2 (218kb)

Good Luck!

[Download] One Finger Zoom sample project (211kb)

Don’t miss to download the Sony Ericsson Tutorials app on Android Market where all applications in this and other Sony Ericsson tutorials are available. With the SonyEricsson tutorials app you can easily try out the different parts of the tutorial and see what the end result will be.

Below is a video showing what you will be able to do after seeing all steps of the tutorial. There following parts of the turoital will be added over the next few weeks.

There will be some math in this tutorial, but there is no need to get discouraged if it is too much for you. Please feel free to skip the math part and accept that they work.

In this first part of the tutorial we are going to make a basic, interactive, zoom control that allows us to zoom into an image. This will be achieved by implementing three classes representing the following: 1) our own View class for drawing images with zoom applied to it, 2) a class holding the state of the zoom, and 3) a class implementing the OnTouchListener interface allowing the user to interact with the zoom. As we progress in the tutorial we will see the benefits of dividing our application into different classes this way, as it makes it easy to change specific parts of the behavior.

Basic zoom listener

Defining a zoom state

The first thing we need to do is to define how the zoom state should work. The goal for our definition should be to make it easy to understand, simple to interact with and do math on. There is probably other decent ways to do this, but I’ll show you one that worked for me.

We’ll define the zoom state using three parameters.

• The amount of zoom, that is how much the content has been scaled. We let a zoom value of 1 define the state where the content fits the view perfectly in at least one dimension.
• The amount of pan in dimension-x (pan-x), that is how much the content is moved in respect to the width of the screen. We let the pan value define where the center position of the zoom-view (the view defining which part of the content we see) is in relation to the content. For example, a pan-x value of 0.5 would mean the center of the content would be visible in the center of the view, while a value of 0 would mean the left hand side of the content would be visible in the center of the screen.
• The amount of pan in dimension-y (pan-y), like the pan-x except how the content is moved in relation to the height of the screen.

Images illustrating how the zoom state works, the dashed gray area represents what is shown in the view and the patterned area represents the content. On the left: Zoom is 1, pan-x and pan-y are both 0.5, in this state the image fits the screen perfectly. In the middle: Zoom is 2, pan-x and pan-y are still both 0.5, less content is now shown on the screen but will be scaled up. To the right: Zoom is 3, pan-x is 0.7 and pan-y is 0.833, we now see less of the image, only the top right corner, scaled up.

Implementation

Now that we’ve got the basics laid down, let’s move on to coding and let’s start by implementing the state. Since we know the view will want to determine when the state has been modified we can implement the state as an instance of Observable, allowing us to easily notify other objects of state changes.
[java]
public class ZoomState extends Observable {

private float mZoom;
private float mPanX;
private float mPanY;

public float getPanX() {
return mPanX;
}

public float getPanY() {
return mPanY;
}

public float getZoom() {
return mZoom;
}

public void setPanX(float panX) {
if (panX != mPanX) {
mPanX = panX;
setChanged();
}
}

public void setPanY(float panY) {
if (panY != mPanY) {
mPanY = panY;
setChanged();
}
}

public void setZoom(float zoom) {
if (zoom != mZoom) {
mZoom = zoom;
setChanged();
}
}
}
[/java]

As simple as that, get/set methods for the available parameters and a call to setChanged() every time a parameter is changed. The client changing the values is responsible for calling notifyObservers() after modifying the state. Now that we have a state class, let’s move on to the view, we will extend the basic View class and implement the Observer interface in order to be able to observe and get callbacks when the state changes.

[java]
public class ImageZoomView extends View implements Observer {

private Bitmap mBitmap;
private ZoomState mState;

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

public void setImage(Bitmap bitmap) {
mBitmap = bitmap;

invalidate();
}

public void setZoomState(ZoomState state) {
if (mState != null) {
mState.deleteObserver(this);
}

mState = state;
mState.addObserver(this);

invalidate();
}

@Override
protected void onDraw(Canvas canvas) {
}

public void update(Observable observable, Object data) {
invalidate();
}

}
[/java]
Now we have created the basic structure of the view, and as this will be a zoom view for images we will be using a Bitmap object as the zoom content. We can set a bitmap to zoom in, we can set a zoom state to observe and we call invalidate when the content or the state changes. Next step we want to draw the bitmap, for this we need a Paint object and two Rect objects representing rectangles; one for the part of the content we wish to draw and one for the area of the view we wish to draw on.

[java]
private final Paint mPaint = new Paint(Paint.FILTER_BITMAP_FLAG);
private final Rect mRectSrc = new Rect();
private final Rect mRectDst = new Rect();

@Override
protected void onDraw(Canvas canvas) {
if (mBitmap != null && mState != null) {
canvas.drawBitmap(mBitmap, mRectSrc, mRectDst, mPaint);
}
}
[/java]
As you can see there is a drawBitmap method on the Canvas object that takes two rectangle objects as input parameters just the way we need it to, and since we will be scaling the bitmap we should enable the bitmap filtering on the paint object. Finally we need to set up the rectangles correctly, and then we’re done.

To set up the rectangles so that the visible part of the source image is cropped correctly and drawn at the correct location on the view we need to introduce a new variable. The reason for this is that if the content does not have the same aspect ratio (width / height) as the view, then a zoom value of 1 will mean that only one of the dimensions fit the view. In the other dimension the content will only partially cover the view, which means it will correspond to a zoom value lower than 1 in that particular dimension. The solution for this is to introduce a variable we will call the aspect quotient, that is the quotient between the aspect ratio of the content and the aspect ratio of the view. By using this value we can separate the zoom value on the x-axis and on the y-axis, and to do so we will add help methods to the ZoomState class to calculate them.

[java]
public float getZoomX(float aspectQuotient) {
return Math.min(mZoom, mZoom * aspectQuotient);
}

public float getZoomY(float aspectQuotient) {
return Math.min(mZoom, mZoom / aspectQuotient);
}
[/java]
As the aspect quotient is defined by the view characteristics and content we will store this value in the ZoomView, and update its value whenever changes are made to the view or content (the content in our case being a bitmap). Such changes are for example if the view changes in size due to the user changing the phone orientation, or if the content changes because of the user switching between zoomable images in an album application.

[java]
private float mAspectQuotient;

private void calculateAspectQuotient() {
if (mBitmap != null) {
mAspectQuotient =
(((float)mBitmap.getWidth()) / mBitmap.getHeight()) /
(((float)getWidth()) / getHeight());
}
}

public void setImage(Bitmap bitmap) {
mBitmap = bitmap;

calculateAspectQuotient();

invalidate();
}

@Override
protected void onLayout(boolean changed, int left, int top, int right, int bottom) {
super.onLayout(changed, left, top, right, bottom);

calculateAspectQuotient();
}
[/java]
With the help of these methods we can now implement the onDraw method correctly. We’ll do this by first calculating how much scaling to apply in relation to the full size of the content (zoomX, zoomY). Then we calculate the source rectangle to crop the portion of the content that should be visible, allowing the calculations to crop outside of the content boundaries. Finally we need to recalculate the source rectangle as the drawBitmap function does not support cropping outside of our bitmap content, and then we recalculate the destination rectangle to compensate for this.

Images showing how the zooming is done by setting up source and destination rectangles. The leftmost image shows the content with the crop area shown with a dashed square, this is how the source rectangle is initially calculated. To its right is the result shown in the zoom view, the dashed square here represents the destination rectangle that now covers the entire zoom view.

The next step is to recalculate the rectangles so that the source rectangle fits inside of the content without changing the result shown on the screen. The left most image now shows the content with the zoom window completely inside the content. To its right is the result shown in the zoom view, the dashed square represents the destination rectangle that has now been recalculated so that it doesn't cover the parts of the view where nothing should be drawn.

[java]
@Override
protected void onDraw(Canvas canvas) {
if (mBitmap != null && mState != null) {
final int viewWidth = getWidth();
final int viewHeight = getHeight();
final int bitmapWidth = mBitmap.getWidth();
final int bitmapHeight = mBitmap.getHeight();

final float panX = mState.getPanX();
final float panY = mState.getPanY();
final float zoomX = mState.getZoomX(mAspectQuotient) * viewWidth / bitmapWidth;
final float zoomY = mState.getZoomY(mAspectQuotient) * viewHeight / bitmapHeight;

// Setup source and destination rectangles
mRectSrc.left = (int)(panX * bitmapWidth – viewWidth / (zoomX * 2));
mRectSrc.top = (int)(panY * bitmapHeight – viewHeight / (zoomY * 2));
mRectSrc.right = (int)(mRectSrc.left + viewWidth / zoomX);
mRectSrc.bottom = (int)(mRectSrc.top + viewHeight / zoomY);
mRectDst.left = getLeft();
mRectDst.top = getTop();
mRectDst.right = getRight();
mRectDst.bottom = getBottom();

// Adjust source rectangle so that it fits within the source image.
if (mRectSrc.left < 0) {
mRectDst.left += -mRectSrc.left * zoomX;
mRectSrc.left = 0;
}
if (mRectSrc.right > bitmapWidth) {
mRectDst.right -= (mRectSrc.right – bitmapWidth) * zoomX;
mRectSrc.right = bitmapWidth;
}
if (mRectSrc.top < 0) {
mRectDst.top += -mRectSrc.top * zoomY;
mRectSrc.top = 0;
}
if (mRectSrc.bottom > bitmapHeight) {
mRectDst.bottom -= (mRectSrc.bottom – bitmapHeight) * zoomY;
mRectSrc.bottom = bitmapHeight;
}

canvas.drawBitmap(mBitmap, mRectSrc, mRectDst, mPaint);
}
}
[/java]
So great, we have our view and state classes working, now let’s make a simple OnTouchListener so we can get to play around with the zoom as soon as possible! The listener will change the zoom or pan values of the state when the user touches the screen. For simplicity we’ll either zoom or pan when touch starts, which to do will be determined by an attribute we’ll call control type. Other than that we need to store the coordinates of the previous touch event so we know how much the touch has moved between each move event we receive.

For the zoom value we use the distance moved in the y-dimension, using this as the exponent when calculating the exponentiation of of a well chosen number, and then multiply the result with the current zoom level. Multiplying with an exponentiation is practical since if we where to for example move 10 pixels in the y-dimension, doing so gives the same result if it’s obtained by one or several move events. This is because, where we get the same result when moving a + b pixels as we get if we first move a pixels and then b pixels

For the pan we will simply add the distance moved in to their respective pan values, making the pan move relative to the touch movement. Finally we call notifyObservers() on the state in order to make the view redraw it’s content.

[java]
public class SimpleZoomListener implements View.OnTouchListener {

public enum ControlType {
PAN, ZOOM
}

private ControlType mControlType = ControlType.ZOOM;

private ZoomState mState;

private float mX;
private float mY;

public void setZoomState(ZoomState state) {
mState = state;
}

public void setControlType(ControlType controlType) {
mControlType = controlType;
}

public boolean onTouch(View v, MotionEvent event) {
final int action = event.getAction();
final float x = event.getX();
final float y = event.getY();

switch (action) {
case MotionEvent.ACTION_DOWN:
mX = x;
mY = y;
break;

case MotionEvent.ACTION_MOVE: {
final float dx = (x – mX) / v.getWidth();
final float dy = (y – mY) / v.getHeight();

if (mControlType == ControlType.ZOOM) {
mState.setZoom(mState.getZoom() * (float)Math.pow(20, -dy));
mState.notifyObservers();
} else {
mState.setPanX(mState.getPanX() – dx);
mState.setPanY(mState.getPanY() – dy);
mState.notifyObservers();
}

mX = x;
mY = y;
break;
}

}

return true;
}

}
[/java]
Alright, so we’re almost done. Now we just need an Activity and a layout to go with this and we’re done, the layout is quite straight forward, we simply add our new ZoomView and tell it to fill it’s parent.

[xml]
<?xml version=”1.0″ encoding=”utf-8″?>
<com.sonyericsson.zoom.ImageZoomView
xmlns:android=”http://schemas.android.com/apk/res/android”
android:id=”@+id/zoomview”
android:layout_width=”fill_parent”
android:layout_height=”fill_parent”
/>
[/xml]
In the activity we set up our zoom components in the onCreate() method, creating a new zoom state, decoding the bitmap we want to zoom in, creating the listener and connecting it to the state, and finally setting up the view. We also implement the onDestroy method and make sure to recycle bitmaps and remove listeners.

Finally we implement onCreateOptionsMenu() and onOptionsItemSelected() respectively enabling the user to change input method using the options menu and to reset the zoom to its original state.

[java]
public class TutorialZoomActivity1 extends Activity {

private static final int MENU_ID_ZOOM = 0;
private static final int MENU_ID_PAN = 1;
private static final int MENU_ID_RESET = 2;

private ImageZoomView mZoomView;
private ZoomState mZoomState;
private Bitmap mBitmap;
private SimpleZoomListener mZoomListener;

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

setContentView(R.layout.main);

mZoomState = new ZoomState();

mBitmap = BitmapFactory.decodeResource(getResources(), R.drawable.image800x600);

mZoomListener = new SimpleZoomListener();
mZoomListener.setZoomState(mZoomState);

mZoomView = (ImageZoomView)findViewById(R.id.zoomview);
mZoomView.setZoomState(mZoomState);
mZoomView.setImage(mBitmap);
mZoomView.setOnTouchListener(mZoomListener);

resetZoomState();
}

@Override
protected void onDestroy() {
super.onDestroy();

mBitmap.recycle();
mZoomView.setOnTouchListener(null);
mZoomState.deleteObservers();
}

@Override
public boolean onCreateOptionsMenu(Menu menu) {
menu.add(Menu.NONE, MENU_ID_ZOOM, 0, R.string.menu_zoom);
menu.add(Menu.NONE, MENU_ID_PAN, 1, R.string.menu_pan);
menu.add(Menu.NONE, MENU_ID_RESET, 2, R.string.menu_reset);
return super.onCreateOptionsMenu(menu);
}

@Override
public boolean onOptionsItemSelected(MenuItem item) {
switch (item.getItemId()) {
case MENU_ID_ZOOM:
mZoomListener.setControlType(ControlType.ZOOM);
break;

case MENU_ID_PAN:
mZoomListener.setControlType(ControlType.PAN);
break;

case MENU_ID_RESET:
resetZoomState();
break;
}

return super.onOptionsItemSelected(item);
}

private void resetZoomState() {
mZoomState.setPanX(0.5f);
mZoomState.setPanY(0.5f);
mZoomState.setZoom(1f);
mZoomState.notifyObservers();
}
}
[/java]
And voila, we’re done! You can now start to play around with the zoom control on your own. It’s basic but works perfectly well for zooming around in images. A few things will probably seem to be lacking at the moment: first panning around doesn’t follow the finger correctly, and there is no limits or snap to functionality to keep us within reasonable bounds. These things, and others, will be the topic of the next parts of this zoom tutorial.

Class diagram showing how the zoom components interact

If you want to learn more about the zoom I suggest playing around with the code a bit, try changing how to zoom is controlled by the listener and try zooming into your own images.

Good luck!

[Download] One Finger Zoom sample project (211kb)