CS 124, Fall 2009
Lab 7: APIs

For this week's lab, you will write a program that uses a simple API. This is an exercise in using APIs: You will have to understand the interface, but not the implementation, of the subroutines that are specified by the API. The program that you write will be similar to the following applet, in which patches of uniform color build up from an initially random state. (Double-click the applet to restore it to randomness.)

For this lab, you will need the four files that can be found in the directory /classes/f09/cs124/files_for_lab_7. The files are Mosaic.java, MosaicCanvas.java, Wanderer.java, and TextIO.java. MosaicCanvas.java is a support file that you will not have to use directly. Mosaic.java defines a small API for working with a window full of small colored rectangles. You will use this API to write this week's program. The JavaDoc documentation for the API can be found at: http://math.hws.edu/eck/cs124/f09/lab7/mosaic_doc/Mosaic.html. This class is also discussed in Section 4.6 of the textbook. The file Wanderer.java is a sample program that uses the Mosaic API. You will want to run the sample program to see what it does. You will also want to read the source code.

You can use Eclipse for this lab, but you are not required to do so. If you want to use Eclipse, start it up and create a new project named lab7. Open /classes/f09/cs124/files_for_lab_7 and copy the files from that directory into the new project. If you are not using Eclipse, you can simply create a lab7 directory and copy the files into that directory.

The exercise for this lab is due next Thursday, as usual. Copy your completed lab7 folder to your homework directory in /classes/f09/cs124/homework.

Color Conversion

The Mosaic class contains a variety of static methods for working with a window that contains a grid of small colored rectangles. See the API for details. The basic idea for the program that you will write is to fill the window with randomly colored squares, the repeat the following procedure over and over, as long as the window is open: Select one of the squares at random by choosing a row at random and a column at random; select one of the four neighbors of the selected square at random; and change the color of the selected square to the color of the selected neighbor. This process tends to build up patches of uniform color in a way that is fun to watch.

The sample program Wanderer shows how to open a Mosaic window, how to loop as long as the window is open, and how to select a neighbor at random. Note that squares along one edge of the grid are considered to be neighbors of the squares along the the opposite edge. The sample program is not completely analogous to the program that you want to write. It does not copy color from one square to another; you have to figure out how to do that. However, the general outline of the program that you have to write is similar.

Here are some specific requirements for your program: You should ask the user to specify the size of the grid (the number of rows and columns, which can be the same). Also ask the user to specify the size of each of the small squares. You will need this information to open the window. You should write a subroutine to convert a random square to the color of a random neighbor, as described above. After opening the window and filling it with random colors, you should go into a loop in which you call your color conversion subroutine over and over. The loop should not contain a delay, although you might want to include one at first so you can better see what is going on. (My own version of the program inserts a small delay for the first 1000 steps through the loop, but not after that.) Every 10,000 or 100,000 steps through the loop, display the number of steps by setting the title of the Mosaic window to something like "1710000 steps".

Extra Credit Opportunity

If you would like a little extra credit, you can add the following feature to your program: Give the user the option of filling in the window with a two-color checkerboard pattern, as an alternative to filling it with random colors. (Before opening the window, ask the user whether they would like to use a checkerboard.)

You will want to write and test your checkerboard subroutine individually before incorporating it into the program. There are several approaches that could be taken to filling the mosaic in a checkerboard pattern. All of them will end up using nested for loops to go through the rows and columns of the checkerboard. You could, for example, do any of the following:

• Fill the checkerboard entirely with one color, then go through the rows and change every other square in the row to the second color. If the row number is even, start with the square in column 0; if the row number is odd, start with the square in column 1.
• Go through the rows. In each row, start with the first color if the row number is even and with the second color if the row number is odd. For each column, set the square in position (row,column) equal to the current color, and then change the color to get ready for the next square so that the colors will alternate as you move down the row.
• Note that a square is one color if either the row number and the column number are both even or the row number and the column number are both odd. (The square is the other color if one of these is odd while the other is even.) This means that you can simply go to each square and calculate what its color should be by checking whether the row and column numbers are even or odd.

You can use any method you want, as long as the mosaic is filled with a checkerboard pattern.