Класс PrinterJob

java.lang.Object

java.awt.print.PrinterJob

public abstract class PrinterJob extends Object

Класс PrinterJob — это основной класс, который управляет печатью. Приложение вызывает методы этого класса для настройки задания, при необходимости для вызова диалогового окна печати с пользователем, а затем для печати страниц задания.

Краткое описание конструкторов

Конструктор	Описание
`PrinterJob()`	Объект `PrinterJob` должен быть создан с помощью статического метода `getPrinterJob`.

Краткое описание методов

Модификатор и тип	Метод	Описание
`abstract void`	`cancel()`	Отменяет задание печати, которое выполняется в данный момент.
`PageFormat`	`defaultPage()`	Создаёт новый экземпляр `PageFormat` и устанавливает его по умолчанию размер и ориентацию.
`abstract PageFormat`	`defaultPage(PageFormat page)`	Клонирует аргумент `PageFormat` и изменяет клон, чтобы описать размер и ориентацию страницы по умолчанию.
`abstract int`	`getCopies()`	Получает количество копий для печати.
`abstract String`	`getJobName()`	Получает имя документа, который будет печататься.
`PageFormat`	`getPageFormat(PrintRequestAttributeSet attributes)`	Вычисляет `PageFormat` со значениями, совместимыми со значениями, поддерживаемыми текущим `PrintService` для этого задания (например, значение, возвращаемое `getPrintService()`) и носителем, печатаемой областью и ориентацией, содержащимися в `attributes`.
`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)`	Метод-удобство, который отображает кроссплатформенное диалоговое окно печати для всех служб, которые могут печатать 2D-графику с помощью интерфейса `Pageable`.
`abstract void`	`setCopies(int copies)`	Устанавливает количество копий для печати.
`abstract void`	`setJobName(String jobName)`	Устанавливает имя документа, который будет печататься.
`abstract void`	`setPageable(Pageable document)`	Запрашивает `document` количество страниц и `PageFormat` и `Printable` для каждой страницы, хранящейся в экземпляре `Pageable`, `document`.
`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()

Объект PrinterJob должен быть создан с помощью статического метода getPrinterJob.

Подробное описание методов

getPrinterJob

public static PrinterJob getPrinterJob()

Создаёт и возвращает PrinterJob, первоначально связанный с принтером по умолчанию. Если на системе нет доступных принтеров, метод всё равно вернёт PrinterJob, но getPrintService() вернёт null, и вызов print с этим PrinterJob может вызвать исключение. Приложениям, которым нужно определить наличие подходящих принтеров перед созданием 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(PrintService)
getPrinterJob()

setPrintService

public void setPrintService(PrintService service) throws PrinterException

Связывает эту PrinterJob с новой PrintService. Этот метод переопределяется подклассами, которые поддерживают указание Print Service. Бросает PrinterException , если указанная служба не может поддерживать Pageable и Printable интерфейсы, необходимые для поддержки 2D печати.

Параметры:

service - служба печати, поддерживающая 2D печать

Исключения:

PrinterException - если указанная служба не поддерживает 2D печать, или этот класс PrinterJob не поддерживает установку 2D службы печати, или указанная служба по другим причинам не является корректной службой печати.

С момента:

1.4

См. также:

getPrintService()

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 количество страниц и PageFormat и Printable для каждой страницы, хранящихся в экземпляре Pageable, document.

Параметры:

document - страницы, которые нужно напечатать. Не может быть null.

Исключения:

NullPointerException - переданный Pageable был null.

См. также:

printDialog

public abstract boolean printDialog() throws HeadlessException

Представляет пользователю диалоговое окно для изменения свойств задания печати. Этот метод отобразит системное диалоговое окно, если выбрана служба печати, и выбор принтера будет ограничен этими системными службами печати. Чтобы отобразить кроссплатформенное диалоговое окно для всех служб, включая системные, используйте printDialog(PrintRequestAttributeSet).

Реализации PrinterJob, которые могут использовать PrintService, обновят PrintService для этого PrinterJob, чтобы отразить новую выбранную пользователем службу.

Возвращает:

true если пользователь не отменил диалог; false в противном случае.

Исключения:

HeadlessException - если GraphicsEnvironment.isHeadless() возвращает true.

См. также:

GraphicsEnvironment.isHeadless()

printDialog

public boolean printDialog(PrintRequestAttributeSet attributes) throws HeadlessException

Удобный метод, отображающий кроссплатформенное диалоговое окно печати для всех служб, которые способны печатать 2D графику с использованием интерфейса Pageable. Выбранный принтер при первоначальном отображении диалога будет отражать службу печати, которая в данный момент подключена к этому заданию печати. Если пользователь изменит службу печати, PrinterJob будет обновлён, чтобы отразить это, если пользователь не отменит диалог. Помимо выбора принтера назначения, пользователь может также выбрать значения различных атрибутов запроса печати.

Параметр attributes при вводе будет отражать первоначальный выбор приложения в диалоговом окне пользователя. Атрибуты, не указанные при выводе, будут отображаться по умолчанию для службы. При выводе он будет отражать выбор пользователя. Выбранные значения могут быть обновлены реализацией, чтобы соответствовать поддерживаемым значениям для выбранной в настоящее время службы печати.

При прокрутке к новому выбору службы печати копируемые значения основаны на настройках предыдущей службы, а также на любых изменениях пользователя. Значения не основаны на первоначальных настройках, предоставленных клиентом.

За исключением выбранного принтера, состояние PrinterJob не обновляется, чтобы отразить изменения пользователя. Для того чтобы выбранные значения повлияли на задание печати, их необходимо указать в вызове метода print(PrintRequestAttributeSet). Если используется интерфейс Pageable, клиенты, которые намерены использовать выбранный пользователем носитель, должны создать PageFormat, полученный из выборов пользователя. Если пользователь отменяет диалог, атрибуты не будут отражать внесённые пользователем изменения.

Параметры:

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 не изменяется.

Parameters:

page - значение PageFormat по умолчанию, представленное пользователю для изменения

Returns:

исходный объект page, если диалоговое окно отменено; новый объект PageFormat, содержащий формат, указанный пользователем, если диалоговое окно подтверждено.

Throws:

HeadlessException - если GraphicsEnvironment.isHeadless() возвращает true.

Since:

1.2

See Also:

GraphicsEnvironment.isHeadless()

pageDialog

public PageFormat pageDialog(PrintRequestAttributeSet attributes) throws HeadlessException

Удобный метод, отображающий диалоговое окно настройки страницы для кроссплатформенной печати. Доступные параметры будут отражать текущую службу печати, установленную в данном PrinterJob.

Параметр attributes на входе отражает первоначальный выбор клиента в диалоговом окне пользователя. Не указанные атрибуты отображаются по умолчанию для службы. На выходе он отразит выбор пользователя. Выбор может быть обновлён реализацией, чтобы соответствовать поддерживаемым значениям для текущей выбранной службы печати.

Возвращаемое значение будет эквивалентом PageFormat для выбора в PrintRequestAttributeSet. Если пользователь отменяет диалоговое окно, атрибуты не будут отражать внесённые пользователем изменения, и возвращаемое значение будет null.

Parameters:

attributes - на вход подаются атрибуты приложения, на выходе содержимое обновляется, чтобы отразить выбор пользователя. Этот параметр не может быть null.

Returns:

формат страницы, если пользователь не отменяет диалоговое окно; null в противном случае.

Throws:

HeadlessException - если GraphicsEnvironment.isHeadless() возвращает true.

NullPointerException - если параметр attributes имеет значение null.

Since:

1.4

See Also:

GraphicsEnvironment.isHeadless()

defaultPage

public abstract PageFormat defaultPage(PageFormat page)

Создаёт клон аргумента PageFormat и изменяет клон, чтобы описать размер и ориентацию страницы по умолчанию.

Parameters:: page - PageFormat для клонирования и изменения
Returns:: клон page, изменённый для описания размера и ориентации страницы по умолчанию.

defaultPage

public PageFormat defaultPage()

Создаёт новый экземпляр PageFormat и устанавливает его размер и ориентацию по умолчанию.

Returns:: экземпляр PageFormat с размером и ориентацией по умолчанию.

getPageFormat

public PageFormat getPageFormat(PrintRequestAttributeSet attributes)

Вычисляет PageFormat со значениями, соответствующими тем, которые поддерживаются текущей PrintService для данного задания (т.е. значение, возвращаемое getPrintService()) и носителя, печатаемой области и ориентации, содержащихся в attributes.

Вызов этого метода не обновляет задание. Он полезен для клиентов, у которых есть набор атрибутов, полученных из printDialog(PrintRequestAttributeSet attributes), и которым необходим PageFormat для печати объекта Pageable.

Parameters:: attributes - набор атрибутов печати, например, полученных вызовом printDialog. Если attributes имеет значение null, возвращается PageFormat по умолчанию.
Returns:: PageFormat с настройками, соответствующими текущей службе и указанным атрибутам.
Since:: 1.6

validatePage

public abstract PageFormat validatePage(PageFormat page)

Возвращает клон page с настройками, адаптированными для текущего принтера этого PrinterJob. Например, возвращённый PageFormat может иметь область изображения, скорректированную для соответствия физической области бумаги, используемой текущим принтером.

Parameters:: page - PageFormat для клонирования и изменения настроек для соответствия текущему принтеру
Returns:: PageFormat с настройками, скопированными из page и адаптированными для этого PrinterJob.

print

public abstract void print() throws PrinterException

Печатает набор страниц.

Throws:

PrinterException - ошибка в системе печати, из-за которой задание было прервано.

See Also:

print

public void print(PrintRequestAttributeSet attributes) throws PrinterException

Печатает набор страниц с использованием настроек из набора атрибутов. Реализация по умолчанию игнорирует набор атрибутов.

Обратите внимание, что некоторые атрибуты могут быть установлены непосредственно в PrinterJob с помощью эквивалентных вызовов методов (например), количество копий: setCopies(int), имя задания: setJobName(String) и указание размера и ориентации носителя через объект PageFormat.

Если в этом наборе атрибутов указано поддерживаемое значение атрибута, оно будет иметь приоритет над настройками API для данной операции print(). Для PageFormat указано следующее поведение: если клиент использует интерфейс Printable, то параметр attributes этого метода проверяется на атрибуты, которые задают носитель (по размеру), ориентацию и область изображения, и эти значения используются для построения нового PageFormat, который передаётся в метод print() объекта Printable. См. Printable для объяснения необходимого поведения Printable, чтобы обеспечить оптимальную печать через PrinterJob. Для клиентов интерфейса Pageable формат страницы всегда передаётся этим интерфейсом на основе каждой страницы.

Это поведение позволяет приложению напрямую передать настройки пользователя, возвращённые из printDialog(PrintRequestAttributeSet attributes, в этот метод print().

Parameters:

attributes - набор атрибутов для задания

Throws:

PrinterException - ошибка в системе печати, из-за которой задание было прервано.

Since:

1.4

See Also:

setCopies

public abstract void setCopies(int copies)

Устанавливает количество копий для печати.

Parameters:

copies - количество копий для печати

See Also:

getCopies()

getCopies

public abstract int getCopies()

Возвращает количество копий для печати.

Returns:

количество копий для печати.

See Also:

setCopies(int)

getUserName

public abstract String getUserName()

Возвращает имя пользователя, выполняющего печать.

Returns:: имя пользователя, выполняющего печать
Throws:: SecurityException - если существует менеджер безопасности и разрешение PropertyPermission - user.name не указано в файле политики

setJobName

public abstract void setJobName(String jobName)

Устанавливает имя документа для печати. Имя документа не может быть null.

Parameters:

jobName - имя документа для печати

See Also:

getJobName()

getJobName

public abstract String getJobName()

Возвращает имя документа для печати.

Returns:

имя документа для печати.

See Also:

setJobName(java.lang.String)

cancel

public abstract void cancel()

Отменяет задание печати, которое выполняется в данный момент. Если метод print был вызван, но ещё не завершён, этот метод сигнализирует, что задание должно быть отменено в ближайшее время. Если задание печати не выполняется, этот вызов ничего не делает.

isCancelled

public abstract boolean isCancelled()

Возвращает true если задание печати выполняется, но будет отменено в ближайшее время; в противном случае возвращает false.

Returns:: true если текущее задание будет отменено; false в противном случае.

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/java/awt/print/PrinterJob.html