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() 獲取要列印的文檔名稱。
PageFormat	getPageFormat(PrintRequestAttributeSet attributes) 使用與受此作業 PrintService 支持的那些值一致的值（即由 getPrintService() 返回的值），以及 attributes 中包含的介質、可列印區域和方向計算 PageFormat。
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。

拋出：

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

 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。如果沒有印表機可用，也將返回 null。

返回：

此印表機作業的服務。

從以下版本開始：

1.4

另請參見：

setPrintService(PrintService), getPrinterJob()

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。

getPageFormat

public PageFormat getPageFormat(PrintRequestAttributeSet attributes)

使用與受此作業 PrintService 支持的那些值一致的值（即由 getPrintService() 返回的值），以及 attributes 中包含的介質、可列印區域和方向計算 PageFormat。

調用此方法不會更新作業。對於擁有一組從 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 複製的 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 為確保通過 PrinterJob 進行最佳列印所需行為的解釋，請參閱 Printable。對於 Pageable 介面的客戶端，每個頁面上的 PageFormat 將始終由該介面提供。

這些行為允許應用程序直接將從 printDialog(PrintRequestAttributeSet attributes) 返回的使用者設置傳遞到此 print() 方法。

參數：

attributes - 作業的屬性集

拋出：

PrinterException - 列印系統中出現導致作業中斷的錯誤。

從以下版本開始：

1.4

另請參見：

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。