Skip to content

Old Wiki

Jump to bottom Edit New page
codeanticode edited this page Jun 14, 2016 · 9 revisions

Table of Contents

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 the following unofficial apps are on Google Play:

Instructions

After installing the mode through the Contribution Manager, you should be able to enable it through the mode selector in the PDE's toolbar. The first time you switch into the mode, if will ask to either automatically download and install the Android SDK, or select an already installed SDK.

Manual SDK Installation

To manually install the SDK, download the SDK from this link. 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 4.0.4 (API 15)”, select “SDK Platform”. The “Google APIs” item is not needed.
  • On Windows, select “Google USB Driver” beneath “Extras”.
You can install other versions of the Android API as well, but you must include version 15. 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.

Mac Users

Depending on your installation, you may need to update or create a .bash_profile file so the Android SDK can be found. Since this is a hidden file, open the Terminal and type the following command: 

 defaults write com.apple.Finder AppleShowAllFiles TRUE

Then restart the Finder to see hidden files: 

 killall Finder

You will now see all hidden files on your system; the .bash_profile file is likely in your user folder. Open it in a text editor, or create the file if it does not already exist. Add the following lines: 

 export ANDROID_HOME=/Developer/AndroidSDK
 export PATH=/Developer/AndroidSDK/platform-tools:/Developer/AndroidSDK/tools:$PATH

"/Developer/AndroidSDK" should be the path to your Android installation folder; the other path's on the second line are folders within the SDK folder. Save the .bash_profile file. To hide hidden files again, use the above commands with FALSE instead of TRUE.

Linux Users

64-bit Linux users should also install 32-bit compatibility libraries using something like the following on the command line (up to Ubuntu 12.04): 

 sudo apt-get install ia32-libs

In newer versions of Ubuntu, you can use the multiarch packages, as described here. More about platform-specific issues can be found in the links to Google's documentation (above).

Download

The latest releases of Processing can be found on the main 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 “Java”). 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, tablet, etc) 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.

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 shoulders 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 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.
  • If you get an error on OSX that reads [javac] Unable to locate an executable at “/Applications/Processing.app/Contents/PlugIns/jdk1.7.0_51.jdk/Contents/Home/jre/bin/javac” (-1), run the following commands in the Terminal:
 cd /Applications/Processing.app/Contents/PlugIns/jdk1.7.0_45.jdk/Contents/Home/jre/bin
 ln -s /Library/Java/Home/bin/javac javac

Be sure to change the JDK version to match your installation (you can go to this folder yourself by right-clicking on the Processing icon and selecting "Show Package Contents". You will need to restart Processing, but it should work! Fix via Ruairi.

Running on a Device

Before testing your sketch on your device, you must:

  • Turn on "USB Debugging" on your device - this process varies by device and which version of the OS you have installed. Try one of the following:
    • Menu → Applications → Development, then enable USB debugging
    • On the Nexus tablets, Settings → About tablet, then click on the Build number seven times to activate USB debugging (so weird).
    • Connecting to Android Wear devices requires USB Debugging as well on your Wear device. Further info on connecting to your Wear device can be found on Google's Debugging over Bluetooth
  • 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 3.0.x (API 11) 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.
  • As of today (July 2015), Gingerbread and lower versions have 5.9% market share and we don't see the point of supporting these versions. Also, we have modified PApplet such that now it extends Fragment class which is only available onwards Honeycomb. This was another reason to take this decision. We could've used support library but managing the proper version and license was another pain.
  • 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.
  • ADB (Android Debug Bridge) is a powerful command line tool for debugging/controlling your Android application. The Processing IDE alone is not enough to fully control your application. More information on the ADB can be found on Google's Android Debug Bridge documentation.

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
}

This may not work (did not for Processing 2.0b8 and a Nexus tablet); the following will allow access to the full selection of MotionEvent methods (full version here): 

import android.view.MotionEvent;

String touchEvent = "";    // string for touch event type
float pressure = 0.0;      // pressure and size variables
float pointerSize = 0.0;

// add the following to the bottom of your sketch; this code overrides the
// built-in method, then sends the data on after we capture it
@Override
public boolean dispatchTouchEvent(MotionEvent event) {

  x = event.getX();                              // get x/y coords of touch event
  y = event.getY();
  
  int action = event.getActionMasked();          // get code for action
  pressure = event.getPressure();                // get pressure and size
  pointerSize = event.getSize();

  switch (action) {                              // let us know which action code shows up
  case MotionEvent.ACTION_DOWN:
    touchEvent = "DOWN";
    break;
  case MotionEvent.ACTION_UP:
    touchEvent = "UP";
    pressure = pointerSize = 0.0;                // when up, set pressure/size to 0
    break;
  case MotionEvent.ACTION_MOVE:
    touchEvent = "MOVE";
    break;
  default:
    touchEvent = "OTHER (CODE " + action + ")";  // default text on other event
  }

  return super.dispatchTouchEvent(event);        // pass data along when done!
}
  • 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:
  <source lang="processing">
  size(displayWidth, displayHeight, P3D);
  </source>
  • 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 void settings() {
    size(displayWidth, displayHeight, 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.densityDpi;
  println("density is " + density); 
  println("densityDpi is " + densityDpi);

The Android documentation describes the 'density' value like so:

This is a scaling factor for the Density Independent Pixel unit, where one DIP is one pixel on an approximately 160 dpi screen (for example a 240x320, 1.5"x2" screen), providing the baseline of the system's display. Thus on a 160dpi screen this density value will be 1; on a 120 dpi screen it would be .75; etc.
The densityDpi value is simply 160 on a 160dpi screen, and you can guess what it is on a 240dpi screen. More can be found in the [http://developer.android.com/reference/android/util/DisplayMetrics.html DisplayMetrics] documentation.
  • The OpenGL renderer is built-in on Android, no need to use 'import processing.opengl.*;' at the beginning of your sketch. The preprocessor will actually remove that text since it would otherwise cause a conflict. This is handled by the preprocessor so that users can quickly move between desktop and Android versions without needing to incessantly comment/uncomment the import line.

API Changed, Gone, or Forgotten

  • The package for the core library remains processing.core on Android. Early releases used processing.android.core in an attempt to avoid confusion between the two platforms. Unfortunately, this requires all libraries—even those that make only basic use of PApplet features—to maintain separate sets of code for each. Because this would needlessly affect nearly all libraries, we've decided to just use the same package naming. This makes us cringe a little, but the alternative is perpetual annoyance at maintaining separate code bases for libraries for which only the package imports differ. In practice, there is little chance for processing.core packages for both platforms to ever collide with one another, since they require completely separate classpaths to build.
  • The size() method operates differently, see above.
  • Using createGraphics() with P3D/OPENGL is only available on devices that support the FBO extension properly, which is mostly Android 2.2 and later devices. Some others may work, but lots of the implementations are very buggy.
  • screen.width and screen.height are replaced by displayWidth and displayHeight. See above.
  • beginRecord, endRecord, beginRaw, endRaw are not available. There are no plans to include them, because it doesn't make sense to use them to export geometry on a handheld or portable device.
  • Registering methods (registerPost(), registerDraw(), etc) is not supported. Too much overhead for too little benefit. We'll need to bring these back in a future release.
  • All cursor-related methods have been removed. (They don't make sense in a touch-controlled interface.)
  • The all-lowercase version of arraycopy() (deprecated from the desktop version) has been removed.
  • The (long since) deprecated openStream() method has been removed. Use createInput().
  • PImage.image is PImage.bitmap, to reflect that a different object type is there, in spite of its identical purpose.
  • PFont.font is PFont.typeface, similar as above.
  • The 'online' variable is not available. It's for applets to determine whether they're running online or not, which doesn't make sense on Android, where there's no such thing as an applet.

API Replacements

  • The selectFolder(), selectInput(), and selectOutput() features don't have a general replacement on Android so they are not available as part of the API. But a contributed library provides the same features if you want to use them in Android projects.

Loading files, connecting to the internet, and permissions

If you want to load data from the internet, or otherwise connect to other servers, you'll need to enable INTERNET permission for your sketch. To do so, use Tools → Android Permissions to bring up the permissions editor. Check the box next to internet.

If you want to use methods like saveStrings() or createWriter, you'll need to enable WRITE_EXTERNAL_STORAGE so that you can save things to the built-in flash a plug-in card.

There are similar permissions for access to the phone, compass, etc. Look through the list in the permissions dialog, or check out other documentation that explains Android permissions in greater detail.

What about Multi-touch, GPS, SMS, Compass?

We hope to have simple examples or libraries for some of this. For multi-touch, I recommend this code that handles some of the awfulness. For other features, please help us out by writing examples and tutorials on how it works. Then we can include them on the site and with the Processing download.

Note, however, that any of these examples will come later—once the software and processing.core has been debugged. So don't hold your breath waiting for us. You'll be disappointed. And turn blue.

Examples

In release 0193, examples have been added for the Compass and Accelerometer. These are very basic (and need additional improvements and API tweaks), but should be helpful for getting started.

Contributed Library

The Ketai library is designed for working with Android sensors and devices in Processing. It includes classes and examples for using device cameras, hardware sensors, multi-touch gestures, databases, and peer-to-peer networking via Bluetooth, WiFi, WiFi Direct, and NFC.

Contributed Examples

Using Eclipse/Android Studio for Development

You should only use Eclipse/Android Studio for Android development if you've already spent time learning how to develop Android applications using Eclipse/Android Studio (separately from Processing), and want to make use of the Processing core library. Android development in Eclipse/Android Studio is significantly more difficult than desktop Processing/Java development with Eclipse. Take time to learn it if you're going this route: get a book, read some Android development tutorials, etc.

In case you already know how to develop Android apps using these advanced IDEs, it is not that difficult either. All our core code is bundled inside the **android-core.zip** file. You just need to rename this file to **android-core.jar** and add it as a dependency to your project. Step by step procedure for both the IDEs is as follows :

  • Make sure you have a file android-core.zip inside sketchbook/modes/AndroidMode/ directory. If not, probably you haven't downloaded the Android mode yet.
  • Create an Android project if you haven't already created one.
  • In case of Eclipse, copy android-core.zip to <project-root>/libs folder and in case of Android Studio, copy this it to &lt;project&#45;root&gt;&lt;/project&#45;root&gt&lt;/app/libs&gt;</project-root>folder. In both cases, create the libs folder if it doesn't exist already.
  • Rename android-core.zip to android-core.jar.
  • Now,
    • For Eclipse : Open eclipse. Now, right click on the jar file and then select Build Path > Add to Build Path.
    • For Android Studio : Either restart the studio or resync the gradle files.
Also, note that instead of the 'data' folder, you have to use the 'assets' folder. If you're converting a Processing project, rename your data folder to assets. Or if you have files you'd like to get at with `loadStrings()`, put them in the assets folder.

For nearly everything else, you're on your own. The point of the PDE is to not have to use something like Eclipse. When you shoot yourself in the foot, don't complain to us when it hurts. Don't take your guns to town, son. Leave your guns at home, Bill.

Sample projects for Android Studio and Eclipse

The following are basic Processing-based projects for Android Studio and Eclipse that include a minimal sketch. These can be used as the starting point for full apps.

Android Studio

Android Studio is the default IDE from Google to develop Processing apps, with the ADT plugin for Eclipse no longer supported. This sample project for AS was created using AS 1.5.1. As for the general steps to use Processing in AS:

  • Create a new project with an empty activity, and then add the Processing's sketch class and a minimal main activity to launch the fragment containing the sketch.
  • The project depends on android-core.jar, which can be obtained from by simply renaming the android-core.zip file bundled with the mode, copying it into the app/libs folder, as explained earlier, and adding it as module dependency.
  • You might also need to edit a few more files so the project is properly configured:
    • The main manifest file, where we need to specify the main and launcher activity with the intent filter:
    • The layout file, to make sure that the Processing fragment uses the entire screen with a frame layout.
    • The strings file, to set the name of the app and its main activity.
    • Change the default style to hide the action bar.
Fragments give you the possibility of embedding several Processing sketches in a single Android app, check out this sample Android Studio project from Umair Khan to learn how.

Eclipse

Although the ADT plugin for Eclipse is no longer supported by Google, I kept this section for those of you who are still hanging to it :-) This sample project. was created with Mars.2 Release (4.5.2), using the latest available version of ADT. The basic steps to create this project were:

  • Create a New Project from the File Menu, and selecting "Android Application Project" under the Android category.
  • Using the project creation wizard, set the Application options (name, project name, package name, SDKs, and Theme), and check the "Create Activity" box in the final step (although the activity can be added separately later using Eclipse's creation wizard again.
  • When creating the activity you don't need to add a fragment to it, since you will create it manually as a subclass of PApplet. The "Blank Activity" option should be enough.
  • Copy android-core.zip into the libs folder of the project, rename it to .jar, and add it to the Java Build Path, as indicated in the first section of this page.
  • The files that need to be created/modified manually are:
    • the class containing the Processing sketch, extending PApplet (and hence Fragment).
    • for main activity, so that it creates the sketch fragment in its onCreate() method
    • The main manifest file, where we need to specify the main and launcher activity with the intent filter:
    • The layout file, to make sure that the Processing fragment uses the entire screen with a frame layout.
    • Maybe adding some missing constants referenced by the manifest, such the title of the main activity in the strings file. Seems that sometimes Eclipse adds these definitions automatically, but not always.
    • Hide the action bar by adding the appropriate customization in the default style.

Debugging the android-core library

You can also help us make Processing for Android better! Either Android Studio and Eclipse+ADT allows you to debug an android app and step into the android-mode source code to understand how things work under the hood, and also find and fix bugs. In the case of Eclipse, this is actually fairly easy, all you need to do is to add the android-core project as a dependency to your main project (instead of the android-core.jar file as explained so far), and making sure that it is added to the Order and Export list in the Java Build Path. But as pointed out already, Android Studio is the only officially supported IDE for Android looking forward, so it is a better idea to use it instead.

It turns our that working with multi-project setups and depending libraries is a little bit more involved in Android Studio, at least that was my initial experience. All dependencies need to be added as subfolders alongside the main app project, and configured as Android library projects, as explained in this guide. The steps indicated in this post are also useful to understand how to work with libraries in Android Studio. Summarizing these guides, I put together another sample project where the main app depends on android-core, which is included as an Android library. A couple of important notes:

  • The build.gradle file for android-core needs to correctly identify the project as an android library, set the location of the manifest file, minimum and target SDK levels, etc.
  • Assets used by android-core, for instance shaders, need to be inside the assets folder directly inside the root of the library, and also indicated in the build file. The resource-loading code needs to be updated accordingly to reflect this location, such as here.

Integrating with other Android code

We definitely do not recommend incorporating Android GUI components into Processing sketches. The drawing model is incompatible, and like using AWT/Swing components can cause trouble with the desktop version of Processing, the same issues apply here: they might work in some cases, but will be inconsistent across other devices and/or Android OS versions.

Because a Processing sketch is an Android Fragment, it is possible to embed a Processing sketch within another application by doing some extra work, however, we don't offer embedding support neither in the Processing API nor the PDE. You would need to figure out the details on your own, and use a more advanced IDE such as Eclipse or Android Studio. Please refer to this section of the wiki on how to setup these IDEs to develop Processing-based apps.

Distributing Apps

It's a lot more fun to share your applications with other people. I'll build out this section as we clear up the features that make it easier to publish your apps on the market (or to make them available yourself from a web page). You might want to read Google's guidelines on Preparing to Publish.

Signing

To publish with the market, your application must be signed. You can use the "Export Signed Package" option in the File Menu to do it. The first time Processing will create a keystore for you, and the only required information you need to provide is the keystore password. Optionally, you can also enter first and last name, organization unit and name, city, state, and country code. The next time you use the export option, you would only need to enter the password, unless you choose to reset it, in which case you will be able to set a new password and all additional information if you want to. Once signed, the package will be available in the android/bin subfolder, inside the sketch folder, with the name <sketch></sketch>-release-signed.apk

You can also “Export” your code, and self-sign it by following these instructions from Google. A great, clear instruction on signing and deploying your app you can find here! (added by RvG)

Icons

Starting with revision 0190, it's possible to specify an icon that goes with your sketch. Actually Android wants lots of icons, which cover the varying screen resolutions where your app might show up, and the different contexts (launcher icons or a long list) where your app might be used.

All sketches use a default icon unless you specify otherwise. To create your own, save images as icon-36.png, icon-48.png, and icon-72.png. These should be 36x36, 48x48, and 72x72 pixel icons. Place them in the sketch folder (not the data folder or any other subfolder). The next time you build your app, these will be used instead of the defaults.

Your icons shouldn't just be images that use the full area of the icon. See the design guidelines for information on how to size, color, and shade your icons.

AndroidManifest.xml

Starting with revision 0190, Android sketches have an AndroidManifest.xml file in their sketch folder. This is manipulated by the various options that control permissions, naming of the sketch, etc. You can also make edits yourself, but keep in mind that breaking the manifest file can cause a lot of trouble. If you start making changes, be sure to back up your previous file first.

Also, be sure to modify the copy in your sketch folder, not the file created by using Export or Export to Application. Those will be replaced next time you use the Export function. In some cases, you may want to make tweaks to the exported folder, but be sure to move it to a new location first so that you don't inadvertently lose changes when using the Export command again.

Hello, I shouldn't have permission to edit this page

Add a custom sidebar
Clone this wiki locally