| TOOLS IN PROCESSING |
| |
| With initial help from code contributed by fjen, Processing release 0147 and |
| later have a dynamically loading tools menu, which can be used to expand the |
| environment in fun and fantastic ways. |
| |
| A Tool is a chunk of code that runs from the Tools menu. Tools are a means |
| of building onto the Processing Development Environment without needing to |
| rebuild the beast from source. |
| |
| The interface (at least for now) is extremely simple: |
| |
| |
| package processing.app.tools.Tool; |
| |
| public interface Tool extends Runnable { |
| |
| public void init(Editor editor); |
| |
| public void run(); |
| |
| public String getMenuTitle(); |
| } |
| |
| |
| The init() method is called when an Editor window first opens. This means |
| you won't have access to a sketch object, or a GUI, and should only do minimal |
| setup. (However it'd be a good idea to stash the "Editor" object for later.) |
| |
| The run() method will be called by the main application when the tool is |
| selected from the menu. This is called using invokeLater(), so that the tool |
| can safely use Swing and any other GUI yackety yack. If you're using a Frame, |
| you'll need to detect whether the Frame is already open (and bring it to the |
| front) or whether to create a new window. |
| |
| Faceless tools also use the run() method. You should avail yourselves of the |
| statusNotice() and statusError() methods in Editor, to let the user know what's |
| happened. (As per p. 107 of the Processing Development Environment Tools |
| Reference User Interface Guide.) |
| |
| The getMenuTitle() method just returns the title for what should appear in the |
| Tools menu. Not doing shortcuts for now, because resolving them between tools |
| (and the rest of the interface) is fugly. We would also need additional |
| modifiers for shift and alt. It just gets messy quick. Ordering in the Tools |
| menu is alphabetical. |
| |
| |
| ////////////////////////////////////////////////////////////// |
| |
| |
| Where to put Tools |
| |
| Core tools live inside the "tools" subfolder of the Processing distribution, |
| however users should install "contributed" tools in their sketchbook folder, |
| inside a subfolder named "tools". |
| |
| If a tool works only with a particular release of Processing, then it may make |
| sense for the user to put things into the Processing tools folder, however we'd |
| like to keep users out of there as much as possible. In fact, it may not be |
| visible in future releases of Processing (for instance, on Mac OS X, the tools |
| folder is hidden inside the .app bundle). |
| |
| Tools should be laid out similar to libraries, though the structure is a little |
| more flexible. The tool folder should be the name of the main class (without |
| its package name but using the same capitalization), and have a subfolder named |
| "tool" that contains the .jar and .zip files it uses. I'll use the included |
| "Mangler" tool as an example. |
| |
| (This Tool is not built by default, due to a lack of non-dubious arguments |
| regarding the usefulness of including (by default) a Tool that mangles code.) |
| |
| The folder should be called Mangler (note the capitalization), and contain: |
| |
| sketchbook/Mangler -> tool folder |
| sketchbook/Mangler/tool -> location for code |
| sketchbook/Mangler/tool/mangle.jar -> jar with one or more classes |
| |
| The naming of jar and zip files in the tool/* directory doesn't matter. |
| |
| When Processing loads, the jar and zip files will be searched for |
| Mangler.class. Even though this tool is found in package poos.shoe, |
| it will be sussed out. Package names are required. |
| |
| Loose .class files are not supported, use only jar and zip files. |
| |
| |
| ////////////////////////////////////////////////////////////// |
| |
| |
| What You Can and Cannot Do |
| |
| The only API methods that are officially scrubbed and sanctioned by the |
| Commissioner on Fair API and Proper Manners for use by the Tools classes |
| are found in: |
| |
| processing.app.Base |
| processing.app.Editor |
| processing.app.Preferences |
| processing.app.Sketch |
| processing.app.SketchCode |
| |
| In fact, most of the API you should be talking to is inside Editor. |
| Full API documentation can be found on dev.processing.org: |
| http://dev.processing.org/reference/everything/ |
| (Keep in mind that this is not always perfectly up to date, but we'll try.) |
| |
| Of course, you're welcome to go spelunking through the rest of the API |
| (that's where all the fun stuff is anyway), but don't be upset when something |
| changes and breaks your tool and makes your users sad. |
| |
| Currently, native code is not supported with tools. This might be possible, |
| but it's another potentially messy thing to dynamically add native library |
| paths to running code. (See "Future Releases" below.) |
| |
| |
| ////////////////////////////////////////////////////////////// |
| |
| |
| Future Releases |
| |
| In future releases, we are considering the following features: |
| |
| 1. How shortcut keys are handled. |
| http://dev.processing.org/bugs/show_bug.cgi?id=140 |
| |
| 2. Whether to allow tools to dock into the Preferences panel. |
| http://dev.processing.org/bugs/show_bug.cgi?id=883 |
| |
| 3. A means to run native code from the Tools menu. |
| http://dev.processing.org/bugs/show_bug.cgi?id=884 |
| |
| 4. Methods for reorganizing the Tools menu, or placing contributed |
| Tools inside other menus (such as Edit or Sketch). |
| http://dev.processing.org/bugs/show_bug.cgi?id=885 |
| |
| This is the first round of documentation for the Tools menu, we reserve the |
| right to update, clarify, and change our mind in future releases. |
| |
| |
| ////////////////////////////////////////////////////////////// |
| |
| |
| Ben Fry, last updated 19 August 2008 |