java2 printing api jean-cédric desrochers march 9, 2000

Java2 Printing API

Jean-Cédric Desrochers

March 9, 2000


2

Agenda

• Java2 Printing API:- Printing concepts

- The java.awt.print package

- Examples

• Real World Experience- Projects and Realization

- Issues and Workarounds

• What’s new in JDK 1.3


3

Printing Concepts

• Based on a callback model :- Printing system controls when pages are printed;

- Application provides pages to print;

- Pages requested out of order and more than once;

• More flexible :- Reverse order;

- Print with a series of bands;


4

• Job control entities :- Initiate and control the printing process;

- Java provides classes like PrinterJob, PageFormat and Paper to manage print jobs;

• Document related entities :- Low-level classes like Printable knows how to

render a single kind of page (page painter);

- High-level classes like Pageable and Book represent a collection of pages with different formats;

Printing Concepts (ii)


5

• Page painter :- Render a page using a graphics context;

- Implements the printable.Print() method;

- Notifies when all pages are rendered;

Printing Concepts (iii)

public int print(Graphics g, PageFormat page, int pageIndex)


6

The java.awt.print package«Abstract»

PrinterJob

+getPrinterJob() : PrinterJob+cancel() : void+defaultPage() : PageFormat+defaultPage(page : PageFormat) : PageFormat+getCopies() : int+getJobName() : int+getUserName() : String+isCancelled() : boolean+pageDialog(page : PageFormat) : PageFormat+print() : void+printDialog() : boolean+setCopies(copies : int) : void+setJobName(jobName : String) : void+setPageable(document : Pageable) : void+setPrintable(painter : Printable) : void+validatePage(page : PageFormat) : PageFormat

«Interface»Printable

+print(g : Graphics, page : PageFormat, pageIndex : int) : int

+NO_SUCH_PAGE : int+PAGE_EXISTS : int

«Interface»Pageable

+getNumberOfPages() : int+getPageFormat(pageIndex : int) : PageFormat+getPrintable(pageIndex : int) : Printable

+UNKNOWN_NUMBER_OF_PAGES : int«Interface»

PrinterGraphics

+getPrinterJob() : PrinterJob

PageFormat

+PageFormat()+clone() : Object+getHeight() : double+getImageableHeight() : double+getImageableWidth() : double+getImageableX() : double+getImageableY() : double+getMatrix() : double[]+getOrientation() : int+getPaper() : Paper+getWidth() : double+setOrientation(orientation : int) : void+setPaper(paper : Paper) : void

+LANDSCAPE : int+PORTRAIT : int+REVERSE_LANDSCAPE : int

Paper

+Paper()+clone() : Object+getHeight() : double+getImageableHeight() : double+getImageableWidth() : double+getImageableX() : double+getImageableY() : double+getWidth() : double+setImageableArea(x : double, y : double, width : double, height : double) : void+setSize(width : double, height : double) : void

Book

+Book()+append(painter : Printable, page : PageFormat) : void+append(painter : Printable, page : PageFormat, numPages : int) : void+getNumberOfPages() : int+getPageFormat(pageIndex : int) : PageFormat+getPrintable(pageIndex : int) : Printable+setPage(pageIndex : int, painter : Printable, page : PageFormat) : void

«Interface»Cloneable


7

Printable Interface

• Simplest way to print:- Application provides a page painter;- Printing system calls the print() method;

• In a Printable job:- Only one painter and one PageFormat;- Job starts with page at index 0 (sequential);- Page painter notifies when the end of the doc

has been reached;- Single-threaded;

«Interface»Printable

+print(g : Graphics, page : PageFormat, pageIndex : int) : int

+NO_SUCH_PAGE : int+PAGE_EXISTS : int


8

Pageable Interface

• More flexible:- Pages differ in layout and implementation;

- The system knows the number of pages;

• In a Pageable job:- Different page painters and PageFormats;

- Pages printed in an arbitrary order;

«Interface»Pageable

+getNumberOfPages() : int+getPageFormat(pageIndex : int) : PageFormat+getPrintable(pageIndex : int) : Printable

+UNKNOWN_NUMBER_OF_PAGES : int


9

PrinterJob Class

• Typical Life-Cycle:1) Get a new PrinterJob by calling getPrinterJob()

2) Determine what PageFormat to use

3) Set the Printable or the Pageable object to be printed

4) Additional properties (copies, job name)

5) Call printDialog() to show a dialog box (optional)

6) Call print() to print the job

«Abstract»PrinterJob

+getPrinterJob() : PrinterJob+cancel() : void+defaultPage() : PageFormat+defaultPage(page : PageFormat) : PageFormat+getCopies() : int+getJobName() : int+getUserName() : String+isCancelled() : boolean+pageDialog(page : PageFormat) : PageFormat+print() : void+printDialog() : boolean+setCopies(copies : int) : void+setJobName(jobName : String) : void+setPageable(document : Pageable) : void+setPrintable(painter : Printable) : void+validatePage(page : PageFormat) : PageFormat


10

PageFormat Class

• Describes the geometry of the page:- Origin is at the upper left corner of paper;

- Units are in 1/72 inch;

- Specifies the imageable area of the page;

PageFormat

+PageFormat()+clone() : Object+getHeight() : double+getImageableHeight() : double+getImageableWidth() : double+getImageableX() : double+getImageableY() : double+getMatrix() : double[]+getOrientation() : int+getPaper() : Paper+getWidth() : double+setOrientation(orientation : int) : void+setPaper(paper : Paper) : void

+LANDSCAPE : int+PORTRAIT : int+REVERSE_LANDSCAPE : int

(0,0)

Imageable Area

X

Y(0,0)

Imageable Area

X

Y


11

Printing using Printableimport java.awt.*;import java.awt.print.*;

public class SimplePrint implements Printable {

private String stringToPrint;

public SimplePrint() { this("This is the Default String. Go Blues!!!"); }

public SimplePrint(String stringToPrint) { this.stringToPrint = stringToPrint; }

public int print(Graphics g, PageFormat pf, int pageIndex) throws PrinterException { if (pageIndex >= 1) { return Printable.NO_SUCH_PAGE; }

g.setFont(new Font("Helvetica", Font.PLAIN, 24)); g.setColor(Color.green); g.drawString(stringToPrint, 100, 100);

return Printable.PAGE_EXISTS; } ...


12

Printing using Printable (ii) ...

public static void main(String[] args) { // Get a PrintJob PrinterJob pj = PrinterJob.getPrinterJob(); Printable painter;

// Specify the painter if (args.length == 0) { painter = new SimplePrint(); } else { painter = new SimplePrint(args[0]); }

pj.setPrintable(painter);

// Show the print dialog if (pj.printDialog()) { try { pj.print(); } catch (PrinterException pe) { System.out.println("Exception while printing.\n"); pe.printStackTrace(); } } }}


13

Example with Graphics2D ...


Graphics2D g2 = (Graphics2D) g; g2.setFont(new Font("Helvetica", Font.PLAIN, 24));

Paint defaultPaint = new GradientPaint(100f, 100f, Color.blue, (float) g2.getFontMetrics().getStringBounds( stringToPrint, g2).getWidth(), 100f, Color.red);

g2.setPaint(defaultPaint); g2.drawString(stringToPrint, 100, 100);

return Printable.PAGE_EXISTS; }

...


14

Printing Swing Components

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

public class PrintableJPanel extends JPanel implements Printable {


paint (g);

return Printable.PAGE_EXISTS; }}


15

Printing Swing Components (ii)

public class SimpleFrame extends JFrame { private PrintableJPanel panel;

...

private void printAction() { // Get a PrintJob PrinterJob pj = PrinterJob.getPrinterJob(); pj.setPrintable(panel);

// Show the print dialog if (pj.printDialog()) { try { pj.print(); } catch (PrinterException pe) { System.out.println("Exception while printing.\n"); pe.printStackTrace(); } } }

...


16

Printing using Pageable ...

public static void main(String[] args) { // Get a PrintJob PrinterJob pj = PrinterJob.getPrinterJob(); Book book = new Book(); Printable painter;

// Specify the painter if (args.length == 0) { painter = new SimplePrint2DBook(); } else { painter = new SimplePrint2DBook(args[0]); }

PageFormat pageFormat = pj.pageDialog(pj.defaultPage()); book.append(painter, pageFormat); pj.setPageable(book);

// Show the print dialog if (pj.printDialog()) { try { pj.print(); } catch (PrinterException pe) { System.out.println("Exception while printing.\n"); pe.printStackTrace(); } } } ...


17

Other Classes

• PrinterGraphics Interface:- Implemented by Graphics objects that are passed to

a Printable object;

• Paper Class:- Physical characteristics of a piece of paper;- Used by the PageFormat;

«Interface»PrinterGraphics

+getPrinterJob() : PrinterJob

Paper

+Paper()+clone() : Object+getHeight() : double+getImageableHeight() : double+getImageableWidth() : double+getImageableX() : double+getImageableY() : double+getWidth() : double+setImageableArea(x : double, y : double, width : double, height : double) : void+setSize(width : double, height : double) : void


18

Exceptions

• PrinterException:- Thrown by the Printable.print() method

• PrinterIOException:- Subclass of PrinterException;

- IO error occured during printing;

• PrinterAbortException:- Subclass of PrinterException;

- User or application cancelled the print job;


19

Real World Experience

• Build and print HTML Reports:- Generated with Oracle Reports;- Available through HTTP server;- Shown in Java GUI with ICEBrowser;

• Great Ideas:- Use the browser’s panel to print;- Manage multiple pages;


20

Challenges

• Image Quality:- Resolution was awful;

• Turn double buffering off:- Faster printing;

- Higher resolution and quality;

RepaintManager.currentManager(frame).setDoubleBufferingEnabled(false);


21

Challenges (ii)

• Formatting of documents:- Unable to set margins;

- Printing system use default PageFormat;

- Known bug;

• Printing very long:- Generating HUGE spool file;

- Only on Windows with Laser Printers;

- Also, known bug;


22

Advance Features

• Use of translate():- Moves an imaginary pen to a next position;

• Use of clip areas:- Restrict the component to only be painted in a given

area;

g2.translate(pf.getImageableX(), pf.getImageableY());

g2.setClip(int x, int y, int width, int height); g2.setClip(Shape clip);


23

Advance Features (ii)

• Use of scaling:- Scales the 2D graphics context;

- Ratio of one maintains the size;

• Other Graphics operations:- Rotation;

- Transformation;

g2.scale(xRatio, yRatio);


24

What’s new in JDK1.3

• Same package, same classes;

• A lot of bug fixes!!!

• New classes for AWT printing model:- JobAttributes class;- PageAttributes class;


25

Conclusion

• A good printing model;

• Need some tuning;

• Based on native resources;

• Learn use of Java2D API;

java2 printing api jean-cédric desrochers march 9, 2000

Documents