Top Description Inners Fields Constructors Methods
javafx.print

public final Class PrinterJob

extends Object
Class Inheritance
Imports
javafx.beans.property.ObjectProperty, .Property, .ReadOnlyObjectProperty, .ReadOnlyObjectWrapper, .SimpleObjectProperty, javafx.beans.value.ObservableValue, javafx.scene.Node, javafx.stage.Window, com.sun.javafx.print.PrinterJobImpl, com.sun.javafx.tk.PrintPipeline
PrinterJob is the starting place for JavaFX scenegraph printing.

It includes

Here ia a very simple example, which prints a single node. 

Node node = new Circle(100, 200, 200);
PrinterJob job = PrinterJob.createPrinterJob();
if (job != null) {
   boolean success = job.printPage(node);
   if (success) {
       job.endJob();
   }
}
Points to note

In the example above the node was not added to a scene. Since most printing scenarios are printing content that's either not displayed at all, or must be prepared and formatted differently, this is perfectly acceptable.

If content that is currently part of a Scene and is being displayed, is printed, then because printing a job or even a single page of the job may span over multiple screen "pulses" or frames, it is important for the application to ensure that the node being printed is not updated during the printing process, else partial or smeared rendering is probable.

It should be apparent that the same applies even to nodes that are not displayed - updating them concurrent with printing them is not a good idea.

There is no requirement to do printing on the FX application thread. A node may be prepared for printing on any thread, the job may be invoked on any thread. However, minimising the amount of work done on the FX application thread is generally desirable, so as not to affect the responsiveness of the application UI. So the recommendation is to perform printing on a new thread and let the implementation internally schedule any tasks that need to be performed on the FX thread to be run on that thread.

Since
JavaFX 8.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
PrinterJob.JobStatus

An enum class used in reporting status of a print job.

Field Summary

Modifier and TypeField and Description
private PrinterJobImpl
jobImpl

private ReadOnlyObjectWrapper<PrinterJob.JobStatus>
jobStatus

private ObjectProperty<Printer>
printer

private JobSettings
settings

Constructor Summary

AccessConstructor and Description
private
PrinterJob(Printer printer)

Method Summary

Modifier and TypeMethod and Description
public void
cancelJob()

Cancel the underlying print job at the earliest opportunity.

private synchronized PrinterJobImpl
createImplJob(Printer printer, JobSettings settings)

public static final PrinterJob

Returns:

a new PrinterJob instance, or null.
createPrinterJob()

Factory method to create a job.

public static final PrinterJob

Returns:

a new PrinterJob, or null.
createPrinterJob(Printer
to use for the job. If the printer is currently unavailable (eg offline) then this may return null.
printer)

Factory method to create a job for a specified printer.

private ObjectProperty<Printer>
createPrinterProperty(Printer printer)

public synchronized boolean

Returns:

true if job is spooled, false if its not, or the job was already in a completed state.
endJob()

If the job can be successfully spooled to the printer queue this will return true.

public synchronized JobSettings

Returns:

current job settings.
getJobSettings()

The JobSettings encapsulates all the API supported job configuration options such as number of copies, collation option, duplex option, etc. The initial values are based on the current settings for the initial printer.

public final PrinterJob.JobStatus
getJobStatus()

public final synchronized Printer
getPrinter()

pack-priv boolean
isJobNew()

Updating settings or printer is only allowed on a new job, meaning before you start printing or cancel etc. The implementation needs to check this wherever job state updates are received.

public final ReadOnlyObjectProperty<PrinterJob.JobStatus>

Returns:

the current JobStatus
jobStatusProperty()

A read only object property representing the current JobStatus

public final ObjectProperty<Printer>

Returns:

the Printer for this job
printerProperty()

Property representing the Printer for this job.

public synchronized boolean

Returns:

whether rendering was successful.
printPage(PageLayout
Layout for this page.
pageLayout, Node
The node to print.
node)

Print the specified node using the specified page layout.

public synchronized boolean

Returns:

whether rendering was successful.
printPage(Node
The node to print.
node)

Print the specified node.

public final synchronized void
setPrinter(Printer printer)

public synchronized boolean

Returns:

false if the user opts to cancel the dialog, or the job is not in the new state. That is if it has already started, has failed, or has been cancelled, or ended.
showPageSetupDialog(Window
to block input, or null.
owner)

Displays a Page Setup dialog.

public synchronized boolean

Returns:

false if the user opts to cancel printing, or the job is not in the new state. That is if it has already started, has failed, or has been cancelled, or ended.
showPrintDialog(Window
to which to block input, or null.
owner)

Displays a Print Dialog.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

pack-priv synchronized PageLayout

Returns:

a PageLayout that is supported in the current job configuration.
validatePageLayout(PageLayout
to be validated
pageLayout)

This method can be used to check if a page configuration is possible in the current job configuration.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

jobImplback to summary
private PrinterJobImpl jobImpl
jobStatusback to summary
private ReadOnlyObjectWrapper<PrinterJob.JobStatus> jobStatus
printerback to summary
private ObjectProperty<Printer> printer
settingsback to summary
private JobSettings settings

Constructor Detail

PrinterJobback to summary
private PrinterJob(Printer printer)

Method Detail

cancelJobback to summary
public void cancelJob()

Cancel the underlying print job at the earliest opportunity. It may return immediately without waiting for the job cancellation to be complete in case this would block the FX user thread for any period of time. If printing is in process at that time, then typically this means cancellation is after the current page is rendered. The job status is updated to CANCELED only once that has happened. Thus determining that the job is CANCELED requires monitoring the job status.

The call has no effect if the job has already been requested to be CANCELED, or is in the state ERROR or DONE. For example it will not de-queue from the printer a job that has already been spooled for printing. Once a job is cancelled, it is not valid to call any methods which render new content or change job state.

createImplJobback to summary
private synchronized PrinterJobImpl createImplJob(Printer printer, JobSettings settings)
createPrinterJobback to summary
public static final PrinterJob createPrinterJob()

Factory method to create a job. If there are no printers available, this will return null. Some platforms may provide a pseudo printer, which creates a document. These will be enumerated here so long as the platform also enumerates them as if they are printers.

Returns:PrinterJob

a new PrinterJob instance, or null.

createPrinterJobback to summary
public static final PrinterJob createPrinterJob(Printer printer)

Factory method to create a job for a specified printer.

The printer argument determines the initial printer

Parameters
printer:Printer

to use for the job. If the printer is currently unavailable (eg offline) then this may return null.

Returns:PrinterJob

a new PrinterJob, or null.

createPrinterPropertyback to summary
private ObjectProperty<Printer> createPrinterProperty(Printer printer)
endJobback to summary
public synchronized boolean endJob()

If the job can be successfully spooled to the printer queue this will return true. Note : this does not mean the job already printed as that could entail waiting for minutes or longer, even where implementable.

A return value of false means the job could not be spooled, or was already completed.

Successful completion will also update job status to DONE, at which point the job can no longer be used.

Calling endJob() on a job for which no pages have been printed is equivalent to calling {code cancelJob()}.

Returns:boolean

true if job is spooled, false if its not, or the job was already in a completed state.

getJobSettingsback to summary
public synchronized JobSettings getJobSettings()

The JobSettings encapsulates all the API supported job configuration options such as number of copies, collation option, duplex option, etc. The initial values are based on the current settings for the initial printer.

Returns:JobSettings

current job settings.

getJobStatusback to summary
public final PrinterJob.JobStatus getJobStatus()
getPrinterback to summary
public final synchronized Printer getPrinter()
isJobNewback to summary
pack-priv boolean isJobNew()

Updating settings or printer is only allowed on a new job, meaning before you start printing or cancel etc. The implementation needs to check this wherever job state updates are received.

jobStatusPropertyback to summary
public final ReadOnlyObjectProperty<PrinterJob.JobStatus> jobStatusProperty()

A read only object property representing the current JobStatus

Returns:ReadOnlyObjectProperty<PrinterJob.JobStatus>

the current JobStatus

printerPropertyback to summary
public final ObjectProperty<Printer> printerProperty()

Property representing the Printer for this job. When setting a printer which does not support the current job settings, (for example if DUPLEX printing is requested but the new printer does not support this), then the values are reset to the default for the new printer, or in some cases a similar value. For example this might mean REVERSE_LANDSCAPE is updated to LANDSCAPE, however this implementation optimisation is allowed, but not required.

The above applies whether the printer is changed by directly calling this method, or as a side-effect of user interaction with a print dialog.

Setting a null value for printer will install the default printer. Setting the current printer has no effect.

Returns:ObjectProperty<Printer>

the Printer for this job

printPageback to summary
public synchronized boolean printPage(PageLayout pageLayout, Node node)

Print the specified node using the specified page layout. The page layout will override the job default for this page only. If the job state is CANCELED, ERROR or DONE, this method will return false.

This method may be called from any thread. If it is called from the FX application thread, then it must either be called from an input event handler or from the run method of a Runnable passed to Platform.runLater. It must not be called during animation or layout processing.

Parameters
pageLayout:PageLayout

Layout for this page.

node:Node

The node to print.

Returns:boolean

whether rendering was successful.

Exceptions
NullPointerException:
if either parameter is null.
IllegalStateException:
if this method is called during animation or layout processing.
printPageback to summary
public synchronized boolean printPage(Node node)

Print the specified node. The page layout is the job default. If the job state is CANCELED, ERROR or DONE, this method will return false.

Parameters
node:Node

The node to print.

Returns:boolean

whether rendering was successful.

Exceptions
NullPointerException:
if the node parameter is null.
setPrinterback to summary
public final synchronized void setPrinter(Printer printer)
showPageSetupDialogback to summary
public synchronized boolean showPageSetupDialog(Window owner)

Displays a Page Setup dialog. A page set up dialog is primarily to allow an end user to configure the layout of a page. Paper size and orientation are the most common and most important components of this.

This will display the most appropriate available dialog for this purpose. However there may be still be access to other settings, including changing the current printer. Therefore a side effect of this dialog display method may be to update that and any other current job settings. The method returns true if the user confirmed the dialog whether or not any changes are made.

If the job is not in a state to display the dialog, such as already printing, cancelled or done, then the dialog will not be displayed and the method will return false.

The window owner may be null, but if it is a visible Window, it will be used as the parent.

This method may be called from any thread. If it is called from the FX application thread, then it must either be called from an input event handler or from the run method of a Runnable passed to Platform.runLater. It must not be called during animation or layout processing.

Parameters
owner:Window

to block input, or null.

Returns:boolean

false if the user opts to cancel the dialog, or the job is not in the new state. That is if it has already started, has failed, or has been cancelled, or ended.

Exceptions
IllegalStateException:
if this method is called during animation or layout processing.
showPrintDialogback to summary
public synchronized boolean showPrintDialog(Window owner)

Displays a Print Dialog. Allow the user to update job state such as printer and settings. These changes will be available in the appropriate properties after the print dialog has returned. The print dialog is also typically used to confirm the user wants to proceed with printing. This is not binding on the application but generally should be obeyed.

In the case that there is no UI available then this method returns true, with no options changed, as if the user had confirmed to proceed with printing.

If the job is not in a state to display the dialog, such as already printing, cancelled or done, then the dialog will not be displayed and the method will return false.

The window owner may be null, but if it is a visible Window, it will be used as the parent.

This method may be called from any thread. If it is called from the JavaFX application thread, then it must either be called from an input event handler or from the run method of a Runnable passed to Platform.runLater. It must not be called during animation or layout processing.

Parameters
owner:Window

to which to block input, or null.

Returns:boolean

false if the user opts to cancel printing, or the job is not in the new state. That is if it has already started, has failed, or has been cancelled, or ended.

Exceptions
IllegalStateException:
if this method is called during animation or layout processing.
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Annotations
@Override
validatePageLayoutback to summary
pack-priv synchronized PageLayout validatePageLayout(PageLayout pageLayout)

This method can be used to check if a page configuration is possible in the current job configuration. For example if the specified paper size is supported. If the original PageLayout is supported it will be returned. If not, a new PageLayout will be returned that attempts to honour the supplied PageLayout, but adjusted to match the current job configuration.

This method does not update the job configuration.

Parameters
pageLayout:PageLayout

to be validated

Returns:PageLayout

a PageLayout that is supported in the current job configuration.

Exceptions
NullPointerException:
if the pageLayout parameter is null.
javafx.print back to summary

public final Enum PrinterJob.JobStatus

extends Enum<PrinterJob.JobStatus>
Class Inheritance
An enum class used in reporting status of a print job. Applications can listen to the job status via the jobStatus property, or may query it directly using getJobStatus().

The typical life cycle of a job is as follows :

A job may not revert to an earlier status in its life cycle and the current job state affects operations that may be performed. For example a job may not begin printing again if it has previously passed that state and entered any of the termination states.

Since
JavaFX 8.0

Field Summary

Modifier and TypeField and Description
public static final PrinterJob.JobStatus
CANCELED

The job has been cancelled by the application.

public static final PrinterJob.JobStatus
DONE

The job initiated printing and later called endJob() which reported success.

public static final PrinterJob.JobStatus
ERROR

The job encountered an error.

public static final PrinterJob.JobStatus
NOT_STARTED

The new job status.

public static final PrinterJob.JobStatus
PRINTING

The job has requested to print at least one page, and has not terminated printing.

Constructor Summary

AccessConstructor and Description
private
JobStatus()

Method Summary

Modifier and TypeMethod and Description
public static PrinterJob.JobStatus
valueOf(String name)

public static PrinterJob.JobStatus[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

CANCELEDback to summary
public static final PrinterJob.JobStatus CANCELED

The job has been cancelled by the application. May not display dialogs or initiate printing. Job should be discarded. There is no need to call endJob().

DONEback to summary
public static final PrinterJob.JobStatus DONE

The job initiated printing and later called endJob() which reported success. The job can be discarded as it cannot be re-used.

ERRORback to summary
public static final PrinterJob.JobStatus ERROR

The job encountered an error. Job should be discarded. There is no need to call endJob().

NOT_STARTEDback to summary
public static final PrinterJob.JobStatus NOT_STARTED

The new job status. May display print dialogs and configure the job and initiate printing.

PRINTINGback to summary
public static final PrinterJob.JobStatus PRINTING

The job has requested to print at least one page, and has not terminated printing. May no longer display print dialogs.

Constructor Detail

JobStatusback to summary
private JobStatus()

Method Detail

valueOfback to summary
public static PrinterJob.JobStatus valueOf(String name)
valuesback to summary
public static PrinterJob.JobStatus[] values()