PrinterJob (JavaFX 19)
Description: declaration: module: javafx.graphics, package: javafx.print, class: PrinterJob

Module javafx.graphics
Package javafx.print

# Class PrinterJob

java.lang.Object
javafx.print.PrinterJob

public final class PrinterJob extends Object
PrinterJob is the starting place for JavaFX scenegraph printing.

It includes

- Printer discovery
- Job creation
- Job configuration based on supported printer capabilities
- Page setup
- Rendering of a node hierachy to a page.

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

- ## Property Summary

  Properties
  Type
  Property
  Description
  `final ReadOnlyObjectProperty<PrinterJob.JobStatus>`
  `jobStatus`
  A read only object property representing the current `JobStatus`
  `final ObjectProperty<Printer>`
  `printer`
  Property representing the `Printer` for this job.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `PrinterJob.JobStatus`
  An enum class used in reporting status of a print job.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cancelJob()`
  Cancel the underlying print job at the earliest opportunity.
  `static final PrinterJob`
  `createPrinterJob()`
  Factory method to create a job.
  `static final PrinterJob`
  `createPrinterJob(Printer printer)`
  Factory method to create a job for a specified printer.
  `boolean`
  `endJob()`
  If the job can be successfully spooled to the printer queue this will return true.
  `JobSettings`
  `getJobSettings()`
  The `JobSettings` encapsulates all the API supported job configuration options such as number of copies, collation option, duplex option, etc.
  `final PrinterJob.JobStatus`
  `getJobStatus()`
  Gets the value of the property jobStatus.
  `final Printer`
  `getPrinter()`
  Gets the value of the property printer.
  `final ReadOnlyObjectProperty<PrinterJob.JobStatus>`
  `jobStatusProperty()`
  A read only object property representing the current `JobStatus`
  `final ObjectProperty<Printer>`
  `printerProperty()`
  Property representing the `Printer` for this job.
  `boolean`
  `printPage(PageLayout pageLayout, Node node)`
  Print the specified node using the specified page layout.
  `boolean`
  `printPage(Node node)`
  Print the specified node.
  `final void`
  `setPrinter(Printer printer)`
  Sets the value of the property printer.
  `boolean`
  `showPageSetupDialog(Window owner)`
  Displays a Page Setup dialog.
  `boolean`
  `showPrintDialog(Window owner)`
  Displays a Print Dialog.

  ### Methods declared in class java.lang.Object

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

- ## Property Details

  - ### printer

    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.

    See Also:
      - `getPrinter()`
      - `setPrinter(Printer)`

  - ### jobStatus

    public final ReadOnlyObjectProperty<PrinterJob.JobStatus> jobStatusProperty
    A read only object property representing the current `JobStatus`
    See Also:
      - `getJobStatus()`

- ## Method Details

  - ### createPrinterJob

    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:
      a new PrinterJob instance, or null.
    Throws:
      `SecurityException` - if a job does not have permission to initiate a printer job.

  - ### createPrinterJob

    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` - to use for the job. If the printer is currently unavailable (eg offline) then this may return null.
    Returns:
      a new PrinterJob, or null.
    Throws:
      `SecurityException` - if a job does not have permission to initiate a printer job.

  - ### printerProperty

    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.

    See Also:
      - `getPrinter()`
      - `setPrinter(Printer)`

  - ### getPrinter

    public final Printer getPrinter()
    Gets the value of the property printer.
    Property description:
      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.

  - ### setPrinter

    public final void setPrinter(Printer printer)
    Sets the value of the property printer.
    Property description:
      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.

  - ### getJobSettings

    public 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:
      current job settings.

  - ### showPrintDialog

    public 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` - to which to block input, or null.
    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.
    Throws:
      `IllegalStateException` - if this method is called during animation or layout processing.

  - ### showPageSetupDialog

    public 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` - to block input, or null.
    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.
    Throws:
      `IllegalStateException` - if this method is called during animation or layout processing.

  - ### printPage

    public 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` - Layout for this page.
      `node` - The node to print.
    Returns:
      whether rendering was successful.
    Throws:
      `NullPointerException` - if either parameter is null.
      `IllegalStateException` - if this method is called during animation or layout processing.

  - ### printPage

    public 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` - The node to print.
    Returns:
      whether rendering was successful.
    Throws:
      `NullPointerException` - if the node parameter is null.

  - ### jobStatusProperty

    public final ReadOnlyObjectProperty<PrinterJob.JobStatus> jobStatusProperty()
    A read only object property representing the current `JobStatus`
    See Also:
      - `getJobStatus()`

  - ### getJobStatus

    public final PrinterJob.JobStatus getJobStatus()
    Gets the value of the property jobStatus.
    Property description:
      A read only object property representing the current `JobStatus`

  - ### cancelJob

    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.

  - ### endJob

    public 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:
      true if job is spooled, false if its not, or the job was already in a completed state.