Chapter 21. The java.awt.print Package

The java.awt.print package contains classes and interfaces that support printing. It has been introduced in Java 1.2 and supersedes the PrintJob class of the java.awt package. The most important class in this package is PrinterJob; it coordinates the printing process. The Printable and Pageable interfaces represent printable objects or documents that can be printed with a PrinterJob. Figure 21-1 shows the class hierarchy of this package. See Chapter 5, "Printing", for more details on printing.

Figure 21-1. The java.awt.print package

Book

Java 1.2

java.awt.print

This class implements a multi-page Pageable document out of individual single-page Printable objects. Each page of the Book can have its own PageFormat specified. You might use this class, for example, in a database-reporting application when you want to print a report that consists of single-page tables and graphs in mixed portrait and landscape modes.

The append() and setPage() methods allow you to specify the Printable pages that make up the book, along with their PageFormat objects. The remaining methods implement the Pageable interface and are used by a PrinterJob to print the Book.

As with all Pageable objects, the Printable objects added to a Book must print only a single page. (See Pageable for details.) Note that the three-argument version of append() takes a numPages argument. This argument does not specify the number of pages in the Printable; instead, it specifies the number of identical copies of the single-page Printable to be printed.

public class Book implements Pageable {
//	Public Constructors
	public Book ();
//	Public Instance Methods
	public void append (Printable painter, PageFormat page);
	public void append (Printable painter, PageFormat page, int numPages);
	public void setPage (int pageIndex, Printable painter, PageFormat page) throws IndexOutOfBoundsException;
//	Methods Implementing Pageable
	public int getNumberOfPages ();	default:0
	public PageFormat getPageFormat (int pageIndex) throws IndexOutOfBoundsException;
	public Printable getPrintable (int pageIndex) throws IndexOutOfBoundsException;
}

Hierarchy: Object-->Book(Pageable)

Pageable

Java 1.2

java.awt.print

This interface is implemented by multipage documents that know how to print themselves in more sophisticated ways than the Printable interface allows. There are two primary differences between Pageable and Printable. The first is that a Pageable object knows how many pages are in the document and can print them in an arbitrary order. This allows a printer dialog to give the user the choice to print only a range of pages within the document. It also allows the user to request that the pages be printed in reverse order, which is useful on some printers that stack document pages in reverse order. The second difference between Pageable and Printable is that each page of a Pageable may have a different PageFormat associated with it. This is useful when a document contains pages in portrait orientation and some pages in landscape orientation, for example.

The heart of the Pageable interface is the method getPrintable(), which returns a Printable object able to print the specified page of the document. The Printable objects returned by this method are used differently and must be implemented differently than Printable objects that are designed to be printed alone. While standalone Printable objects may print multiple pages, the Printable objects returned by a Pageable represent only a single page. In other words, the getPrintable() method of Pageable is called once for every page in the document, and the Printable it returns is used to print only that one page.

The Pageable interface lends itself to two distinct implementation strategies. In the first, the getPrintable() method returns a different Printable object for each page of the document. This Printable object knows exactly what page to print and can ignore the pageIndex argument passed to its print() method. The second strategy is to implement a single Printable object and have the getPrintable() method always return this one object, regardless of page number. In this case, the print() method uses the pageIndex argument to decide what page to print. Note that a Printable implemented in this way must be more flexible than a standalone Printable object, since its pages may be printed in any order and are not guaranteed to be accessed sequentially.

Finally, as with standalone Printable objects, Printable objects returned by Pageable objects must be prepared to have their print() methods called multiple times for the same page number. This is a requirement for banded raster printing in low-memory environments. See Printable for details.

public abstract interface Pageable {
//	Public Constants
	public static final int UNKNOWN_NUMBER_OF_PAGES ;	=-1
//	Public Instance Methods
	public abstract int getNumberOfPages ();
	public abstract PageFormat getPageFormat (int pageIndex) throws IndexOutOfBoundsException;
	public abstract Printable getPrintable (int pageIndex) throws IndexOutOfBoundsException;
}

Implementations: Book

Passed To: PrinterJob.setPageable()

PageFormat

Java 1.2

java.awt.print

cloneable

This class is a combination of a Paper object that specifies page size and imageable area with a field that specifies the orientation of the page. The orientation values are the following:

PORTRAIT: This is the normal orientation of a piece of paper. The origin is at the top left, with the X axis running from left to right and the Y axis running from top to bottom.
LANDSCAPE: This is the orientation that results from rotating a piece of paper 90 degrees clockwise. The origin is at the bottom left of the sheet of paper, with the X axis running from bottom to top and the Y axis running from left to right.
REVERSE_LANDSCAPE: This is the orientation that results from rotating a piece of paper 90 degrees counterclockwise. The origin is at the top right of the sheet of paper, with the X axis running from top to bottom and the Y axis running from right to left.

Printable and Pageable objects are not responsible for performing the rotations necessary to print in these orientations. The appropriate transform has already been done in the Graphics object passed to the print() method of Printable.

public class PageFormat implements Cloneable {
//	Public Constructors
	public PageFormat ();
//	Public Constants
	public static final int LANDSCAPE ;	=0
	public static final int PORTRAIT ;	=1
	public static final int REVERSE_LANDSCAPE ;	=2
//	Property Accessor Methods (by property name)
	public double getHeight ();	default:792.0
	public double getImageableHeight ();	default:648.0
	public double getImageableWidth ();	default:468.0
	public double getImageableX ();	default:72.0
	public double getImageableY ();	default:72.0
	public double[ ] getMatrix ();
	public int getOrientation ();	default:1
	public void setOrientation (int orientation) throws IllegalArgumentException;
	public Paper getPaper ();
	public void setPaper (Paper paper);
	public double getWidth ();	default:612.0
//	Public Methods Overriding Object
	public Object clone ();
}

Hierarchy: Object-->PageFormat(Cloneable)

Passed To: Book.{append(), setPage()}, Printable.print(), PrinterJob.{defaultPage(), pageDialog(), setPrintable(), validatePage()}

Returned By: Book.getPageFormat(), Pageable.getPageFormat(), PrinterJob.{defaultPage(), pageDialog(), validatePage()}

Paper

Java 1.2

java.awt.print

cloneable

This class describes the width, height, and imageable area of a piece of paper. The imageable area is the region of a page that should be printed on--the area inside the margins. Most printers cannot print all the way to the edges of the page and require margins of at least a quarter inch on all sides. All coordinates and sizes used by this class are measured in printer's points, where one point is defined as exactly 1/72nd of an inch.

public class Paper implements Cloneable {
//	Public Constructors
	public Paper ();
//	Property Accessor Methods (by property name)
	public double getHeight ();	default:792.0
	public double getImageableHeight ();	default:648.0
	public double getImageableWidth ();	default:468.0
	public double getImageableX ();	default:72.0
	public double getImageableY ();	default:72.0
	public double getWidth ();	default:612.0
//	Public Instance Methods
	public void setImageableArea (double x, double y, double width, double height);
	public void setSize (double width, double height);
//	Public Methods Overriding Object
	public Object clone ();
}

Hierarchy: Object-->Paper(Cloneable)

Passed To: PageFormat.setPaper()

Returned By: PageFormat.getPaper()

Printable

Java 1.2

java.awt.print

This interface is implemented by objects that know how to print themselves. It should be implemented by objects that always print a single page, or by multipage documents that know how to print their pages in sequential order only. Multipage documents that are able to print their pages in arbitrary order should implement the somewhat more complex Pageable interface.

When a PrinterJob prints a Printable object, it calls the print() method one or more times to print the pages. This method should print the page specified by pageIndex, using the specified Graphics object and the page size and orientation specified in the PageFormat object.

The PrinterJob guarantees that it prints the pages of a Printable in strictly sequential order. The pageIndex argument begins at 0 and increases. After printing a page, the print() method should return the PAGE_EXISTS constant. Since the PrinterJob has no way of knowing how many pages there are in a Printable object, it keeps increasing the page number until the print() method returns the NO_SUCH_PAGE constant. When this value is returned, the PrinterJob knows that it has reached the end of the print job.

There is a very important twist in this communication protocol between PrinterJob and Printable. While the PrinterJob guarantees that it does not try to print pages out of order, it is allowed to print the same page multiple times. This means, for example, that the print() method may be called with a pageIndex argument of 0 three times in a row. Printable objects must be implemented with this possibility in mind. The reason that this is necessary is that, in some cases, printing is done into a very large (high-resolution) off-screen image, and this image data is then transferred to the printer. On systems with limited memory, this printing technique must be done in multiple passes, printing only a fraction, or band, of the page at each pass.

The Printable interface is also used by Pageable objects that know how to print their pages out of order. When a Printable object is returned by a Pageable object, the PrinterJob uses it differently than it does a standalone Printable object. See Pageable for details.

public abstract interface Printable {
//	Public Constants
	public static final int NO_SUCH_PAGE ;	=1
	public static final int PAGE_EXISTS ;	=0
//	Public Instance Methods
	public abstract int print (Graphics graphics, PageFormat pageFormat, int pageIndex) throws PrinterException;
}

Passed To: Book.{append(), setPage()}, PrinterJob.setPrintable()

Returned By: Book.getPrintable(), Pageable.getPrintable()

PrinterAbortException

Java 1.2

java.awt.print

serializable checked

Signals that a print job has been aborted, typically because of a user request to terminate it.

public class PrinterAbortException extends PrinterException {
//	Public Constructors
	public PrinterAbortException ();
	public PrinterAbortException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->PrinterException-->PrinterAbortException

PrinterException

Java 1.2

java.awt.print

serializable checked

This class serves as the superclass for all exceptions that may arise in the process of printing. See the subclasses PrinterAbortException and PrinterIOException. PrinterException and its subclasses are checked exceptions, they must be declared in the throws clauses of methods that may throw them.

public class PrinterException extends Exception {
//	Public Constructors
	public PrinterException ();
	public PrinterException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->PrinterException

Subclasses: PrinterAbortException, PrinterIOException

Thrown By: Printable.print(), PrinterJob.print()

PrinterGraphics

Java 1.2

java.awt.print

This interface is implemented by any Graphics object that is passed to the print() method of a Printable object. This means that a Printable can always cast its Graphics object to a PrinterGraphics object and use the getPrinterJob() method to obtain the PrinterJob that is in use.

public abstract interface PrinterGraphics {
//	Public Instance Methods
	public abstract PrinterJob getPrinterJob ();
}

PrinterIOException

Java 1.2

java.awt.print

serializable checked

Indicates that an I/O error occurred during the printing process. This usually means that the PrinterJob had trouble communicating with the printer or print server.

public class PrinterIOException extends PrinterException {
//	Public Constructors
	public PrinterIOException (java.io.IOException exception);
//	Public Instance Methods
	public java.io.IOException getIOException ();
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->PrinterException-->PrinterIOException

PrinterJob

Java 1.2

java.awt.print

This class controls printing of Printable and Pageable objects. Applications typically use this class as follows:

Create a PrinterJob by calling the static method getPrinterJob(). This requires appropriate security permissions, so untrusted applets cannot do this.

Configure the PrinterJob, if desired, by calling setJobName() and setCopies().

Interactive applications that want to give the user a choice about page orientation and margins should call pageDialog(), passing in a default PageFormat object. This method returns a new PageFormat object that contains the user's choices. While pageDialog() is suitable for simple single-page Printable objects, it typically is not necessary for more complex multipage documents, since these often have implicit or explicit margin sizes and page orientation already specified.

Call setPrintable() or setPageable() to specify the object to be printed. You can use the PageFormat object returned by pageDialog(), defaultPage(), or validatePage() when creating the Printable or Pageable object used in this step. Or you can pass such a PageFormat object to the two-argument version of setPrintable().

If your application is an interactive one, call printDialog() to give the user a chance to specify what range of pages to print or to cancel the print job. printDialog() configures the PrinterJob and returns true if the user wants to proceed with the print job. If printDialog() returns false, you should not continue with the print job. Non-interactive jobs that run unattended should skip this step.

Finally, call print() to begin printing. If you are using more than one thread, you can abort the print job by calling cancel().

PrinterJob is the preferred class for printing in Java 1.2. Do not confuse it with java.awt.PrintJob, which was introduced in Java 1.1.

public abstract class PrinterJob {
//	Public Constructors
	public PrinterJob ();
//	Public Class Methods
	public static PrinterJob getPrinterJob ();
//	Property Accessor Methods (by property name)
	public abstract boolean isCancelled ();
	public abstract int getCopies ();
	public abstract void setCopies (int copies);
	public abstract String getJobName ();
	public abstract void setJobName (String jobName);
	public abstract String getUserName ();
//	Public Instance Methods
	public abstract void cancel ();
	public PageFormat defaultPage ();
	public abstract PageFormat defaultPage (PageFormat page);
	public abstract PageFormat pageDialog (PageFormat page);
	public abstract void print () throws PrinterException;
	public abstract boolean printDialog ();
	public abstract void setPageable (Pageable document) throws NullPointerException;
	public abstract void setPrintable (Printable painter);
	public abstract void setPrintable (Printable painter, PageFormat format);
	public abstract PageFormat validatePage (PageFormat page);
}

Returned By: PrinterGraphics.getPrinterJob(), PrinterJob.getPrinterJob()