maxwell planck

undergraduate researcher
aesthetics + computation group
mit media laboratory
mplanck (at)


[ my research ] [ treehouse studio demo ] [ how to extend ths ] [ the future of ths ]
[ the source of ths ] [ personal site ] [ resume ] [ misc ]


This section is still under construction. I'm around for the summer doing other things, but I'm still anxious to polish this documentation off. If you are involved with the development of this project, please update this section.

Why Extend Treehouse Studio?

I very much want this project to grow and branch based on input from many different designers. For now, I want designer/programmers to add their own painting tools and in so doing feel nostalgia for the tools we once knew and have now outgrown. Furthermore, this process could help reground designers into the basics and reveal that sometimes the restriction of the MacPaint simplism is effective in creating some powerful designs. The following material describes how you can add your own tool or menu item that adds functionality to the applet.

On a grander note, I'd also like the Studio to expand with more applets added. Right now, I have a simple painting applet, but the possibility of having a vector based applet, an animation applet, even a video editing applet, etc. could be a reality. I've designed the code keeping in mind that this sort of expansion is charted for the future. Therefore, I am also planning to add documentation about the generic framework that the paint canvas lies within.

How to Extend Treehouse Studio

First of all, you'll need the code.

Secondly, you'll need to first make sure you can compile the darn thing. I work with Project Builder of Mac OS X (my preferred developing machine), so I've included the project file. I keep away from packages, so you shouldn't have to deal with that mess. The main applet file is I'm still in the process of commenting and cleaning up the code, so be patient. The following tutorials will guide you through how to add to this applet as well as create your own applet using the framework provided. Refer to one of the following sections if you have a specific question:

The Class Structure of the Treehouse Studio

The code has a naming convention to help explain the code on first glance. All classes with the prefix THS are classes I recommend you don't replace or drastically modify. These classes implement the framework of the applet while the other classes handle all action that occurs within the painting canvas. These classes are also contained in the treehouse package. So if you are using any of the original framework, make sure to add the line:

import treehouse.*;

The Treehouse Studio applet is essentially a layout of panels that interact by sending messages between each other. One interacts with the panels by mouse and key input. A panel, therefore, implements the resulting action of all possible inputs the user can make. What happens when the mouse is pressed? What happens when it's dragged? What happens when a key is held? The applet works by taking in any given input and relays the message to the panel if the input falls within it's region (for mouse input only). As for key inputs, every panel receives the message and performs its respective action. Furthermore, panels can also contain imbedded panels, and therefore, can relay an input through itself to one of its children.

The main applet class is called THSApplet. This class holds all panels in the applet and tells all applets to paint every time the applet is refreshed. If you are planning to make your own Applet, make your main applet class an extension of this one. In the paint applet, PaintApplet is the main class that extends to THSApplet. It is within this extension class that you can modify and add menus and menu items. If you are planning to make a new application with the given framework, follow the comments in the code and make sure to replace the doSetup() method with the specific methods that will initialize your canvas area. See PaintApplet for an example of how to setup.

A THSPanel is an abstract class representing a generic panel. It contains functionality for determining if a given coordinate falls within itself, for handling and adding children panels. It also defines abstract methods that must be implemented by its subclasses, including:

public abstract void mouseDown(Event ev, int x, int y);
public abstract void mouseUp(Event ev, int x, int y);
public abstract void mouseDrag(Event ev, int x, int y);
public abstract void mouseMove(Event ev, int x, int y);
public abstract boolean keyDown(Event ev, int k);

public abstract void paint(Graphics g);
public abstract void message(String fromWho, Object odat);

The first methods handle all mouse interaction when the mouse is within that panel and the keyDown method handles any key input. The paint method must be implemented so the applet knows how to paint that particular panel when the applet's paint method is called. The message method is used so that other panels inside the applet can relay information to each other. For example, if the icon palette panel wants to tell the paint canvas panel if a new tool has been selected, it calls the paint canvas panel's message method passing it information that it is the one doing the messaging as well as the object data it is passing through. A message method should be able to discern who is sending the message and then do something with the given object. Furthermore, the icon palette is able to message the paint canvas because the instantiation of the canvas is set as the target of the icon palette (using the setTarget method).

The THSIconPanel class is a subclass of a THSPanel provided to act as essentially a toolbox. A user can access any of the tools within the icon panel and the class is actually responsible for passing the paint canvas the tool with which the user can create. Once the selected tool is determined, the paint canvas then passes all input to the tool (asking what how to paint). A tool object is an extension of the THSGeneralTool class, which describes the generic methods of a tool:

public abstract void mouseDown(int mx, int my, THSCanvas c);
public abstract void mouseMove(int mx, int my, THSCanvas c);
public abstract void mouseUp(int mx, int my, THSCanvas c);
public abstract void mouseDrag(int mx, int my, THSCanvas c);

public abstract boolean keyPressed(Event ke, int k, THSCanvas c);
public abstract boolean keyUp(Event ke, int k, THSCanvas c);
public abstract boolean keyDown(Event ke, int k, THSCanvas c);

public abstract String getIconImage();

public abstract String getCursorImage();

public abstract String getString();

The first two sets of methods describe how the paint canvas will respond to any of the given inputs. The last three methods are used to identify the name, icon image, and cursor image for the tool. The icon image is just a string describing the name of the GIF file. An icon image and a name are required. Right now, the cursor image is not implemented, but will be in the future. For now, just return an empty string. Refer to examples of tool implementation in the source code. To add a tool to the icon panel, refer to the section below.

The menu bar of the applet is implemented by a group of classes. The menu bar itself is an extension of a THSPanel called THSMenuBar. A THSMenuBar class then has a set of menus which are instances of the THSMenu class, which is also an extension of THSPanel. The menus, therefore, are children panels of the menu bar. The menu bar, therefore, relays inputs through itself to it's children and then handles any menu item selection and messages the paint canvas. Each menu object has a set of menu item instances that are NOT extensions of panels (this is important to note). A menu item is essentially an extension of the THSGeneralMenuItem class which defines an abstract framework for a menu item. A menu item simply has the name that would be displayed in the menu bar and then an actuate method. The actuate method determines how the menu item will act on certain objects. The menu item classes themselves are in the THSMenuItems class, which is a factory class that produces menu items with the static method makeMenuItem(). All menu item classes specific to the applet are placed in an extension of the THSMenuItems class. In the paint applet, PaintMenuItems is the extended class. Take a look at the source for THSMenuItems and PaintMenuItems to get an idea of what I'm talking about.

The paint canvas itself is a subclass of a THSCanvas which is a subclass of a THSPanel. The PaintCanvas class handles all painting to the actual image being created by the user, it also parses byte data when saving and opening. It asks the selected tool how to behave when painting by relaying the input it receives from the applet. It also receives any messages from the menu bar, icon palette, and color palette, and then interprets the object data sent to it.

The THSWriteCanvas class is an abstract class that defines the method framework for converting a canvas to bytes and then for converting bytes to a canvas. Extend this class to implement your own particular byte encoder/decoder. The paint applet uses PaintImageRasterizer as the implementation. Take a look at the class for an idea of protocol.

THSIOPortal is a straightforward class that interacts with the database. It can be used to save and load canvases from the database. Take a look at the comments along with the code to get an idea for its use. It's important to note that doOpen() and doSave() should be overridden with a call to the super class function. This feature allows any one to add to the functionality of saving and loading without touching the core code that interacts with the DB. In other words, any subclass of THSIOPortal should be a true subtype according to the two functions described above.

The ColorPalette class provided in the source is specific to the paint application and is also an extension of the THSPanel class. It simply relays whether or not to change the paint canvas' foreground or background color. You can take a look at the source to better understand what is going on, or even use the panel in your own application.

To implement a new applet, all you'd really have to do is make a new extension of the THSCanvas class and the THSApplet class and then make new tools for that particular applet. You can also make other panels to help your user in his or her creation process (see below for details-- UNDER CONSTRUCTION).

back to top

How to Add a Menu Item

To add a menu item, you'll need to first start with an idea of what functionality you'd like to add. Most of the tools I've been working on mimic the old MacPaint functionality, but I encourage you to think of new tools to make the applet more enjoyable. Keep in mind that the focus of the applet is to let students explore painting on computers with a very pixel by pixel state of mind. Don't make things too complicated.




back to top
  © 2003 | maxwell planck