Class Room

java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----java.awt.Panel
                           |
                           +----java.applet.Applet
                                   |
                                   +----Room

public class Room

extends Applet

This class defines the graphics operations, and creates a window environment for an arbitrary number of Spider objects. The class name, "Room", refers to the container of Feldman's "Spider graphics" programs developed in the textbook "Ada 95".

To use Room and Spider objects in Java programs, the programmer will typically instantiate Room first, then install the Room object in a Frame. New Spider instances can be created at any time. Sample code for these three steps may look like this:

    int    width    = 400;   // pixels
    int    height   = 300;
    Room   barn     = new Room();
    Frame  myWindow = new AppFrame("My Room", barn, width, height);
    Spider itzy     = new Spider();
   

After setup, the methods defined here and in the Spider class can be used programmatically in Java code, to effect graphic operations in the target Room (or multiple Rooms), in the sequence specified. Although it would be possible to run individual spiders asynchronously as threads, only the synchronous operational mode is developed here. Spiders may be shared naturally, among different Room objects installed in a Frame, or even between different Frames instantiated within a program.

Although the Room class defines a main() method, other programs will not be calling Room.main(). This method serves as a builtin test program that can be run from the command line with

    java Room
   

In this context main() implements an interactive command loop, allowing the programmer to select simple one-shot graphics commands on behalf of one of six spiders, and then executing the selected operation in the only Room instance created in main(). The code of the main() method may also be useful as an example for writing other Spider graphics programs.

The AppFrame object in creating a Room, allows proper bootstrapping of the Graphics object (context), as is explained in the API of AppFrame. By subclassing Room from Applet, we make use of the Applet.init() method; this lets us call getGraphics() only after the Room object is safely installed in its Frame.

See Also:

AppFrame, Spider

EAST

The spider faces or moves toward the right wall of the room

myFullSize

The width and height of the drawing area, in pixels

mySurface

The Graphics object, context or handle to use for drawing in the room

NORTH

The spider faces or moves toward the top wall of the room

SOUTH

The spider faces or moves toward the bottom wall of the room

WEST

The spider faces or moves toward the left wall of the room

Room()

crawl(Spider, int)

This method advances a spider in its current direction and draws a trail of colored "silk" to mark the spider's path.

drawSpider(Spider, Graphics)

This method draws a Spider object at its current coordinates in the room.

drawTo(Spider, int, int)

This method relocates a spider to the specified X, Y coordinates within the room, leaving a silk trail.

drawTo(Spider, Point)

This method relocates a spider to the specified X, Y coordinates within the room, leaving a silk trail.

init()

This method overrides java.applet.Applet.init() to perform initialization once the Graphics object (graphics context) of the drawable surface has been established.

isAtWall(Spider)

This method returns "true" if the spider is at a wall and faces the wall, it returns "false" otherwise.

jumpTo(Spider, int, int)

This method relocates a spider to the specified X, Y coordinates within the room, without leaving a silk trail.

jumpTo(Spider, Point)

This method relocates a spider to the specified X, Y coordinates within the room, without leaving a silk trail.

jumpToMiddle(Spider)

This method relocates a spider to the center of the room.

main(String[])

This is the builtin test program of the Room class.

showMe(Spider)

This method displays a spider and updates the room so that all silk trails laid since the last repaint() become visible.

showRoom()

This method displays all silk trails laid since the last call to repaint(), showMe() or showRoom().

update(Graphics)

This method overrides java.awt.Component.update() to prevent it from clearing the background every time it calls paint().

veer(Spider, int, int)

This method advances a spider in its current direction biased by a positive or negative offset, and draws a trail of colored "silk" to mark the spider's path.

  public final static int NORTH

The spider faces or moves toward the top wall of the room

  public final static int EAST

The spider faces or moves toward the right wall of the room

  public final static int SOUTH

The spider faces or moves toward the bottom wall of the room

  public final static int WEST

The spider faces or moves toward the left wall of the room

  public Graphics mySurface

The Graphics object, context or handle to use for drawing in the room

  public Dimension myFullSize

The width and height of the drawing area, in pixels

  public Room()

  public static void main(String args[]) throws IOException

This is the builtin test program of the Room class. When starting Room.class as a standalone application, the Java interpreter first calls Room.main() --- much as if the code made a call to any static method, for example Math.min() --- without instantiating a Room object. As its first order of business, this.main() creates a new Room object, "inHere", and then passes this object as an Applet, to the AppFrame constructor method which creates a Frame object and installs inHere as a component in this Frame. Because we never again need the handle of this Frame, we do not assign or keep the reference returned by

       new AppFrame(myTitle,inHere, width, height);

Parameters:

args - is the String array expected by the interpreter; not used here.

Throws: IOException

on input error (when, for example, input is redirected from a file, and an End-of-File condition is detected). The exception is not caught here, and will terminate the program.

  public void init()

This method overrides java.applet.Applet.init() to perform initialization once the Graphics object (graphics context) of the drawable surface has been established. For an applet program, this method would be called by the browser or the "appletviewer" to inform the applet that it has been loaded into the system. Here, instead of a browser or appletviewer, the constructor method of AppFrame (a subclass of Frame) calls this.init(), when the constructor has already sized and shown the new Frame.

Overrides:

init in class Applet

  public void update(Graphics mySurface)

This method overrides java.awt.Component.update() to prevent it from clearing the background every time it calls paint().

Parameters:

mySurface - is the current Graphics object (graphics context) of this room.

Overrides:

update in class Component

See Also:

update

  public void drawSpider(Spider which,
                         Graphics mySurface)

This method draws a Spider object at its current coordinates in the room. The spider is shaped like a letter M, with a small circle for the spider's belly at the point where the slanted inner lines meet. The four lines that represent the (front) legs of the spider are always in the foreground color (black), the belly color is specific to the spider. The spider is oriented upright (like the letter M) if its heading is NORTH, it is drawn like the letter W if its heading is SOUTH. A spider headed WEST looks like a letter M turned on its left side; a spider headed EAST looks like a letter M turned on its right side.

To be able to show a spider and then erase it, a spider is always drawn in the XOR mode. A second call to draw the same spider (in the same place and headed the same way as before) will erase the previously drawn spider.

Parameters:

which - selects a particular spider (object) to show.

mySurface - is the Graphics handle for drawing operations.

  public Point crawl(Spider which,
                     int howFar)

This method advances a spider in its current direction and draws a trail of colored "silk" to mark the spider's path. The spider's silk is not allowed to get beyond the bounding box of the "walls" of the room (drawn as a rectangle 5 pixels inside the drawable surface), although the body of the spider may protrude beyond the walls. The silk trail will not be made visible until the next repaint() operation which may be triggered by events or by calls to showMe() or showRoom().

Parameters:

which - selects a particular spider (object) to advance.

howFar - specifies the maximum distance (in pixels) to advance the spider. The actual distance moved may be less, if the spider hits a wall. Negative values are silently converted to absolute values.

Returns:

the new X and Y coordinates of the spider, as a Point object.

See Also:

showMe, showRoom, repaint

  public Point veer(Spider which,
                    int howFar,
                    int offset)

This method advances a spider in its current direction biased by a positive or negative offset, and draws a trail of colored "silk" to mark the spider's path. The spider's silk is not allowed to get beyond the bounding box of the "walls" of the room (drawn as a rectangle 5 pixels inside the drawable surface), although the body of the spider may protrude beyond the walls. The silk trail will not be made visible until the next repaint() operation which may be triggered by events or by calls to showMe() or showRoom().

Parameters:

which - selects a particular spider (object) to advance.

howFar - specifies the maximum distance (in pixels) to advance the spider in its current direction. The actual distance moved may be less, if the spider hits a wall. Negative values are silently converted to absolute values.

offset - a positive or negative displacement (in pixels) at right angles to the direction of travel. The actual displacement is bounded by the surrounding walls.

Returns:

the new X and Y coordinates of the spider, as a Point object.

See Also:

showMe, showRoom, repaint

  public boolean isAtWall(Spider which)

This method returns "true" if the spider is at a wall and faces the wall, it returns "false" otherwise.

Parameters:

which - selects a particular spider (object) to test.

Returns:

true if the spider is at a wall and faces the wall, false otherwise.

  public Point jumpTo(Spider which,
                      int x,
                      int y)

This method relocates a spider to the specified X, Y coordinates within the room, without leaving a silk trail. The spider is never allowed to breach the walls; out of bounds values are silently adjusted to the nearest wall.

Parameters:

which - selects a particular spider (object) to relocate.

x - is the horizontal (pixel) ordinate of the new position.

y - is the vertical (pixel) ordinate of the new position.

Returns:

the new X and Y coordinates of the spider, as a Point object.

  public Point jumpTo(Spider which,
                      Point newSpot)

This method relocates a spider to the specified X, Y coordinates within the room, without leaving a silk trail. The spider is never allowed to breach the walls; out of bounds values are silently adjusted to the nearest wall.

Parameters:

which - selects a particular spider (object) to relocate.

newSpot - is the Point representing the new position.

Returns:

the new X and Y coordinates of the spider, as a Point object (which will be different from the Point passed in, if the passed Point was out of bounds).

  public Point drawTo(Spider which,
                      int x,
                      int y)

This method relocates a spider to the specified X, Y coordinates within the room, leaving a silk trail. The spider is never allowed to breach the walls; out of bounds values are silently adjusted to the nearest wall.

Parameters:

which - selects a particular spider (object) to relocate.

x - is the horizontal (pixel) ordinate of the new position.

y - is the vertical (pixel) ordinate of the new position.

Returns:

the new X and Y coordinates of the spider, as a Point object.

  public Point drawTo(Spider which,
                      Point newSpot)

This method relocates a spider to the specified X, Y coordinates within the room, leaving a silk trail. The spider is never allowed to breach the walls; out of bounds values are silently adjusted to the nearest wall.

Parameters:

which - selects a particular spider (object) to relocate.

newSpot - is the Point representing the new position.

Returns:

the new X and Y coordinates of the spider, as a Point object (which will be different from the Point passed in, if the passed Point was out of bounds).

  public Point jumpToMiddle(Spider which)

This method relocates a spider to the center of the room.

Parameters:

which - selects a particular spider (object) to relocate.

Returns:

the new X and Y coordinates of the spider, as a Point object.

  public void showMe(Spider which)

This method displays a spider and updates the room so that all silk trails laid since the last repaint() become visible. ShowMe is really just a wrapper for calling drawSpider() followed by java.awt.Component.repaint().

Parameters:

which - selects a particular spider (object) to display.

See Also:

repaint

  public void showRoom()

This method displays all silk trails laid since the last call to repaint(), showMe() or showRoom(). showRoom is really just a wrapper for java.awt.Component.repaint(), to keep the method names of class Room consistent.

See Also:

showMe, showRoom, repaint