Java Print Service API User Guide: 5 - Printing and Streaming 2D Graphics

Using PrinterJob to Print or Stream Graphics

The API in java.awt.print consists of these PrinterJob methods:

Static convenience methods to look up print services that can image 2D graphics, which are returned as an array of PrintService or StreamPrintServiceFactory objects depending on the method.
Methods to set and get a PrintService on a PrinterJob.
A pageDialog method that takes a PrintRequestAttributeSet parameter.
A printDialog method that takes a PrintRequestAttributeSet parameter.
A print method that takes a PrintRequestAttributeSet parameter.

Because the printDialog and pageDialog methods take an attribute set, users can edit the initial attribute settings from the dialogs.

Applications can use PrinterJob to print 2D graphics to a printer or to an output stream. The lookupPrintServices method returns an array of PrintService objects, each of which represents a printer that can print 2D graphics. The lookupStreamPrintServices method returns an array of StreamPrintServiceFactory objects, each of which can return a StreamPrintService. An application uses the StreamPrintService to send print data to an output stream. As with printing documents, applications can use a StreamPrintService to transcode 2D graphics to other formats. This section discusses using PrinterJob to submit 2D graphics to a printer and to an output stream.

Printing 2D Graphics

The pageDialog, printDialog, and print methods allow an application to initialize print settings and pass these settings to a dialog so that a user can update the settings before submitting the print request, as demonstrated by this code sample:

// Step 1: Set up initial print settings.
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
// Step 2: Obtain a print job.
PrinterJob pj = PrinterJob.getPrinterJob();
// Step 3: Find print services.
PrintService []services = PrinterJob.lookupPrintServices();
if (services.length > 0) {
        System.out.println("selected printer: " + services[0]);
        try {
        pj.setPrintService(service[0]); 
        // Step 2: Pass the settings to a page dialog and print dialog.
        pj.pageDialog(aset);
        if (pj.printDialog(aset)) {
                // Step 4: Update the settings made by the user in the dialogs.
                // Step 5: Pass the final settings into the print request.
                pj.print(aset);
        }
        } catch (PrinterException(pe)) {
                System.err.println(pe):
        }
}

See Example: Print2DPrinterJob.java for the complete application.

Note that Step 4 in this code sample does not seem to correspond to any particular line of code. In fact, the user updates the print settings in the dialogs, and the updated settings are saved in the PrintRequestAttributeSet, aset.

One problem with using Java 2D and the Java Print Service together is that some attributes, such as number of copies, are defined in both APIs. If such an attribute is specified in a PrintRequestAttributeSet, it takes precedence over the same attribute specified in the PrinterJob. Note that if a user updates the number of copies in a print dialog, the PrinterJob is automatically updated to reflect that, which reconfirms the existing behavior.

The PageFormat specification also overlaps with the Java Print Service Media, MediaPrintableArea, and OrientationRequested attributes. If an application uses the Printable interface and the print(PrintRequestAttributeSet) method, the media, orientation, and imageable area attributes contained in the attribute set are added to a new PageFormat, which is passed to the print method of the Printable object. If an application uses the Pageable interface, the PageFormat does not change.

Streaming 2D Graphics

An application can also use a PrinterJob and a StreamPrintService to send print data to an output stream. This example is similar to the example in the previous section, except a StreamPrintService is used in place of a PrintService:

PrinterJob job = PrinterJob.getPrinterJob();
String psMimeType = "application/postscript";
FileOutputStream outstream; 
StreamPrintService psPrinter; 
StreamPrintServiceFactory []spsFactories =
        PrinterJob.lookupStreamPrintServices(psMimeType);
if (factories.length > 0) { 
        try { 
                outstream = new File("out.ps"); 
                psPrinter = factories[0].getPrintService(fos); 
                // psPrinter can now be set as the service on a PrinterJob 
        } catch (FileNotFoundException e) { } 
} 
job.setPrintService(service[0]); // if app wants to specify this printer.
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(new Copies(2));
job.print(aset);
}

CONTENTS | PREV | NEXT