APIdia Launch Partner
Top Description Constructors Methods
java.awt.print

public abstract Class PrinterJob

extends Object
Class Inheritance
Known Direct Subclasses
sun.print.RasterPrinterJob
Imports
java.awt.AWTError, .HeadlessException, javax.print.DocFlavor, .PrintService, .PrintServiceLookup, .StreamPrintServiceFactory, javax.print.attribute.AttributeSet, .PrintRequestAttributeSet, javax.print.attribute.standard.Media, .MediaPrintableArea, .MediaSize, .MediaSizeName, .OrientationRequested
The PrinterJob class is the principal class that controls printing. An application calls methods in this class to set up a job, optionally to invoke a print dialog with the user, and then to print the pages of the job.

Constructor Summary

AccessConstructor and Description
public
PrinterJob()

A PrinterJob object should be created using the static getPrinterJob method.

Method Summary

Modifier and TypeMethod and Description
public abstract void
cancel()

Cancels a print job that is in progress.

public abstract PageFormat

Returns:

clone of page, altered to describe a default PageFormat.
defaultPage(PageFormat
the PageFormat to be cloned and altered
page)

Clones the PageFormat argument and alters the clone to describe a default page size and orientation.

public PageFormat

Returns:

a PageFormat set to a default size and orientation.
defaultPage()

Creates a new PageFormat instance and sets it to a default size and orientation.

public abstract int

Returns:

the number of copies to be printed.
getCopies()

Gets the number of copies to be printed.

public abstract String

Returns:

the name of the document to be printed.
getJobName()

Gets the name of the document to be printed.

public PageFormat

Returns:

a PageFormat whose settings conform with those of the current service and the specified attributes.
getPageFormat(PrintRequestAttributeSet
a set of printing attributes, for example obtained from calling printDialog. If attributes is null a default PageFormat is returned.
attributes)

Calculates a PageFormat with values consistent with those supported by the current PrintService for this job (ie the value returned by getPrintService()) and media, printable area and orientation contained in attributes.

public static PrinterJob

Returns:

a new PrinterJob.
getPrinterJob()

Creates and returns a PrinterJob which is initially associated with the default printer.

public PrintService

Returns:

the service for this printer job.
getPrintService()

Returns the service (printer) for this printer job.

public abstract String

Returns:

the name of the printing user
getUserName()

Gets the name of the printing user.

public abstract boolean

Returns:

true if the job in progress is going to be cancelled; false otherwise.
isCancelled()

Returns true if a print job is in progress, but is going to be cancelled at the next opportunity; otherwise returns false.

public static PrintService[]

Returns:

a possibly empty array of 2D print services.
lookupPrintServices()

A convenience method which looks up 2D print services.

public static StreamPrintServiceFactory[]

Returns:

a possibly empty array of 2D stream print service factories.
lookupStreamPrintServices(String
the required output format, or null to mean any format.
mimeType)

A convenience method which locates factories for stream print services which can image 2D graphics.

public abstract PageFormat

Returns:

the original page object if the dialog is cancelled; a new PageFormat object containing the format indicated by the user if the dialog is acknowledged.
pageDialog(PageFormat
the default PageFormat presented to the user for modification
page)

Displays a dialog that allows modification of a PageFormat instance.

public PageFormat

Returns:

a page format if the user does not cancel the dialog; null otherwise.
pageDialog(PrintRequestAttributeSet
on input is application supplied attributes, on output the contents are updated to reflect user choices. This parameter may not be null.
attributes)

A convenience method which displays a cross-platform page setup dialog.

public abstract boolean

Returns:

true if the user does not cancel the dialog; false otherwise.
printDialog()

Presents a dialog to the user for changing the properties of the print job.

public boolean

Returns:

true if the user does not cancel the dialog; false otherwise.
printDialog(PrintRequestAttributeSet
on input is application supplied attributes, on output the contents are updated to reflect user choices. This parameter may not be null.
attributes)

A convenience method which displays a cross-platform print dialog for all services which are capable of printing 2D graphics using the Pageable interface.

public abstract void
setCopies(int
the number of copies to be printed
copies)

Sets the number of copies to be printed.

public abstract void
setJobName(String
the name of the document to be printed
jobName)

Sets the name of the document to be printed.

public abstract void
setPageable(Pageable
the pages to be printed. It can not be null.
document)

Queries document for the number of pages and the PageFormat and Printable for each page held in the Pageable instance, document.

public abstract void
setPrintable(Printable
the Printable that renders each page of the document.
painter)

Calls painter to render the pages.

public abstract void
setPrintable(Printable
the Printable called to render each page of the document
painter, PageFormat
the size and orientation of each page to be printed
format)

Calls painter to render the pages in the specified format.

public void
setPrintService(PrintService
a print service that supports 2D printing
service)

Associate this PrinterJob with a new PrintService.

public abstract PageFormat

Returns:

a PageFormat that is cloned from page and whose settings are changed to conform with this PrinterJob.
validatePage(PageFormat
the PageFormat that is cloned and whose settings are changed to be compatible with the current printer
page)

Returns the clone of page with its settings adjusted to be compatible with the current printer of this PrinterJob.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

PrinterJobback to summary
public PrinterJob()

A PrinterJob object should be created using the static getPrinterJob method.

Method Detail

cancelback to summary
public abstract void cancel()

Cancels a print job that is in progress. If print has been called but has not returned then this method signals that the job should be cancelled at the next chance. If there is no print job in progress then this call does nothing.

defaultPageback to summary
public abstract PageFormat defaultPage(PageFormat page)

Clones the PageFormat argument and alters the clone to describe a default page size and orientation.

Parameters
page:PageFormat

the PageFormat to be cloned and altered

Returns:PageFormat

clone of page, altered to describe a default PageFormat.

defaultPageback to summary
public PageFormat defaultPage()

Creates a new PageFormat instance and sets it to a default size and orientation.

Returns:PageFormat

a PageFormat set to a default size and orientation.

getCopiesback to summary
public abstract int getCopies()

Gets the number of copies to be printed.

Returns:int

the number of copies to be printed.

See Also
setCopies
getJobNameback to summary
public abstract String getJobName()

Gets the name of the document to be printed.

Returns:String

the name of the document to be printed.

See Also
setJobName
getPageFormatback to summary
public PageFormat getPageFormat(PrintRequestAttributeSet attributes)

Calculates a PageFormat with values consistent with those supported by the current PrintService for this job (ie the value returned by getPrintService()) and media, printable area and orientation contained in attributes.

Calling this method does not update the job. It is useful for clients that have a set of attributes obtained from printDialog(PrintRequestAttributeSet attributes) and need a PageFormat to print a Pageable object.

Parameters
attributes:PrintRequestAttributeSet

a set of printing attributes, for example obtained from calling printDialog. If attributes is null a default PageFormat is returned.

Returns:PageFormat

a PageFormat whose settings conform with those of the current service and the specified attributes.

Since
1.6
getPrinterJobback to summary
public static PrinterJob getPrinterJob()

Creates and returns a PrinterJob which is initially associated with the default printer. If no printers are available on the system, a PrinterJob will still be returned from this method, but getPrintService() will return null, and calling print with this PrinterJob might generate an exception. Applications that need to determine if there are suitable printers before creating a PrinterJob should ensure that the array returned from lookupPrintServices is not empty.

Returns:PrinterJob

a new PrinterJob.

getPrintServiceback to summary
public PrintService getPrintService()

Returns the service (printer) for this printer job. Implementations of this class which do not support print services may return null. null will also be returned if no printers are available.

Returns:PrintService

the service for this printer job.

Since
1.4
See Also
setPrintService(PrintService), getPrinterJob()
getUserNameback to summary
public abstract String getUserName()

Gets the name of the printing user.

Returns:String

the name of the printing user

isCancelledback to summary
public abstract boolean isCancelled()

Returns true if a print job is in progress, but is going to be cancelled at the next opportunity; otherwise returns false.

Returns:boolean

true if the job in progress is going to be cancelled; false otherwise.

lookupPrintServicesback to summary
public static PrintService[] lookupPrintServices()

A convenience method which looks up 2D print services. Services returned from this method may be installed on PrinterJobs which support print services. Calling this method is equivalent to calling PrintServiceLookup.lookupPrintServices() and specifying a Pageable DocFlavor.

Returns:PrintService[]

a possibly empty array of 2D print services.

Since
1.4
lookupStreamPrintServicesback to summary
public static StreamPrintServiceFactory[] lookupStreamPrintServices(String mimeType)

A convenience method which locates factories for stream print services which can image 2D graphics. Sample usage : 

FileOutputStream outstream;
StreamPrintService psPrinter;
String psMimeType = "application/postscript";
PrinterJob pj = PrinterJob.getPrinterJob();

StreamPrintServiceFactory[] factories =
    PrinterJob.lookupStreamPrintServices(psMimeType);
if (factories.length > 0) {
    try {
        outstream = new File("out.ps");
        psPrinter =  factories[0].getPrintService(outstream);
        // psPrinter can now be set as the service on a PrinterJob
        pj.setPrintService(psPrinter)
    } catch (Exception e) {
        e.printStackTrace();
    }
}
Services returned from this method may be installed on PrinterJob instances which support print services. Calling this method is equivalent to calling StreamPrintServiceFactory.lookupStreamPrintServiceFactories() and specifying a Pageable DocFlavor.
Parameters
mimeType:String

the required output format, or null to mean any format.

Returns:StreamPrintServiceFactory[]

a possibly empty array of 2D stream print service factories.

Since
1.4
pageDialogback to summary
public abstract PageFormat pageDialog(PageFormat page) throws HeadlessException

Displays a dialog that allows modification of a PageFormat instance. The page argument is used to initialize controls in the page setup dialog. If the user cancels the dialog then this method returns the original page object unmodified. If the user okays the dialog then this method returns a new PageFormat object with the indicated changes. In either case, the original page object is not modified.

Parameters
page:PageFormat

the default PageFormat presented to the user for modification

Returns:PageFormat

the original page object if the dialog is cancelled; a new PageFormat object containing the format indicated by the user if the dialog is acknowledged.

Exceptions
HeadlessException:
if GraphicsEnvironment.isHeadless() returns true.
Since
1.2
See Also
java.awt.GraphicsEnvironment#isHeadless
pageDialogback to summary
public PageFormat pageDialog(PrintRequestAttributeSet attributes) throws HeadlessException

A convenience method which displays a cross-platform page setup dialog. The choices available will reflect the print service currently set on this PrinterJob.

The attributes parameter on input will reflect the client's required initial selections in the user dialog. Attributes which are not specified display using the default for the service. On return it will reflect the user's choices. Selections may be updated by the implementation to be consistent with the supported values for the currently selected print service.

The return value will be a PageFormat equivalent to the selections in the PrintRequestAttributeSet. If the user cancels the dialog, the attributes will not reflect any changes made by the user, and the return value will be null.

Parameters
attributes:PrintRequestAttributeSet

on input is application supplied attributes, on output the contents are updated to reflect user choices. This parameter may not be null.

Returns:PageFormat

a page format if the user does not cancel the dialog; null otherwise.

Exceptions
HeadlessException:
if GraphicsEnvironment.isHeadless() returns true.
NullPointerException:
if attributes parameter is null.
Since
1.4
See Also
java.awt.GraphicsEnvironment#isHeadless
printback to summary
public abstract void print() throws PrinterException

Prints a set of pages.

Exceptions
PrinterException:
an error in the print system caused the job to be aborted.
See Also
Book, Pageable, Printable
printback to summary
public void print(PrintRequestAttributeSet attributes) throws PrinterException

Prints a set of pages using the settings in the attribute set. The default implementation ignores the attribute set.

Note that some attributes may be set directly on the PrinterJob by equivalent method calls, (for example), copies: setCopies(int), job name: setJobName(String) and specifying media size and orientation though the PageFormat object.

If a supported attribute-value is specified in this attribute set, it will take precedence over the API settings for this print() operation only. The following behaviour is specified for PageFormat: If a client uses the Printable interface, then the attributes parameter to this method is examined for attributes which specify media (by size), orientation, and imageable area, and those are used to construct a new PageFormat which is passed to the Printable object's print() method. See Printable for an explanation of the required behaviour of a Printable to ensure optimal printing via PrinterJob. For clients of the Pageable interface, the PageFormat will always be as supplied by that interface, on a per page basis.

These behaviours allow an application to directly pass the user settings returned from printDialog(PrintRequestAttributeSet attributes to this print() method.

Parameters
attributes:PrintRequestAttributeSet

a set of attributes for the job

Exceptions
PrinterException:
an error in the print system caused the job to be aborted.
Since
1.4
See Also
Book, Pageable, Printable
printDialogback to summary
public abstract boolean printDialog() throws HeadlessException

Presents a dialog to the user for changing the properties of the print job. This method will display a native dialog if a native print service is selected, and user choice of printers will be restricted to these native print services. To present the cross platform print dialog for all services, including native ones instead use printDialog(PrintRequestAttributeSet).

PrinterJob implementations which can use PrintService's will update the PrintService for this PrinterJob to reflect the new service selected by the user.

Returns:boolean

true if the user does not cancel the dialog; false otherwise.

Exceptions
HeadlessException:
if GraphicsEnvironment.isHeadless() returns true.
See Also
java.awt.GraphicsEnvironment#isHeadless
printDialogback to summary
public boolean printDialog(PrintRequestAttributeSet attributes) throws HeadlessException

A convenience method which displays a cross-platform print dialog for all services which are capable of printing 2D graphics using the Pageable interface. The selected printer when the dialog is initially displayed will reflect the print service currently attached to this print job. If the user changes the print service, the PrinterJob will be updated to reflect this, unless the user cancels the dialog. As well as allowing the user to select the destination printer, the user can also select values of various print request attributes.

The attributes parameter on input will reflect the applications required initial selections in the user dialog. Attributes not specified display using the default for the service. On return it will reflect the user's choices. Selections may be updated by the implementation to be consistent with the supported values for the currently selected print service.

As the user scrolls to a new print service selection, the values copied are based on the settings for the previous service, together with any user changes. The values are not based on the original settings supplied by the client.

With the exception of selected printer, the PrinterJob state is not updated to reflect the user's changes. For the selections to affect a printer job, the attributes must be specified in the call to the print(PrintRequestAttributeSet) method. If using the Pageable interface, clients which intend to use media selected by the user must create a PageFormat derived from the user's selections. If the user cancels the dialog, the attributes will not reflect any changes made by the user.

Parameters
attributes:PrintRequestAttributeSet

on input is application supplied attributes, on output the contents are updated to reflect user choices. This parameter may not be null.

Returns:boolean

true if the user does not cancel the dialog; false otherwise.

Exceptions
HeadlessException:
if GraphicsEnvironment.isHeadless() returns true.
NullPointerException:
if attributes parameter is null.
Since
1.4
See Also
java.awt.GraphicsEnvironment#isHeadless
setCopiesback to summary
public abstract void setCopies(int copies)

Sets the number of copies to be printed.

Parameters
copies:int

the number of copies to be printed

See Also
getCopies
setJobNameback to summary
public abstract void setJobName(String jobName)

Sets the name of the document to be printed. The document name can not be null.

Parameters
jobName:String

the name of the document to be printed

See Also
getJobName
setPageableback to summary
public abstract void setPageable(Pageable document) throws NullPointerException

Queries document for the number of pages and the PageFormat and Printable for each page held in the Pageable instance, document.

Parameters
document:Pageable

the pages to be printed. It can not be null.

Exceptions
NullPointerException:
the Pageable passed in was null.
See Also
PageFormat, Printable
setPrintableback to summary
public abstract void setPrintable(Printable painter)

Calls painter to render the pages. The pages in the document to be printed by this PrinterJob are rendered by the Printable object, painter. The PageFormat for each page is the default page format.

Parameters
painter:Printable

the Printable that renders each page of the document.

setPrintableback to summary
public abstract void setPrintable(Printable painter, PageFormat format)

Calls painter to render the pages in the specified format. The pages in the document to be printed by this PrinterJob are rendered by the Printable object, painter. The PageFormat of each page is format.

Parameters
painter:Printable

the Printable called to render each page of the document

format:PageFormat

the size and orientation of each page to be printed

setPrintServiceback to summary
public void setPrintService(PrintService service) throws PrinterException

Associate this PrinterJob with a new PrintService. This method is overridden by subclasses which support specifying a Print Service. Throws PrinterException if the specified service cannot support the Pageable and Printable interfaces necessary to support 2D printing.

Parameters
service:PrintService

a print service that supports 2D printing

Exceptions
PrinterException:
if the specified service does not support 2D printing, or this PrinterJob class does not support setting a 2D print service, or the specified service is otherwise not a valid print service.
Since
1.4
See Also
getPrintService
validatePageback to summary
public abstract PageFormat validatePage(PageFormat page)

Returns the clone of page with its settings adjusted to be compatible with the current printer of this PrinterJob. For example, the returned PageFormat could have its imageable area adjusted to fit within the physical area of the paper that is used by the current printer.

Parameters
page:PageFormat

the PageFormat that is cloned and whose settings are changed to be compatible with the current printer

Returns:PageFormat

a PageFormat that is cloned from page and whose settings are changed to conform with this PrinterJob.