
         CircleProgram.java

For an event driven GUI program, we must instantiate four kinds of
objects. There must be (at least) one object that is a source of
GUI events. There must be (at least) one object that is registered
to handle the GUI events generated by the event source. There must
be (at least) one object that holds "state" information about our
GUI. And there must be (at least) one object that uses the state
information to repaint the GUI.

In addition to the four kinds of objects that we must instantiate,
the JVM will instantiate a fifth kind of object. When an event occurs,
the JVM will instantiate an Event object that encapsulates information
about the event. This Event object gets passed to each object that is
registered to handle the event.


  Event source object
+----------------------+
|                      |       List<EventListener>
| List<EventListener>--|------->+------+
|                      |        |      |           EventListener object
|                      |        +------+         +----------------------+
|   addListener()      |        |  ----|-------->|                      |
+----------------------+        +------+         |                      |
An object that generates        |      |         | handleEvent(Event e) |
events and receives Event       +------+         |                      |
objects from the JVM.                            |                      |
                                                 |                      |
                                                 +----------------------+
     Event object                                An object that implements
  +-------------------+                          the EventListener interface.
  | Created by JVM    |
  | using information |
  | from the OS about |     Program state object          GUI object
  | an event          |    +----------------------+     +------------------+
  +-------------------+    |  Information about   |     |                  |
                           |  the current state   |     | paintComponent() |
                           |  of the GUI program. |     |                  |
                           |  This needs to be    |     |                  |
                           |  updated when a GUI  |     |                  |
                           |  event occurs.       |     +------------------+
                           +----------------------+     GUI object that needs
                                                        to be repainted after
                                                        an event occurs.


Below is how the above diagram would be modified for CircleProgram.java.


    JFrame object
+----------------------+    List<KeyListener>     CircleListener object (Controller)
|  List<KeyListener>---|------->+------+        +----------------------------+
|                      |        |      |        | CircleState cs             |
|  addKeyListener()    |        +------+        | CirclePanel cp             |
+----------------------+        |  ----|------->|                            |<--------------------+
GUI object that receives        +------+        | keyTyped(KeyEvent e)       |                     |
KeyEvent objects from           |      |        | mouseClicked(MouseEvent e) |                     |
the JVM.                        +------+        +----------------------------+                     |
                                                 An object that implements                         |
                                                 the KeyListener interface and                     |
    KeyEvent object                              the MouseListener interface.                      |
  +-----------------+                                                                              |
  |  information    |                                                                              |
  |  from the OS    |      CircleState object        CirclePanel object (View)                     |
  |  about the      |      (Model)                  +---------------------+                        |
  |  keyboard event |      +-----------------+      | CircleState cs      |                        |
  +-----------------+      |  int xNew       |      |                     |    List<MouseListener> |
                           |  int yNew       |      | List<MouseListener>-|----->+------+          |
    MouseEvent object      |  int xOld       |      |                     |      |      |          |
  +-----------------+      |  int yOld       |      | addMouseListener()  |      +------+          |
  |  information    |      +-----------------+      |                     |      |  ----|----------+
  |  from the OS    |                               | paintComponent()    |      +------+
  |  about the      |                               +---------------------+      |      |
  |  mouse event    |                               GUI object that needs        +------+
  +-----------------+                               to be repainted after
                                                    an event occurs.


For CircleProgram.java, there are two sources of events, mouse clicks
on a JPanel and key strokes from the keyboard (and Java makes the key
strokes appear to come from the JFrame). The program therefore needs
two kinds of event listeners, but the two kinds of listeners are
combined into one object of type CircleListener.

The Java Virtual machine (JVM) will deliver key stroke events to the
JFrame and it will deliver mouse events to the JPanel. All of these
events will end up being handled by the CircleListener object (the
Controller). Each CircleListener event handling method will update the
CircleState object (the Model) with the new coordinates for the red dot,
and then the event handlers will tell the CirclePanel (the View) to
repaint itself. The CirclePanel's paintComponent() method accesses
the CircleState object (the Model) to find out where to draw the
red dot.

Notice how each object holds a reference to any other object that it
needs to communicate with. The Controller (CircleListener) holds a
reference to each of the Model (CircleState) and the View (CirclePanel).
The View (CirclePanel) holds a reference to the Model (CircleState).
The Model (CircleState) does not need to communicate with any other
object so it does not hold any references.

Here is the Model-View-Controller diagram for CircleProgram.java,

                       +-----------------+
                       |                 |
                       |      Model      |
                       |  (CircleState)  |
                       |                 |
                       +-----------------+
  4. View queries the   /               \
     Model and then    /                 \  2. Controller updates
     repaints itself. /                   \    the Model.
                     /                     \
        +-------------+                  +------------------+
        |             |                  |                  |
        |    View     |<-----------------|    Controller    |
        |(CirclePanel)|                  | (CircleListener) |
        |             |  3. Controller   |                  |
        +-------------+     notifies     +------------------+
                    \       the View       /
       5. User sees  \      by calling    /  1. User interacts
          repainted   \     repaint().   /      with the Controller.
          View.        \                /       (The JVM sends an
                        +--------------+         Event object to the
                        |              |         Controller.)
                        |     User     |
                        |              |
                        +--------------+
