CS 101 Laboratory #3
Repulsive Behavior


Objective: To gain experience implementing classes and methods.
Note that you must bring a program design to lab this week!

Due date: Monday, October 3, at the beginning of your lecture section.

The Scenario

For this lab, we would like you to write a program that simulates the action of two bar magnets. Each magnet will be represented by a simple rectangle with one end labeled N for north and the other labeled S for south. Your program should allow the person using it to move either magnet around the screen by dragging it with the mouse. You know that opposite poles attract, while similar poles repel each other. So, if one magnet is dragged to a position where one or both of its poles is close to the similar poles of the other magnet, the other magnet should move away as if repelled by magnetic forces. If, on the other hand, opposite poles come close to one another, the free magnet should move closer and become stuck to the magnet being dragged.

To make things a bit more interesting, one should be allowed to flip a magnet from end to end (swapping the poles) by clicking on the magnet without moving the mouse. This will provide a way to separate the two magnets if they get stuck together (since as soon as one of them is reversed it will repel the other).

To start, click on this link to download the Magnets starter. As usual, move the "Magnets" project folder into the "cs101" folder inside your "public_html" folder.

Here is a working demo of what we have in mind:

Some Video Game Physics

If you are worried that you might not remember (or never knew) enough about magnetic fields to do this assignment, relax. First, we will be providing you with most of the code that does the "physics". Even if you had to write all the code yourself, you still would not need a deep knowledge of magnetism and mechanics. Instead, you could exploit something every special effects expert or video game author must know. Most humans observe the world carelessly enough that even a very coarse approximation of reality will appear "realistic". Our code takes advantage of this by simplifying the behavior of our magnets. We never compute the force between two magnets, just the distance between them. If they get too close together, our code moves them apart or makes them stick together.

Despite the fact that we will provide most of the code to handle this approximate version of physics, there are two aspects of a magnet's behavior that will impact the code you write. The first is a simplifying assumption. The magnets will not be allowed to rotate. They only slide up, down and across the screen.

More significantly, there is one aspect of the behavior of the real magnets that we must model fairly well. Earlier, we said that we just compute the distance between two magnets. This would not really be accurate enough, since it is not the distance between the magnets that matters, but the distances between their similar and opposite poles.

Consider the two pairs of magnets shown below:

                               

The magnets shown in the left pair are the same distance apart as the magnets in the right pair. In the pair on the left, however, the opposite poles are close together while the similar poles are relatively far apart. The situation is reversed in the other pair. In one case, one would expect the magnets to attract, in the other to repel.

Therefore, it is the poles rather than the magnets that really matter when deciding whether something should be attracted or repelled. As a result, instead of just manipulating magnet objects in your program, you will also need objects that explicitly represent poles.

Design of the Program

We will help you design this program by identifying the classes and methods needed. In particular, you will need two classes named Magnet and Pole and a class that is an extension of FrameWindowController. We will provide the code for the Pole class. You will write the other two class definitions.

The Pole Class

You will be able to use the Pole class we have defined much like one of the built-in graphics classes we constructed for the class. In this handout, we explain how to construct a new Pole and describe the methods that can be used to manipulate Poles. You can then write code to work with Poles just as you wrote code to work with FilledRects. We will see, however, that the interaction of Poles with the rest of your program is a little more complex than that of rectangles.

A Pole's constructor will expect you to specify the coordinate position at which it should initially appear and the label that should be displayed (i.e. N or S). It will also require you to provide as parameters the canvas and the Magnet to which the new pole will belong. The signature of the constructor for the Pole class is: 

   public Pole( Magnet container, 
                double x, double y, 
                String poleName,
                DrawingCanvas canvas )
Since you will usually create the Poles within the code of the Magnet constructor, the name this will refer to the Magnet that contains the Pole. Thus, the code to construct a Pole might look like: 
   new Pole( this, poleX, poleY, "N", canvas);
where poleX and poleY are the coordinates around which the label N should be displayed.

The Pole class provides several methods similar to those associated with graphical objects. In particular, Pole's methods will include getX, getY, getLocation, and move, which all behave like the similarly named methods associated with basic graphic classes.

In addition, the Pole class has two more specialized methods: attract and repel. Each of these methods expects to be passed the Pole of another magnet as a parameter. If you say, 

   somePole.attract( anotherPole )
then somePole and anotherPole should have opposite polarities. If somePole is a north pole, then anotherPole must be a south pole and vice versa. Note that a pole's label is used for the graphical display only; you must keep track of a pole's polarity yourself within the program. The repel method, on the other hand, assumes that the pole provided as its parameter has the same polarity as the object to which the method is applied. Therefore, if you write: 
   somePole.repel( anotherPole )
and somePole is a north pole, then anotherPole should also be a north pole.

Each of these methods checks to see if the two Poles involved are close enough together to exert enough force to move the magnets to which they belong. If so, they use the move and moveTo methods of the magnets to either bring the magnets closer together or move the free magnet so that they are far enough apart that they would no longer interact.

The good news is that we have already written the code for all the methods described above and will provide these methods to you.

In summary, the Pole class provides the following methods. Note that we have given you complete method headers here, illustrating the format to follow in defining your own methods. Think carefully about how you will invoke each of the following methods.

  • public double getX()

  • public double getY()

  • public Location getLocation()

  • public void move( double xoff, double yoff )

  • public void attract( Pole opposite )

  • public void repel( Pole similar )
Important: Do not modify the provided Pole class!

Part 1: Design

For the first part of this program, you should just worry about creating the magnets and moving them around. We'll worry about their interactions (attracting and repelling) later. To reinforce the notion that preparing for your lab section greatly increases the value of the time spent in lab, we want you to come to lab with a written design. For this lab, we will give you feedback on the design. In later labs, we will grade those designs as well. At the end of this section, we will be more specific about what you should bring with you to lab. To give you a better sense of what we mean by a written design, you can see a sample design for the first part of the laundry lab.

The key to this lab is the design of the Magnet class. A magnet is represented by a FramedRect and two poles. To ensure that our Poles work well with your Magnets, each magnet should be 150 by 50 pixels. The poles should be located near each end of the magnet. We recommend locating them so the distance from the pole to the closest end, top, and bottom, are all 1/2 the height of the magnet (i.e. 25 pixels away from each).

Your Magnet class will have to provide the methods that will enable someone running your program to drag magnets about within a window. The Magnet class will have to include the following methods:

The headers for these methods are already included in the starter file for the Magnet class. These methods should behave just like the corresponding methods for rectangles and ovals. In particular, the offsets provided to the move method are doubles, someMagnet.getLocation() should return a Location value, and someMagnet.contains(point) should return a boolean. (You will add other methods later, but we'll postpone discussing them until you need them.)

In order to write these methods, your magnet will need to contain several instance variables. A magnet should consist of a rectangle and two poles, and you will need instance variables for each of those. The constructor for a Magnet needs the following parameters:

The header of the constructor for the Magnet class should be: It should construct the framed rectangle forming the outline of the magnet (using the parameters), and should create two poles in the correct positions inside the magnet (see the earlier discussion on the constructor for Pole).

Once these instance variables have been declared and initialized, writing the methods should be easy. The move and moveTo methods should simply move the rectangle and poles to their new positions. The move method is pretty straightforward as all three items get moved the same distance, but moveTo takes a little thought as the Pole class does not have a moveTo method. Instead you'll need to calculate how far to move it. (Hint: check to see how far the rectangle is moving from its current position.) The method getLocation will simply return the location of the rectangle, while a magnet contains a point exactly when the rectangle does.

When you have this much of the Magnet class written, you can test it by writing MagnetGame, an extension of the FrameWindowController class that creates a magnet, and then write methods onMousePress and onMouseDrag that will allow you to drag it around.

Once onMousePress and onMouseDrag work, it should be pretty easy to add a second magnet and be able to drag either of them around. We suggest declaring a variable (movingMagnet) that can be associated with the appropriate magnet and used to remember which magnet to move whenever the mouse is dragged. This variable will be useful in other parts of your assignment as well.

As you were writing the methods for the Magnet class, you probably noticed that two additional methods are already included there. They are getWidth and getHeight. These are used by the Pole class to ensure that the methods attract and repel draw the magnets appropriately in the window.

As mentioned earlier, you should bring a design with you to lab. The design should show us how you plan to organize your Magnet and MagnetGame classes to accomplish the actions required of the first part of this lab only. We have told you what methods each class should have and the behavior that they should provide. You should write (in English, not Java) your plan for how each method will provide the necessary behavior. You should also describe (in English) what variables you feel are necessary for each class. This level of preparation will allow you to progress much more quickly in lab so that you can take better advantage of the presence of the instructors and TAs.

Part 2: Flipping the Magnet

When you click on a magnet, it should reverse its north and south poles. Add method flip to class Magnet that interchanges the north and south poles. Remember that you can move a Pole, and one possible way to implement flip is to just move the north pole to the south pole's position and vice versa.

Add an onMouseClick method to your MagnetGame class that invokes flip.

Part 3: Interacting Magnets

Finally, after you move or flip a magnet, you will need to tell the magnet to check if it is close enough to the other magnet to move it. To make this possible, include a method named interact in your Magnet class. The method interact should be invoked on the moving (or changing) magnet, and should take as a parameter the Magnet that has not just been moved or flipped. It should effect the interaction by calling the attract and repel methods of its poles with the appropriate poles of the other magnet passed as parameters. For simplicity, you might want to just check for attraction first, and only worry about repelling after the attraction works correctly.

When writing interact you will discover you need to add two more methods in the Magnet class to enable you to access the other magnet's poles: getNorth and getSouth. Both of these methods will return objects belonging to our Pole class. Also, note that the attract method that we have provided in the Pole class calls the moveTo method that you must define in the Magnet class. If you do not fill in the body of this method correctly, attraction will not work properly.

You will need to call the interact method every time one of the magnets is either moved or flipped. Because you want to send the interact message to the magnet that moved and provide the other magnet as the parameter, you will need to keep track of which is which. As we suggested above, whenever you start dragging a magnet (i.e., in the onMousePressed method), you should associate a name with the moving magnet. You will also find it convenient to associate a name with the resting magnet in order to call your interact method appropriately.

When your program is finished, your Magnet class should have a constructor and method bodies implemented for getLocation, move, moveTo, and contains, for which headers were provided. In addition, you will need to provide the methods interact, getNorth, getSouth, and flip. You should think carefully about the structure of the method headers for each of these. To help you in formulating your ideas, the following gives typical uses of the methods:

Getting Started

The starter project contains several files intended to hold Java code. The file MagnetGame.java should be used to write the extension of the FrameWindowController that will serve as your "main program". The Magnet.java file should be used to hold your code for the Magnet class. Both of these files will initially contain skeletons of the code that you will need to complete. The final ".java" file will be Pole.java. It will hold our implementation of the Pole class. You should not change this file.

Submitting Your Work

We will grade your assignment both by running your actual program over the web and by reading a printout of your Java source code. Homework is due by the beginning of your lecture section. Here is the procedure for submitting your work:

  1. Make sure that each of your source files includes a comment containing your name and lab section. Also, before turning in your work, be sure to double check both its logical organization and your style of presentation. Make your code as clear as possible and include appropriate comments describing major sections of code and declarations.

  2. Print out the "MagnetGame.java" and "Magnet.java" files. Since other students may be printing at the same time, you should pick up your printouts immediately and make sure that you take only your own printouts.

  3. Print out a copy of the Homework #3 Cover Page. Turn in one stapled hardcopy of all your work, with this cover page on top. Include at the bottom any textbook exercises assigned in class.

  4. As with last time, use TextWrangler to insert your name into the "magnets.html" file in your "Magnets" folder, and save the file.
You can see what the graders will see by visiting http://bj.middlebury.edu/~USERNAME/cs101/Magnets/magnets.html from your web browser, where USERNAME is replaced by your username (but make sure to include the tilde (~) character before your username). You will notice that a blank "panel" window gets created. Don't worry about this; just close the window to see your program running in the browser.

Good luck and have fun!

Quick Reference of the Pole Class

This section provides no new information. It is a quick reference to the constructor and methods provided in the Pole class that you will be using.

 Constructor

To create a new pole:

public Pole (Magnet parent, double x, double y, String name, DrawingCanvas canvas)

  Example Usage

Pole myPole = new Pole (this, xLoc, yLoc, "N", canvas);

 Accessor Methods

To get information about a pole:

  Getting the x coordinate of the pole's center:

public double getX()

  Example Usage

double x = somePole.getX();

  Getting the y coordinate of the pole's center:

public double getY()

  Example Usage

double y = somePole.getY();

  Getting the coordinate pair of the pole's center:

public Location getLocation()

  Example Usage

Location loc = somePole.getLocation();

 Mutator Methods

To modify a pole:

  Moving the pole relative to its current location:

public void move (double xoff, double yoff)

  Example Usage

somePole.move (xOffset, yOffset);

  Attracting another pole if close enough:

public void attract (Pole oppositePole)

  Example Usage

somePole.attract (anotherPole);

  Repelling another pole if close enough:

public void repel (Pole similarPole)

  Example Usage

somePole.repel (anotherPole);

 

Sample Design

This section shows the sample design for the first part of the laundry lab. Use this to help you understand what to include in your own sample design.

The laundry lab includes constants for the following values:

The program contains the following instance variables:

begin method - creates the display and initializes the correct basket. It does this as follows:

onMouseClick method - checks if the user clicks the mouse in the correct basket, and then changes the color of the laundry. It does this as follows:

Back to Computer Science 101 Home
Department of Computer Science