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