Класс QPrinter

Класс QPrinter — это устройство отрисовки, предназначенное для печати на принтере. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются реентерабельными.

Открытые типы

Открытые функции

Реализованные публичные функции

Защищенные функции

Подробное описание

Данный объект представляет серию страниц печатного вывода и используется практически так же, как и другие устройства рисования, такие как QWidget и QPixmap. Предоставлен набор дополнительных функций для управления функциями, специфичными для устройства, такими как ориентация и разрешение, а также для перехода по страницам документа по мере его создания.

При печати непосредственно на принтер в Windows или macOS QPrinter использует встроенные драйверы принтера. В X11 QPrinter использует Common Unix Printing System (CUPS) для отправки PDF-вывода на принтер. В качестве альтернативы, функцию printProgram() можно использовать для указания команды или утилиты, которые необходимо использовать вместо стандартных.

Обратите внимание, что установка параметров, таких как размер бумаги и разрешение на недействительном принтере, не определена. Можно использовать QPrinter::isValid(), чтобы проверить это перед изменением каких-либо параметров.

QPrinter поддерживает ряд параметров, большинство из которых может изменить конечный пользователь через диалог печати. В общем случае, QPrinter передает эти функции на базовую QPrintEngine.

Наиболее важными параметрами являются:

• setPageLayout() сообщает QPrinter о том, какой ориентации страницы использовать и какого размера ожидать от принтера.
• setResolution() сообщает QPrinter о требуемом разрешении принтера в точках на дюйм (DPI).
• setFullPage() сообщает QPrinter, нужно ли обрабатывать всю страницу или только часть, на которой принтер может рисовать.
• setCopyCount() сообщает QPrinter, сколько копий документа нужно распечатать.

Многие из этих функций можно вызывать только до начала фактической печати (то есть до вызова QPainter::begin()). Это обычно логично, потому что, например, невозможно изменить количество копий, когда печать уже выполняется наполовину. Также есть некоторые настройки, которые пользователь задаёт (через диалоговое окно принтера), и которые приложения должны соблюдать. Для получения более подробной информации см. документацию QAbstractPrintDialog.

При вызове QPainter::begin() связанный с ним QPrinter подготавливается к новой странице, позволяя QPainter сразу же использовать её для рисования первой страницы документа. После рисования первой страницы можно вызвать newPage(), чтобы запросить новую пустую страницу для рисования, или QPainter::end(), чтобы завершить печать. Вторая и все последующие страницы подготавливаются с помощью вызова newPage() перед их рисованием.

Первой странице документа не обязательно предшествует вызов newPage(). Вам нужно вызвать newPage() только после QPainter::begin(), если вы хотите вставить пустую страницу в начало печатаемого документа. Аналогично, вызов newPage() после рисования последней страницы документа приведет к добавлению пустой страницы в конец печатаемого документа.

Если вы хотите прервать задачу печати, abort() постарается остановить печать. Он может отменить всю задачу или только её часть.

Так как QPrinter может печатать на любой подклассе QPrintEngine, можно расширить поддержку печати, чтобы охватить новые типы подсистем печати, наследовавшись от QPrintEngine и переопределив его интерфейс.

См. также QPrintDialog и Поддержка печати Qt.

Документация типов членов

enum QPrinter::ColorMode

Этот перечисление используется для указания, должен ли QPrinter печатать в цвете или нет.

enum QPrinter::DuplexMode

Это перечисление используется для указания, будет ли печать происходить на одной или обеих сторонах каждой страницы бумаги (простая или двусторонняя печать).

enum QPrinter::OutputFormat

Перечисление OutputFormat используется для описания формата, который QPrinter должен использовать для печати.

См. также outputFormat(), setOutputFormat(), и setOutputFileName().

enum QPrinter::PageOrder

Этот тип перечисления используется QPrinter, чтобы указать приложению, как печатать.

enum QPrinter::PaperSource

Это перечисление задает источник бумаги, который должен использовать QPrinter. QPrinter не проверяет, доступен ли источник бумаги; он просто использует эту информацию, чтобы попытаться установить источник бумаги. Будет ли установлен источник бумаги, зависит от того, есть ли у принтера этот конкретный источник.

Предупреждение: В настоящее время реализовано только для Windows.

enum QPrinter::PrintRange

Используется для указания варианта выбора диапазона печати.

См. также setPrintRange(), printRange(), и QAbstractPrintDialog::PrintRange.

enum QPrinter::PrinterMode

Это перечисление описывает режим работы принтера. В основном, это предварительно заданное разрешение и режим работы.

Примечание: При отрисовке текста на устройстве QPrinter важно понимать, что размер текста, когда он задан в пунктах, не зависит от разрешения, заданного для самого устройства. Поэтому может быть полезно указывать размер шрифта в пикселях при объединении текста с графикой, чтобы гарантировать, что их относительные размеры соответствуют вашим ожиданиям.

enum QPrinter::PrinterState

enum QPrinter::Unit

Этот перечисление тип используется для указания единиц измерения размеров страницы и бумаги.

Обратите внимание на разницу между Point и DevicePixel. Единица Point определена как 1/72-я часть дюйма, а единица DevicePixel зависит от разрешения и основана на фактических пикселях или точках на принтере.

Документация функций-членов

QPrinter::QPrinter(const QPrinterInfo &printer, QPrinter::PrinterMode mode = ScreenResolution)

Создаёт новый объект принтера с заданным printer и mode.

QPrinter::QPrinter(QPrinter::PrinterMode mode = ScreenResolution)

Создаёт новый объект принтера с заданным mode.

[virtual] QPrinter::~QPrinter()

Уничтожает объект принтера и освобождает все выделенные ресурсы. Если принтер уничтожается во время выполнения задания печати, это может или не может повлиять на задание печати.

bool QPrinter::abort()

Прерывает текущую печать. Возвращает true если выполнение печати было успешно прервано, и printerState() вернёт QPrinter::Aborted; в противном случае возвращает false.

Не всегда возможно прервать задание печати. Например, все данные уже переданы принтеру, но принтер не может или не будет отменять задание при запросе.

bool QPrinter::collateCopies() const

Возвращает true если сортировка включена при выборе нескольких копий. Возвращает false если она выключена при выборе нескольких копий. Когда сортировка выключена, печать каждой отдельной страницы будет повторяться numCopies() раз, прежде чем начнется следующая страница. При включенной сортировке все страницы печатаются, прежде чем начнется следующая копия этих страниц.

См. также setCollateCopies().

QPrinter::ColorMode QPrinter::colorMode() const

Возвращает текущий режим цвета.

См. также setColorMode().

int QPrinter::copyCount() const

Возвращает количество копий, которые будут напечатаны. Значение по умолчанию — 1.

См. также setCopyCount() и supportsMultipleCopies().

QString QPrinter::creator() const

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

См. также setCreator().

QString QPrinter::docName() const

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

См. также setDocName() и QPrintEngine::PrintEnginePropertyKey.

QPrinter::DuplexMode QPrinter::duplex() const

Возвращает текущий режим двусторонней печати.

См. также setDuplex().

bool QPrinter::fontEmbeddingEnabled() const

Возвращает true если вставка шрифтов включена.

См. также setFontEmbeddingEnabled().

int QPrinter::fromPage() const

Возвращает номер первой страницы в диапазоне страниц для печати (настройка "страница с"). Страницы в документе нумеруются в соответствии с соглашением, что первая страница — это страница 1.

По умолчанию эта функция возвращает специальное значение 0, что означает, что настройка "страница с" не установлена.

Примечание: Если fromPage() и toPage() оба возвращают 0, это означает, что будет напечатан весь документ.

См. также setFromTo(), toPage() и pageRanges().

bool QPrinter::fullPage() const

Возвращает true если начало системы координат принтера находится в углу страницы и false, если оно находится на краю печатаемой области.

См. setFullPage() для подробностей и ограничений.

См. также setFullPage() и QPagedPaintDevice::pageLayout().

bool QPrinter::isValid() const

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

Для обнаружения других ошибок проверьте результат вызова QPainter::begin() или QPrinter::newPage().

    QPrinter printer;
    printer.setOutputFormat(QPrinter::PdfFormat);
    printer.setOutputFileName("/foobar/nonwritable.pdf");
    QPainter painter;
    if (! painter.begin(&printer)) { // failed to open file
        qWarning("failed to open file, is it writable?");
        return 1;
    }
    painter.drawText(10, 10, "Test");
    if (! printer.newPage()) {
        qWarning("failed in flushing page to disk, disk full?");
        return 1;
    }
    painter.drawText(10, 10, "Test 2");
    painter.end();

См. также setPrinterName().

[override virtual] bool QPrinter::newPage()

Переопределяет: QPagedPaintDevice::newPage().

Сообщает принтеру вытолкнуть текущую страницу и продолжить печать на новой странице. Возвращает true если это было выполнено успешно; в противном случае возвращает false.

Вызов newPage() для неактивного объекта QPrinter всегда завершится неудачей.

QString QPrinter::outputFileName() const

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

См. также setOutputFileName() и QPrintEngine::PrintEnginePropertyKey.

QPrinter::OutputFormat QPrinter::outputFormat() const

Возвращает формат вывода для этого принтера.

См. также setOutputFormat().

QPrinter::PageOrder QPrinter::pageOrder() const

Возвращает текущий порядок страниц.

Порядок страниц по умолчанию — FirstPageFirst.

См. также setPageOrder().

QRectF QPrinter::pageRect(QPrinter::Unit unit) const

Возвращает прямоугольник страницы в единицах unit; он обычно меньше, чем paperRect(), так как страница обычно имеет поля между своими границами и бумагой.

См. также QPagedPaintDevice::pageLayout().

[override virtual] QPaintEngine *QPrinter::paintEngine() const

Реализует: QPaintDevice::paintEngine() const.

Возвращает движок отрисовки, используемый принтером.

QRectF QPrinter::paperRect(QPrinter::Unit unit) const

Возвращает прямоугольник бумаги в единицах unit; обычно он больше, чем pageRect().

См. также pageRect().

QPrinter::PaperSource QPrinter::paperSource() const

Возвращает источник бумаги принтера. Это Manual или лоток принтера или кассета с бумагой.

См. также setPaperSource().

[since 5.10] QPagedPaintDevice::PdfVersion QPrinter::pdfVersion() const

Возвращает версию PDF для этого принтера. По умолчанию PdfVersion_1_4.

Эта функция была добавлена в Qt 5.10.

См. также setPdfVersion().

QPrintEngine *QPrinter::printEngine() const

Возвращает движок печати, используемый принтером.

QString QPrinter::printProgram() const

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

По умолчанию возвращает пустую строку; это означает, что QPrinter будет пытаться действовать умно в зависимости от системы. Только на X11 вы можете установить это значение на что-то другое, чтобы использовать определённую программу печати. На других платформах это возвращает пустую строку.

См. также setPrintProgram() и setPrinterSelectionOption().

QPrinter::PrintRange QPrinter::printRange() const

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

См. также setPrintRange().

QString QPrinter::printerName() const

Возвращает имя принтера. Это значение по умолчанию устанавливается в имя принтера по умолчанию.

См. также setPrinterName().

QString QPrinter::printerSelectionOption() const

Возвращает строку выбора параметров принтера. Это полезно только в том случае, если команда печати была явно задана.

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

Любое другое значение подразумевает, что должно использоваться данное значение.

Эта функция всегда возвращает пустую строку в Windows и Mac.

См. также setPrinterSelectionOption() и setPrintProgram().

QPrinter::PrinterState QPrinter::printerState() const

Возвращает текущее состояние принтера. Это может не всегда быть точным (например, если принтер не может сообщать о своём состоянии операционной системе).

int QPrinter::resolution() const

Возвращает текущую предполагаемую разрешающую способность принтера, заданную функцией setResolution() или драйвером принтера.

См. также setResolution().

void QPrinter::setCollateCopies(bool collate)

Устанавливает значение по умолчанию для флажка сортировки при отображении диалога печати. Если collate истинно, это активирует setCollateCopiesEnabled(). Значение по умолчанию — ложь. Это значение будет изменено тем, что пользователь нажимает в диалоге печати.

См. также collateCopies().

void QPrinter::setColorMode(QPrinter::ColorMode newColorMode)

Устанавливает цветовой режим принтера на newColorMode, который может быть Color или GrayScale.

См. также colorMode().

void QPrinter::setCopyCount(int count)

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

Драйвер принтера считывает это значение и печатает указанное количество копий.

См. также copyCount() и supportsMultipleCopies().

void QPrinter::setCreator(const QString &creator)

Устанавливает имя приложения, которое создало документ, в creator.

Эта функция применима только к версии Qt для X11. Если имя создателя не указано, создатель будет установлен как «Qt» с добавлением некоторого номера версии.

См. также creator().

void QPrinter::setDocName(const QString &name)

Устанавливает имя документа в name.

В X11 имя документа используется, например, в качестве имени файла вывода по умолчанию в QPrintDialog. Обратите внимание, что имя документа не влияет на имя файла, если печать осуществляется в файл. Используйте функцию setOutputFile() для этого.

См. также docName() и QPrintEngine::PrintEnginePropertyKey.

void QPrinter::setDuplex(QPrinter::DuplexMode duplex)

Включает двустороннюю печать в зависимости от режима duplex.

См. также duplex().

[protected] void QPrinter::setEngines(QPrintEngine *printEngine, QPaintEngine *paintEngine)

Эта функция используется подклассами QPrinter для указания пользовательских движков печати и отрисовки (printEngine и paintEngine, соответственно).

QPrinter не берет на себя владение движками, поэтому вам нужно самостоятельно управлять экземплярами этих движков.

Обратите внимание, что изменение движков сбросит состояние принтера и все его свойства.

См. также printEngine(), paintEngine() и setOutputFormat().

void QPrinter::setFontEmbeddingEnabled(bool enable)

Включает или отключает встраивание шрифтов в зависимости от enable.

См. также fontEmbeddingEnabled().

void QPrinter::setFromTo(int from, int to)

Устанавливает диапазон страниц для печати, охватывая страницы с номерами, указанными from и to, где from соответствует первой странице в диапазоне, а to — последней.

Примечание: страницы в документе нумеруются по соглашению, что первая страница — страница 1. Однако, если from и to оба установлены в 0, будет напечатан весь документ.

Эта функция в основном используется для установки значения по умолчанию, которое пользователь может переопределить в диалоге печати, когда вы вызываете setup().

См. также fromPage(), toPage() и pageRanges().

void QPrinter::setFullPage(bool fp)

Если fp истинно, включает поддержку отрисовки по всей странице; в противном случае ограничивает отрисовку областью печати, указанной устройством.

По умолчанию печать по всей странице отключена. В этом случае начало координат системы координат QPrinter совпадает с верхним левым углом области печати.

Если печать по всей странице включена, начало координат системы координат QPrinter совпадает с верхним левым углом самой бумаги. В этом случае метрики устройства device metrics будут сообщать о тех же самых размерах, что и указано {QPageSize}. Возможно, не удастся напечатать на всей физической странице из-за полей принтера, поэтому приложение должно учитывать поля самостоятельно.

См. также fullPage(), QPagedPaintDevice::pageLayout() и QPagedPaintDevice::setPageSize().

void QPrinter::setOutputFileName(const QString &fileName)

Устанавливает имя выходного файла в fileName.

Установка нулевого или пустого имени (0 или "") отключает печать в файл. Установка ненулевого имени включает печать в файл.

Это может изменить значение outputFormat(). Если имя файла имеет расширение «.pdf», генерируется PDF. Если имя файла имеет расширение, отличное от «.pdf», используемый формат вывода — тот, который установлен с помощью setOutputFormat().

QPrinter использует кроссплатформенные движки печати PDF Qt соответственно. Если вы можете создать этот формат напрямую, например macOS может генерировать PDF из своего движка печати, установите формат вывода обратно в NativeFormat.

См. также outputFileName() и setOutputFormat().

void QPrinter::setOutputFormat(QPrinter::OutputFormat format)

Устанавливает формат вывода для этого принтера на format.

Если format имеет то же значение, что и текущее значение, то изменений не произойдёт.

Если format равен NativeFormat, то printerName будет установлен на стандартный принтер. Если не задано ни одного действующего принтера, то изменений не произойдёт. Если вы хотите установить NativeFormat со специфическим printerName, то используйте setPrinterName().

См. также outputFormat() и setPrinterName().

void QPrinter::setPageOrder(QPrinter::PageOrder pageOrder)

Устанавливает порядок страниц на pageOrder.

Порядок страниц может быть QPrinter::FirstPageFirst или QPrinter::LastPageFirst. Приложение отвечает за чтение порядка страниц и печать соответственно.

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

Эта функция поддерживается только под X11.

См. также pageOrder().

void QPrinter::setPaperSource(QPrinter::PaperSource source)

Устанавливает параметры источника бумаги на source.

Только Windows: Этот параметр может быть изменён во время печати и вступит в силу с следующего вызова newPage()

См. также paperSource().

[since 5.10] void QPrinter::setPdfVersion(QPagedPaintDevice::PdfVersion version)

Устанавливает версию PDF для этого принтера на version.

Если version имеет то же значение, что и текущее значение, то изменений не произойдёт.

Эта функция была добавлена в Qt 5.10.

См. также pdfVersion().

void QPrinter::setPrintProgram(const QString &printProg)

Устанавливает имя программы, которая должна выполнить задание печати, на printProg.

В X11 эта функция устанавливает программу для вызова с выходными данными PDF. На других платформах она не оказывает никакого влияния.

См. также printProgram().

void QPrinter::setPrintRange(QPrinter::PrintRange range)

Устанавливает опцию диапазона печати на range.

См. также printRange().

void QPrinter::setPrinterName(const QString &name)

Устанавливает имя принтера на name.

Если name пустая, то формат вывода будет установлен на PdfFormat.

Если name не является валидным именем принтера, то изменений не произойдёт.

Если name является валидным именем принтера, то формат вывода будет установлен на NativeFormat.

См. также printerName(), isValid(), и setOutputFormat().

void QPrinter::setPrinterSelectionOption(const QString &option)

Устанавливает принтер для использования параметра option для выбора принтера. option имеет значение null по умолчанию (что означает, что Qt должен достаточно разумно угадать), но его можно установить на другие значения для использования специфической опции выбора принтера.

Если опция выбора принтера изменена во время активности принтера, текущая задача печати может быть или не быть затронута.

Эта функция не имеет эффекта на Windows или Mac.

См. также printerSelectionOption() и setPrintProgram().

void QPrinter::setResolution(int dpi)

Запрашивает печать на принтере с разрешением dpi или как можно ближе к dpi.

Этот параметр влияет на систему координат, возвращаемую, например, QPainter::viewport().

Эта функция должна быть вызвана перед QPainter::begin(), чтобы иметь эффект на всех платформах.

См. также resolution() и QPagedPaintDevice::setPageSize().

QList<QPrinter::PaperSource> QPrinter::supportedPaperSources() const

Возвращает поддерживаемые размеры бумаги для этого принтера.

Значения могут быть либо значением, соответствующим записи в QPrinter::PaperSource, либо значением, специфичным для драйвера. Значения, специфичные для драйвера, больше, чем константа DMBIN_USER, объявленная в wingdi.h.

Предупреждение: Эта функция доступна только в Windows.

QList<int> QPrinter::supportedResolutions() const

Возвращает список разрешений (список целых чисел точек на дюйм), которые поддерживает принтер.

Для X11, где вся печать выполняется непосредственно в PDF, эта функция всегда будет возвращать список из одного элемента, содержащий только разрешение PDF, т.е. 72 (72 dpi — см. PrinterMode).

bool QPrinter::supportsMultipleCopies() const

Возвращает true, если принтер поддерживает печать нескольких копий одного документа в одной задаче; в противном случае возвращается false.

На большинстве систем эта функция вернёт true. Однако на системах X11, которые не поддерживают CUPS, эта функция вернёт false. Это означает, что приложение должно обрабатывать количество копий, печатая один и тот же документ необходимое количество раз.

См. также setCopyCount() и copyCount().

int QPrinter::toPage() const

Возвращает номер последней страницы в диапазоне страниц для печати ("номер страницы по"). Страницы в документе нумеруются в соответствии с соглашением, что первая страница — это страница 1.

По умолчанию эта функция возвращает специальное значение 0, что означает, что параметр "номер страницы по" не задан.

Примечание: Если fromPage() и toPage() оба возвращают 0, это указывает на то, что будет напечатан весь документ.

Программист отвечает за чтение этого параметра и печать соответственно.

См. также setFromTo(), fromPage(), и pageRanges().