Your Own Java Components

Extending the Canvas class

By Andrew Downs

This article assumes you know what Java is and how object-oriented programming works at a conceptual level. You should also be familiar with C syntax, as that is the basis of Java syntax. This project was developed with Roaster™, the first Macintosh Java integrated development environment (IDE). Roaster is a stable product, easy to use, and priced competitively.

Java provides the Canvas class for developers creating their own Graphical User Interface (GUI) objects. We extend the Canvas class to create a GUI design tool applet. It shows how to create objects that function primarily as data containers, similar to structs in C. This is a useful intermediate step for programmers who are learning object-oriented programming. This article also shows the addition of methods that set and return the object variable values. We will use the data and methods to draw an outline of our object, and move it around inside a window. Our project will run as a Java applet.

Stretching Canvas

When you hear the word canvas, you probably think of what painters paint on. In this article, we will build upon that metaphor. First, some background information is in order...

Java’s Abstract Windows Toolkit consists of classes. (See Figure 1.) The Component class defines a generic GUI primitive; classes like Button, Choice, and Canvas are subclassed from Component. (Component is an abstract class, which is a class that is used not to instatiate objects, but to group similar classes together.)

The Component class defines many useful properties (that’s Java for class variables) for a generic object, and methods (Java for functions) for getting and setting the values of those properties. These properties include the bounds, color, text, and numerous others. When you create a class that extends a class, your new class inherits the properties and methods of the parent class. (The terms “extend” and “subclass” are synonymous.) You can override (redefine) methods inherited from the parent class, and you can also define new methods and properties. (The exception to this inheritance rule are classes and methods declared using the final keyword, which indicates that the class cannot be inherited or the method overridden. )

Figure 1. Class Hierarchy

Canvas is a subclass of Component (which is itself a subclass of Object, the topmost Java class), provided for programmers who wish to subclass from Component. If you want to create and manipulate your own components, do not subclass Component; extend Canvas instead. A Canvas is a Component that does no default drawing or event handling on its own. By subclassing Canvas, you will have access to Component’s properties and methods.

In our project, we extend the Canvas class with two subclasses. First, we create a backdrop to draw on, called the BackdropCanvas class. Unlike many drawing surfaces, this backdrop plays an active role in our project; it has its own properties and methods. Second, we create a generic object class, called the DecafObject class, which forms the basis of the GUI objects we will create and draw on the backdrop. This generic object class will also have its own properties and methods.

We need to determine how to construct our applet, and what it will include. The general steps we will follow are:

• define the frame (window) that will hold our backdrop

• create/initialize an instance of our backdrop

• define the objects to display on our backdrop (both properties and methods)

• create/initialize the objects we will draw on our backdrop

To make things more interesting, we will also create a separate frame that will function as our “tool palette”. This tool palette will contain buttons that let us control objects on our backdrop, popup menus that let us set the colors of objects, and a button to let us gracefully exit our applet.

Figure 2 shows the relationships between the Java source code files that comprise our project. Each file contains one class definition. Demo.java, the file in the center of the diagram, is our actual applet definition; the Demo class extends the Applet class. The arrows indicate that most activity flows through the Demo class. The ToolPalette class houses the definition for our tool palette. When a user clicks on one of the buttons or popup menus on the tool palette, the ToolPalette class gets the selected item, then passes control to Demo. Demo then takes appropriate action by passing information to methods in other classes.

BackdropCanvas is our backdrop class. When the user requests that a new object be created (by clicking on “Add Button...” or “Add Panel”), ToolPalette informs Demo, which in turn informs BackdropCanvas. BackdropCanvas then creates a new instance of DecafObject, the class that contains our generic object information.

BackdropCanvas also handles drawing DecafObjects and maintains information about the drawing environment. The DecafObjects exist as a doubly-linked list, which means that each object contains a reference to the object before and after it. BackdropCanvas maintains a reference to the first object created. When the backdrop need redrawing, it retrieves a reference to the first object, it obtains that object’s properties, draws the outline, then gets the reference to the next object. Many of the methods in the BackdropCanvas class use this approach to walk the list of objects.

Figure 2. Class/file relationships for this project.

Figure 3 shows our project definition within Roaster. The files listed are the source files, each ending in a .java extension, that contain the classes our applet uses. Each file contains one class declared with the keyword public.

The AppletViewer.class file is supplied with Roaster. The arrow next to AppletViewer.class indicates that it is selected as the startup file. The startup file must contain a main() method. When you select “Run”, Roaster automatically launches Roaster Applet Runner, which then reads the selected startup file

Figure 3. Our project definition within Roaster.

(AppletViewer.class), using its main() method to setup the display and input/output environment for our applet.

The startup file can be selected through the “Startup class name” field in the Preferences dialog. Setting this field to “mac/applet/AppletViewer” assigns AppletViewer.class as the default startup file for new projects.

Applet Initialization

Our applet is defined in the class named Demo. Listing 1 shows the entire Demo class definition (contained in the source file Demo.java). At the top of the file we list the Java classes we want to import, which is similar to #include-ing header files in C. We then define our applet class, which is called Demo. It is declared public, and is an extension of the Java Applet class. (All applets must extend the Applet class.) Within the Demo class, we reserve space for several variables which refer to instances of our other classes. We also create the variable myDemo, with which our applet can refer to itself.

Once our class variables are declared, we call the init() method to set up the class. In init(), we create a frame (our applet’s main window, for you non-Java types out there). In this frame (or over it), we will stretch our backdrop on which we draw. We also set up our tool palette, and the “Add Button” dialog, which remains hidden until called for. I will describe these additional class definitions shortly.

Following init() are our applet’s other methods. When looking through the methods, remember that the Demo class serves as the focal point for requests made from our ToolPalette. User requests get passed from the Tool Palette to Demo, which then calls the appropriate methods in theBackdropCanvas to draw and change objects. Such an architecture gives us the flexibility to reuse these classes in other programs. You may wish to refer back to Figure 2 to clarify the class relationships.

To give you an idea of what our applet looks like, Figure 4 shows our applet running in Roaster Applet Runner. The method Demo.init() has just finished, so each of the Demo class variables that refer to other classes has been instantiated (assigned values). The tool palette is shown to the left of our backdrop frame (which contains theBackdropCanvas). Both frames are selectable and moveable.

Figure 4. Our applet running in the Roaster Applet Runner.

The BackdropCanvas class

We now need to define our BackdropCanvas class, which functions as our backdrop. Let us start with some properties. What do we need? Here is a short list:

• a way to reference the objects we will create later

• a way to keep track of the colors for our new objects and our BackdropCanvas

• the state of the mouse

• the cursor location, relative to the bounding rectangle of any selected object

In addition to properties, we need to add some methods for controlling the painting of objects on our backdrop and for handling mouse-clicks.

Listing 2 shows our BackdropCanvas class. The import statements at the top of the file are the same for all our class files. We then define our BackdropCanvas class as public, and as an extension of the Java Canvas class. Within BackdropCanvas we reserve space for several variables which refer to instances of our objects. (I will describe these objects later in this article.) We also keep track of the background color for our BackdropCanvas, and the state of the mouse (up or down, within a grow region, etc.).

If you remember, the init() method from our Demo class creates a new instance of our BackdropCanvas class and stores the reference in the variable theBackdropCanvas. Creating a new BackdropCanvas is accomplished through a constructor method called BackdropCanvas(). If you look through the constructor methods for our other classes, you will notice that the constructor method has the same name as the class, and may or may not take arguments. The constructor method for BackdropCanvas sets the default background color for the backdrop.

Following BackdropCanvas() are the other methods for this class. When looking through the methods, remember that BackdropCanvas serves as a relay point for object actions requested through our Demo class. These methods are primarily used to draw and change objects.

The DecafObject class

Keep in mind that we intend to paint on our BackdropCanvas. Naturally, we need something to paint. Let’s create another subclass of Canvas, this time called DecafObject. The DecafObject class will be our object class. When we want to create a new object, we create a new instance of the DecafObject class.

Listing 3 shows our DecafObject class. We need to make sure our variables get initialized properly for each new object. We also add two methods for each variable: one for getting its value, one for setting its value. This getting and setting code can get long, it’s true, but it gives you some flexibility to change variable names and determine what actually goes on “behind the scenes” in the DecafObject class. The alternative, accessing the DecafObject variables directly from other classes without going through methods, becomes difficult to maintain as your code grows and your data structures change.

Purists may ask why we did not use the Component method Component.bounds() to get the bounding rectangle of our DecafObject. The answer is that I had some trouble screening mouseDown events within the BackdropCanvas and sending the events to individual DecafObjects for handling. The object coordinates did not relate properly to the BackdropCanvas.

Instead, I decided to handle the mouseDown events only within the BackdropCanvas. To accomplish this, we maintain a separate bounding rectangle for each DecafObject. The coordinates of this bounding rectangle are always calculated in relation to the origin (upper-left corner) of the BackdropCanvas. The BackdropCanvas retrieves this bounding rectangle for each DecafObject to pin down the recipient of the mouseDown. This may not be the best solution, but it works.

The ToolPalette class

[For a tutorial on layouts and panels, see this month’s Getting Started.]

The tool palette is used to control our applet. Refer to Listing 4 for the class definition, and to Figure 5 to see it running. We will use a simple frame containing four buttons and two popups: the buttons Add Panel, Add Button, Delete Item, and Quit, a popup to select an item, and a popup to select an item’s color.

We use panels to group interface components. Each panel has an associated layout. The Java Layout class organizes interface elements within the panel, based on the layout you specify.

We create two panels. On the first, we place our buttons; on the second, we place our popups. We then create the appropriate buttons and popups and add them to the appropriate panels. We then add the panels to the frame, theToolPalette.

We use a GridLayout for both of the panels. The GridLayout allows us to specify the number of rows and columns the layout contains, making it easy to align the buttons and popup menus. This gives a neat, if rigid, appearance. We can add space between items in the grid by either: a) adding a blank label instead of a button or popup menu, or b) specifying hgap and vgap parameters when creating the GridLayout. (The terms hgap and vgap refer to the horizontal and vertical gaps between items in the grid.) We use the first method for pColorPalette to add a blank row between the popup menus.

ToolPalette contains many string and label variables with hardcoded values. Macintosh programmers know how to use resources for text-based items. Text resources can be changed easily when modifying the application or porting it to another language. No such mechanism currently exists in Java; there are not even the C language #define macros that allow you to define all your string constants in one place. To translate a Java applet into another language, someone needs to go through your sources, manually editing each text string in you code.

There is a solution. We could create a class comprising variables declared static final to use as constants throughout our applet. The keyword static indicates that one copy of the variable will be shared by all instances of the class, and final indicates that the variable cannot be overridden by a subclass (and thus modified). Another benefit: we would not have to actually create an instance of such a class in order to reference its variables. An example of this kind of class is the Java System class, which defines variables and methods that can be used by an applet without explicitly creating an instance of the System class (Anuff, 1996, and Ritchey, 1995).

ToolPalette has a method for handling action() events. In our applet, action() events are generated when the user selects one of the buttons or popup items on our tool palette. The parent class, Frame, has an action() method, which the programmer is supposed to override with his own code.

Inside our action() method, we check to see if a button was clicked or a popup item selected, and if so, call the appropriate method in the Demo class. If you look at the Demo methods called from our action() method, you will observe that they often call methods in the BackdropCanvas class. Remember from earlier in this article that the Demo class serves as a focal point for handling user interaction: control passes from the tool palette to the applet (myDemo), then to theBackdropCanvas or another frame if appropriate.

Aside from ToolPalette(), there is one other method in this class that gets called externally (from other classes): doGetColor(). This method returns the values associated with the popup menus (which are stored in theItemColorArray). It takes as a parameter an integer specifying the item (of the object). It returns an integer representing the color of the item. The actual matching of the integer to the corresponding color (i.e. a 1 corresponds to Color.green) is performed by the calling method.

Figure 5. Our applet after adding a panel.

The NewButtonFrame class

We need a way to prompt for a button label when the user selects “Add Button...” from the tool palette. We will use a simple frame containing a text entry field and two buttons: OK and Cancel. This frame will serve as our new button dialog. We need only the label text because:

• the default location for the new button is hardcoded in the DecafObject class definition

• the color is selectable using the popup menu on the tool palette

NewButtonFrame is shown in Listing 5 and in Figure 6. In this class, we first create a text field and label, then a panel on which to place them. Next, we create our OK and Cancel buttons, and a panel to contain them. Once the panels are created and the appropriate components (text field, label, and buttons) added, we add the panels to theNewButtonFrame.

This class also has a method for handling action() events. Once again, we override the action() method of the parent class, Frame. Inside our action() method, we check to see if a button was clicked. In response to Cancel, we simply hide the Frame. In response to OK, we retrieve the contents of the text field, send the text off to Demo for adding to the button, then hide the Frame.

There is one method in NewButtonFrame that gets called externally: doSetupDefaults(). This method clears the text string in the text input field. It is called from Demo just before displaying the Frame.

Figure 6. NewButtonFrame in action.

Figure 7. Our applet with two panels and two buttons.

Improvements

There are several ways to improve our code. One way is to put more of the initialization and drawing methods into the DecafObject class, and let each object handle everything relating to itself.

A second way involves limiting the scope of our object data and methods. Currently, most of the methods within each class are declared public, but some of them could be private. Private data and methods would better protect a class against inappropriate calls from outside it.

A third way involves managing our objects using existing classes. We can eliminate the need for our doubly-linked list by making use of the Vector class, which uses a list to keep track of objects. If we create an instance of the Vector class, we can use the methods Vector.addElement(), Vector.removeElement(), and Vector.elementAt() to add, remove, and retrieve objects from this list. Of course, there are several variations of these methods for finer control.

Since access to our DecafObjects is straightforward (thanks to our doubly-linked list), we can also support writing each object’s properties to a file. Maybe in a future article...

Using Roaster

This article was written using Developer Release 1.1, a stable but incomplete version of Roaster. Roaster provides a familiar project-based environment for developers to work in. You create a new project, then add the appropriate files to it. You can select one or more files for compiling, and/or make the project to produce runnable code. There are also menu choices for clearing and updating the method list for each class file. Also, Roaster has a Message Window which displays compile errors. Double-clicking on an error takes you to the offending line of code.

Roaster preferences include the categories of Editor, Text Styles, Compiler, and Project. You can use font, style, size and/or color to distinguish between comments, reserved words, and the remainder of your code. Roaster includes both the javac (Sun) and Roaster compilers, although NI recommends using the javac compiler for now, since it is more stable than the current Roaster compiler. This should soon change; NI is working to remove the bugs from its compiler, which is faster than the javac compiler.

Occasionally I found it necessary to compile the files within projects based on their hierarchical relationship. That is, source files containing classes that were imported into other classes, but not vice versa, needed to be compiled first. Other times I found it necessary to remove the class files from the project directory, then remake the project.

The more RAM you have, the better. I was very happy with the performance of both Roaster and Applet Runner on a PowerMac 7100/90 with 16 MB of RAM. It also performs reasonably well on a PowerMac 6100/60 with 8 MB of RAM.

I look forward to being able to create standalone (self-contained, double-clickable) applications with Roaster Pro. It is possible to make our applet into an application by adding a main() method to our Demo class, then selecting Demo as the startup file. This eliminates the need to include AppletViewer.class in our project. The Roaster FAQ discusses in more detail how to do this. You can obtain the FAQ using the Roaster URL listed at the end of this article.

Writing applets is slightly simpler, although Roaster Applet Runner requires that we create a simple HTML document that contains a reference to our applet (refer to Listing 6). This information is provided in the Roaster documentation. As noted previously, we also need to set AppletViewer.class as our startup file in the project definition.

Natural Intelligence has provided a stable, easy-to-use product which should set the standard for Java development environments on the Macintosh.

Credits

Thank you to John Dhabolt of Natural Intelligence for proofreading this article and suggesting several enhancements.

Bibliography and References

Anuff, Ed. Java Sourcebook. Wiley Computer Publishing (1996), pp. 89-92.

Ritchey, Tim. Programming with Java! New Riders Publishing (1995), pp. 183-4.

URLs

Class files: http://www1.omi.tulane.edu/adowns/MacTech/source/

Demo applet: http://www1.omi.tulane.edu/adowns/MacTech/demo/

Current version of the Decaf applet:

http://www1.omi.tulane.edu/adowns/decaf/

Roaster product information: http://www.roaster.com/