Most of the text and formatting (in html) below was taken from Professor David Eck's book "Introduction to Programming Using Java", version 5.0. The description below also assumes you are using this textbook, and that you have covered the first two chapters. Paint and its documentation was written by Marc Corliss, with modifications by Stina Bridgeman.

Paint Class

Everthing you see on a computer screen has to be drawn there, even the text. The Java API includes a range of classes and methods that are devoted to drawing. Later in the semester we'll look at these. For now, we'll use one class called Paint, which acts like a wrapper for these classes, in the same way that TextIO acts as a wrapper for Java IO classes. To use the Paint class you will have to download the file Paint.java and move it to the same directory as the Java file that needs to use it.

The (concise) interface for this class, which is also described below in more detail, is available here.

In Java, graphics are drawn in a rectangle made up of pixels. A position in the rectangle is specified by a pair of integer coordinates, (x,y). The upper left corner has coordinates (0,0). The x coordinate increases from left to right, and the y coordinate increases from top to bottom. The illustration shows a 16-by-10 pixel component (with very large pixels). A small line, rectangle, and oval are shown as they would be drawn by coloring individual pixels. (Note that, properly speaking, the coordinates don't belong to the pixels but to the grid lines between them.)

Creating a new window

To create a new window with the Paint class, you must call the method Paint.buildWindow().

Paint.buildWindow(String title, int x, int y, int width, int height, Color background) -- Creates a new window with the title of the window equal to the title argument. The window is positioned on the screen at (x, y) using the coordinate system described above. If x is 100 and y is 200, then the window will appear on the screen at 100 pixels right of the leftside of the screen and 200 pixels below the top of the screen. The size of the window is determined by width and height. If the width is 300 then the hozizontal distance in pixels of the window is 300 pixels. If the height is 400 then the vertical distance in pixels of the window is 400 pixels. The final argument determines the background color of the window. Colors are described below in the Color section. But for example, if you set the color to Color.RED, then window will have a red background.

Here is an example of how the window created by the following method call looks on a Macintosh computer with a screen resolution of 1440 by 900: Paint.buildWindow("My Picture", 100, 200, 300, 400, Color.RED).

Shapes

The Paint class includes a large number of instance methods for drawing various shapes, such as lines, rectangles, and ovals. The shapes are specified using the (x,y) coordinate system described above. As described in the next two sections, the color and font (for text-based shapes) can be set arbitrarily for each shape.

• Paint.drawString(String str, int x, int y) -- Draws the text given by the string str. The string is drawn using the current color and font of the graphics context (discussed in the next two sections). x specifies the position of the left end of the string. y is the y-coordinate of the baseline of the string. The baseline is a horizontal line on which the characters rest. Some parts of the characters, such as the tail on a y or g, extend below the baseline.
• Paint.drawLine(int x1, int y1, int x2, int y2) -- Draws a line from the point (x1,y1) to the point (x2,y2).
• Paint.drawRect(int x, int y, int width, int height) -- Draws the outline of a rectangle. The upper left corner is at (x,y), and the width and height of the rectangle are as specified. If width equals height, then the rectangle is a square. If the width or the height is negative, then nothing is drawn.
• Paint.drawTriangle(int x1, int y1, int x2, int y2, int x3, int y3) -- Draws the outline of a triangle. The first corner is at (x1,y1), the second at (x2,y2), and the third at (x3,y3).
• Paint.drawOval(int x, int y, int width, int height) -- Draws the outline of an oval. The oval is one that just fits inside the rectangle specified by x, y, width, and height. If width equals height, the oval is a circle.
• Paint.drawRoundRect(int x, int y, int width, int height, int xdiam, int ydiam) -- Draws the outline of a rectangle with rounded corners. The basic rectangle is specified by x, y, width, and height, but the corners are rounded. The degree of rounding is given by xdiam and ydiam. The corners are arcs of an ellipse with horizontal diameter xdiam and vertical diameter ydiam. A typical value for xdiam and ydiam is 16, but the value used should really depend on how big the rectangle is.
• Paint.drawArc(int x, int y, int width, int height, int startAngle, int arcAngle) -- Draws part of the oval that just fits inside the rectangle specified by x, y, width, and height. The part drawn is an arc that extends arcAngle degrees from a starting angle at startAngle degrees. Angles are measured with 0 degrees at the 3 o'clock position (the positive direction of the horizontal axis). Positive angles are measured counterclockwise from zero, and negative angles are measured clockwise. To get an arc of a circle, make sure that width is equal to height.
• Paint.fillRect(int x, int y, int width, int height) -- Draws a filled-in rectangle. This fills in the interior of the rectangle that would be drawn by drawRect(x,y,width,height).
• Paint.fillTriangle(int x1, int y1, int x2, int y2, int x3, int y3) -- Draws a filled-in triangle.
• Paint.fillOval(int x, int y, int width, int height) -- Draws a filled-in oval.
• Paint.fillRoundRect(int x, int y, int width, int height, int xdiam, int ydiam) -- Draws a filled-in rounded rectangle.
• Paint.fillArc(int x, int y, int width, int height, int startAngle, int arcAngle) -- Draw a filled-in arc. This looks like a wedge of pie, whose crust is the arc that would be drawn by the drawArc method.
• Paint.clear() -- Clear the drawing window.

By default, the window is repainted after each shape is drawn, so shapes appear immediately. This can be very slow if there are a large number of shapes. In that case, auto-repaint should be turned off and window repainted manually when desired.

• Paint.setAutoRepaint(boolean auto) -- Set the auto-repaint setting - if true, repaint after every drawing command; if false, paint only when Paint.paint() is called.
• Paint.paint() -- Paint the window.

Colors

You will probably want to use color when drawing shapes with the Paint class. One of the properties of the Paint class is the current drawing color, which is used for all drawing of shapes and text. Java is designed to work with the RGB color system. An RGB color is specified by three numbers that give the level of red, green, and blue, respectively, in the color. To specify a color, you will do the following:

Paint.setColor(r,g,b);

r, g, and b are integers in the range 0 to 255. In addition, some basic colors are already defined in the built-in Java class Color: Color.WHITE, Color.BLACK, Color.RED, Color.GREEN, Color.BLUE, Color.CYAN, Color.MAGENTA, Color.YELLOW, Color.PINK, Color.ORANGE, Color.LIGHT_GRAY, Color.GRAY, and Color.DARK_GRAY. To set the color in the Paint class to a pre-defined color, you would do the following:

Paint.setColor(Color.RED);

Fonts

If you use Paint.drawString() (described above) you will probably want to set the font of the text. A font represents a particular size and style of text. The same character will appear different in different fonts. In Java, a font is characterized by a font name, a style, and a size. The available font names are system dependent, but you can always use the following four strings as font names: "Serif", "SansSerif", "Monospaced", and "Dialog". (A "serif" is a little decoration on a character, such as a short horizontal line at the bottom of the letter i. "SansSerif" means "without serifs." "Monospaced" means that all the characters in the font have the same width. The "Dialog" font is the one that is typically used in dialog boxes.)

The style of a font is specified using named constants that are defined in the Font class. You can specify the style as one of the four values:

• Font.PLAIN,
• Font.ITALIC,
• Font.BOLD, or
• Font.BOLD + Font.ITALIC.

The size of a font is an integer. Size typically ranges from about 10 to 36, although larger sizes can also be used. The size of a font is usually about equal to the height of the largest characters in the font, in pixels, but this is not an exact rule. The size of the default font is 12.

Like color, the Paint class has a current font, which is used for drawing text. You can change the the current font with the setFont() method. To set the font in the Paint class, do the following:

Paint.setFont("Serif", Font.PLAIN, 12);

Paint.setFont("SansSerif", Font.BOLD, 24);

Every graphics context has a current font, which is used for drawing text. You can change the current font with the setFont() method. For example, the command Paint.setFont("Serif", Font.PLAIN, 12) will set the current font to serif, plain with size 12. Paint.setFont("SansSerif", Font.BOLD, 24) will set the current font to sans-serif, bold with size 24. The new font will be used for any text that is drawn after the setFont() command is given.

Reading input from the user

Paint also provides limited ways of reading input from the keyboard. This process works similarly to TextIO. You can call Paint.getChar() to get a single character, Paint.getln() to get a whole line of text, and Paint.getArrow() to get an arrow key. All three routines block, meaning that the program will sit and wait until there is some input to get.

• Paint.getChar() -- Blocks until the user enters a single character, and returns that character as a char.
Paint.getln() -- Blocks until the user enters some text, and returns that text as a String.
• Paint.getArrow() -- Blocks until the user enters an arrow key, and returns an int indicating the direction of the arrow. 0 means up, 1 means down, 2 means left, and 3 means right.

API

The application programming interface (API) for the Paint class is online. It was generated from the javadoc command using comments within the source file. This webpage looks similar to Oracle's Java API webpage at http://docs.oracle.com/javase/7/docs/api.

Example

/* must include these two imports whenever using graphics, they tell 'javac' and 'java' commands that this
   program will use some built-in graphics components.
   note: these imports should go at the top of the file */
import java.awt.*;
import javax.swing.*;

/** A program that draws a number of shapes to a window with a red background.  this program uses the file
 *  Paint.java to perform the painting, therefore, Paint.java must be in the same working directory as this
 *  file in order for Picture.java to compile.
 *  @author: Marc Corliss 
 *  */
class Picture {
    /** main() method 
     *  @param args command-line arguments (unused) 
     *  */
    public static void main(String[] args) {
	// build new window
	Paint.buildWindow(/* title */"My Picture", /* starting x */100, /* starting y */100, 
			  /* horizontal size */500, /* vertical size */500, /* background color */Color.RED);

	// draw a blue outline of a rectangle (actually it's a square since width==height)
	// must first set current color in Paint to blue
	Paint.setColor(/* new color */Color.BLUE);
	// then call drawRect()
	Paint.drawRect(/* starting x */100, /* starting y */100, /* horizontal size */50, /* vertical size */50);

	// draw a green filled-in oval (actually it's a circle since width==height)
	// must first set current color in Paint to green
	Paint.setColor(/* new color */Color.GREEN);
	// then call fillOval()
	Paint.fillOval(/* starting x */100, /* starting y */100, /* horizontal size */200, /* vertical size */50);

	// draw a white outline of a triangle. method takes size parameters: x and y for each edge of triangle
	// first point is at (x1, y1), second point is at (x2, y2), and third point is at (x3, y3)
	// must first set current color in Paint to white
	Paint.setColor(/* new color */Color.WHITE);
	// then call drawTriangle()
	Paint.drawTriangle(/* x1 */300, /* y1 */300, /* x2 */350, /* y2 */300, /* x3 */400, /* y3 */350);

	// draw a black string that says "FOO" with serif, bold,24pt font
	// must first set current color in Paint to black
	Paint.setColor(/* new color */Color.BLACK);
	// must also set current font in Paint to "Serif", BOLD with size 24
	Paint.setFont(/* general type of font (either "Serif" or "SansSerif") */"Serif", 
		      /* specific type of font (e.g., Font.PLAIN, Font.BOLD, Font.ITALIC) */Font.BOLD,
		      /* size of font */24);
	// then call drawString()
	Paint.drawString(/* string to draw */"FOO", /* starting x */400, /* starting y */400);

    } // end of method main()

} // end of class Picture

Note that with graphics programs you should put the following two import statements at the top of your program:

import java.awt.*;
import javax.swing.*;

Here is what the window and screen (again with resolution 1440 by 900) will look like after compiling and running Picture.java: