Skip to content

Tool Basics

Jump to bottom Edit New page
prisonerjohn edited this page Feb 12, 2013 · 3 revisions

What follows is a very basic example to build a Processing tool from scratch. This sample tool replaces the contents of the current sketch tab with an obnoxious message:

package toolexample;

import processing.app.Editor;

public class DestructiveTool implements Tool {

  Editor editor;

  public void init(Editor editor) {
    this.editor = editor;
  }
  
  public void run() {
    editor.setText("Deleted your code. What now?");
  }
  
  public String getMenuTitle() {
    return "A Destructive Tool";
  }
}

All tools must implement the Tool interface from the processing.core.app.tools package. It's important to note that in order for an exported tool to appear in the Tools menu, the class implementing Tool cannot reside in the default package.

If you're unfamiliar with the concept of interfaces or inheritance in object oriented programming, refer to this Java tutorial. When a class "implements" an interface it allows other code to make assumptions about how that class works. The Tool interface prescribes three methods and is defined as follows:

package processing.app.tools.Tool;

public interface Tool extends Runnable {

  public void init(Editor editor);

  public void run();

  public String getMenuTitle();
  
}

Tool Methods

public void init(Editor editor)

This 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, its usually a good idea to store the Editor object as a class variable for use in the run() method.

public void run()

This method will be called by the main application when the tool is selected from the menu. This is called using SwingUtilities::invokeLater(), so that the tool can safely use Swing or any other GUI.

If your tool needs to open a window, you may want to use the Frame class from the java.awt package. The first time run() is called you'll create the Frame object. Subsequent calls to run() should check to see if the Frame is still open. If it is, the Frame should be brought to the front of the screen. If not, a new Frame should be created. This ensures the user won't create superfluous instances of your tool's window(s).

You can really do anything in the run() method. In lieu of opening a new window, you can use the statusNotice() and statusError() methods in Editor to let the user know what's happened. See below for a list of Processing classes sanctioned for use in tool development.

public String getMenuTitle()

This method simply returns the title for what should appear in the Tools menu. Typically the body for this method looks something like return "Tool Name";. Ordering in the Tools menu is alphabetical.

We've yet to implement shortcut assignment for contributed tools. Resolving keystroke collisions between user contributed tools and the rest of the environment is tougher than it might appear.

What Tools Can and Cannot Do

The following classes have been sufficiently documented for use in Tool classes:

processing.app.Base

The base class for the main Processing application.

processing.app.Editor

Main editor panel for the Processing Development Environment.

processing.app.Preferences

Storage class for user preferences and environment settings.

processing.app.Sketch

Stores information about files in the current sketch

processing.app.SketchCode

Represents a single tab of a sketch.

For the most part, your code should use the methods provided by the Editor API. Of course, you're welcome to explore the documentation and leverage objects that Editor's methods might return (most notably JEditTextArea). Developers should use caution when accessing/manipulating these objects as they might disrupt existing PDE interface elements or features. Contributed tools will be scrutinized to ensure no such issues exist before being included for promotion on the Processing Tools page.

Structure of a Tool Folder

Tools should be distributed as zipped files, and the distribution should be laid out as follows:

MyTool/tool/MyTool.jar
MyTool/src/

The tool folder contains the tool's .jar file (and if necessary, any additional .jar, .dll, .so, or .jnilib files). The name of the outermost folder must conform to the name of the class implementing the Tool interface. The name of the JAR contained in /tool/ does not matter. When Processing loads, the JAR will be searched for MyToolClass.class. Once again, package names are required.

See the Eclipse Tool Template for information on compiling a JAR for your tool.

Describing Your Tool -- tool.properties

Processing 2.0 will support installing tools from within the PDE. To make the installation of your tool as easy as possible, you should add file named tool.properties to the base directory of your tool. For example, if we were to extract ColorSelectorPlusTool.zip, we should see the following file structure:

ColorSelectorPlusTool/tool.properties
ColorSelectorPlusTool/tool/ColoSelectorPlusTool.jar
...

In tool.properties, you should include the following attributes:

# UTF-8 supported.

# The name of your tool as you want it formatted.
name = HelloTool

# List of authors. Links can be provided using the syntax [author name](url).
authorList = [Your Name](http://yoururl.com)

# A web page for your tool, NOT a direct link to where to download it.
url = http://yourtoolname.com

# The category of your tool, must be one (or many) of the following:
#   "3D"            "Animation"     "Compilations"      "Data"          
#   "Fabrication"   "Geometry"      "GUI"               "Hardware"      
#   "I/O"           "Language"      "Math"              "Simulation"    
#   "Sound"         "Utilities"     "Typography"        "Video & Vision"
# 
# If a value other than those listed is used, your tool will listed as "Other".
category = Other

# A short sentence (or fragment) to summarize the tool's function. This will be
# shown from inside the PDE when the tool is being installed. Avoid repeating
# the name of your tool here. Also, avoid saying anything redundant like
# mentioning that it's a tool. This should start with a capitalized letter, and
# end with a period.
sentence = A collection of utilities for solving this and that problem.

# Additional information suitable for the Processing website. The value of
# 'sentence' always will be prepended, so you should start by writing the
# second sentence here. If your tool only works on certain operating systems,
# mention it here.
paragraph =  

# Links in the 'sentence' and 'paragraph' attributes can be inserted using the
# same syntax as for authors. 
# That is, [here is a link to Processing](http://processing.org/)


# A version number that increments once with each release. This is used to 
# compare different versions of the same tool, and check if an update is 
# available. You should think of it as a counter, counting the total number of 
# releases you've had.
version = 1  # This must be parsable as an int

# The version as the user will see it. If blank, the version attribute will be 
# used here.
prettyVersion = 0.1.1  # This is treated as a String

Advertising Your Tool

Starting with Processing 2.0, tools that are advertised on Processing's website also have the option of being advertised through the PDE. To support this, you'll need to include a tool.properties file with your tool and make a few changes to how it's hosted on your server.

First, you must include the following attributes in tool.properties:

  • name
  • authorList
  • url
  • category
  • sentence
  • version

You'll also need to provide a static link to the latest version of your tool, and host a copy of your tool.properties alongside it. The result on your server should look something like this:

http://www.example.com/awesometool.zip/ (The latest version of awesometool)
http://www.example.com/awesometool.txt/ (A copy of the tool.properties file contained in awesometool.zip)

Once everything is in place, send your static 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 of advertised tools.

On our end, we'll only record the location of awesometool.txt, and we'll assume that a copy of the tool file is hosted at an address by the same name, except ending in zip. Each day, a script on processing.org will scrape the information from all the .txt files and aggregate it into a single file, which is then used by each user to browse what's available and check for updates. Even if your tool is not being advertised, you should still include the tool.properties file inside your zip.

Releasing An Update

When you want to release a new version of your tool, here's what you'll need to do:

Option 1: Manual Update

  1. Update your tool.properties file inside your .zip
  • Increment the value of version. This is an integer that we'll use to check for updates. You can think of it as a counter, counting the total number of releases you've had.
  • Write whatever you want for the new value of prettyVersion.
  1. Copy your latest release to the static address you gave us earlier (e.g. http://www.example.com/awesometool.zip)
  2. Copy the tool.properties file from your latest release to a .txt file hosted at an address by the same name as your .zip, except instead ending in .txt (e.g. http://www.example.com/awesometool.txt)

Option 2: Update using the Eclipse Tool Template

  1. Update your build.properties file from the resources folder.
  • Increment the value of tool.version. This is an integer that we'll use to check for updates. You can think of it as a counter, counting the total number of releases you've had.
  • Write whatever you want for the new value of tool.prettyVersion.
  1. Recompile the project using the Ant script. This will generate the appropriate files in the distribution/name-version/download folder.
  2. Copy your latest release and properties files to the static address you gave us earlier (e.g. http://www.example.com/awesometool.zip and http://www.example.com/awesometool.txt)

That's it. The next time the aggregator script runs and your users start the PDE, they'll be notified that updates are available.

Add a custom footer
Add a custom sidebar
Clone this wiki locally