Introducing ViewPropertyAnimator

[This post is by Chet Haase, an Android engineer who specializes in graphics and animation, and who occasionally posts videos and articles on these topics on his CodeDependent blog at graphics-geek.blogspot.com. — Tim Bray]

In an earlier article, Animation in Honeycomb, I talked about the new property animation system available as of Android 3.0. This new animation system makes it easy to animate any kind of property on any object, including the new properties added to the View class in 3.0. In the 3.1 release, which was made available recently, we added a small utility class that makes animating these properties even easier.

First, if you’re not familiar with the new View properties such as alpha and translationX, it might help for you to review the section in that earlier article that discusses these properties entitled, rather cleverly, “View properties”. Go ahead and read that now; I’ll wait.

Okay, ready?

Refresher: Using ObjectAnimator

Using the ObjectAnimator class in 3.0, you could animate one of the View properties with a small bit of code. You create the Animator, set any optional properties such as the duration or repetition attributes, and start it. For example, to fade an object called myView out, you would animate the alpha property like this:

    ObjectAnimator.ofFloat(myView, "alpha", 0f).start();

This is obviously not terribly difficult, either to do or to understand. You’re creating and starting an animator with information about the object being animated, the name of the property to be animated, and the value to which it’s animating. Easy stuff.

But it seemed that this could be improved upon. In particular, since the View properties will be very commonly animated, we could make some assumptions and introduce some API that makes animating these properties as simple and readable as possible. At the same time, we wanted to improve some of the performance characteristics of animations on these properties. This last point deserves some explanation, which is what the next paragraph is all about.

There are three aspects of performance that are worth improving about the 3.0 animation model on View properties. One of the elements concerns the mechanism by which we animate properties in a language that has no inherent concept of “properties”. The other performance issues relate to animating multiple properties. When fading out a View, you may only be animating the alpha property. But when a view is being moved on the screen, both the x and y (or translationX and translationY) properties may be animated in parallel. And there may be other situations in which several properties on a view are animated in parallel. There is a certain amount of overhead per property animation that could be combined if we knew that there were several properties being animated.

The Android runtime has no concept of “properties”, so ObjectAnimator uses a technique of turning a String denoting the name of a property into a call to a setter function on the target object. For example, the String “alpha” gets turned into a reference to the setAlpha() method on View. This function is called through either reflection or JNI, mechanisms which work reliably but have some overhead. But for objects and properties that we know, like these properties on View, we should be able to do something better. Given a little API and knowledge about each of the properties being animated, we can simply set the values directly on the object, without the overhead associated with reflection or JNI.

Another piece of overhead is the Animator itself. Although all animations share a single timing mechanism, and thus don’t multiply the overhead of processing timing events, they are separate objects that perform the same tasks for each of their properties. These tasks could be combined if we know ahead of time that we’re running a single animation on several properties. One way to do this in the existing system is to use PropertyValuesHolder. This class allows you to have a single Animator object that animates several properties together and saves on much of the per-Animator overhead. But this approach can lead to more code, complicating what is essentially a simple operation. The new approach allows us to combine several properties under one animation in a much simpler way to write and read.

Finally, each of these properties on View performs several operations to ensure proper invalidation of the object and its parent. For example, translating a View in x invalidates the position that it used to occupy and the position that it now occupies, to ensure that its parent redraws the areas appropriately. Similarly, translating in y invalidates the before and after positions of the view. If these properties are both being animated in parallel, there is duplication of effort since these invalidations could be combined if we had knowledge of the multiple properties being animated. ViewPropertyAnimator takes care of this.

Introducing: ViewPropertyAnimator

ViewPropertyAnimator provides a simple way to animate several properties in parallel, using a single Animator internally. And as it calculates animated values for the properties, it sets them directly on the target View and invalidates that object appropriately, in a much more efficient way than a normal ObjectAnimator could.

Enough chatter: let’s see some code. For the fading-out view example we saw before, you would do the following with ViewPropertyAnimator:

    myView.animate().alpha(0);

Nice. It’s short and it’s very readable. And it’s also easy to combine with other property animations. For example, we could move our view in x and y to (500, 500) as follows:

    myView.animate().x(500).y(500);

There are a couple of things worth noting about these commands:

• animate(): The magic of the system begins with a call to the new method animate() on the View object. This returns an instance of ViewPropertyAnimator, on which other methods are called which set the animation properties.

• Auto-start: Note that we didn’t actually start() the animations. In this new API, starting the animations is implicit. As soon as you’re done declaring them, they will all begin. Together. One subtle detail here is that they will actually wait until the next update from the UI toolkit event queue to start; this is the mechanism by which ViewPropertyAnimator collects all declared animations together. As long as you keep declaring animations, it will keep adding them to the list of animations to start on the next frame. As soon as you finish and then relinquish control of the UI thread, the event queue mechanism kicks in and the animations begin.

• Fluent: ViewPropertyAnimator has a Fluent interface, which allows you to chain method calls together in a very natural way and issue a multi-property animation command as a single line of code. So all of the calls such as x() and y() return the ViewPropertyAnimator instance, on which you can chain other method calls.

You can see from this example that the code is much simpler and more readable. But where do the performance improvements of ViewPropertyAnimator come in?

Performance Anxiety

One of the performance wins of this new approach exists even in this simple example of animating the alpha property. ViewPropertyAnimator uses no reflection or JNI techniques; for example, the alpha() method in the example operates directly on the underlying "alpha" field of a View, once per animation frame.

The other performance wins of ViewPropertyAnimator come in the ability to combine multiple animations. Let’s take a look at another example for this.

When you move a view on the screen, you might animate both the x and y position of the object. For example, this animation moves myView to x/y values of 50 and 100:

    ObjectAnimator animX = ObjectAnimator.ofFloat(myView, "x", 50f);
    ObjectAnimator animY = ObjectAnimator.ofFloat(myView, "y", 100f);
    AnimatorSet animSetXY = new AnimatorSet();
    animSetXY.playTogether(animX, animY);
    animSetXY.start();

This code creates two separate animations and plays them together in an AnimatorSet. This means that there is the processing overhead of setting up the AnimatorSet and running two Animators in parallel to animate these x/y properties. There is an alternative approach using PropertyValuesHolder that you can use to combine multiple properties inside of one single Animator:

    PropertyValuesHolder pvhX = PropertyValuesHolder.ofFloat("x", 50f);
    PropertyValuesHolder pvhY = PropertyValuesHolder.ofFloat("y", 100f);
    ObjectAnimator.ofPropertyValuesHolder(myView, pvhX, pvyY).start();

This approach avoids the multiple-Animator overhead, and is the right way to do this prior to ViewPropertyAnimator. And the code isn’t too bad. But using ViewPropertyAnimator, it all gets easier:

    myView.animate().x(50f).y(100f);

The code, once again, is simpler and more readable. And it has the same single-Animator advantage of the PropertyValuesHolder approach above, since ViewPropertyAnimator runs one single Animator internally to animate all of the properties specified.

But there’s one other benefit of the ViewPropertyAnimator example above that’s not apparent from the code: it saves effort internally as it sets each of these properties. Normally, when the setX() and setY() functions are called on View, there is a certain amount of calculation and invalidation that occurs to ensure that the view hierarchy will redraw the correct region affected by the view that moved. ViewPropertyAnimator performs this calculation once per animation frame, instead of once per property. It sets the underlying x/y properties of View directly and performs the invalidation calculations once for x/y (and any other properties being animated) together, avoiding the per-property overhead necessitated by the ObjectAnimator property approach.

An Example

I finished this article, looked at it ... and was bored. Because, frankly, talking about visual effects really begs having some things to look at. The tricky thing is that screenshots don’t really work when you’re talking about animation. (“In this image, you see that the button is moving. Well, not actually moving, but it was when I captured the screenshot. Really.”) So I captured a video of a small demo application that I wrote, and will through the code for the demo here.

Here’s the video. Be sure to turn on your speakers before you start it. The audio is really the best part.

In the video, the buttons on the upper left (“Fade In”, “Fade Out”, etc.) are clicked one after the other, and you can see the effect that those button clicks have on the button at the bottom (“Animating Button”). All of those animations happen thanks to the ViewPropertyAnimator API (of course). I’ll walk through the code for each of the individual animations below.

When the activity first starts, the animations are set up to use a longer duration than the default. This is because I wanted the animations to last long enough in the video for you to see. Changing the default duration for the animatingButton object is a one-line operation to retrieve the ViewPropertyAnimator for the button and set its duration:

    animatingButton.animate().setDuration(2000);

The rest of the code is just a series of OnClickListenerobjects set up on each of the buttons to trigger its specific animation. I’ll put the complete listener in for the first animation below, but for the rest of them I’ll just put the inner code instead of the listener boilerplate.

The first animation in the video happens when the Fade Out button is clicked, which causes Animating Button to (you guessed it) fade out. Here’s the listener for the fadeOut button which performs this action:

    fadeOut.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View v) {
            animatingButton.animate().alpha(0);
        }
    });

You can see, in this code, that we simply tell the object to animate to an alpha of 0. It starts from whatever the current alpha value is.

The next button performs a Fade In action, returning the button to an alpha value of 1 (fully opaque):

    animatingButton.animate().alpha(1);

The Move Over and Move Back buttons perform animations on two properties in parallel: x and y. This is done by chaining calls to those property methods in the animator call. For the Move Over button, we have the following:

    int xValue = container.getWidth() - animatingButton.getWidth();
    int yValue = container.getHeight() - animatingButton.getHeight();
    animatingButton.animate().x(xValue).y(yValue);

And for the Move Back case (where we just want to return the button to its original place at (0, 0) in its container), we have this code:

    animatingButton.animate().x(0).y(0);

One nuance to notice from the video is that, after the Move Over and Move Back animations were run, I then ran them again, clicking the Move Back animation while the Move Over animation was still executing. The second animation on the same properties (x and y) caused the first animation to cancel and the second animation to start from that point. This is an intentional part of the functionality of ViewPropertyAnimator. It takes your command to animate a property and, if necessary, cancels any ongoing animation on that property before starting the new animation.

Finally, we have the 3D rotation effect, where the button spins twice around the Y (vertical) axis. This is obviously a more complicated action and takes a great deal more code than the other animations (or not):

    animatingButton.animate().rotationYBy(720);

One important thing to notice in the rotation animations in the video is that they happen in parallel with part of the Move animations. That is, I clicked on the Move Over button, then the Rotate button. This caused the movement to stat, and then the Rotation to start while it was moving. Since each animation lasted for two seconds, the rotation animation finished after the movement animation was completed. Same thing on the return trip - the button was still spinning after it settled into place at (0, 0). This shows how independent animations (animations that are not grouped together on the animator at the same time) create a completely separate ObjectAnimator internally, allowing the animations to happen independently and in parallel.

Play with the demo some more, check out the code, and groove to the awesome soundtrack for 16.75. And if you want the code for this incredibly complex application (which really is nothing more than five OnClick listeners wrapping the animator code above), you can download it from here.

And so...

For the complete story on ViewPropertyAnimator, you might want to see the SDK documentation. First, there’s the animate() method in View. Second, there’s the ViewPropertyAnimator class itself. I’ve covered the basic functionality of that class in this article, but there are a few more methods in there, mostly around the various properties of View that it animates. Thirdly, there’s ... no, that’s it. Just the method in View and the ViewPropertyAnimator class itself.

ViewPropertyAnimator is not meant to be a replacement for the property animation APIs added in 3.0. Heck, we just added them! In fact, the animation capabilities added in 3.0 provide important plumbing for ViewPropertyAnimator as well as other animation capabilities in the system overall. And the capabilities of ObjectAnimator provide a very flexible and easy to use facility for animating, well, just about anything! But if you want to easily animate one of the standard properties on View and the more limited capabilities of the ViewPropertyAnimator API suit your needs, then it is worth considering.

Note: I don’t want to get you too worried about the overhead of ObjectAnimator; the overhead of reflection, JNI, or any of the rest of the animator process is quite small compared to what else is going on in your program. it’s just that the efficiencies of ViewPropertyAnimator offer some advantages when you are doing lots of View property animation in particular. But to me, the best part about the new API is the code that you write. It’s the best kind of API: concise and readable. Hopefully you agree and will start using ViewPropertyAnimator for your view property animation needs.

ADK at Maker Faire

This weekend is Maker Faire, and Google is all over it.

Following up on yesterday’s ADK post, we should take this opportunity to note that the Faire has chased a lot of ADK-related activity out of the woodwork. The level of traction is pretty surprising giving that this stuff only decloaked last week.

Convenience Library

First, there’s a new open-source project called Easy Peripheral Controller. This is a bunch of convenience/abstraction code; its goal is to help n00bs make their first robot or hardware project with Android. It takes care of lots of the mysteries of microcontroller wrangling in general and Arduino in particular.

Bits and Pieces from Googlers at the Faire

Most of these are 20%-project output.

Project Tricorder: Using the ADK and Android to build a platform to support making education about data collection and scientific process more interesting.

Disco Droid: Modified a bugdroid with servos and the ADK to show off some Android dance moves.

Music Beta, by Google: Android + ADK + cool box with lights for a Music Beta demo.

Optical Networking: Optical network port connected to the ADK.

Interactive Game: Uses ultrasonic sensors and ADK to control an Android game.

Robot Arm: Phone controlling robot arm for kids to play with.

Bugdroids: Balancing Bugdroids running around streaming music from an Android phone.

The Boards

We gave away an ADK hardware dev kit sample to several hundred people at Google I/O, with the idea of showing manufacturers what kind of thing might be useful. This seems to have worked better than we’d expected; we know of no less than seven makers working on Android Accessory Development Kits. Most of these are still in “Coming Soon” mode, but you’ll probably be able to get your hands on some at the Faire.

1. RT Technology's board is pretty much identical to the kit we handed out at I/O.

2. SparkFun has one in the works, coming soon.

3. Also, SparkFun’s existing IOIO product will be getting ADK-compatible firmware.

4. Arduino themselves also have an ADK bun in the oven.

5. Seeedstudio’s Seeeeduino Main Board.

6. 3D Robotics’ PhoneDrone Board.

7. Microchip’s Accessory Development Starter Kit.

It looks like some serious accessorized fun is in store!

A Bright Idea: Android Open Accessories

[This post is by Justin Mattson, an Android Developer Advocate, and Erik Gilling, an engineer on the Android systems team. — Tim Bray]

Android’s USB port has in the past been curiously inaccessible to programmers. Last week at Google I/O we announced the Android Open Accessory APIs for Android. These APIs allow USB accessories to connect to Android devices running Android 3.1 or Android 2.3.4 without special licensing or fees. The new “accessory mode” does not require the Android device to support USB Host mode. This post will concentrate on accessory mode, but we also announced USB Host mode APIs for devices with hardware capable of supporting it.

To understand why having a USB port is not sufficient to support accessories let’s quickly look at how USB works. USB is an asymmetric protocol in that one participant acts as a USB Host and all other participants are USB Devices. In the PC world, a laptop or desktop acts as Host and your printer, mouse, webcam, etc., is the USB Device. The USB Host has two important tasks. The first is to be the bus master and control which device sends data at what times. The second key task is to provide power, since USB is a powered bus.

The problem with supporting accessories on Android in the traditional way is that relatively few devices support Host mode. Android’s answer is to turn the normal USB relationship on its head. In accessory mode the Android phone or tablet acts as the USB Device and the accessory acts as the USB Host. This means that the accessory is the bus master and provides power.

Establishing the Connection

Building an Open Accessory is simple as long as you include a USB host and can provide power to the Android device. The accessory needs to implement a simple handshake to establish a bi-directional connection with an app running on the Android device.

The handshake starts when the accessory detects that a device has been connected to it. The Android device will identify itself with the VID/PID that is appropriate based on the manufacturer and model of the device. The accessory then sends a control transaction to the Android device asking if it supports accessory mode.

Once the accessory confirms the Android device supports accessory mode, it sends a series of strings to the Android device using control transactions. These strings allow the Android device to identify compatible applications as well as provide a URL that Android will use if a suitable app is not found. Next the accessory sends a control transaction to the Android device telling it to enter accessory mode.

The Android device then drops off the bus and reappears with a new VID/PID combination. The new VID/PID corresponds to a device in accessory mode, which is Google’s VID 0x18D1, and PID 0x2D01 or 0x2D00. Once an appropriate application is started on the Android side, the accessory can now communicate with it using the first Bulk IN and Bulk OUT endpoints.

The protocol is easy to implement on your accessory. If you’re using the ADK or other USB Host Shield compatible Arduino you can use the AndroidAccessory library to implement the protocol. The ADK is one easy way to get started with accessory mode, but any accessory that has the required hardware and speaks the protocol described here and laid out in detail in the documentation can function as an Android Open Accessory.

Communicating with the Accessory

After the low-level USB connection is negotiated between the Android device and the accessory, control is handed over to an Android application. Any Android application can register to handle communication with any USB accessory. Here is how that would be declared in your AndroidManifest.xml:

<activity android:name=".UsbAccessoryActivity" android:label="@string/app_name">
    <intent-filter>
        <action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" />
    </intent-filter>

    <meta-data android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED"
               android:resource="@xml/accessory_filter" />
</activity>

Here's how you define the accessories the Activity supports:

<resources>
    <usb-accessory manufacturer="Acme, Inc" model="Whiz Banger" version="7.0" />
</resources>

The Android system signals that an accessory is available by issuing an Intent and then the user is presented with a dialog asking what application should be opened. The accessory-mode protocol allows the accessory to specify a URL to present to the user if no application is found which knows how communicate with it. This URL could point to an application in Android Market designed for use with the accessory.

After the application opens it uses the Android Open Accessory APIs in the SDK to communicate with the accessory. This allows the opening of a single FileInputStream and single FileOutputStream to send and receive arbitrary data. The protocol that the application and accessory use is then up to them to define.

Here’s some basic example code you could use to open streams connected to the accessory:

public class UsbAccessoryActivity extends Activity {
    private FileInputStream mInput;
    private FileOutputStream mOutput;

    private void openAccessory() {
        UsbManager manager = UsbManager.getInstance(this);
        UsbAccessory accessory = UsbManager.getAccessory(getIntent());

        ParcelFileDescriptor fd = manager.openAccessory(accessory);

        if (fd != null) {
            mInput = new FileInputStream(fd);
            mOutput = new FileOutputStream(fd);
        } else {
            // Oh noes, the accessory didn’t open!
        }
    }
}

Future Directions

There are a few ideas we have for the future. One issue we would like to address is the “power problem”. It’s a bit odd for something like a pedometer to provide power to your Nexus S while it’s downloading today’s walking data. We’re investigating ways that we could have the USB Host provide just the bus mastering capabilities, but not power. Storing and listening to music on a phone seems like a popular thing to do so naturally we’d like to support audio over USB. Finally, figuring out a way for phones to support common input devices would allow for users to be more productive. All of these features are exciting and we hope will be supported by a future version of Android.

Accessory mode opens up Android to a world of new possibilities filled with lots of new friends to talk to. We can’t wait to see what people come up with. The docs and samples are online; have at it!

[Android/USB graphic by Roman Nurik.]

Android 3.1 Platform, New SDK tools

As we announced at Google I/O, today we are releasing version 3.1 of the Android platform. Android 3.1 is an incremental release that builds on the tablet-optimized UI and features introduced in Android 3.0. It adds several new features for users and developers, including:

• Open Accessory API. This new API provides a way for Android applications to integrate and interact with a wide range of accessories such as musical equipment, exercise equipment, robotics systems, and many others.
• USB host API. On devices that support USB host mode, applications can now manage connected USB peripherals such as audio devices. input devices, communications devices, and more.
• Input from mice, joysticks, and gamepads. Android 3.1 extends the input event system to support a variety of new input sources and motion events such as from mice, trackballs, joysticks, gamepads, and others.
• Resizable Home screen widgets. Developers can now create Home screen widgets that are resizeable horizontally, vertically, or both.
• Media Transfer Protocol (MTP) Applications can now receive notifications when external cameras are attached and removed, manage files and storage on those devices, and transfer files and metadata to and from them.
• Real-time Transport Protocol (RTP) API for audio. Developers can directly manage on-demand or interactive data streaming to enable VOIP, push-to-talk, conferencing, and audio streaming.

For a complete overview of what’s new in the platform, see the Android 3.1 Platform Highlights.

To make the Open Accessory API available to a wide variety of devices, we have backported it to Android 2.3.4 as an optional library. Nexus S is the first device to offer support for this feature. For developers, the 2.3.4 version of the Open Accessory API is available in the updated Google APIs Add-On.

Alongside the new platforms, we are releasing an update to the SDK Tools (r11).

Visit the Android Developers site for more information about Android 3.1, Android 2.3.4, and the updated SDK tools. To get started developing or testing on the new platforms, you can download them into your SDK using the Android SDK Manager.

Commerce Tracking with Google Analytics for Android

[This post is by Jim Cotugno and Nick Mihailovski, engineers who work on Google Analytics — Tim Bray]

Today we released a new version of the Google Analytics Android SDK which includes support for tracking e-commerce transactions. This post walks you through setting it up in your mobile application.

Why It’s Important

If you allow users to purchase goods in your application, you’ll want to understand how much revenue your application generates as well as which products are most popular.

With the new e-commerce tracking functionality in the Google Analytics Android SDK, this is easy.

Before You Begin

In this post, we assume you’ve already configured the Google Analytics Android SDK to work in your application. Check out our SDK docs if you haven’t already.

We also assume you have a Google Analytics tracking object instance declared in your code:

GoogleAnalyticsTracker tracker;

Then in the activity’s onCreate method, you have initialized the tracker member variable and called start:

tracker = GoogleAnalyticsTracker.getInstance();
tracker.start("UA-YOUR-ACCOUNT-HERE", 30, this);

Setting Up The Code

The best way to track a transaction is when you’ve received confirmation for a purchase. For example, if you have a callback method that is called when a purchase is confirmed, you would call the tracking code there.

public void onPurchaseConfirmed(List purchases) {
 // Use Google Analytics to record the purchase information here...
}

Tracking The Transaction

The Google Analytics Android SDK provides its own Transaction object to store values Google Analytics collects. The next step is to copy the values from the list of PurchaseObjects into a Transaction object.

The SDK’s Transaction object uses the builder pattern, where the constructor takes the required arguments and the optional arguments are set using setters:

Transaction.Builder builder = new Transaction.Builder(
   purchase.getOrderId(),
   purchase.getTotal())
       .setTotalTax(purchase.getTotalTax())
       .setShippingCost(purchase.getShippingCost()
       .setStoreName(purchase.getStoreName());

You then add the transaction by building it and passing it to a Google Analytics tracking Object:

tracker.addTransaction(builder.build());

Tracking Each Item

The next step is to track each item within the transaction. This is similar to tracking transactions, using the Item class provided by the Google Analytics SDK for Android. Google Analytics uses the OrderID as a common ID to associate a set of items to it’s parent transaction.

Let’s say the PurchaseObject above has a list of one or more LineItem objects. You can then iterate through each LineItem and create and add the item to the tracker.

for (ListItem listItem : purchase.getListItems()) {
  Item.Builder itemBuilder = new Item.Builder(
      purchase.getOrderId(),
      listItem.getItemSKU(),
      listItem.getPrice(),
      listItem.getCount())
          .setItemCategory(listItem.getItemCategory())
          .setItemName(listItem.getItemName());

  // Now add the item to the tracker. The order ID is the key
  // Google Analytics uses to associate this item to the transaction.
  tracker.addItem(itemBuilder.build());
}

Sending the Data to Google Analytics

Finally once all the transactions and items have been added to the tracker, you call:

tracker.trackTransactions();

This sends the transactions to the dispatcher, which will transmit the data to Google Analytics.

Viewing The Reports

Once data has been collected, you can then log into the Google Analytics Web Interface and go to the Conversions > Ecommerce > Product Performance report to see how much revenue each product generated.

Here we see that many people bought potions, which generated the most revenue for our application. Also, more people bought the blue sword than the red sword, which could mean we need to stock more blue items in our application. Awesome!

Learning More

You can learn more about the new e-commerce tracking feature in the Google Analytics SDK for Android developer documentation.

What’s even better is that we’ll be demoing all this new functionality this year at Google IO, in the Optimizing Android Apps With Google Analytics session.