Grid Package

Alyce Brady
Computer Science Department
Kalamazoo College

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.

Evolution of the Grid Package:

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.

Update: The package has been updated several times (2006, 2012, 2016, and 2017) to use the new for style introduced in Java 5, to clean up the handling of threads (which conflicted with BlueJ), and to make other minor changes.

Links and Downloadable Files (last updated May 2017):

Older Links and Downloadable Files (last updated 6 March 2005):


Sample Assignments that Use the Grid Package:

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).


Running the Grid Package under BlueJ:

To run the starting code for one of the assignments above under BlueJ, create a +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 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 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.