Module java.desktop
Package java.awt.print

Class PrinterJob

java.lang.Object
java.awt.print.PrinterJob
public abstract class PrinterJob extends Object
PrinterJob类是控制打印的主要类。应用程序调用此类中的方法来设置作业，可选择与用户调用打印对话框，然后打印作业的页面。

  • Constructor Details

    • PrinterJob

      public PrinterJob()
      应使用静态的getPrinterJob方法创建一个PrinterJob对象。

  • Method Details

    • getPrinterJob

      public static PrinterJob getPrinterJob()
      创建并返回一个最初与默认打印机关联的PrinterJob。如果系统上没有可用的打印机，则仍将从此方法返回一个PrinterJob，但getPrintService()将返回null，并且使用此PrinterJob调用print可能会生成异常。需要在创建PrinterJob之前确定是否有合适的打印机的应用程序应确保从lookupPrintServices返回的数组不为空。
      返回：
      一个新的PrinterJob。
      抛出：
      SecurityException - 如果存在安全管理器并且其SecurityManager.checkPrintJobAccess()方法禁止此线程创建打印作业请求

    • lookupPrintServices

      public static PrintService[] lookupPrintServices()
      一个方便的方法，用于查找2D打印服务。从此方法返回的服务可以安装在支持打印服务的PrinterJob上。调用此方法等效于调用PrintServiceLookup.lookupPrintServices()并指定一个Pageable DocFlavor。
      返回：
      一个可能为空的2D打印服务数组。
      自：
      1.4

    • lookupStreamPrintServices

      public static StreamPrintServiceFactory[] lookupStreamPrintServices(String mimeType)
      一个方便的方法，用于查找可以绘制2D图形的流打印服务的工厂。示例用法： 
      
 FileOutputStream outstream;
 StreamPrintService psPrinter;
 String psMimeType = "application/postscript";
 PrinterJob pj = PrinterJob.getPrinterJob();

 StreamPrintServiceFactory[] factories =
     PrinterJob.lookupStreamPrintServices(psMimeType);
 if (factories.length > 0) {
     try {
         outstream = new File("out.ps");
         psPrinter =  factories[0].getPrintService(outstream);
         // psPrinter can now be set as the service on a PrinterJob
         pj.setPrintService(psPrinter)
     } catch (Exception e) {
         e.printStackTrace();
     }
 }
      从此方法返回的服务可以安装在支持打印服务的PrinterJob实例上。调用此方法等效于调用StreamPrintServiceFactory.lookupStreamPrintServiceFactories()并指定一个Pageable DocFlavor。
      参数：
      mimeType - 所需的输出格式，如果为null，则表示任何格式。
      返回：
      一个可能为空的2D流打印服务工厂数组。
      自：
      1.4

    • getPrintService

      public PrintService getPrintService()
      返回此打印作业的服务（打印机）。不支持打印服务的此类的实现可能返回null。如果没有可用的打印机，也将返回null。
      返回：
      此打印作业的服务。
      自：
      1.4
      另请参见：

    • setPrintService

      public void setPrintService(PrintService service) throws PrinterException
      将此PrinterJob与新的PrintService关联起来。支持指定打印服务的子类将覆盖此方法。如果指定的服务无法支持支持2D打印所需的Pageable和Printable接口，则会抛出PrinterException。
      参数：
      service - 支持2D打印的打印服务
      抛出：
      PrinterException - 如果指定的服务不支持2D打印，或者此PrinterJob类不支持设置2D打印服务，或者指定的服务不是有效的打印服务。
      自：
      1.4
      另请参见：

    • setPrintable

      public abstract void setPrintable(Printable painter)
      调用painter来渲染页面。由此PrinterJob打印的文档中的页面由Printable对象painter渲染。每个页面的PageFormat为默认页面格式。
      参数：
      painter - 渲染文档每个页面的Printable。

    • setPrintable

      public abstract void setPrintable(Printable painter, PageFormat format)
      调用painter以在指定的format中渲染页面。由此PrinterJob打印的文档中的页面由Printable对象painter渲染。每个页面的PageFormat为format。
      参数：
      painter - 用于渲染文档每个页面的Printable
      format - 要打印的每个页面的大小和方向

    • setPageable

      public abstract void setPageable(Pageable document) throws NullPointerException
      查询document的页面数量以及Pageable实例document中保存的每个页面的PageFormat和Printable。
      参数：
      document - 要打印的页面。不能为null。
      抛出：
      NullPointerException - 传入的Pageable为null。
      另请参见：

    • printDialog

      public abstract boolean printDialog() throws HeadlessException
      向用户呈现一个对话框，用于更改打印作业的属性。如果选择了本机打印服务，则此方法将显示本机对话框，并且用户选择的打印机将受限于这些本机打印服务。要为所有服务呈现跨平台打印对话框，包括本机服务，请使用printDialog(PrintRequestAttributeSet)。

      可以使用PrintService的PrinterJob实现来更新此PrinterJob的PrintService以反映用户选择的新服务。

      返回：
      如果用户未取消对话框，则返回true；否则返回false。
      抛出：
      HeadlessException - 如果GraphicsEnvironment.isHeadless()返回true。
      另请参见：

    • printDialog

      public boolean printDialog(PrintRequestAttributeSet attributes) throws HeadlessException
      一个方便的方法，显示一个跨平台的打印对话框，用于所有能够使用Pageable接口打印2D图形的服务。当对话框初始显示时选择的打印机将反映当前附加到此打印作业的打印服务。如果用户更改打印服务，则PrinterJob将更新以反映此更改，除非用户取消对话框。除了允许用户选择目标打印机外，用户还可以选择各种打印请求属性的值。

      输入的属性参数将反映应用程序在用户对话框中的初始选择。未指定的属性将使用服务的默认值显示。返回时，它将反映用户的选择。实现可能会更新选择，以使其与当前所选打印服务支持的值一致。

      当用户滚动到新的打印服务选择时，复制的值基于先前服务的设置，以及任何用户更改。这些值不是基于客户端提供的原始设置。

      除了选择的打印机之外，PrinterJob状态不会更新以反映用户的更改。要使选择影响打印作业，必须在调用print(PrintRequestAttributeSet)方法时指定属性。如果使用Pageable接口，打算使用用户选择的介质的客户端必须创建一个从用户选择派生的PageFormat。如果用户取消对话框，则属性将不反映用户所做的任何更改。

      参数:
      attributes - 输入时为应用程序提供的属性，输出时内容将更新以反映用户的选择。此参数不能为空。
      返回:
      如果用户未取消对话框，则返回true; 否则返回false。
      抛出:
      HeadlessException - 如果GraphicsEnvironment.isHeadless()返回true。
      NullPointerException - 如果attributes参数为null。
      自从:
      1.4
      参见:

    • pageDialog

      public abstract PageFormat pageDialog(PageFormat page) throws HeadlessException
      显示一个对话框，允许修改PageFormat实例。使用page参数初始化页面设置对话框中的控件。如果用户取消对话框，则此方法返回未修改的原始page对象。如果用户确认对话框，则此方法返回一个包含指定更改的新PageFormat对象。在任何情况下，原始page对象都不会被修改。
      参数:
      page - 提供给用户修改的默认PageFormat
      返回:
      如果对话框被取消，则返回原始page对象; 如果对话框被确认，则返回一个包含用户指定格式的新PageFormat对象。
      抛出:
      HeadlessException - 如果GraphicsEnvironment.isHeadless()返回true。
      自从:
      1.2
      参见:

    • pageDialog

      public PageFormat pageDialog(PrintRequestAttributeSet attributes) throws HeadlessException
      显示一个跨平台的页面设置对话框。可用的选择将反映当前设置在此PrinterJob上的打印服务。

      输入的属性参数将反映客户端在用户对话框中所需的初始选择。未指定的属性将使用服务的默认值显示。返回时，它将反映用户的选择。实现可能会更新选择，以使其与当前所选打印服务支持的值一致。

      返回值将是一个与PrintRequestAttributeSet中的选择等效的PageFormat。如果用户取消对话框，则属性将不反映用户所做的任何更改，返回值将为null。

      参数:
      attributes - 输入时为应用程序提供的属性，输出时内容将更新以反映用户的选择。此参数不能为空。
      返回:
      如果用户未取消对话框，则返回一个页面格式; 否则返回null。
      抛出:
      HeadlessException - 如果GraphicsEnvironment.isHeadless()返回true。
      NullPointerException - 如果attributes参数为null。
      自从:
      1.4
      参见:

    • defaultPage

      public abstract PageFormat defaultPage(PageFormat page)
      克隆PageFormat参数并更改克隆体以描述默认的页面大小和方向。
      参数:
      page - 要克隆和更改的PageFormat
      返回:
      克隆的page，更改为描述默认的PageFormat。

    • defaultPage

      public PageFormat defaultPage()
      创建一个新的PageFormat实例并将其设置为默认大小和方向。
      返回:
      一个设置为默认大小和方向的PageFormat。

    • getPageFormat

      public PageFormat getPageFormat(PrintRequestAttributeSet attributes)
      计算一个与当前PrinterJob的打印机支持的值一致的PageFormat，该值包含在attributes中的媒体、可打印区域和方向。

      调用此方法不会更新作业。对于从printDialog(PrintRequestAttributeSet attributes)获得的一组属性的客户端，此方法很有用，并且需要一个PageFormat来打印一个Pageable对象。

      参数:
      attributes - 一组打印属性，例如从调用printDialog获得。如果attributes为null，则返回默认的PageFormat。
      返回:
      一个PageFormat，其设置符合当前服务和指定属性的设置。
      自从:
      1.6

    • validatePage

      public abstract PageFormat validatePage(PageFormat page)
      返回page的克隆体，并将其设置更改为与此PrinterJob的当前打印机兼容。例如，返回的PageFormat可以将其可打印区域调整为适合当前打印机使用的纸张的物理区域内。
      参数:
      page - 要克隆并更改其设置以与当前打印机兼容的PageFormat
      返回:
      一个从page克隆并其设置更改以符合此PrinterJob的PageFormat。

    • print

      public abstract void print() throws PrinterException
      打印一组页面。
      抛出:
      PrinterException - 打印系统中的错误导致作业被中止。
      参见:

    • print

      public void print(PrintRequestAttributeSet attributes) throws PrinterException
      使用属性集中的设置打印一组页面。默认实现会忽略属性集。

      请注意，某些属性可以通过等效的方法调用直接在PrinterJob上设置（例如），拷贝: setCopies(int)，作业名称: setJobName(String)以及通过PageFormat对象指定介质大小和方向。

      如果在此属性集中指定了受支持的属性值，则该属性集将优先于此打印()操作的API设置。对于PageFormat指定以下行为: 如果客户端使用Printable接口，则此方法的attributes参数将被检查，以查找指定介质（按大小）、方向和可打印区域的属性，并将这些属性用于构造一个新的PageFormat，该PageFormat将传递给Printable对象的print()方法。请参见Printable，了解确保通过PrinterJob实现最佳打印的Printable所需行为的解释。对于Pageable接口的客户端，PageFormat将始终按照该接口提供的方式，按页进行提供。

      这些行为允许应用程序直接将从printDialog(PrintRequestAttributeSet attributes返回的用户设置传递给此print()方法。

      参数:
      attributes - 作业的一组属性
      抛出:
      PrinterException - 打印系统中的错误导致作业被中止。
      自从:
      1.4
      参见:

    • setCopies

      public abstract void setCopies(int copies)
      设置要打印的副本数。
      参数:
      copies - 要打印的副本数
      参见:

    • getCopies

      public abstract int getCopies()
      获取要打印的副本数。
      返回:
      要打印的副本数。
      参见:

    • getUserName

      public abstract String getUserName()
      获取打印用户的名称。
      返回:
      打印用户的名称
      抛出:
      SecurityException - 如果存在安全管理器并且策略文件中未给出PropertyPermission - user.name

    • setJobName

      public abstract void setJobName(String jobName)
      设置要打印的文档名称。文档名称不能为空。
      参数:
      jobName - 要打印的文档的名称
      参见:

    • getJobName

      public abstract String getJobName()
      获取要打印的文档的名称。
      返回:
      要打印的文档的名称。
      参见:

    • cancel

      public abstract void cancel()
      取消正在进行的打印作业。如果已调用print但尚未返回，则此方法表示应在下次机会时取消作业。如果没有正在进行的打印作业，则此调用不起作用。

    • isCancelled

      public abstract boolean isCancelled()
      如果正在进行打印作业，但将在下次机会时取消，则返回true；否则返回false。
      返回:
      如果正在进行的作业将被取消，则返回true；否则返回false。