You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
144 lines
5.3 KiB
Plaintext
144 lines
5.3 KiB
Plaintext
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
|