JavaTM 2 Platform
Std. Ed. v1.3

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.

JavaTM 2 Platform
Std. Ed. v1.3

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.