Module  javafx.graphics
软件包  javafx.print

Class PrinterJob


  • public final class PrinterJob
extends Object
    PrinterJob是JavaFX场景打印的起点。

    这包括

    • 打印机发现
    • 创造就业机会
    • 基于支持打印机功能的作业配置
    • 页面设置
    • 将节点层叠渲染到页面。

    这里是一个很简单的例子，它打印出一个单一的节点。 

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

    在上面的示例中，节点未添加到场景。 由于大多数打印方案都是打印完全不显示的内容，或者必须准备和格式不同，这是完全可以接受的。

    如果目前是场景的一部分并正在显示的内容被打印出来，那么由于打印作业或甚至单个页面的作业可能跨越多个屏幕“脉冲”或帧，因此应用程序必须确保正在打印的节点在打印过程中不被更新，否则部分或模糊渲染是可能的。

    应该显而易见的是，即使是不显示的节点也是如此 - 更新它们同时打印它们不是一个好主意。

    没有要求在FX应用程序线程上进行打印。 节点可以准备在任何线程上打印，可以在任何线程上调用该作业。 然而，最小化在FX应用程序线程上完成的工作量通常是可取的，以免影响应用程序UI的响应性。 因此，建议在新线程上执行打印，并让内部调度任何需要在FX线程上执行的任务，以便在该线程上运行。

    从以下版本开始：
    JavaFX 8.0

    • 方法详细信息

      • createPrinterJob

        public static final PrinterJob createPrinterJob​()
        创建工作的工厂方法。 如果没有可用的打印机，这将返回null。 一些平台可以提供伪打印机，其创建文档。 这些将在这里列举，只要平台也列举他们，就像他们是打印机。
        结果
        一个新的PrinterJob实例，或null。
        异常
        SecurityException - 如果作业没有启动打印机作业的权限。

      • createPrinterJob

        public static final PrinterJob createPrinterJob​(Printer printer)
        为指定的打印机创建作业的工厂方法。

        printer参数确定初始打印机

        参数
        printer - 用于工作。 如果打印机当前不可用（例如脱机），则可能返回null。
        结果
        一个新的PrinterJob，或null。
        异常
        SecurityException - 如果作业没有启动打印机作业的权限。

      • getPrinter

        public Printer getPrinter​()
        获取当前与此作业相关联的打印机。
        结果
        打印机的工作。

      • setPrinter

        public void setPrinter​(Printer printer)
        更改此作业的打印机。 如果新的打印机不支持当前的作业设置（例如，如果请求了DUPLEX打印但是新的打印机不支持此功能），那么这些值将重新设置为新打印机的默认值，或者在某些情况下将重置为类似的值。 例如，这可能意味着REVERSE_LANDSCAPE更新为LANDSCAPE，但是这种实现优化是允许的，但不是必需的。

        无论打印机是通过直接调用此方法进行更改还是作为用户与打印对话框进行交互的副作用，都适用上述内容。

        为打印机设置空值将安装默认打印机。 设置当前打印机没有任何效果。

        参数
        printer - 用于此打印作业。

      • getJobSettings

        public JobSettings getJobSettings​()
        JobSettings封装了所有API支持的作业配置选项，例如份数，归类选项，双面选项等。初始值基于初始打印机的当前设置。
        结果
        当前作业设置。

      • showPrintDialog

        public boolean showPrintDialog​(Window owner)
        显示打印对话框。 允许用户更新打印机和设置等作业状态。 打印对话框返回后，这些更改将在适当的属性中可用。 打印对话框通常也用于确认用户想继续打印。 这对应用程序没有约束力，但通常应该遵循。

        在没有UI可用的情况下，该方法返回true，没有更改任何选项，就像用户已确认继续打印一样。

        如果作业未处于显示对话框的状态，例如已经打印，取消或完成，则对话框将不会显示，方法将返回false。

        窗口owner可以是空的，但是如果它是可视窗口，它将被用作父级。

        可以从任何线程调用此方法。 如果从JavaFX应用程序线程调用，则必须从输入事件处理程序或从Runnable的run方法调用传递给Platform.runLater 。 在动画或布局处理过程中不得调用它。

        参数
        owner - 要阻止输入，或为空。
        结果
        如果用户选择取消打印，或作业不处于新状态，则为false。 那就是如果它已经开始，已经失败，或者已被取消或已经结束。
        异常
        IllegalStateException - 如果在动画或布局处理期间调用此方法。

      • showPageSetupDialog

        public boolean showPageSetupDialog​(Window owner)
        显示页面设置对话框。 页面设置对话框主要是允许最终用户配置页面的布局。 纸张尺寸和方向是最常见和最重要的组成部分。

        为此，将显示最合适的可用对话框。 但是，仍然可以访问其他设置，包括更改当前打印机。 因此，此对话框显示方法的副作用可能是更新该任何其他当前作业设置。 如果用户确认对话是否进行任何更改，该方法将返回true。

        如果作业未处于显示对话框的状态，例如已经打印，取消或完成，则对话框将不会显示，方法将返回false。

        窗口owner可以是空的，但是如果它是可视窗口，它将被用作父。

        可以从任何线程调用此方法。 如果从FX应用程序线程调用，则必须从输入事件处理程序或Runnable的run方法调用传递给Platform.runLater 。 在动画或布局处理过程中不得调用它。

        参数
        owner - 阻止输入，或为空。
        结果
        如果用户选择取消对话框，或作业未处于新状态，则为false。 那就是如果它已经开始，已经失败，或者已被取消或已经结束。
        异常
        IllegalStateException - 如果在动画或布局处理期间调用此方法。

      • printPage

        public boolean printPage​(PageLayout pageLayout,
                         Node node)
        使用指定的页面布局打印指定的节点。 页面布局将仅覆盖此页面的作业默认值。 如果作业状态为CANCELED，ERROR或DONE，则此方法将返回false。

        可以从任何线程调用此方法。 如果从FX应用程序线程调用，则必须从输入事件处理程序或Runnable的run方法调用传递给Platform.runLater 。 在动画或布局处理过程中不得调用它。

        参数
        pageLayout - 此页面的布局。
        node - 要打印的节点。
        结果
        渲染是否成功
        异常
        NullPointerException - 如果任一参数为空。
        IllegalStateException - 如果在动画或布局处理期间调用此方法。

      • printPage

        public boolean printPage​(Node node)
        打印指定的节点。 页面布局是作业默认值。 如果作业状态为CANCELED，ERROR或DONE，则此方法将返回false。
        参数
        node - 要打印的节点。
        结果
        渲染是否成功
        异常
        NullPointerException - 如果节点参数为空。

      • getJobStatus

        public PrinterJob.JobStatus getJobStatus​()
        获取工作的当前状态。
        结果
        目前为 JobStatus

      • cancelJob

        public void cancelJob​()
        最早取消底层打印作业。 如果这样会阻止FX用户线程持续一段时间，它可能会立即返回而不等待作业取消完成。 如果打印正在进行中，那么通常这意味着取消当前页面。 作业状态仅在发生一次后更新为已取消。 因此，确定作业已取消需要监视作业状态。

        如果作业已被请求取消，或处于ERROR或DONE状态，则该呼叫不起作用。 例如，它不会从打印机中排除已经假脱机打印的作业。 一旦作业被取消，调用任何渲染新内容或更改作业状态的方法是无效的。

      • endJob

        public boolean endJob​()
        如果作业可以成功地假脱机到打印机队列，这将返回true。 注意：这并不意味着已经打印的作业可能需要等待几分钟或更长时间，即使可实施。

        返回值为false表示作业无法假脱机或已完成。

        成功的完成也会将作业状态更新为DONE ，此时该作业将无法再使用。

        在没有打印页面的作业上调用endJob（）等效于调用{code cancelJob（）}。

        结果
        如果作业被假脱机，则为true，否则为false，或者该作业已经处于完成状态。

      • toString

        public String toString​()
        描述从类别复制： Object
        返回对象的字符串表示形式。 一般来说， toString方法返回一个字符串，“文本地表示”此对象。 结果应该是一个简明扼要的表达，容易让人阅读。 建议所有子类覆盖此方法。

        该toString类方法Object返回一个由类的名称，其中所述对象是其实例，该符号字符`的字符串@ ”，并且对象的哈希码的无符号的十六进制表示。 换句话说，这个方法返回一个等于下列值的字符串： 

         getClass().getName() + '@' + Integer.toHexString(hashCode())
        重写：
        toString在 Object
        结果
        对象的字符串表示形式。