Класс 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 Поддержка печати.

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

перечисление QPrinter::ColorMode

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

перечисление QPrinter::DuplexMode

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

перечисление QPrinter::OutputFormat

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

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

перечисление QPrinter::PageOrder

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

перечисление QPrinter::PaperSource

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

перечисление QPrinter::PrintRange

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

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

перечисление QPrinter::PrinterMode

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

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, означающее, что параметр «начальная страница» не задан.

См. также 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 и macOS.

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

QPrinter::PrinterState QPrinter::printerState() const

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

int QPrinter::resolution() const

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

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

void QPrinter::setCollateCopies(bool collate)

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

См. также 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 — последней.

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

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

void QPrinter::setFullPage(bool fp)

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

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

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

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

void QPrinter::setOutputFileName(const QString &fileName)

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

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

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

QPrinter использует кроссплатформенные движки Qt для PDF-печати, соответственно. Если вы можете генерировать этот формат напрямую, например, 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.

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, что означает, что параметр "номер страницы до" не задан.

Разработчик отвечает за чтение этого параметра и соответствующую печать.

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