CPSC 124, Fall 2005
Lab 9: Events and Applets

In this lab, you will be learning a little more about event-driven programming by writing a program that handles mouse events. A mouse generates several types of events (seven types in Java). You can program responses to any of these events. In the first exercise of the lab, you will respond by doing some simple drawing operations.

The second exercise of the lab asks you to set up a web site where you can display some of the work you have done. You will publish the work as "applets," which are small programs that run on a web page. You will not be required to learn a lot about web site programming, since you will just be modifying a small starter site that has already been created for you.

This lab is due, as usual, at next Tuesday's lab.

Handling Mouse Events

As usual, you can begin the lab by creating a new Java project in Eclipse. You should import the following three files from the directory /classes/f05/cs124/lab9/SourceCode: MouseEventsApplet.java, MouseEventsApplication.java, and MouseEventsDemo.java. The only file that you will have to edit is MouseEventsDemo.java. The main program is MouseEventsApplication.java, so you can run that file as a Java application. If you do this before editing the file, you'll get a window that just shows a gray rectangle. Clicking on this area will draw a small square centered at the point where you click; shift-clicking will draw a small oval. This drawing area of the program is a JPanel that is defined by the MouseEventsDemo class (which is a subclass of JPanel). It has already been programmed to respond to mouse clicks. You will be programming it to respond to other types of mouse events. The outline of the event handling has already been set up for you -- all you have to do is edit the methods in the class and add a few instance variables.

Java has a very flexible system for handling events. This means that there are various ways to design an event-driven program. This is good, but the unfortunate side of it is that there is no one correct way that you can learn once and for all. In this lab, you will write a program that handles mouse events, but you should be aware that the way the program works is not the only way, or even the best way, that the program could be designed.

One way for a program to receive mouse events is to "listen" for them. Any object can be a listener, as long as it defines certain event-handling methods. (This technique is described in Section 6.4, but you don't have to completely understand it to do the lab, because the basic event-handling has already been set up in MouseEventsDemo.java.) The methods that are required for handling mouse events are defined in two "interfaces". An interface is basically just a list of subroutines. There are two interfaces for handling mouse events. The MouseListener interface specifies the subroutines:

           public void mousePressed(MouseEvent e)
           public void mouseReleased(MouseEvent e)
           public void mouseClicked(MouseEvent e)
           public void mouseEntered(MouseEvent e)
           public void mouseExited(MouseEvent e)

The other interface is MouseMotionListener, which specifies two subroutines that handle events generated when the user moves the mouse:

           public void mouseMoved(MouseEvent e)
           public void mouseDragged(MouseEvent e)

For more information about each method, see the comments in MouseEventsDemo.java, or read Section 6.4.

Remember that these methods will be called by the system when the user does certain things with the mouse. You don't call the methods yourself -- you just have to define them to respond to the user's actions whenever they occur.

Note that each method has a parameter of type MouseEvent. This parameter is provided to you by the system when it calls the method. It contains information about the mouse event. You can get at this method by calling methods in the parameter object e. Here are some of the most useful methods in e:

• e.getX() -- returns the x-coordinate of the pixel where the mouse was located when the event occurred.
• e.getY() -- returns the y-coordinate of the pixel where the mouse was located when the event occurred.
• e.isShiftDown() -- returns a boolean value that tells whether the user was holding down the shift key when the event occurs. (This lets the user modify the event, so that you can respond differently depending on whether or not the shift key is down.)
• e.isControlDown() -- returns a boolean value that tells whether the user was holding down the control key when the event occurs.
• e.isMetaDown() -- returns a boolean value that tells whether the right mouse button is the one that was clicked (or, on the Mac, the Command key was pressed when the mouse button was clicked). This lets you respond differently to the right and left mouse buttons.
• e.isAltDown() -- returns a boolean value that tells whether either the ALT key was pressed or the middle mouse button was the one that was clicked. (The confusion is caused by the fact that not all mice have middle and right buttons.)

In your program, you will respond to mouse events by drawing something on the panel. You will need a Graphics object to do any drawing. The format for obtaining and using an graphics object is:

          Graphics g = getGraphics();  // An object for drawing on this panel.
              .
              .   // Use g to draw on the panel.
              .
          g.dispose();  // Free the operating system resources used by g.

(Drawing in this way is not considered to be good style in modern Java, but we will do it anyway.)

You can see how the mouse event parameter and a graphics object are used in the mousePressed method in the original program:

    public void mousePressed(MouseEvent e) {
        Graphics g = getGraphics();   // For drawing on the panel.
        g.setColor( Color.RED );
        if (e.isShiftDown()) {
               // If the user is holding the shift key down,  
               // draw a circle centered at (e.getX(),e.getY())
            g.fillOval(e.getX() - 20, e.getY() - 20, 40, 40);
        }
        else {
               // If the user is NOT holding shift down,  
               // draw a rectangle centered at (e.getX(),e.getY())
            g.fillRect(e.getX() - 20, e.getY() - 20, 40, 40);
        }
        g.dispose();  // Frees resources used by the Graphics object.
    }

Here are some ideas for things that your applet could do:

• You can use the method setBackground(c) to change the background color of the panel, where c is any Color. When you do this, the panel is redrawn with the new background color. Because any stuff that you draw is simply drawn the applet, and not represented in memory, it will be erased. You could change the background color -- possibly to a random value -- when the mouse enters the panel.
• You could draw a message (using g.drawString) on the panel when the mouse exits the panel.
• You could draw a random color circle or square when the user drags the mouse. Since you get a stream of such events as the mouse is moved, this will let the user draw a long curve made up of randomly colored circles. Alternatively, you could alternate black and white circles. (This would require a state variable to keep track of how many circles have been drawn so far.)
• You can do neat things with symmetry. Instead of simply drawing a square centered at (e.getX(),e.getY()), draw four symmetrically placed squares at centered at: (getWidth()-e.getX(),e.getY()), (e.getX(),e.getHeight()-e.getY()), and (getWidth()-e.getX(),e.getHeight()-e.getY()). Try it, it's fun.
• Every time mouseDragged is called, draw a line from the current mouse location back to the point where the mouse was first pressed. This would require state variables to keep track of the starting point. (This can also be rather neat.)
• Vary the drawing that occurs when the mouse moves, based on the values of e.isShiftDown(), e.isMetaDown(), and/or e.isAltDown().

Your CS124 Web Site

Java programs can be either applications or applets. An applet is a small program that runs in a rectangular area on a Web page. Applets are introduced in Section 6.1 of the textbook, and the basics of HTML, the languages that is used for writing web pages, are covered in Section 6.2. Lab 5 explained how you can publish an applet on the Math/CS department web server, but you were not required to do so at that time. This time around, it is required.

The MouseEvents program that you wrote for this lab can be run either as an application or as an applet. The file that you worked on, MouseEventsDemo.java, defines a JPanel. It is easy to use this JPanel in either a frame or in an applet. The application MouseEventsApplication.java is a short program that simply creates a JFrame and adds a MouseEventsDemo panel to it, so when you run this application, you see your mouse events panel in its own window. On the other hand, the file MouseEventsApplet.java defines a subclass of the JApplet class; this subclass defines an applet that displays a MouseEventDemo panel. If you add this applet to a web page, your program will be running in a rectangular area on the page. The mosaic draw program that you wrote for Assignment 2 works in a similar way; that is, it can be used either in the stand-alone application defined by the file MosaicDraw.java, or it can be used in the applet defined by MosaicDrawApplet.java. Several of the remaining labs in the course will follow a similar pattern.

As part of your work for this lab, you will start posting some of your work on the Web as applets. You can publish something on the web simply by placing it in the www directory in your home directory. To get you started, there is a small sample web site that you should copy into your www directory. (If you had previously created a cs124 directory in your www directory, consult with me about what to do.) You can do this in one of two ways: