CONTENTS | PREV | NEXT | Java 2D API |
The Java 2D Printing API defines three key printing abstractions:
To enable printing in an application, you need to implement the Printable interface. Your application must also generate a Book that contains the pages to be printed and then initiate the printing process through a PrintJob object.Once the application starts the print job, the printing system controls the printing process. Through calls to Printable.print, the application is asked to image pages as needed.
A Book represents a collection of pages. The pages in a book do not have to share the same size or orientation. For example, Figure 7-1 illustrates a Book that contains two letter size pages in portrait orientation, a legal size page in landscape orientation, and a tabloid size page in portrait orientation.
When a Book is first constructed, it is empty. To add pages to a Book, you use the append method. This method takes a PageFormat instance that defines the page's size, printable area, and orientation and an object that implements the Printable interface. The object that implements the Printable interface is referred to as the page painter and is responsible for drawing the page.Multiple pages in a Book can share the same page format and painter. The append method is overloaded to enable you to add a series of pages that have the same attributes by specifying a third parameter, the number of pages. You can also append the contents of one Book to another.
The setPage method is used to change a page's page format or painter. The page to be changed is identified by a page index that indicates the page's location in the book.
You can allow the user to alter the page setup information contained in the PageFormat by displaying a page setup dialog. To display the page setup dialog, you call the Toolkit.setupPage method. If the host operating system supports a page setup dialog, it is initialized from the PageFormat parameter and displayed to the user. If the user clicks the OK button in the dialog, the PageFormat instance is cloned, altered to reflect the user's selections, and then returned. If the user cancels the dialog, setupPage returns the original, unaltered PageFormat.Not all operating systems support a page setup dialog. You can determine whether or not calling setupPage will display a dialog by calling Toolkit.hasSetupPage. If the page setup dialog is not supported, setupPage will return the unaltered PageFormat when called.
A PrintJob holds print time settings and controls the printing of a Book. You get an instance of PrintJob by calling getPrintJob on the current GraphicsEnvironment. For example:
PrintJob PrintJob = GraphicsEnvironment.getLocalGraphicsEnvironment().getPrintJob( );
The collection of pages in a Book is printed by calling PrintJob.print. When a book is printed, the printing system makes calls back into the application through the page painter associated with each page.The page painter implements the Printable interface, which consists of a single method, print. When invoked, print must draw the page into a Graphics instance. The system might call the print method repeatedly for a particular page to handle banded raster printing or retrieve information about the drawing performed on that page.
Typically, an application presents a print dialog to the user when a print menu item or button is activated. To display this print dialog, you call PrintJob.setupJob, passing in the Book to be printed. The user's choices in the dialog are constrained based on the number and format of the pages in the Book.If the user clicks OK in the print dialog, setupJob returns TRUE and stores the result in the PrintJob, If the user cancels the print dialog, FALSE is returned, and the print job should be considered canceled.
To determine what portions of the page need to be drawn, you can call Graphics.getClip or Graphics.getClipBounds in the print implementation.When the printing system calls the Printable.print method, it passes in a Graphics object. On systems where the Java 2D API is available, this is an instance of Graphics2D. This Graphics object also implements the PageContext interface, enabling you to obtain information about the page from the Graphics object, including the PageFormat and the PageIndex.
To support printing in your application, you implement the Printable interface and provide the mechanism for imaging a page in the print method. This method is called by the printing system whenever a page or portion of a page needs to be drawn.You also need to provide a way for the user to trigger the print operation, for example a button or menu item. When the user initiates printing, your application should:
The system then calls your print method to image the pages.The following example illustrates how the Java 2D printing system works by printing five pages that each display a large, green page number.
import java.awt.*;
import java.awt.print.*;
public class SimplePrintTest implements Printable {
private static Font helveticaBold = new Font("Helvetica-Bold",
Font.Plain, 200);
public static void main(String[] args) {
Book book = new Book();
book.append(new PageFormat(), new SimplePrintTest(), 5);
PrintJob printJob =
GraphicsEnvironment.getLocalGraphicsEnvironment().getPrintJob();
if(printJob.setupJob(book) == true){
printJob.print(book);
}
}
void print(Graphics graphics) {
PageContext pageContext = (PageContext) graphics;
String pageName =
Integer.toString(pageContext.getPageIndex() + 1);
graphics.setFont(helveticaBold);
graphics.setColor(Color.green);
graphics.drawString(pageName, 100, 100);
}
}