Skip to content

Mode Overview

Jump to bottom
Ben Fry edited this page Jan 20, 2023 · 3 revisions

Modes allow Processing users to code and run sketches in different languages and on different platforms. The default Mode in the Processing Development Environment (PDE) is called “Java Mode”, and compiles Processing code (with its Java-like syntax) to run sketches on the Java Virtual Machine (JVM). The name of the selected mode for each sketch appears in the small drop-down menu in the upper-right corner of the sketch window. To begin a sketch in a different mode, create a new blank sketch and then select a different mode type from that drop-down before editing the sketch contents.

Additional modes may be installed and include Android Mode, Python Mode, p5.js Mode, CoffeeScript, Processing.R, among others.

Installing modes

In PDE, modes may be installed via via the Contributions Manager "Modes" tab. A shortcut to this tab from any sketch window is the mode dropdown menu → Manage Modes. For more on Modes in the PDE interface, see the Environment reference page.

Note: Modes are distributed through PDE, however there are some Modes, like CoffeeScript, which are no longer compatible with Processing 3 and later. (They only run on Processing 2 and earlier.)

Other projects are related to or inspired by Processing but that are not distributed as modes. They are available as stand-alone applications. Examples include JRubyArt, p5py, and pyp5js.

Modes, Languages, and Libraries

Modes enable writing Processing sketches in different programming languages: Python mode in the syntax of Python 2, R mode in R, p5.js in JavaScript. Each mode has its own language documentation and examples. All modes implement core features of Processing such as setup, draw, size, point, line, rect, stroke, fill, translate, and rotate... but they may differ in language specific-ways: different variable types, naming conventions, or things available in some modes but not others such as advanced features (PShape) or included libraries (p5.dom).

Modes also target different platforms: p5.js runs in the web browser, Android mode runs on Android devices, Python and R mode are both transpiled into Java to run on JVM, much like the default mode.

Modes are compiled anr/or run on diffent platforms. This affects whether and how modes can access Processing (Java) libraries -- or libraries in their own language. The following table lists some currently available modes in PDE, what platform they run on, and their access to P5 libs and/or native libs.

Mode Language Runs on Processing libraries Language libraries
Java Processing Java JVM all any Java
Android Java Android many Android Java
p5.js JavaScript browser no p5.js libraries, potentially anything in JavaScript
p5py Python 3 Python 3 no Python 3
Python Python 2 Jython/JVM many any Java, pure Python 2
R R Renjin/JVM many any Java, some R

Differences in how and where a mode runs affect how that mode can access other Processing code or language libraries. p5.js runs in JavaScript, so it can interact natively with other JavaScript libraries developed for the web—but it cannot use Processing contributed libraries developed in Java, as they will not run in a browser JavaScript engine. By contrast, the Python and R modes run as Java, so they can load many of the same Java libraries that are available for the default Processing mode. However, unlike p5.js these modes are limited in what libraries they can use from their "native" language: Python mode's Jython interpreter can import most "pure" (uncompiled) Python 2 packages without compiled dependencies, while R mode's Renjin maintains a list compatible R packages. Compiled libraries, scientific libraries, and libraries with many dependencies tend not to work.

Note: some libraries are published for multiple modes, with e.g. a Java Mode and p5.js version.

Where to Put Modes

PDE Contributions Manager automatically places downloaded and installed modes inside the Processing folder in a folder named modes. You may also install modes directly by unzipping them to Processing/modes. This can be useful during development for testing. You may need to restart PDE to detect a manually installed mode.

Creating Your Own Mode

Documentation on how to author and build a Mode is currently incomplete.

Mode developers currently learn by examining the structure and layout existing modes on their public code repositories.

There is also a mode template for PDE 3.

If you are building your own mode, IntelliJ is the recommended development environment. It's not possible to build Modes from within the Processing application. Like libraries, creating a Mode with the PDE will cause problems because the JAR file exported from the PDE will contain the current version of the processing.core classes, which will cause major conflicts when trying to use the PDE. Modes that contain processing packages in this manner will have to be rejected or removed from the site. Use an IDE such as IntelliJ or Eclipse to build new Modes.

How Distribution Works

On startup, the PDE Contributions Manager downloads the latest contribs.txt file. It uses this information to display the Mode in the Contributions Manager and to check for updates against any currently installed version.

When the user clicks "Download" on a mode, the Contribution Manager looks for a zip file at the download link specified in contribs.txt, such as:

https://py.processing.org/4/PythonMode.txt

The PDE then downloads the Mode, unzips it, verifies it as valid, and installs it into the folder Processing/Modes/PythonMode.

Distributing a Mode with the Contributions Manager

In order for modes to be distributed via PDE Contributions Manager, the mode must:

  1. define properties by creating a mode properties txt file, e.g. mymode.txt
  2. build and package the mode in a zip file with an identical name, e.g. mymode.zip
  3. release the mode by uploading both files to the same public URL directory.
  4. list in PDE by submitting the .txt URL to Processing for listing in the PDE file sources.conf

For an existing example, see Python mode:

To update a mode, update the txt and zip. No changes need be made to sources.conf.

1. Define properties: the properties .txt file

This enables discovery, download, and update of your mode through PDE. Each time you release a new version of your mode, you must update the properties file in order to notify PDE Contributions Manager that a new update is available.

A properties .txt file looks like this:

name=p5.js Mode
category=Unknown
authors=[Fathom Information Design](http://fathom.info/)
url=https://github.com/fathominfo/processing-p5js-mode
sentence=Adds a simple editor for p5.js code
paragraph=p5jsMode is a simple editor for p5.js
version=16
prettyVersion=1.5.1
minRevision=1280
maxRevision=0
imports=processing.mode.java.JavaMode

Use the minRevision and maxRevision entries to restrict your Mode to certain Processing revisions. For instance, if your Mode requires the final version of Processing 4.0, that's revision 1285 (the revision numbers can be found in the revisions.md file). Set either of these to 0 (or leave them out entirely) to specify no minimum (or maximum).

Use the imports line if your Mode depends on an existing Mode. In the example above, p5.js Mode extends the class processing.mode.java.JavaMode, so this makes sure that the necessary class files are loaded.

The file may be hand-edited. However, many modes generate them automatically at build time. For example, Python Mode uses a mode.properties template file which is filed out during the build process, e.g. using Eclipse.

Note: The .properties file should be encoded as UTF-8. This is different from other .properties files in Java (reference) that use ISO 8859-1 encoding.

2. Build and package: the .zip file

This is the downloadable and installable release of your mode. It is created during your build process, e.g. using Eclipse.

Documentation on how to author and build a Mode is currently incomplete.

3. Release: publishing the Mode

In order to publish your mode (and update it thereafter) in a way that is compatible with PDE discovery, you may upload your latest txt and zip file to any public URL, so long as they have the same exact name/path with different extensions.

For this example, we will assume:

  • You have created a public repo https://github.com/foo/mymode/
  • You have written your mode, it builds, and it can be locally installed in PDE
  • You are using a GitHub repo and GitHub releases for your public URLs -- although this could be any web server.

To publish your mode, whether the first time or as an update:

  1. build your mode, creating build artifacts mymode.txt and mymode.zip
  2. use git tag to tag your release commit with a semantic version number, e.g. v1.0
  3. push the tag/commit to GitHub
  4. create a release
    • on github.com, navigate to releases in your repo -- e.g. https://github.com/foo/mymode/releases -- and begin creating a new release
    • select the tag, e.g. v1.0
    • attach the two build artifacts to the release: mymode.txt and mymode.zip
    • publish the release

Your mode is now available via two URLs:

...and those have two corresponding download URLs:

This second URL is stable—it always refers to whatever the attachment on the latest release. That will be important for later listing in PDE.

To update your mode, follow the numbered steps above again. Your new release will have a new tag and release URL, e.g. v1.1, but it will also be available at GitHub latest, replacing the old release. You do not need to submit any changes to sources.conf after your first release -- all future updates to your public .txt + .zip URLs will be automatically discovered by PDE Contributions Manager, generally on PDE restart.

List in PDE: appearing in the Contributions Manager for install

Once you have published your .txt and .zip files to a stable URL, send those links to the Processing Librarian: Elie Zananiri. We'll review your properties file to make sure everything is in order and add your contribution to the list. New listings are discovered by the Contributions Manager—generally on restart—and available for download.

Note: Submitting your mode for listing in PDE only needs to be done once, not every time you make a new release. All future updates to your public .txt and .zip will be automatically discovered by a script that auto-generates contribs.txt on a daily basis.

Clone this wiki locally