17.1 PrintGraphics Interface

Printing is similar to drawing an object on the screen. Just as you draw onto a graphics context to display something on the screen, you draw onto a "printing context" to create an image for printing. Furthermore, the printing context and graphics context are very closely related. The graphics context is an instance of the class Graphics. The printing context is also an instance of Graphics, with the additional requirement that it implement the PrintGraphics interface. Therefore, any methods that you use to draw graphics can also be used for printing. Furthermore, the paint() method (which a component uses to draw itself on the screen) is also called when a component must draw itself for printing.

In short, to print, you get a special Graphics object that implements the PrintGraphics interface by calling the getGraphics() method of PrintJob (discussed later in this chapter) through Toolkit. You then call a component's print() or printAll() method or a container's printComponents() method, with this object as the argument. These methods arrange for a call to paint(), which can draw on the printing context to its heart's content. In the simple case where you're just rendering the component on paper, you shouldn't have to change paint() at all. Of course, if you are doing something more complex (that is, printing something that doesn't look exactly like your component), you'll have to modify paint() to determine whether it's painting on screen or on paper, and act accordingly. The code would look something like this:

public void paint(Graphics g) {
    if (g instanceof PrintGraphics) {
        // Printing
    }else {
        // Painting
    }
}

If the graphics object you receive is an instance of PrintGraphics, you know that paint() has been called for a print request and can do anything specific to printing. As I said earlier, you can use all the methods of Graphics to draw on g. If you're printing, though, you might do anything from making sure that you print in black and white to drawing something completely different. (This might be the trick you use to print the contents of a component rather than the component itself. However, as of Java 1.1, it's impossible to prevent the component from drawing itself. Remember that your paint() method was never responsible for drawing the component; it only drew additions to the basic component. For the time being, it's the same with printing.)

When you call printComponents() on a Container, all the components within the container will be printed. Early beta versions of 1.1 only painted the outline of components within the container. The component should print as it appears on the screen.