JobSettings (JavaFX 17)

Module javafx.graphics
Package javafx.print

## Class JobSettings

- java.lang.Object
- - javafx.print.JobSettings

-     public final class JobSettings
      extends Object

  The JobSettings class encapsulates most of the configuration of a print job. Applications do not - and cannot - directly create or set a JobSettings instance. One is already installed on the print job when it is created.

  As documented on PrinterJob, the JobSettings installed on that job will initially reflect the current default settings for the initially associated printer for that job.

  The JobSettings delegate then remains the same for the life of the job, and will have it's member properties updated to be compatible with a change in Printer on the job. For example as a result of a user interaction via a platform's dialog. An incompatible setting will usually cause the setting to revert to the default for the new printer.

  Any implicit or explicit updates to settings resulting from the user interaction with dialog will be propagated and visible to the application once the user approves the settings by dismissing the dialog using its "accept" option.

  For most printing applications it is likely sufficient to let the user set the desired options and have these propagated to the job. For applications which need them, there are setter and getter methods for the individual options, which are also available as properties, and change in values of settings may be monitored and updated via these properties.

  Not all values of settings are available on all printers. For example a printer may not support two-sided printing. See the `Printer` class for how to to determine supported settings.

  Since:
    JavaFX 8.0

- - ### Property Summary

    Properties
    Type | Property | Description
    --- | --- | ---
    `ObjectProperty<Collation>` | `collation` | Property representing an instance of `Collation`.
    `IntegerProperty` | `copies` | `IntegerProperty` representing the number of copies of the job to print.
    `StringProperty` | `jobName` | `StringProperty` representing the name of a job.
    `StringProperty` | `outputFile` | A `StringProperty` representing the name of a filesystem file, to which the platform printer driver should spool the rendered print data.
    `ObjectProperty<PageLayout>` | `pageLayout` | Property representing an instance of `PageLayout`.
    `ObjectProperty` | `pageRanges` | An `ObjectProperty` whose value represents the job pages to print as an array of PageRange.
    `ObjectProperty<PaperSource>` | `paperSource` | Property representing an instance of `PaperSource`.
    `ObjectProperty<PrintColor>` | `printColor` | Property representing an instance of `PrintColor`.
    `ObjectProperty<PrintQuality>` | `printQuality` | Property representing an instance of `PrintQuality`.
    `ObjectProperty<PrintResolution>` | `printResolution` | Property representing an instance of `PrintResolution`.
    `ObjectProperty<PrintSides>` | `printSides` | Property representing an instance of `PrintSides`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ObjectProperty<Collation>` | `collationProperty()` | Property representing an instance of `Collation`.
    `IntegerProperty` | `copiesProperty()` | `IntegerProperty` representing the number of copies of the job to print.
    `Collation` | `getCollation()` | Collation determines how sheets are sorted when multiple copies of a document are printed.
    `int` | `getCopies()` | Get the number of copies to print.
    `String` | `getJobName()` | Get the name of a job.
    `String` | `getOutputFile()` | Gets the value of the property outputFile.
    `PageLayout` | `getPageLayout()` | Get the current page layout for this job.
    `PageRange[]` | `getPageRanges()` | The range of pages to print.
    `PaperSource` | `getPaperSource()` | Gets the value of the property paperSource.
    `PrintColor` | `getPrintColor()` | Gets the value of the property printColor.
    `PrintQuality` | `getPrintQuality()` | Gets the value of the property printQuality.
    `PrintResolution` | `getPrintResolution()` |
    `PrintSides` | `getPrintSides()` | If a printer supports it, then a job may be printed on both sides of the media (paper), ie duplex printing.
    `StringProperty` | `jobNameProperty()` | `StringProperty` representing the name of a job.
    `StringProperty` | `outputFileProperty()` | A `StringProperty` representing the name of a filesystem file, to which the platform printer driver should spool the rendered print data.
    `ObjectProperty<PageLayout>` | `pageLayoutProperty()` | Property representing an instance of `PageLayout`.
    `ObjectProperty` | `pageRangesProperty()` | An `ObjectProperty` whose value represents the job pages to print as an array of PageRange.
    `ObjectProperty<PaperSource>` | `paperSourceProperty()` | Property representing an instance of `PaperSource`.
    `ObjectProperty<PrintColor>` | `printColorProperty()` | Property representing an instance of `PrintColor`.
    `ObjectProperty<PrintQuality>` | `printQualityProperty()` | Property representing an instance of `PrintQuality`.
    `ObjectProperty<PrintResolution>` | `printResolutionProperty()` | Property representing an instance of `PrintResolution`.
    `ObjectProperty<PrintSides>` | `printSidesProperty()` | Property representing an instance of `PrintSides`.
    `void` | `setCollation​(Collation collation)` | Set the `Collation` property.
    `void` | `setCopies​(int nCopies)` | Set the number of copies to print.
    `void` | `setJobName​(String name)` | Set the name of a job.
    `void` | `setOutputFile​(String filePath)` | Sets the value of the property outputFile.
    `void` | `setPageLayout​(PageLayout pageLayout)` | Set the PageLayout to use.
    `void` | `setPageRanges​(PageRange... pages)` | The range of pages to print as an array of PageRange.
    `void` | `setPaperSource​(PaperSource value)` | Sets the value of the property paperSource.
    `void` | `setPrintColor​(PrintColor color)` | Set the `PrintColor` property.
    `void` | `setPrintQuality​(PrintQuality quality)` | Set the `PrintQuality` property.
    `void` | `setPrintResolution​(PrintResolution resolution)` | Set the `PrintResolution` property.
    `void` | `setPrintSides​(PrintSides sides)` | Set the `PrintSides` property which controls duplex printing.

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

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

- - ### Property Detail

    - #### jobName

          public final StringProperty jobNameProperty

      `StringProperty` representing the name of a job.
      See Also:
        `getJobName()`, `setJobName(String)`

    - #### outputFile

          public final StringProperty outputFileProperty

      A `StringProperty` representing the name of a filesystem file, to which the platform printer driver should spool the rendered print data.

      Applications can use this to programmatically request print-to-file behavior where the native print system is capable of spooling the output to a filesystem file, rather than the printer device.

      This is often useful where the printer driver generates a format such as Postscript or PDF, and the application intends to distribute the result instead of printing it, or for some other reason the application does not want physical media (paper) emitted by the printer.

      The default value is an empty string, which is interpreted as unset, equivalent to null, which means output is sent to the printer. So in order to reset to print to the printer, clear the value of this property by setting it to null or an empty string.

      Additionally if the application displays a printer dialog which allows the user to specify a file destination, including altering an application specified file destination, the value of this property will reflect that user-specified choice, including clearing it to reset to print to the printer, if the user does so.

      If the print system does not support print-to-file, then this setting will be ignored.

      If the specified name specifies a non-existent path, or does not specify a user writable file, when printing the results are platform-dependent. Possible behaviours might include replacement with a default output file location, printing to the printer instead, or a platform printing error. If a `SecurityManager` is installed and it denies access to the specified file a `SecurityException` may be thrown.

      Default value:
        an empty string
      Since:
        17
      See Also:
        `getOutputFile()`, `setOutputFile(String)`

    - #### copies

          public final IntegerProperty copiesProperty

      `IntegerProperty` representing the number of copies of the job to print.
      See Also:
        `getCopies()`, `setCopies(int)`

    - #### pageRanges

          public final ObjectProperty pageRangesProperty

      An `ObjectProperty` whose value represents the job pages to print as an array of PageRange. A null values mean print all pages. Otherwise it must be a non-overlapping array of PageRange instances ordered in increasing page number. Page numbers start from 1 (one). An empty array is considered equivalent to a null array.

      An illegal or unsupported (by the printer) set of page ranges will be ignored.

      Ranges which exceed beyond the number of pages imaged by the job during printing do not cause any error.

      See Also:
        `getPageRanges()`, `setPageRanges(PageRange[])`

    - #### printSides

          public final ObjectProperty<PrintSides> printSidesProperty

      Property representing an instance of `PrintSides`.
      See Also:
        `getPrintSides()`, `setPrintSides(PrintSides)`

    - #### collation

          public final ObjectProperty<Collation> collationProperty

      Property representing an instance of `Collation`.
      See Also:
        `getCollation()`, `setCollation(Collation)`

    - #### printColor

          public final ObjectProperty<PrintColor> printColorProperty

      Property representing an instance of `PrintColor`.
      See Also:
        `getPrintColor()`, `setPrintColor(PrintColor)`

    - #### printQuality

          public final ObjectProperty<PrintQuality> printQualityProperty

      Property representing an instance of `PrintQuality`.
      See Also:
        `getPrintQuality()`, `setPrintQuality(PrintQuality)`

    - #### printResolution

          public final ObjectProperty<PrintResolution> printResolutionProperty

      Property representing an instance of `PrintResolution`.
      See Also:
        `getPrintResolution()`, `setPrintResolution(PrintResolution)`

    - #### paperSource

          public final ObjectProperty<PaperSource> paperSourceProperty

      Property representing an instance of `PaperSource`.
      See Also:
        `getPaperSource()`, `setPaperSource(PaperSource)`

    - #### pageLayout

          public final ObjectProperty<PageLayout> pageLayoutProperty

      Property representing an instance of `PageLayout`.
      See Also:
        `getPageLayout()`, `setPageLayout(PageLayout)`

  - ### Method Detail

    - #### jobNameProperty

          public final StringProperty jobNameProperty()

      `StringProperty` representing the name of a job.
      See Also:
        `getJobName()`, `setJobName(String)`

    - #### getJobName

          public String getJobName()

      Get the name of a job.
      Returns:
        a string representing the name of a job

    - #### setJobName

          public void setJobName​(String name)

      Set the name of a job.
      Parameters:
        `name` - string representing the name of a job

    - #### outputFileProperty

          public final StringProperty outputFileProperty()

      A `StringProperty` representing the name of a filesystem file, to which the platform printer driver should spool the rendered print data.

      Applications can use this to programmatically request print-to-file behavior where the native print system is capable of spooling the output to a filesystem file, rather than the printer device.

      This is often useful where the printer driver generates a format such as Postscript or PDF, and the application intends to distribute the result instead of printing it, or for some other reason the application does not want physical media (paper) emitted by the printer.

      The default value is an empty string, which is interpreted as unset, equivalent to null, which means output is sent to the printer. So in order to reset to print to the printer, clear the value of this property by setting it to null or an empty string.

      Additionally if the application displays a printer dialog which allows the user to specify a file destination, including altering an application specified file destination, the value of this property will reflect that user-specified choice, including clearing it to reset to print to the printer, if the user does so.

      If the print system does not support print-to-file, then this setting will be ignored.

      If the specified name specifies a non-existent path, or does not specify a user writable file, when printing the results are platform-dependent. Possible behaviours might include replacement with a default output file location, printing to the printer instead, or a platform printing error. If a `SecurityManager` is installed and it denies access to the specified file a `SecurityException` may be thrown.

      Default value:
        an empty string
      Since:
        17
      See Also:
        `getOutputFile()`, `setOutputFile(String)`

    - #### getOutputFile

          public String getOutputFile()

      Gets the value of the property outputFile.
      Property description:
        A `StringProperty` representing the name of a filesystem file, to which the platform printer driver should spool the rendered print data.

        Applications can use this to programmatically request print-to-file behavior where the native print system is capable of spooling the output to a filesystem file, rather than the printer device.

        This is often useful where the printer driver generates a format such as Postscript or PDF, and the application intends to distribute the result instead of printing it, or for some other reason the application does not want physical media (paper) emitted by the printer.

        The default value is an empty string, which is interpreted as unset, equivalent to null, which means output is sent to the printer. So in order to reset to print to the printer, clear the value of this property by setting it to null or an empty string.

        Additionally if the application displays a printer dialog which allows the user to specify a file destination, including altering an application specified file destination, the value of this property will reflect that user-specified choice, including clearing it to reset to print to the printer, if the user does so.

        If the print system does not support print-to-file, then this setting will be ignored.

        If the specified name specifies a non-existent path, or does not specify a user writable file, when printing the results are platform-dependent. Possible behaviours might include replacement with a default output file location, printing to the printer instead, or a platform printing error. If a `SecurityManager` is installed and it denies access to the specified file a `SecurityException` may be thrown.

      Default value:
        an empty string
      Since:
        17

    - #### setOutputFile

          public void setOutputFile​(String filePath)

      Sets the value of the property outputFile.
      Property description:
        A `StringProperty` representing the name of a filesystem file, to which the platform printer driver should spool the rendered print data.

        Applications can use this to programmatically request print-to-file behavior where the native print system is capable of spooling the output to a filesystem file, rather than the printer device.

        This is often useful where the printer driver generates a format such as Postscript or PDF, and the application intends to distribute the result instead of printing it, or for some other reason the application does not want physical media (paper) emitted by the printer.

        The default value is an empty string, which is interpreted as unset, equivalent to null, which means output is sent to the printer. So in order to reset to print to the printer, clear the value of this property by setting it to null or an empty string.

        Additionally if the application displays a printer dialog which allows the user to specify a file destination, including altering an application specified file destination, the value of this property will reflect that user-specified choice, including clearing it to reset to print to the printer, if the user does so.

        If the print system does not support print-to-file, then this setting will be ignored.

        If the specified name specifies a non-existent path, or does not specify a user writable file, when printing the results are platform-dependent. Possible behaviours might include replacement with a default output file location, printing to the printer instead, or a platform printing error. If a `SecurityManager` is installed and it denies access to the specified file a `SecurityException` may be thrown.

      Default value:
        an empty string
      Since:
        17

    - #### copiesProperty

          public final IntegerProperty copiesProperty()

      `IntegerProperty` representing the number of copies of the job to print.
      See Also:
        `getCopies()`, `setCopies(int)`

    - #### getCopies

          public int getCopies()

      Get the number of copies to print.
      Returns:
        number of copies to print

    - #### setCopies

          public final void setCopies​(int nCopies)

      Set the number of copies to print.
      Parameters:
        `nCopies` - number of copies to print

    - #### pageRangesProperty

          public final ObjectProperty pageRangesProperty()

      An `ObjectProperty` whose value represents the job pages to print as an array of PageRange. A null values mean print all pages. Otherwise it must be a non-overlapping array of PageRange instances ordered in increasing page number. Page numbers start from 1 (one). An empty array is considered equivalent to a null array.

      An illegal or unsupported (by the printer) set of page ranges will be ignored.

      Ranges which exceed beyond the number of pages imaged by the job during printing do not cause any error.

      See Also:
        `getPageRanges()`, `setPageRanges(PageRange[])`

    - #### getPageRanges

          public PageRange[] getPageRanges()

      The range of pages to print. null always means all pages. See `pageRangesProperty()` for more details.
      Returns:
        null or an array as specified above

    - #### setPageRanges

          public void setPageRanges​(PageRange... pages)

      The range of pages to print as an array of PageRange. The use of varargs means the common case of a single range can be auto-boxed. `((PageRange[])null)` always means all pages however since this is the default it is less likely to be used. See `pageRangesProperty()` for more details.
      Parameters:
        `pages` - null or a varargs array as specified above

    - #### printSidesProperty

          public final ObjectProperty<PrintSides> printSidesProperty()

      Property representing an instance of `PrintSides`.
      See Also:
        `getPrintSides()`, `setPrintSides(PrintSides)`

    - #### getPrintSides

          public PrintSides getPrintSides()

      If a printer supports it, then a job may be printed on both sides of the media (paper), ie duplex printing. This method returns the selected setting.
      Returns:
        the duplex (side) setting.

    - #### setPrintSides

          public void setPrintSides​(PrintSides sides)

      Set the `PrintSides` property which controls duplex printing. A null value is ignored.
      Parameters:
        `sides` - new setting for number of sides.

    - #### collationProperty

          public final ObjectProperty<Collation> collationProperty()

      Property representing an instance of `Collation`.
      See Also:
        `getCollation()`, `setCollation(Collation)`

    - #### getCollation

          public Collation getCollation()

      Collation determines how sheets are sorted when multiple copies of a document are printed. As such it is only relevant if 2 or more copies of a document with 2 more sheets are printed. A sheet is the physical media, so documents with 2 pages that are printed N-up, or double-sided may still have only one sheet. A collated print job produces documents with sheets of a document sorted in sequence. An uncollated job collects together the multiple copies of the same sheet. Uncollated (`false`) is the typical default value.
      Returns:
        the collation

    - #### setCollation

          public void setCollation​(Collation collation)

      Set the `Collation` property. A null value is ignored.
      Parameters:
        `collation` - new setting for collation

    - #### printColorProperty

          public final ObjectProperty<PrintColor> printColorProperty()

      Property representing an instance of `PrintColor`.
      See Also:
        `getPrintColor()`, `setPrintColor(PrintColor)`

    - #### getPrintColor

          public PrintColor getPrintColor()

      Gets the value of the property printColor.
      Property description:
        Property representing an instance of `PrintColor`.

    - #### setPrintColor

          public void setPrintColor​(PrintColor color)

      Set the `PrintColor` property. A null value is ignored.
      Parameters:
        `color` - new setting for print color.

    - #### printQualityProperty

          public final ObjectProperty<PrintQuality> printQualityProperty()

      Property representing an instance of `PrintQuality`.
      See Also:
        `getPrintQuality()`, `setPrintQuality(PrintQuality)`

    - #### getPrintQuality

          public PrintQuality getPrintQuality()

      Gets the value of the property printQuality.
      Property description:
        Property representing an instance of `PrintQuality`.

    - #### setPrintQuality

          public void setPrintQuality​(PrintQuality quality)

      Set the `PrintQuality` property. A null value is ignored.

      Note that quality and resolution overlapping concepts. Therefore a printer may support setting one, or the other but not both. Applications setting these programmatically should query both properties and select appropriately from the supported values. If a printer supports non-standard values, code likely cannot distinguish the printer's interpretation of these values and is safest to stick to selecting from the standard value that matches the requirement.

      Parameters:
        `quality` - new setting for print quality.

    - #### printResolutionProperty

          public final ObjectProperty<PrintResolution> printResolutionProperty()

      Property representing an instance of `PrintResolution`.
      See Also:
        `getPrintResolution()`, `setPrintResolution(PrintResolution)`

    - #### getPrintResolution

          public PrintResolution getPrintResolution()

      Returns:
        the print resolution

    - #### setPrintResolution

          public void setPrintResolution​(PrintResolution resolution)

      Set the `PrintResolution` property. A null value is ignored.

      Note that quality and resolution overlapping concepts. Therefore a printer may support setting one, or the other but not both. Applications setting these programmatically should query both properties and select appropriately from the supported values. If a printer supports non-standard values, code likely cannot distinguish the printer's interpretation of these values and is safest to stick to selecting from the standard value that matches the requirement.

      Parameters:
        `resolution` - new setting for print resolution.

    - #### paperSourceProperty

          public final ObjectProperty<PaperSource> paperSourceProperty()

      Property representing an instance of `PaperSource`.
      See Also:
        `getPaperSource()`, `setPaperSource(PaperSource)`

    - #### getPaperSource

          public PaperSource getPaperSource()

      Gets the value of the property paperSource.
      Property description:
        Property representing an instance of `PaperSource`.

    - #### setPaperSource

          public void setPaperSource​(PaperSource value)

      Sets the value of the property paperSource.
      Property description:
        Property representing an instance of `PaperSource`.

    - #### pageLayoutProperty

          public final ObjectProperty<PageLayout> pageLayoutProperty()

      Property representing an instance of `PageLayout`.
      See Also:
        `getPageLayout()`, `setPageLayout(PageLayout)`

    - #### getPageLayout

          public PageLayout getPageLayout()

      Get the current page layout for this job.
      Returns:
        page layout to use for the job.

    - #### setPageLayout

          public void setPageLayout​(PageLayout pageLayout)

      Set the PageLayout to use.
      Parameters:
        `pageLayout` - The page layout to use.