Week 1

   Overview of the course and introduction to Java, events, and graphics


MECHANICS we use to create and run Java programs:

- Plain text editor (DrJava) creates Java source (.java) file containing a legal
  program in the Java language.

- Java compiler (javac command) takes the source file, and existing program
  libraries, and produces Java byte code (.class) files.

- Java Virtual Machine (JVM, java command) takes class files of program and
  libraries and runs the program

All integrated in DrJava. Details in the lab.

-------------------

****** MakeBox.java
import objectdraw.*;
import java.awt.*;

public class MakeBox extends FrameWindowController {
   
   public void begin() {
      // draw on canvas a 20 by 40 rectangle at location (80, 40)
      new FilledRect(80, 40, 20, 40, canvas);
   }
}





******

import libraries

class declaration

  * program is an object that responds to action messages

  * appropriate name (beginning with a capital letter)

  * source file name must match

  * extends java.objectdraw.FrameWindowController, giving us a canvas in a
    frame for drawing on 

method declaration (method automatically invoked when program begins

comment

statement creates a new graphic instance of the class objectdraw.FilledRect

 - invokes initialization code belonging to the class, called a
   CONSTRUCTOR, giving location, dimensions, and canvas to draw on

 - coordinate system

-----------------

Modify program so when mouse is pressed, a square box appears where it is pressed

****** MakeBoxOnPress.java
import objectdraw.*;
import java.awt.*;

public class MakeBoxOnPress extends FrameWindowController {
   
   /** Draw a square box where the mouse is pressed. */
   public void onMousePress(Location point) {
      // draw on canvas 20 pixel square box at the press location
      new FilledRect(point, 20, 20, canvas);      
   }
}


******

Javadoc comment: javadoc command generates documentation from such comments
before method and class declarations. (Not used in Eventful text.)

Method is invoked when event occurs, and is passed the mouse location.

Different constructor arguments. Demo API javadoc documentation.

-------------------- 

****** MouseIndicator.java
import objectdraw.*;
import java.awt.*;

/** 
 * Display DOWN and UP text, with the word indicating the mouse button position
 * in red and the other in grey. Assume the button is upText initially.
 */
public class MouseIndicator extends FrameWindowController {
   
   private Text upText;
   private Text downText;
   
   public void begin() {
      upText = new Text("UP", 200, 220, canvas);
      downText = new Text("DOWN", 200, 200, canvas);
      
      upText.setColor(Color.RED);
      downText.setColor(Color.GRAY);
   }
   
   public void onMousePress(Location point) {
      downText.setColor(Color.RED);
      upText.setColor(Color.GRAY);
   }
   
   public void onMouseRelease(Location point) {
      upText.setColor(Color.RED);
      downText.setColor(Color.GRAY);
   }
}

******

Must store text objects in INSTANCE VARIABLES.

Instance variable declaration of the form: private <type> <variable name> ;

- <...> indicates a SYNTACTIC CATEGORY, like a part of speech such as "verb"
  or "verb phrase" in a natural language.

- can use the name of its class for the type of an object

- variable naming rules and conventions

- Java is a STATICALLY TYPED LANGUAGE, unlike Scheme
  * TYPE CHECKER (part of the compiler) catches type error
  * disallows some programs that are otherwise ok!

Variable assignment is of the form: <variable name> = <expression> ;

Method call syntax for sending messages: object.methodName(arguments...)

Color.RED refers to the constant RED in the class java.awt.Color (also
called Color.red).

------------------

We can define our own constants with declarations of the form:

   private static final <type> <variable name> = <expression> ;

Constants cannot be assigned after they are initialized. That's what
"final" means here. 

Since they are the same for all instances of the class, they are declared
"static", which means they are associated with the class, not its
instances. More on that later.

The most common integer type in Java is "int".

****** MouseIndicator2.java
import objectdraw.*;
import java.awt.*;

/** 
 * Display DOWN and UP text, with the word indicating the mouse button position
 * in red and the other in grey. Assume the button is upText initially.
 */
public class MouseIndicator2 extends FrameWindowController {
   
   private static final int TEXT_X = 200;
   private static final int UP_Y = 220;
   private static final int DOWN_Y = 200;
      
   private Text upText;
   private Text downText;
   
   public void begin() {
      upText = new Text("UP", TEXT_X, UP_Y, canvas);
      downText = new Text("DOWN", TEXT_X, DOWN_Y, canvas);
      
      upText.setColor(Color.RED);
      downText.setColor(Color.GRAY);
   }
   
   public void onMousePress(Location point) {
      downText.setColor(Color.RED);
      upText.setColor(Color.GRAY);
   }
   
   public void onMouseRelease(Location point) {
      upText.setColor(Color.RED);
      downText.setColor(Color.GRAY);
   }
}

******

--------------------

Just as FilledRect has a constructor that takes a single point instead of
two integer coordinates, there is a Text constructor that takes a point
instead of two separate coordinates. 

As we have seen, Location is the type of points. There is a Location class,
and as you might guess, it's constructor takes two integer coordinates.

So we can do a final version of MouseIndicator that uses two Location
constants instead of three int constants.

We have seen that variable declarations may or may not have an "=
<expression>" part, called an INITIALIZER. Field (including constant)
initializers are evaluated when the class is created. They cannot refer
to data that is available when they are created, which is when their
variables are created. 

instance variables are created when instances are created.

static variables (e.g. constants) are created when the class is created. In
particular, constants can't refer to instance variables, such as the window
controller CANVAS variable.


****** MouseIndicator3.java
import objectdraw.*;
import java.awt.*;

/** 
 * Display DOWN and UP text, with the word indicating the mouse button position
 * in red and the other in grey. Assume the button is upText initially.
 */
public class MouseIndicator3 extends FrameWindowController {
   
   private static final Location UP_LOCATION = new Location(200, 220);
   private static final Location DOWN_LOCATION = new Location(200, 200);
      
   private Text upText;
   private Text downText;
   
   public void begin() {
      upText = new Text("UP", UP_LOCATION, canvas);
      downText = new Text("DOWN", DOWN_LOCATION, canvas);
      
      upText.setColor(Color.RED);
      downText.setColor(Color.GRAY);
   }
   
   public void onMousePress(Location point) {
      downText.setColor(Color.RED);
      upText.setColor(Color.GRAY);
   }
   
   public void onMouseRelease(Location point) {
      upText.setColor(Color.RED);
      downText.setColor(Color.GRAY);
   }
}

******

-------------------

Of course variables can vary. They can be assigned any number of time.
And the value on the right side of an assignment statement can be any
expression with the same type as the variable.

So how can we use this to write a scribbling program?

****** Scribble1.java
import objectdraw.*;
import java.awt.*;

public class Scribble1 extends FrameWindowController {
   
   private Location nextLineStart;
   
   public void onMouseDrag(Location point) {
      new Line(point, point, canvas);
   }   
}

******

The dots need to be connected.

****** Scribble2.java
import objectdraw.*;
import java.awt.*;

public class Scribble2 extends FrameWindowController {
   
   private Location nextLineStart;
   
   public void onMouseDrag(Location point) {
      // draw a line from the last mouse point to the current point
      new Line(nextLineStart, point, canvas);
      // remember the current point so we have it to start the next line
      nextLineStart = point;
   }   
}

******

Null pointer exception!

****** Scribble.java
import objectdraw.*;
import java.awt.*;

public class Scribble extends FrameWindowController {
   
   private Location nextLineStart;
   
   public void onMousePress(Location point) {
      // remember where the mouse went down
      nextLineStart = point;
   }
   
   public void onMouseDrag(Location point) {
      // draw a line from the last mouse point to the current point
      new Line(nextLineStart, point, canvas);
      // remember the current point so we have it to start the next line
      nextLineStart = point;
   }   
}

******

--------------------

We have seen that a point (an instances of the Location class) contain X and Y
coordinate values. We can get these out of a point by sending it the
messages getX() and getY(). Methods like getX and getY that take no
arguments and simply return values stored in instance fields are called
GETTERS.

Points actually contain floating point values of type "double" to make
graphics calculations easier. So these getters return doubles.

A very common operation is to make a new string by sticking the characters
in one string after the characters in another. This is called CONCATENATION
and is expressed with the + operator. The + operator is said to be
OVERLOADED, because it is also used for arithmetic addition.

For example, the value of the expression

   "hi " + "there" 

is

   "hi there"

Note the importance of the space in the string "hi ".

If one argument of + is a string and the other is of some other type, Java
will automatically convert the other value to its string representation. 
This is a bit confusing, but very handy.

We use this new knowledge in a program that displays the mouse position in
the common mathematical form ( X , Y ).


****** MouseMeter.java
import objectdraw.*;
import java.awt.*;

/** Display the mouse position. */
public class MouseMeter extends FrameWindowController {
   
   private static final Location DISPLAY_LOCATION = new Location(150, 200);
   
   private Text display;
   
   public void begin() {
      display = new Text("Move the mouse", DISPLAY_LOCATION, canvas);
   }
   
   public void onMouseMove(Location point) {
      display.setText("( " + point.getX() + " , " + point.getY() + " )");
   }
}

******