java.awt.print
Class PrinterJob

java.lang.Object
  |
  +--java.awt.print.PrinterJob

public abstract class PrinterJob

extends Object

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

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

Method Summary

abstract void	cancel() Cancels a print job that is in progress.
PageFormat	defaultPage() Creates a new PageFormat instance and sets it to a default size and orientation.
abstract PageFormat	defaultPage(PageFormat page) Clones the PageFormat argument and alters the clone to describe a default page size and orientation.
abstract int	getCopies() Gets the number of copies to be printed.
abstract String	getJobName() Gets the name of the document to be printed.
static PrinterJob	getPrinterJob() Creates and returns a PrinterJob.
abstract String	getUserName() Gets the name of the printing user.
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.
abstract PageFormat	pageDialog(PageFormat page) Displays a dialog that allows modification of a PageFormat instance.
abstract void	print() Prints a set of pages.
abstract boolean	printDialog() Presents a dialog to the user for changing the properties of the print job.
abstract void	setCopies(int copies) Sets the number of copies to be printed.
abstract void	setJobName(String jobName) Sets the name of the document to be printed.
abstract void	setPageable(Pageable document) Queries document for the number of pages and the PageFormat and Printable for each page held in the Pageable instance, document.
abstract void	setPrintable(Printable painter) Calls painter to render the pages.
abstract void	setPrintable(Printable painter, PageFormat format) Calls painter to render the pages in the specified format.
abstract PageFormat	validatePage(PageFormat page) Returns the clone of page with its settings adjusted to be compatible with the current printer of this PrinterJob.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PrinterJob

public PrinterJob()

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

Method Detail

getPrinterJob

public static PrinterJob getPrinterJob()

Creates and returns a PrinterJob.

Returns:

a new PrinterJob.

setPrintable

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 - the Printable that renders each page of the document.

setPrintable

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 - the Printable called to render each page of the document

format - the size and orientation of each page to be printed

setPageable

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 - the pages to be printed. It can not be null.

Throws:

NullPointerException - the Pageable passed in was null.

See Also:

PageFormat, Printable

printDialog

public abstract boolean printDialog()

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

Returns:

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

pageDialog

public abstract PageFormat pageDialog(PageFormat page)

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 - the default PageFormat presented to the user for modification

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.

Since:

1.2

defaultPage

public abstract PageFormat defaultPage(PageFormat page)

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

Parameters:

page - the PageFormat to be cloned and altered

Returns:

clone of page, altered to describe a default PageFormat.

defaultPage

public PageFormat defaultPage()

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

Returns:

a PageFormat set to a default size and orientation.

validatePage

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 - the PageFormat that is cloned and whose settings are changed to be compatible with the current printer

Returns:

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

print

public abstract void print()
                    throws PrinterException

Prints a set of pages.

Throws:

PrinterException - an error in the print system caused the job to be aborted.

See Also:

Book, Pageable, Printable

setCopies

public abstract void setCopies(int copies)

Sets the number of copies to be printed.

Parameters:

copies - the number of copies to be printed

getCopies

public abstract int getCopies()

Gets the number of copies to be printed.

Returns:

the number of copies to be printed.

getUserName

public abstract String getUserName()

Gets the name of the printing user.

Returns:

the name of the printing user

setJobName

public abstract void setJobName(String jobName)

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

Parameters:

jobName - the name of the document to be printed

getJobName

public abstract String getJobName()

Gets the name of the document to be printed.

Returns:

the name of the document to be printed.

cancel

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.

isCancelled

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:

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