There are many introductory programming assignments that involve objects in a two-dimensional data structure. They include games, like tic-tac-toe, checkers, and chess; maze programs; simulations, like Conway's Game of Life† or the AP® Marine Biology Simulation (MBS) case study‡; and simpler programs that use a grid as graph paper for drawing histograms or bit-mapped drawings. These projects lend themselves to graphical representations, but the overhead involved in implementing graphical user interfaces for such assignments, especially interfaces that support user interaction, is non-trivial. The Grid Package provides a set of simple Java classes for modeling objects in a two-dimensional grid, and provides a library of other classes that make it easy to create graphical user interfaces to display and interact with such models.
The Grid Package started out in the fall of 2002 as the Environment Package,
a refactoring of the graphical user interface provided with the AP® Marine
Biology Simulation (MBS) case study†. In
December 2003 it underwent a major revision and a name change, when
the MBS
Environment class and Locatable interface were dropped
as the core modeling classes at the heart of the package in favor of the current Grid and GridObject classes. The
reason for this change was that the Locatable interface cannot
guarantee that objects in an environment satisfy the Environment object
invariant that an environment and the objects in it must agree about the object
locations. The
GridObject class not only specifies a location method,
but also provides a changeLocation implementation
that guarantees that the invariant is always met. Once I decided
not to stick with the Environment and Locatable classes
as they appear in the MBS, it became possible to make other small changes that
improve the readability, flexibility, or generality of the Grid and GridObject classes.
The package was revised again in the summer of 2004 with the help of Joel
Booth, a senior at Kalamazoo College. This revision included introducing
the RotatedDecorator and ScaledImageDecorator classes,
and moving toward customizing user interfaces using includeXYZ methods
(e.g., includeMenu,
includeRunButton, etc) rather than using a myriad of constructor
parameters. The
"nuggets" and "util" classes (e.g., ClearGridButton, ColorChoiceMenu, BasicHelpMenu, NamedColor, and ValidatedInputReader)
were also added at that time.
The package is now quite stable, although some of the documentation is still under construction. Please contact me if you find errors, have questions, or wish to make a suggestion.
javadoc class documentation for all classes in the package.javadoc
class documentation for all classes in the package.grid.jar),
the draft Overview
document and a set of examples, and the complete javadoc documentation
for the classes in the package.javadoc class documentation.javadoc class documentation.grid.jar), without any documentation or examples.The assignments above were developed using Eclipse and so come with
Eclipse project files already in place. They can be used, however, with
any Java compiler or IDE; the key is to know how to incorporate the
grid.jar Java archive file into your application
under your specific compiler (analogous to handling the mbsbb.jar
and mbsgui.jar files in the MBS case study).
+libs folder under the folder containing the
assignment source files (e.g., JavaSourceFiles or
src), then move the grid.jar file to the new
+libs folder. Bring up BlueJ, choose "Open Non
BlueJ..." under the "File" menu, and navigate to the source folder.
After you have opened it once as a non-BlueJ application you can subsequently
open it as a BlueJ project.
You may delete the CompiledClassFiles and
JavadocDocumentation folders since BlueJ will generate
compiled class files and javadoc documentation under the source file
folder.
To run the examples in the main Grid Package
OverviewAndExamples folder, you may need to pull the
various examples out of the single ExampleSourceFiles
folder into separate folders. For example, you might create an
Example1 folder, move Example1.java there,
create a +libs folder under the Example1
folder, move or copy the grid.jar file into the new
+libs folder, and then open the Example1
folder in BlueJ (initially as a non-BlueJ project). You could then create a
ColorExample folder, move ColorExample.java there,
copy the +libs folder from Example1 to
ColorExample, and then open the ColorExample
folder in BlueJ. Some examples include several
classes, not just one, that must be moved together into the new folder
created for that example.