| CONTENTS | PREV | NEXT | Java 2D API |
The Java Printing API is based on a callback printing model in which the printing system, not the application, controls when pages are printed. The application provides information about the document to be printed and the printing system asks the application to render each page as it needs them.The printing system might request that a particular page be rendered more than once or request that pages be rendered out of order. The application must be able to generate the proper page image, no matter which page the printing system requests. In this respect, the printing system is similar to the window toolkit, which can request components to repaint at any time, in any order.
The callback printing model is more flexible than traditional application-driven printing models and supports printing on a wider range of systems and printers. For example, if a printer stacks output pages in reverse order, the printing system can ask th e application to generate pages in reverse order so that the final stack is in proper reading order.
This model also enables applications to print to a bitmap printer from computers that don't have enough memory or disk space to buffer a full-page bitmap. In this situation, a page is printed as a series of small bitmaps or bands. For example , if only enough memory to buffer one tenth of a page is available, the page is divided into ten bands. The printing system asks the application to render each page ten times, once to fill each band. The application does not need to be aware of the number or size of the bands; it simply must be able to render each page when requested.
An application has to perform two tasks to support printing:
The user often initiates printing by clicking a button or selecting a menu item in an application. When a print operation is triggered by the user, the application creates a PrinterJob object and uses it to manage the printing process.The application is responsible for setting up the print job, displaying print dialogs to the user, and starting the printing process.
When a document is printed, the application has to render each page when the printing system requests it. To support this mechanism, the application provides a page painter that implements the Printable interface. When the printing sys tem needs a page rendered, it calls the page painter's print method.When a page painter's print method is called, it is passed a Graphics context to use to render the page image. It is also passed a PageFormat object that specifies the geometric layout of the page, and an integer p age index that identifies the ordinal position of the page in the print job.
The printing system supports both Graphics and Graphics2D rendering. To print Java 2DTM Shapes, Text, and Images, you cast the Graphics object passed into the print me thod to a Graphics2D.
To print documents in which the pages use different page painters and have different formats, you use a pageable job. To create a pageable job, you can use the Book class or your own implementation of the Pageable interface. To implement simple printing operations, you do not need to use a pageable print job; Printable can be used as long as all of the pages share the same page format and painter.
The principal job of a page painter is to render a page using the graphics context that is provided by the printing system. A page painter implements the Printable.print method:public int print(Graphics g, PageFormat pf, int pageIndex)
The graphics context passed to the print method is either an instance of Graphics or Graphics2D, depending on the packages loaded in your Java Virtual Machine. To use Graphics2D features, you can cast the G raphics object to a Graphics2D. The Graphics instance passed to print also implements the PrinterGraphics interface.
The PageFormat passed to a Printable describes the geometry of the page being printed. The coordinate system of the graphics context passed to print is fixed to the page: the origin of the coordinate system is at the upper left corner of the paper, X increases to the right, Y increases downward, and the units are 1/72 inch. If the page is in portrait orientation, the x-axis aligns with the paper's "width," while the y-axis aligns with the pape r's "height." (Normally, but not always, a paper's height exceeds its width.) If the page is in landscape orientation, the roles are reversed: the x-axis aligns with the paper's "height" and the y-axis with its "width."
Because many printers cannot print on the entire paper surface, the PageFormat specifies the imageable area of the page: this is the portion of the page in which it's safe to render. The specification of the imageable area does not alter the coordinate system; it is provided so that the contents of the page can be rendered so that they don't extend into the area where the printer can't print.
The graphics context passed to print has a clip region that describes the portion of the imageable area that should be drawn. It is always safe to draw the entire page into the context; the printing system will handle the necessary clipping. Ho wever, to eliminate the overhead of drawing portions of the page that won't be printed, you can use the clipping region to limit the areas that you render. To get the clipping region from the graphics context, call Graphics.getClip. You are strongly encouraged to use the clip region to reduce the rendering overhead.
It is sometimes desirable to launch the entire printing operation "in the background" so that a user can continue to interact with the application while pages are being rendered. To do this, call PrinterJob.print in a separate thread.
If possible, you should avoid graphics operations that require knowledge of the previous image contents, such as copyArea, setXOR, and compositing. These operations can slow rendering and the results might be inconsistent.
A Printable job provides the simplest way to print. Only one page painter is used; the application provides a single class that implements the Printable interface. When it's time to print, the printing system calls the page paint er's print method to render each page. The pages are requested in order, starting with page index 0. However, the page painter might be asked to render each page several times before it advances to the next page. When the last page has been printed, the page painter's print method returns NO_SUCH_PAGE.
- All pages use the same page painter and PageFormat. If a print dialog is presented, it will not display the number of pages in the document because that information is not available to the printing system.
- The printing system always asks the page painter to print each page in indexed order, starting with the page at index 0. No pages are skipped. For example, if a user asks to print pages 2 and 3 of a document, the page painter will be called with indices 0 , 1, and 2. The printing system might request that a page be rendered multiple times before moving to the next page.
- The page painter informs the printing system when the end of the document has been reached.
- All page painters are called in the same thread.
- Some printing systems might not be able to achieve the ideal output. For example, the stack of pages emerging from the printer might be in the wrong order, or the pages might not be collated if multiple copies are requested.
A Pageable job is more flexible than a Printable job. Unlike the pages in a Printable job, pages in a Pageable job can differ in layout and implementation. To manage a Pageable job, you can use theBook class or implement your own Pageable class. Through the Pageable, the printing system can determine the number of pages to print, the page painter to use for each page, and the PageFormat to use for each page . Applications that need to print documents that have a planned structure and format should use Pageable jobs.
- Different pages can use different page painters and PageFormats.
- The printing system can ask page painters to print pages in an arbitrary order and some pages might be skipped. For example, if a user asks to print pages 2 and 3 of a document, the page painter will be called with indices 1 and 2 and page index 0 will be skipped.
- Pageable jobs do not need to know in advance how many pages are in the document. However, unlike Printable jobs, they must be able to render pages in any order. There might be gaps in the sequencing and the printing system might requ est that a page be rendered multiple times before moving to the next page. For example, a request to print pages 2 and 3 of a document might result in a sequence of calls that request pages with indices 2,2,1,1, and 1.
An application steers the PrinterJob object through a sequence of steps to complete a printing job. The simplest sequence used by an application is:
- Determine what PageFormat to use for printing. A default PageFormat can be obtained by calling defaultPage or you can invoke pageDialog to present a dialog box that allows the user to specify a format.
- Specify the characteristics of the job to be printed to the PrinterJob. For a Printable job, call setPrintable; for a Pageable job, call setPageable. Note that a Book object is ideal for pa ssing to setPageable.
- Specify additional print job properties, such as the number of copies to print or the name of the job to print on the banner page.
- Call printDialog to present a dialog box to the user. This is optional. The contents and appearance of this dialog can vary across different platforms and printers. On most platforms, the user can use this dialog to change the printer selection . If the user cancels the print job, the printDialog method returns FALSE.
- Call Printerjob.print to print the job. This method in turn calls print on the appropriate page painters.
A job can be interrupted during printing if:
- A PrinterException is thrown--the exception is caught by the print method and the job is halted. A page painter throws a PrinterException if it detects a fatal error.
- PrinterJob.cancel is called--the printing loop is terminated and the job is canceled. The cancel method can be called from a separate thread that displays a dialog box and allows the user to cancel printing by clicking a but ton in the box.
Pages generated before a print job is stopped might or might not be printed.The print job is usually not finished when the print method returns. Work is typically still being done by a printer driver, print server, or the printer itself. The state of the PrinterJob object might not reflect the state of the a ctual job being printed.
Because the state of a PrinterJob changes during its life cycle, it is illegal to invoke certain methods at certain times. For example, calling setPageable after you've called print makes no sense. When illegal calls a re detected, the PrinterJob throws a java.lang.IllegalStateException.
The Java Printing API requires that applications invoke user-interface dialogs explicitly. These dialogs might be provided by the platform software (such as Windows) or by a JavaTM 2 SDK software implementation. For interactive applications, it is customary to use such dialogs. For production printing applications, however, dialogs are not necessary. For example, you wouldn't want to display a dialog when automatically generating and printing a nightly database report. A print job that requ ires no user interaction is sometimes called a silent print job.
You can allow the user to alter the page setup information contained in a PageFormat by displaying a page setup dialog. To display the page setup dialog, you call PrinterJob.pageDialog. The page setup dialog is initialized using the parameter passed to pageDialog. 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, pageDialog returns the original unaltered PageFormat.
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 the PrinterJob's printDialog method. The user's choices in the dialog are constrained ba sed on the number and format of the pages in the Printable or Pageable that have been furnished to the PrinterJob. If the user clicks OK in the print dialog, printDialog returns TRUE. If the user canc els the print dialog, FALSE is returned and the print job should be considered abandoned.