java.awt.print
类 PrinterJob

java.lang.Object
  java.awt.print.PrinterJob

public abstract class PrinterJob
extends Object

PrinterJob 类是控制打印的主要类。应用程序调用此类中的方法以设置作业、以可选方式调用与用户的打印对话框，然后打印作业的页面。

构造方法摘要

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

方法摘要

abstract void	cancel() 取消正在进行的打印作业。
PageFormat	defaultPage() 创建新的 PageFormat 实例，并将它设置为默认大小和方向。
abstract PageFormat	defaultPage(PageFormat page) 克隆 PageFormat 参数，并更改该克隆，以描述默认页面的大小和方向。
abstract int	getCopies() 获取要打印的副本数。
abstract String	getJobName() 获取要打印的文档名称。
static PrinterJob	getPrinterJob() 创建并返回最初与默认打印机关联的 PrinterJob。
PrintService	getPrintService() 返回此打印机作业的服务（打印机）。
abstract String	getUserName() 获取打印用户的名称。
abstract boolean	isCancelled() 如果打印作业正在进行中，而下一次将被取消，则返回 true；否则返回 false。
static PrintService[]	lookupPrintServices() 查找 2D 打印服务的便捷方法。
static StreamPrintServiceFactory[]	lookupStreamPrintServices(String mimeType) 定位可以成像 2D 图形的流打印服务工厂的便捷方法。
abstract PageFormat	pageDialog(PageFormat page) 显示允许修改 PageFormat 实例的对话框。
PageFormat	pageDialog(PrintRequestAttributeSet attributes) 显示跨平台页面设置对话框的便捷方法。
abstract void	print() 打印一组页面。
void	print(PrintRequestAttributeSet attributes) 使用属性集中的设置打印一组页面。
abstract boolean	printDialog() 向用户呈现一个对话框，用来更改打印作业的属性。
boolean	printDialog(PrintRequestAttributeSet attributes) 为所有服务显示跨平台打印对话框的便捷方法，这些服务能够使用 Pageable 接口打印 2D 图形。
abstract void	setCopies(int copies) 设置要打印的副本数。
abstract void	setJobName(String jobName) 设置要打印的文档名称。
abstract void	setPageable(Pageable document) 查询 document，以获得页数以及 Pageable 实例 document 中保存的每个页面的 PageFormat 和 Printable。
abstract void	setPrintable(Printable painter) 调用 painter 以呈现该页面。
abstract void	setPrintable(Printable painter, PageFormat format) 调用 painter，以用指定的 format 呈现该页面。
void	setPrintService(PrintService service) 将此 PrinterJob 与新的 PrintService 关联。
abstract PageFormat	validatePage(PageFormat page) 返回 page 的克隆，调整其设置，以与此 PrinterJob 的当前打印机兼容。

从类 java.lang.Object 继承的方法

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

构造方法详细信息

PrinterJob

public PrinterJob()

应使用静态 getPrinterJob 方法创建 PrinterJob 对象。

方法详细信息

getPrinterJob

public static PrinterJob getPrinterJob()

创建并返回最初与默认打印机关联的 PrinterJob。如果系统上没有可用的打印机，则仍从此方法返回 PrinterJob，但是，getPrintService() 将返回 null，并且使用此 PrinterJob 调用 print 可能产生异常。需要在创建 PrinterJob 之前确定是否有合适打印机的应用程序应确保从 lookupPrintServices 返回的数组不为空。

返回：

新的 PrinterJob。

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";

 StreamPrintServiceFactory[] factories =
     PrinterJob.lookupStreamPrintServices(psMimeType);
 if (factories.length > 0) {
     try {
         outstream = new File("out.ps");
         psPrinter =  factories[0].getPrintService(fos);
         // psPrinter can now be set as the service on a PrinterJob 
     } catch (FileNotFoundException e) {
     }
 }            
 

在支持打印服务的 PrinterJob 实例上可以安装从此方法返回的服务。调用此方法等效于调用 StreamPrintServiceFactory.lookupStreamPrintServiceFactories() 并指定一个 Pageable DocFlavor。

参数：

mimeType - 需要的输出格式，或 null（指任何格式）。

返回：

2D 流打印服务工厂的可能为空的数组。

从以下版本开始：

1.4

getPrintService

public PrintService getPrintService()

返回此打印机作业的服务（打印机）。不支持打印服务的此类的实现可能返回 null；

返回：

此打印机作业的服务。

从以下版本开始：

1.4

另请参见：

setPrintService(PrintService)

setPrintService

public void setPrintService(PrintService service)
                     throws PrinterException

将此 PrinterJob 与新的 PrintService 关联。支持指定 Print Service 的子类重写此方法。 如果指定的服务不能支持执行 2D 打印所需的 Pageable 和 Printable 接口，则抛出 PrinterException。

参数：

service - 支持 2D 打印的打印服务

抛出：

PrinterException - 如果指定的服务不支持 2D 打印，或此 PrinterJob 类不支持设置 2D 打印服务，或指定的服务不是有效的打印服务。

从以下版本开始：

1.4

另请参见：

getPrintService()

setPrintable

public abstract void setPrintable(Printable painter)

调用 painter 以呈现该页面。Printable 对象 painter 可以呈现由此 PrinterJob 打印的文档中的页面。每页的 PageFormat 是默认的页面格式。

参数：

painter - 呈现该文档每个页面的 Printable。

setPrintable

public abstract void setPrintable(Printable painter,
                                  PageFormat format)

调用 painter，以用指定的 format 呈现该页面。Printable 对象 painter 可以呈现由此 PrinterJob 打印的文档中的页面。每个页面的 PageFormat 为 format。

参数：

painter - 呈现该文档的每个页面所调用的 Printable

format - 要打印的每个页面的大小和方向

setPageable

public abstract void setPageable(Pageable document)
                          throws NullPointerException

查询 document，以获得页数以及 Pageable 实例 document 中保存的每个页面的 PageFormat 和 Printable。

参数：

document - 要打印的页面。它不能为 null。

抛出：

NullPointerException - 传入的 Pageable 为 null。

另请参见：

PageFormat, Printable

printDialog

public abstract boolean printDialog()
                             throws HeadlessException

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

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

返回：

如果用户不取消该对话框，则返回 true；否则返回 false。

抛出：

HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。

另请参见：

GraphicsEnvironment.isHeadless()

printDialog

public boolean printDialog(PrintRequestAttributeSet attributes)
                    throws HeadlessException

为所有服务显示跨平台打印对话框的便捷方法，这些服务能够使用 Pageable 接口打印 2D 图形。在最初显示对话框时，选择的打印机将反映当前连接到此打印作业的打印服务。如果用户更改了打印服务，则 PrinterJob 将被更新以反映此更改，除非该用户取消该对话框。除了允许用户选择目标打印机外，用户还可以选择各种打印请求属性的值。

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

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

除了选择的打印机外，不会为反映该用户的更改更新 PrinterJob 的状态。对于影响打印机作业的选择，在对 print(PrintRequestAttributeSet) 方法的调用中必须指定 attributes。如果使用 Pageable 接口，打算使用用户选择的媒体的客户端必须创建源自用户选择的 PageFormat。如果用户取消对话框，则 attributes 将不会反映用户进行的任何更改。

参数：

attributes - 输入时，是为应用程序提供的属性；输出时，内容将更新以反映用户的选择。此参数不可以为 null。

返回：

如果用户不取消该对话框，则返回 true；否则返回 false。

抛出：

HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。

NullPointerException - 如果 attributes 参数为 null。

从以下版本开始：

1.4

另请参见：

GraphicsEnvironment.isHeadless()

pageDialog

public abstract PageFormat pageDialog(PageFormat page)
                               throws HeadlessException

显示允许修改 PageFormat 实例的对话框。page 参数用于在页面设置对话框中初始化控制。如果用户取消对话框，则此方法会返回未修改的初始 page 对象。如果用户认可对话框，那么此方法将返回具有指示更改的新 PageFormat 对象。在两种情况下，都不会修改初始 page 对象。

参数：

page - 提供给用户用来修改的默认 PageFormat。

返回：

如果取消对话框，则返回初始 page 对象；如果承认对话框，则返回包含用户指示格式的新 PageFormat 对象。

抛出：

HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。

从以下版本开始：

1.2

另请参见：

GraphicsEnvironment.isHeadless()

pageDialog

public PageFormat pageDialog(PrintRequestAttributeSet attributes)
                      throws HeadlessException

显示跨平台页面设置对话框的便捷方法。可用的选择将反映当前在此 PrinterJob 上设置的打印服务。

输入的 attributes 参数将反映用户对话框中最初选择所需的客户端。未指定 attributes 时使用该服务的默认应用程序显示。返回时，它将反映用户的选择。可以更新选择，以与当前选择的打印服务支持的值一致。

返回值为 PageFormat，它等于 PrintRequestAttributeSet 中选择的值。如果用户取消对话框，则 attributes 将不会反映用户进行的任何更改，并且返回值将为 null。

参数：

attributes - 对于输入，是为用户提供的属性；对于输出，内容将更新以反映用户的选择。此参数不可以为 null。

返回：

如果用户不取消该对话框，则返回页面格式；否则返回 null。

抛出：

HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。

NullPointerException - 如果 attributes 参数为 null。

从以下版本开始：

1.4

另请参见：

GraphicsEnvironment.isHeadless()

defaultPage

public abstract PageFormat defaultPage(PageFormat page)

克隆 PageFormat 参数，并更改该克隆，以描述默认页面的大小和方向。

参数：

page - 要克隆和更改的 PageFormat

返回：

page 的克隆，已为描述默认的 PageFormat 而更改。

defaultPage

public PageFormat defaultPage()

创建新的 PageFormat 实例，并将它设置为默认大小和方向。

返回：

要设置为默认大小和方向的 PageFormat。

validatePage

public abstract PageFormat validatePage(PageFormat page)

返回 page 的克隆，调整其设置，以与此 PrinterJob 的当前打印机兼容。例如，返回的 PageFormat 所具有的可成像区域应该调整到适合当前打印机使用的纸张的物理区域。

参数：

page - 克隆的 PageFormat，其设置被更改为与当前打印机兼容

返回：

从 page 克隆的 PageFormat，其设置被更改为符合此 PrinterJob。

print

public abstract void print()
                    throws PrinterException

打印一组页面。

抛出：

PrinterException - 打印系统中出现导致作业中断的错误。

另请参见：

Book, Pageable, Printable

print

public void print(PrintRequestAttributeSet attributes)
           throws PrinterException

使用属性集中的设置打印一组页面。默认实现忽略属性集。

注意，通过调用等效的方法（例如，副本：setcopies(int)、作业名称：setJobName(String)）和指定媒体大小和方向（通过 PageFormat 对象）可以直接在 PrinterJob 上设置某些属性。

如果在此属性集中指定了支持的属性值，则该属性值仅对此 print() 操作优先于 API 设置。对于 PageFormat 指定以下行为：如果客户端使用 Printable 接口，则检查此方法的 attributes 参数，以了解指定媒体（按大小）、方向和可成像区域的属性以及用于构建新 PageFormat（传递到 Printable 对象的 print() 方法）的属性。有关 Printable 的所需行为的解释，请参阅 Printable，以确保通过 PrinterJob 进行最佳打印。对于 Pageable 接口的客户端，每个页面上的 PageFormat 将始终由该接口提供。

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

参数：

attributes - 作业的属性集

抛出：

PrinterException - 打印系统中出现导致作业中断的错误。

另请参见：

Book, Pageable, Printable

setCopies

public abstract void setCopies(int copies)

设置要打印的副本数。

参数：

copies - 要打印的副本数

另请参见：

getCopies()

getCopies

public abstract int getCopies()

获取要打印的副本数。

返回：

要打印的副本数。

另请参见：

setCopies(int)

getUserName

public abstract String getUserName()

获取打印用户的名称。

返回：

打印用户的名称

setJobName

public abstract void setJobName(String jobName)

设置要打印的文档名称。文档名称不能为 null。

参数：

jobName - 要打印的文档名称

另请参见：

getJobName()

getJobName

public abstract String getJobName()

获取要打印的文档名称。

返回：

要打印的文档的名称。

另请参见：

setJobName(java.lang.String)

cancel

public abstract void cancel()

取消正在进行的打印作业。如果调用了 print，但未返回，那么此方法会发送下一次应取消该作业的信号。如果没有正在进行的打印作业，则此调用不执行任何操作。

isCancelled

public abstract boolean isCancelled()

如果打印作业正在进行中，而下一次将被取消，则返回 true；否则返回 false。

返回：

如果进行中的作业将被取消，则返回 true；否则返回 false。