Swing Graphics

Introduction

To do custom graphics in an applet or application, you will almost always write a new class that extends the JPanel class. In that class, you override the definition of the paintComponent() method. This method should have the following form.

    public void paintComponent(Graphics g) {
	super.paintComponent(g);
	drawing messages sent to g
    }

The kinds of messages that you can send to g are described in the next section.

In addition, if the drawings need to be updated while the applet or application is running then you need to invoke the following method.

void repaint()

This method can be invoked from within the JPanel subclass or from another object.

Graphics

A Graphics object controls the visual appearance of a Swing component. Most Swing components have a built-in appearance, but a JPanel has none except for a uniform background color. This makes JPanel ideal for custom graphics. Its Graphics object is obtained as a parameter to the paintComponent() method. Once you have the Graphics object, you can send it messages to change the color or font that it uses, or to draw a variety of geometric figures. You can send it messages using the following methods.

void setColor(Color color)
void setFont(Font font)
void drawString(String text, int x, int y)
void drawLine(int x1, int y1, int x2, int y2)
void drawRect(int x, int y, int width, int height)
void drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight)
void drawOval(int x, int y, int width, int height)
void drawArc(int x, int y, int width, int height, int startAngle, int angularExtent)
void fillRect(int x, int y, int width, int height)
void fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight)
void fillOval(int x, int y, int width, int height)
void fillArc(int x, int y, int width, int height, int startAngle, int angularExtent)

The meanings of the parameters is most easily understood by working with the Graphics Demo applet.

A Custom Graphics Template

Here is a template for a custom graphics JPanel subclass.

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

    public class ClassName
    extends JPanel {

	instance variable declarations

	helper methods

	public constructors

	public methods for communication

	public void paintComponent(Graphics g) {
	    super.paintComponent(g);
	    drawing messages sent to g
	}

    }

Java 2D Graphics

The graphics that you can do with a Graphics object is primitive. You cannot use real number coordinates. You cannot draw dotted or dashed lines or lines with varying widths. You cannot easily draw complex curves or draw or fill complex shapes. You cannot use textures or gradient colors for filling shapes.

To address these limitations, Sun introduced the Graphics2D class into its class libraries. This class extends the Graphics class, so all of the Graphics methods can be used with a Graphics2D object.

Sun also modified the implementation of its graphical user interface components so that they used a Graphics2D object instead of a Graphics object. To maintain compatibility with existing code, the paint methods are still declared with a Graphics parameter, but a Graphics2D object is actually passed.

To use the Graphics2D capabilities in a JPanel subclass, you need to have a variable of type Graphics2D. This can be obtained by coercing the paint method parameter. For example, you can modify the paintComponent() method in the above template as follows.

    public void paintComponent(Graphics g) {
	super.paintComponent(g);
	Graphics2D g2d = (Graphics2D)g;
	drawing messages sent to g2d
    }

In this code, g and g2d actually refer to the same object, which is an instance of the Graphics2D class. They differ only in the variable types, which determines the operations allowed by a Java compiler. A compiler will allow a setStroke() (see the next section) message to be sent to g2d, but not to g. The reason is that setStroke() is a Graphics2D method but not a Graphics method.

Graphics2D Class

The full capabilities of the Graphics2D class are beyond the scope of this document. Only one method is documented here to give you an idea of the capabilities.

void setStroke(Stroke strk)

Stroke is an inteface defined in the java.awt package. Since it is an interface, you cannot directly construct one. Instead, you construct an instance of a class that implements the Stroke interface. The only direct implementing class is the BasicStoke class, which is described in the next section.

BasicStroke Class

You will rarely need to do anything with the BasicStroke class other than specifying a BasicStroke object as a parameter in some method such as Graphics2D.setStroke(Stroke). For this, you only need to use one of the following constructors.

new BasicStroke(float width)
new BasicStroke(float width, int cap, int join)

The width parameter is specified in pixels. If it is a literal value with a decimal point, it should have the character "f" immediately following (e.g. 3.5f) to avoid being treated as a double.

The second parameter should be one of the predefined constants

BasicStroke.CAP_BUTT
BasicStroke.CAP_ROUND
BasicStroke.CAP_SQUARE

The third parameter should be one of the predefined constants

BasicStroke.JOIN_BEVEL
BasicStroke.JOIN_MITER
BasicStroke.JOIN_ROUND

More Information

For further information on Swing graphics, see Sun's tutorial web pages Painting and Working with Graphics. For more information on Java 2D graphics, see 2D Graphics. You can also check the documentation for the Java APIs for the java.awt and java.awt.geom packages.