Android

From Processing

Jump to: navigation, search
spacer

Contents

  • 1 About Processing for Android
  • 2 Instructions
  • 3 Download
  • 4 Android Mode
  • 5 Troubleshooting, Discussion, and Known Issues
    • 5.1 Common problems
    • 5.2 Running on a Device
  • 6 Developing for Android
  • 7 Understanding changes to processing.core
    • 7.1 Mouse, Motion, Keys, and Input
    • 7.2 Screen, Orientation, and the size() command
    • 7.3 API Changed, Gone, or Forgotten
  • 8 Loading files, connecting to the internet, and permissions
  • 9 What about Multi-touch, GPS, SMS, Compass?
    • 9.1 Examples
    • 9.2 Contributed Library
    • 9.3 Contributed Examples
  • 10 Using Eclipse for Development
  • 11 Integrating with other Android code
  • 12 Distributing Apps
    • 12.1 Signing
    • 12.2 Icons
    • 12.3 AndroidManifest.xml

About Processing for Android

The primary goal of this project is to make it foolishly easy to create Android apps using the Processing API. Once you have Processing on your machine (and the Android developer tools), you can simply write a line of code, hit Run (Ctrl-R or Cmd-R), and have your sketch show up in the emulator as a working Android app. Select Run on Device (Ctrl-Shift-R or Cmd-Shift-R) to have it run on an Android device that you have plugged into your machine. That's good stuff!

Note that this code is incomplete and contains bugs. It should be considered "beta" quality. Do not use this code while operating heavy equipment. Do not rely on this code for thesis or diploma work, as you will not graduate. Do not use this code if you're prone to whining about incomplete software that you download for free.

We currently have no plans to make a version of the development environment (the PDE) that runs on the phone, but that might be fun for you internetpeople to hack together on your own, and amaze us all.

Instructions

spacer

Download and install the Android SDK from here. Instead of the default “ADT Bundle” link, click “Use an Existing IDE” toward the bottom of the page, and then click the “Download the SDK Tools” button.

After downloading, follow Google's instructions here and then for the Adding Platforms and Packages section, do the following:

  • Underneath “Tools”, check the box for “Android SDK Platform-tools”. (The “Android SDK Tools” item will already be installed.)
  • Beneath “Android 2.3.3 (API 10)”, select “SDK Platform”. (As of Processing 2.0b7, you longer need to include the “Google APIs” item.)
  • On Windows, select “Google USB Driver” beneath “Extras”.

At the right is an image of what it looks like on Windows (current as of December 2012). If any of the items above are missing from the list, use the checkboxes next to “Show” at the bottom of the window.

64-bit Linux users should also install 32-bit compatibility libraries using something like the following on the command line:

sudo apt-get install ia32-libs

More about platform-specific issues can be found in the links to Google's documentation (above).

You can install other versions of the Android API as well, but you must include version 10. You can't install API 13 or 14 or 17 just because it's newer. Also note that these revisions are for the individual "SDK Platforms" (which refer to Android OS versions), which is different from the revision numbers (see the Rev. column in the GUI) on the "Android SDK Tools" mentioned above. Confusing? Yes.

In keeping with the spirit of the Processing project, we hope to remove the Android SDK installation step from the download/install process (Issue 203). If you'd like to see that made a higher priority, click the star icon at the top of that page. (Or better yet, help us implement it!)

Download

The latest releases can be found on the main download page.

Due to significant SDK changes by Google, Processing 2.0a7 (and later) requires Android SDK Tools revision 20 (or later). Later versions of Google's tools may break this release of Processing, but I'll do my best to keep things up to date.

Note that due to major changes by Google to the Android dev tools, Android mode in older versions of Processing do not work. For best results, use the latest that's on the download page.

Please do not use earlier releases and older SDKs. Help us out by using the most current release and filing a bug if you run into a problem.

Read the revisions.txt document in the download to find out what's new and old in this release.

Android Mode

To build for Android, select “Android” from the drop-down box in the toolbar (by default it reads “Standard”). This places the current editor window into Android mode. To show you that you've now entered a new world, the window will also get a lot more green.

The Run and Export features change a bit in Android mode:

  • Run in Emulator - preprocess the current sketch, create an Android project, and run (debug) it in the Android emulator.
  • Run on Device - the same as Run, but run on a device (phone) that's attached by USB.
  • Export Android Project - creates an 'android' folder that contains the files necessary to build an APK using Ant.
  • Export Signed Package - same as export, but creates a signed version of the 'release' build for the market. (not yet implemented, coming soon)

Troubleshooting, Discussion, and Known Issues

Use this forum for questions about Processing for Android. Do not put questions in the general questions category, otherwise it's gonna be a confusing mess.

Do not use the forums to post bug reports, I cannot fix bugs if they only show up on the forum, and I cannot track bugs that are posted there.

If you find a bug, please file it here, clearly noting that it's an issue on the Android side. Please report issues: as much as I'd like to sit over the should of you and the other 40-50,000 people who will do battle with Processing this week, current laws of physics disqualify me. If it's not in the bugs database, I don't know about it, and it probably won't be fixed. Second, it's much easier for me to mark a bug as duplicate rather than trying to separate a new issue that's been added to an existing bug, so please just file issues (however related they may seem) separately.

A list of known bugs, sorted by priority, can be found here.

If it's a known bug, just click the star at the top of the bug report. This gives it a “vote,” and lets me know that more people are having the problem. (Do not reply to the report and say "this is broken!" because we already know that.)

Common problems

  • If you get an error that reads “Error: Android Virtual Device 'Processing-Android-10' already exists.”, select “Android SDK & AVD Manager” beneath the Processing “Android” menu, and delete the Processing-Android-7 AVD. It will be automatically re-created the next time you try to run a sketch.
  • On 64-bit Linux, “File not found” errors in the console for things like “aapt” means that you didn't read our installation instructions (above) or Google's as they pertain to 64-bit systems.

Running on a Device

Before testing your sketch on your device, you must:

  • Turn on "USB Debugging" on your device. Press Menu, select ApplicationsDevelopment, then enable USB debugging.
  • If you are running Windows or Linux, you need to read Google's Using Hardware Devices documentation to install a special USB driver and take care of additional settings.

Developing for Android

  • The emulator stays running, even after you hit stop. This is because it takes a fortnight to launch the emulator. You don't have that kind of time.
  • We're only supporting Android 2.3.3 (API 10) and later. After years of supporting Java 1.1, we're not going to start out this Android effort by supporting already abandoned (by Google) versions of the OS. It's already difficult enough supporting a myriad of devices, screen resolutions, and installed features across what's currently available. And it's only going to get worse better.
  • We had hoped to support Android 2.2 (Froyo, API 8), since it's still (as of March 2012) running 25% of the devices out there, but starting with 2.0a5, we'll only be supporting Android 2.3.3 (Gingerbread, API 10) and later. Due to a major API omission in the OpenGL bindings before 2.3, we can't support the earlier OS. There could be ways around this, or we could require 2.3 only when using OpenGL, but we don't have enough (any) developers to support this sort of thing.
  • As of 2.0b7, you can place files in a 'res' folder inside your sketch and they'll be copied to the Android build for use. Note that this copying happens *after* files are built and moved to res, so make sure you don't have files with the same names as those used by Processing (the default layout, icons, etc), *or* make sure that you know what you're doing. This was implemented to address issue 767, which was about NFC support and other hardware libraries.
  • Performance reminds me a lot of Java performance on desktop machines when we first started the project in 2001. Most Processing sketches will benefit significantly from the JIT that arrived with Android 2.2 (Froyo). There are some things that we can speed up, but short of writing everything in native code, we'll be praying for enhancements to the Android platform.
  • Android seems to have a very shallow stack depth, perhaps ~32 calls. As a result, you might get StackOverflowError in code that worked fine with the Java version of Processing.
  • You cannot use .gz files in the data or assets folder, because Android wants to compress the files itself.
  • Accuracy of colors is more limited on Android. Most screens will not be full 24-bit color, which especially shows up with gradients, highly detailed color sketches, or when using a lot of transparency. With gradients, you might see banding of colors, or when using transparency, you might see halos or visual artifacts left behind. These are just mathematical artifacts due to how colors are handled, subject to limitations of the screen.
  • Using createFont() (instead of loadFont()) can help improve text quality, particularly with 2D rendering. Use PFont.list() to get a list of available fonts on the system, and select one of those, or include a .ttf or .otf file in the data directory of your sketch.
  • Because all code for Android exists inside packages, any .java files included with your sketch that do not specify a package will be placed into the same package as the main class for your sketch. This breaks the "we won't touch .java files with the preprocessor" rule we have on the desktop side, but the alternatives are truly much worse. We simply don't support packages at this point on the desktop side, so don't get any weird ideas about adding package declarations to your .java files in general. If this bothers you deeply, stop taking yourself so seriously you'll probably be happier using Eclipse for development.

Understanding changes to processing.core

A guide for the excited, hopeful, weary, and confused.

Mouse, Motion, Keys, and Input

In a future release, we plan to include a proper API for touch and gesture events. Unfortunately, it looks like time is running out to bake this into the 2.0 release, so we're backing off a bit. In 2.0 beta 7, a number of changes have happened to make things more compatible with the desktop and JavaScript versions of Processing:

  • The motionX, motionY, motionPressure, etc. variables have all been removed. This was sort of a kludge, and it'll be handled better by a later touch API. It should be easy to bring them back with a dozen lines of code in your sketch, if you were relying on them. Instead, just use mouseX/Y for now.
  • Processing now has classes called Event, KeyEvent, and others like it, so you'll have to specify “android.view.KeyEvent” instead of just “KeyEvent” when you're using the Android version. (See usage in the examples below.)
  • The "mouse drag" events have less fidelity in 2.0b7 than they did in earlier releases, because we're now ignoring the "history" field in the event. Again, you can override the code with your own version if you want more detail. But because the artificial "mouse" events are a compatibility workaround, we don't want to slow things down just to support them for the future.
  • To get at the native android.view.MotionEvent that prompted a "mouse" event, use the following code (in 2.0b7 and later. This is also how to bring back the motionX/Y/Pressure variables, the extra fidelity on mouse drags, or anything else that involved Android-specific API. You can do something similar with key events as well, though that's probably less necessary.
import android.view.MotionEvent;
 
void mouseDragged() {
 MotionEvent me = (MotionEvent) mouseEvent.getNative();
 // code here, like me.getHistorySize() and other Android-y things
}
  • For compatibility, mouseX and mouseY work similar to the original API, and always contain the most recent mouse position.
  • The mouseButton variable is not available, for perhaps obvious reasons.
  • Watch out for rollovers. While commonly used in mouse-based interfaces, they don't make any sense for touch interfaces. Lots of sketches (most of them, really) will need to be rewritten for use on Android to make better use of the affordances given by the hardware.
  • To use the virtual keyboard, hold down the MENU key on the device. This is an Android default, but some users might not be familiar with it.
  • The 'back' key works similar to ESC in the desktop version of Processing. (Pressing ESC in the emulator actually emulates hitting the 'back' key, though it may beep at you first.) By default, this will exit your application. If you want to do something smarter, override keyPressed() and set 'key' to 0 so that the key doesn't get picked up by the base class. Also note that android.view needs to be in front of KeyEvent, because Processing has its own KeyEvent class.
  void keyPressed() {
    // doing other things here, and then:
    if (key == CODED && keyCode == android.view.KeyEvent.KEYCODE_BACK) {
      keyCode = 0;  // don't quit by default
    }
  }
  • Constants for ALT, CONTROL, and SHIFT are not present. SHIFT may come back, but the other two don't exist on Android. However, in 2.0b7, methods like keyEvent.isShiftDown() or keyEvent.isAltDown() have been added (for parity with the desktop release) so that you can make use of them in event handling.
  • The LEFT, RIGHT, UP and DOWN constants are mapped to the directional pad. To get the center button on the d-pad, use DPAD (added in revision 0190). Keep in mind that the meaning of UP, DOWN, LEFT and RIGHT can feel different based on the hardware: it might be a trackball, or an optical pad, or even hard buttons.
  void keyPressed() {
    if (key == CODED) {
      if (keyCode == DPAD) {
        // user pressed the center button on the d-pad
      } else if (keyCode == UP) {
        // user triggered 'up' on the d-pad
      } else if (keyCode == DOWN) {
        // user triggered 'down' on the d-pad
      } else if (keyCode == LEFT) {
        // user triggered 'left' on the d-pad
      } else if (keyCode == RIGHT) {
        // user triggered 'right' on the d-pad
      }
    }
  }
  • Starting with revision 0190, new constants for the BACK and MENU keys are available, as seen in this example:
  void keyPressed() {
    if (key == CODED) {
      if (keyCode == BACK) {
        // do something here for the back button behavior
        // you'll need to set keyCode to 0 if you want to prevent quitting (see above)
      } else if (keyCode == MENU) {
        // user hit the menu key, take action
      }
    }
  }

Other key codes can be found in the Android documentation for KeyEvent. We're including what we feel are the essentials, so as not to pollute the namespace too much. To use one of those constants, you'd do something like the following, replacing KEYCODE_HOME with whatever other key code you wish. For instance, you might want KEYCODE_VOLUME_DOWN, KEYCODE_VOLUME_UP, KEYCODE_CAMERA, etc.

  void keyPressed() {
    // doing other things here, and then:
    if (key == CODED && keyCode == android.view.KeyEvent.KEYCODE_HOME) {
      // override the home key here
    }
  }

Screen, Orientation, and the size() command

  • The main issue with size() is that it doesn't make a lot of sense on a mobile device. Outside of compatibility with older sketches, there isn't a good reason to set the width and height of a sketch.
  • The size() method operates differently on Android. If no size() method is used, then the sketch is opened and uses the entire display. Use the width and height variables to get the size of the display that's available to you. Then, make calculations in your sketch based on how those are set. Also note that if the phone/device is rotated while the sketch is running, the sketch will reset, and the width and height updated.
  • One reason to use the size() method is to set the renderer to use 3D. (Like the desktop version, the default is the built-in 2D renderer). To use 3D, it's recommended that you use something like:
  size(displayWidth, displayHeight, P3D);
  • Android is even more particular about the "no variables in the size() method" rule found in the desktop version. This is because the size() method is actually removed from the sketch. Behind the scenes, source like:
  void setup() {
    size(displayWidth, displayHeight, P3D);
  }

will be removed from the source when it's preprocessed, and turned into:

  void setup() {
  }
 
  public int sketchWidth() {
    return displayWidth;
  }
 
  public int sketchHeight() {
    return displayHeight;
  }
 
  public String sketchRenderer() {
    return P3D; 
  }

Basically, we opted not to duplicate the (error-prone) dark magic used in the desktop version to change the sketch size mid-setup.

  • There are only two renderers on Android. If you specify JAVA2D (or no renderer at all), it will use the built-in Android 2D renderer. P2D, P3D and OPENGL specify graphics rendered OpenGL.
  • In previous releases we also had A2D and A3D (which were aliases to the same 2D and 3D renderers), but those only create confusion. In the 2.0 alpha releases, those constants have been removed.
  • Because the size() command is handled by the preprocessor, Eclipse users will have to write sketchWidth(), sketchHeight(), and sketchRenderer() methods if they want to control the size. In most cases, you shouldn't need to mess with the size, but you may want to override the sketchRenderer() method so that you can use P3D.
  • If you're more capable with Eclipse than reading comprehension, the previous points boil down to: When using Eclipse, 1) never call size(), 2) don't try to specify dimensions via sketchWidth/Height methods, and 3) if you want to use 3D instead of 2D, add this single method to your sketch:
  public String sketchRenderer() {
    return P3D; 
  }
  • Including both size() and the sketchXxxx() methods in a sketch will cause an error. Don't do that.
  • Use displayWidth and displayHeight instead of screen.width and screen.height. Since Processing 2.0a6, both variables have been added to the desktop version of processing.core, where the screen variable has been deprecated. Aside from this being more consistent with the rest of the Processing API, the java.awt.Dimension type that's used for screen is not present on Android. The screen variable was something that was being used internally and then others began to use it so we felt compelled to document it. Not a terribly well thought out decision.
  • Use keypad 7 or keypad 9 to rotate the emulator one direction or another. Or if you don't have a keypad or numlock, like you're using a laptop from the all-knowing geniuses from Cupertino, then press Ctrl-F12 (Ctrl-Fn-F12 on OS X) to rotate the screen.
  • If you want to lock orientation to one direction, you can use one of the following commands inside setup(). These are new as of revision 0190.
  orientation(PORTRAIT);  // the hamburger way
  orientation(LANDSCAPE);  // the hot dog way
  • We considered using size() as a hint for whether the emulator should open in portrait or landscape mode, but decided against it because it 1) added additional complexity, and 2) there wasn't a good way to control what actually happened one you're started up. Would it lock in one orientation? Hm, too clever. Instead, we're keeping it simple and we'll play it by ear.
  • Screen density and pixels/dots per inch can vary greatly between devices. If you need specific information about density to make your application work, you can use the DisplayMetrics class from android.util. Use the following to get the density and densityDpi for the sketch:
  // Place this at the top of your sketch
  import android.util.DisplayMetrics; 
 
  // Place this inside your setup() method
  DisplayMetrics dm = new DisplayMetrics();
  getWindowManager().getDefaultDisplay().getMetrics(dm);
  float density = dm.density; 
  int densityDpi = dm


gipoco.com is neither affiliated with the authors of this page nor responsible for its contents. This is a safe-cache copy of the original web site.