Applet Export
Application Export
Applet Security Restrictions
"Present" Features
Applet Export
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:
- index.html
HTML file with the applet embedded and a link to the source code and the Processing homepage. Doubleclick this file to open it in the default Web browser. - Sketch_123.jar
Java Archive containing all necessary files for the sketch to run. Includes the Processing core classes, those written for the sketch, and all included media files from the data folder such as images, fonts, and sounds. - Sketch_123.java
The JAVA file generated by the pre-processor from the PDE file. This is the actual file that is compiled into the Applet by the Java Compiler used in Processing. - Sketch_123.pde
The original program file. It is linked from the index.html file. - loading.gif
An image file displayed while the program is loading in a Web browser.
Every time a sketch is exported, the contents of the "applet" folder are deleted and the files are written from scratch. Any changes previously made to the "index.html" file are lost. To customize the HTML that's included when an applet is exported, copy the applet.html file from Processing → lib → export to the root of your sketch folder.
Media files not needed for the applet should be deleted from the data folder before exporting to keep the file size small. For example, if there are unused images in the "data" folder, they will be added to the JAR file, thus needlessly increasing its size.
When exporting an applet, a description can be included on the default HTML page that's created. Processing will include everything from the first instance of /** to a closing */ as a javadoc comment. So you can add this to your sketch:
/** * You can't rock Processing like I can rock Processing. */and that text would automatically be embedded in the exported html page. Like a javadoc comment, the text can (and should) be any valid html since it will be embedded directly in the page. Asterisks at the left of each line will be removed.
Application Export
In addition to exporting Java Applets for the Web, Processing can also export Java Applications for the Linux, Macintosh, and Windows platforms. When "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.
Making applications can be trickier than applets. Some hints and notes follow below. If you find problems, file a bug.
- Just like when exporting as an applet, 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());
Note that within the PDE, the icon will only show up when a code folder is in use or a library has been imported. However, it should show up on all occasions when exported to an application. - 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 may not work properly.
- If you just want an executable jar file, export as an applet. Executable jar files will most likely not work with libraries 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).
Applet Security Restrictions
Applets running inside a web browser have several security restrictions, in order to protect web users. For instance, an applet cannot read files from the local disk or connect to servers other than the server from which it came. To avoid these restrictions, it's possible to "sign" an applet. In a signed applet, a dialog box will appear to ask the user whether they trust you as the provider of the applet, and if it's ok for the applet to perform actions that might be a security risk. More information can be found in Sun's documentation.
"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).