| |
|
| java.lang.Object
 java.awt.print.PrinterJob
| PrinterJob | | abstract public class PrinterJob (Code) | | 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.
|
| Method Summary | |
| abstract public void | cancel()
Cancels a print job that is in progress. | | abstract public PageFormat | defaultPage(PageFormat page)
Clones the PageFormat argument and alters the
clone to describe a default page size and orientation. | | public PageFormat | defaultPage()
Creates a new PageFormat instance and
sets it to a default size and orientation. | | abstract public int | getCopies()
Gets the number of copies to be printed. | | abstract public String | getJobName()
Gets the name of the document to be printed. | | 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 - a set of printing attributes, for example obtainedfrom calling printDialog. | | public PrintService | getPrintService()
Returns the service (printer) for this printer job.
Implementations of this class which do not support print services
may return null. | | 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
PrinterJob.print() print with this PrinterJob might
generate an exception. | | abstract public String | getUserName()
Gets the name of the printing user. | | abstract public boolean | 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[] | lookupPrintServices()
A convenience method which looks up 2D print services. | | 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";
StreamPrintServiceFactory[] factories =
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) {
}
}
Services returned from this method may be installed on
PrinterJob instances which support print services.
Calling this method is equivalent to calling
javax.print.StreamPrintServiceFactory.lookupStreamPrintServiceFactories(DocFlavorString)StreamPrintServiceFactory.lookupStreamPrintServiceFactories() and specifying a Pageable DocFlavor.
Parameters:
mimeType - the required output format, or null to mean any format. | | abstract public PageFormat | pageDialog(PageFormat page)
Displays a dialog that allows modification of a
PageFormat instance. | | public PageFormat | pageDialog(PrintRequestAttributeSet attributes)
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. | | abstract public void | print()
Prints a set of pages. | | public void | print(PrintRequestAttributeSet attributes)
Prints a set of pages using the settings in the attribute
set. | | abstract public boolean | printDialog()
Presents a dialog to the user for changing the properties of
the print job. | | public boolean | printDialog(PrintRequestAttributeSet 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. | | abstract public void | setCopies(int copies)
Sets the number of copies to be printed. | | abstract public void | setJobName(String jobName)
Sets the name of the document to be printed. | | abstract public 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.
Parameters:
document - the pages to be printed. | | public void | setPrintService(PrintService service)
Associate this PrinterJob with a new PrintService. | | abstract public void | setPrintable(Printable painter)
Calls painter to render the pages. | | abstract public void | setPrintable(Printable painter, PageFormat format)
Calls painter to render the pages in the specified
format. | | abstract public PageFormat | validatePage(PageFormat page)
Returns the clone of page with its settings
adjusted to be compatible with the current printer of this
PrinterJob. |
| cancel | | abstract public void cancel()(Code) | | Cancels a print job that is in progress. If
PrinterJob.print() 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.
|
| defaultPage | | abstract public PageFormat defaultPage(PageFormat page)(Code) | | 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 clone of page, altered to describe a defaultPageFormat. |
| defaultPage | | public PageFormat defaultPage()(Code) | | Creates a new PageFormat instance and
sets it to a default size and orientation.
a PageFormat set to a default size andorientation. |
| getCopies | | abstract public int getCopies()(Code) | | Gets the number of copies to be printed.
the number of copies to be printed.
See Also: PrinterJob.setCopies |
| getJobName | | abstract public String getJobName()(Code) | | Gets the name of the document to be printed.
the name of the document to be printed.
See Also: PrinterJob.setJobName |
| getPageFormat | | public PageFormat getPageFormat(PrintRequestAttributeSet attributes)(Code) | | 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 - a set of printing attributes, for example obtainedfrom calling printDialog. If attributes is null a defaultPageFormat is returned. a PageFormat whose settings conform withthose of the current service and the specified attributes.
since:
1.6 |
| getPrinterJob | | public static PrinterJob getPrinterJob()(Code) | | 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
PrinterJob.print() 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
PrinterJob.lookupPrintServices() lookupPrintServices is not empty.
a new PrinterJob.
throws:
SecurityException - if a security manager exists and itsjava.lang.SecurityManager.checkPrintJobAccessmethod disallows this thread from creating a print job request |
| getUserName | | abstract public String getUserName()(Code) | | Gets the name of the printing user.
the name of the printing user |
| isCancelled | | abstract public boolean isCancelled()(Code) | | Returns true if a print job is
in progress, but is going to be cancelled
at the next opportunity; otherwise returns
false.
true if the job in progressis going to be cancelled; false otherwise. |
| lookupPrintServices | | public static PrintService[] lookupPrintServices()(Code) | | 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
javax.print.PrintServiceLookup.lookupPrintServices(DocFlavorAttributeSet) PrintServiceLookup.lookupPrintServices() and specifying a Pageable DocFlavor.
a possibly empty array of 2D print services.
since:
1.4 |
| lookupStreamPrintServices | | public static StreamPrintServiceFactory[] lookupStreamPrintServices(String mimeType)(Code) | | 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";
StreamPrintServiceFactory[] factories =
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) {
}
}
Services returned from this method may be installed on
PrinterJob instances which support print services.
Calling this method is equivalent to calling
javax.print.StreamPrintServiceFactory.lookupStreamPrintServiceFactories(DocFlavorString)StreamPrintServiceFactory.lookupStreamPrintServiceFactories() and specifying a Pageable DocFlavor.
Parameters:
mimeType - the required output format, or null to mean any format. a possibly empty array of 2D stream print service factories.
since:
1.4 |
| pageDialog | | abstract public PageFormat pageDialog(PageFormat page) throws HeadlessException(Code) | | 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 theuser for modification the original page object if the dialogis cancelled; a new PageFormat objectcontaining the format indicated by the user if thedialog is acknowledged.
exception:
HeadlessException - if GraphicsEnvironment.isHeadless()returns true.
See Also: java.awt.GraphicsEnvironment.isHeadless
since:
1.2 |
| pageDialog | | public PageFormat pageDialog(PrintRequestAttributeSet attributes) throws HeadlessException(Code) | | 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 - on input is application supplied attributes,on output the contents are updated to reflect user choices.This parameter may not be null. a page format if the user does not cancel the dialog;null otherwise.
exception:
HeadlessException - if GraphicsEnvironment.isHeadless()returns true.
exception:
NullPointerException - if attributes parameteris null.
See Also: java.awt.GraphicsEnvironment.isHeadless
since:
1.4 |
| print | | public void print(PrintRequestAttributeSet attributes) throws PrinterException(Code) | | 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 - a set of attributes for the job
exception:
PrinterException - an error in the print systemcaused the job to be aborted.
See Also: Book
See Also: Pageable
See Also: Printable
since:
1.4 |
| printDialog | | abstract public boolean printDialog() throws HeadlessException(Code) | | 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.
true if the user does not cancel the dialog;false otherwise.
exception:
HeadlessException - if GraphicsEnvironment.isHeadless()returns true.
See Also: java.awt.GraphicsEnvironment.isHeadless |
| printDialog | | public boolean printDialog(PrintRequestAttributeSet attributes) throws HeadlessException(Code) | | 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 - on input is application supplied attributes,on output the contents are updated to reflect user choices.This parameter may not be null. true if the user does not cancel the dialog;false otherwise.
exception:
HeadlessException - if GraphicsEnvironment.isHeadless()returns true.
exception:
NullPointerException - if attributes parameteris null.
See Also: java.awt.GraphicsEnvironment.isHeadless
since:
1.4 |
| setCopies | | abstract public void setCopies(int copies)(Code) | | Sets the number of copies to be printed.
Parameters:
copies - the number of copies to be printed
See Also: PrinterJob.getCopies |
| setJobName | | abstract public void setJobName(String jobName)(Code) | | 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
See Also: PrinterJob.getJobName |
| setPageable | | abstract public void setPageable(Pageable document) throws NullPointerException(Code) | | 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 benull.
exception:
NullPointerException - the Pageable passed inwas null.
See Also: PageFormat
See Also: Printable |
| setPrintService | | public void setPrintService(PrintService service) throws PrinterException(Code) | | 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 - a print service that supports 2D printing
exception:
PrinterException - if the specified service does not support2D printing, or this PrinterJob class does not supportsetting a 2D print service, or the specified service isotherwise not a valid print service.
See Also: PrinterJob.getPrintService
since:
1.4 |
| setPrintable | | abstract public void setPrintable(Printable painter)(Code) | | 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 ofthe document. |
| setPrintable | | abstract public void setPrintable(Printable painter, PageFormat format)(Code) | | 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 rendereach page of the document
Parameters:
format - the size and orientation of each page tobe printed |
| validatePage | | abstract public PageFormat validatePage(PageFormat page)(Code) | | 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 withthe current printer a PageFormat that is cloned frompage and whose settings are changed to conform with this PrinterJob. |
|
|
|