Export Info and Tips

From Processing

Application Export

Processing can export Java Applications for the Linux, Macintosh, and Windows platforms. When the "Export Application" button is pressed or "Export Application" is selected from the "File" menu, a dialog box opens and you can select which platforms you want to export to. You may also select if you want the application to run full screen (in present mode). A folder will be created for each of the operating systems selected; each folder contains the application, the source code for the sketch, and all required libraries for a specific platform.

Some hints and notes follow below. If you find problems, file a bug.

• The "application.xxxx" folders will be removed completely on export.

• It is important that you don't have a method named main() in your sketch, unless you know what you're doing (writing your own main). Otherwise this will fool the preprocessor into thinking you have a clue, when in fact you don't.

• If running in "Java" mode, where your code starts "public class blah extends PApplet", you'll need to write your own main() method in order for Export to Application to work. It should look something like this:

static public void main(String args[]) {
    PApplet.main(new String[] { "YourClassName" });
}

Not doing this, or using your own main can cause problems internally with variables not being properly set up. If you opt not to use PApplet.main(), make sure you read the source code for it so that you understand how it works, and don't whine if it breaks.

• The "Movie" and "Capture" examples do not yet work properly, this will be fixed shortly. (Bug 230)

• Exporting sketches that use the video library may be broken, it's not clear the extent of this issue (Bug 231), but it will be repaired for a future release.

• When exporting for Mac OS X from Windows, be sure to read through the readme.txt file in the application.macosx folder—your application likely won't work on Mac OS X without a minor modification.

• The Mac OS X export is a nice .app bundle like a regular OS X application. You can change the icon or edit its settings by using "Show Package Contents" and editing Info.plist or replacing sketch.icns with something more exciting.

• Windows is a shell .exe that calls the code and requires the "lib" folder along with it be kept intact. Someday we might make Windows be a nice single .exe file, but this requires more time to implement, and more specifically, make work consistently with the libraries. If you're finicky about this, use a Java EXE generator such as JSmooth or launch4j.

• To set the icon used on the title bar for Windows, use the following code: (submitted by dxtx)

ImageIcon titlebaricon = new ImageIcon(loadBytes("myicon.gif"));
frame.setIconImage(titlebaricon.getImage());

• Linux is just a shell script, which can probably be used on most Unix platforms (there's almost nothing to it).

• When distributing your application, the "source" folder can be removed from the export if you'd like, but other files (such as the lib folder and any .dll files or whatever) should be left intact otherwise the application will not work.

• If you just want an executable jar file, export as an applet. Executable jar files will not work if you're using libraries or a code folder because the path information will not be properly set, and the additional library jars won't be referenced.

• Library writers can now specify what files to export for each platform, see the updated libraries/howto.txt for more information.

• Your current memory settings will be exported with the application. If you've set outrageous memory requirements, you might want to undo that before exporting for others, or edit the exported files by hand (Contents/Resources/Info.plist on Mac OS X and lib/args.txt on Windows).

• If you want to replace (or add) titlebar text, just do this in setup():

frame.setTitle("This is in the titlebar!");

(thanks dxtx for pointing this out)

• Holding down shift while clicking "Export" on the toolbar will export to application instead of an applet.

• Except for Mac OS X, users will need to install Java to use your exported application. To avoid the installation requirement, you can also copy the "java" folder from Processing to the same folder as your application. This also ensures that a certain version of the Java VM is used. At least for now, the error message shown when Java is missing may be nonexistant or cryptic. Similar to Processing itself, the folder can also by a symbolic link (but not a Mac OS X or Windows shortcut) to the Java runtime installation.

• Someday we'll also add features like icon files to the applications produced by Processing. Or at least a default icon for the exported stuff. Or maybe even a splash screen while Java is loading. Again, if you want more control, use your own application generator (see above for Windows, or use the Java package maker whatchamacallit on Mac OS X).

"Present" Features

• The ESC key will quit a sketch, even in Present mode. To prevent this from happening, intercept the ESC on keyPressed() so that it isn't passed through to PApplet. Use the following code to prevent ESC from quitting the application:

void keyPressed() {
  if (key == ESC) {
    key = 0;  // Fools! don't let them escape!
  }
}

• You can hide the stop button with the --hide-stop command line option to PApplet. More details about command line options are above in the "Export to Application" section. From inside the Processing environment, you can't hide the stop button (unless your sketch window obscures it anyway) easily, so better to export as an application.

• To make a sketch run with a window the size of the screen, use size(screen.width, screen.height). The "screen" variable will be initialized with the width and height of your main display (your default monitor).

Applet Export

Note: Applets aren't supported in Processing 2.0+

The export feature packages a sketch to run within a Web browser. When code is exported from Processing it is converted into Java code and then compiled as a Java Applet. When a project is exported, a series of files are written to a folder named "applet" that is created within the sketch folder. All files from the sketch folder are exported into a single JAR file with the same name as the sketch. For example, if the sketch is named "Sketch_123", the exported file will be called "Sketch_123.jar".

The applet folder contains the following:

/**
 * You can't rock Processing like I can rock Processing.
 */

We use the deployment script because it takes care of handling more special cases (and there are many, in web development) than the regular code in the file. And we don't include deployJava.js with each download because it would add 17kb to every sketch, instead of using something that can be cached once by your browser, and available to any applet that might use it.