Qt Print Support

El módulo Qt Print Support proporciona un amplio soporte multiplataforma para la impresión. Utilizando los sistemas de impresión de cada plataforma, las aplicaciones Qt pueden imprimir en impresoras conectadas y, a través de redes, en impresoras remotas. El sistema de impresión también soporta la generación de archivos PDF, proporcionando la base para la generación de informes básicos.

Qt Print Support no está disponible en:

• Android™
• iOS

Clases que soportan la impresión

Las siguientes clases soportan la selección y configuración de impresoras y la salida de impresión.

Dispositivos de pintura e impresión

Las impresoras están representadas por QPrinter, un dispositivo de pintura que proporciona funciones específicas para la impresión, como la compatibilidad con varias páginas y la impresión a doble cara. Como resultado, la impresión implica el uso de QPainter para pintar en una serie de páginas de la misma manera que pintaría en un widget personalizado o en una imagen.

Creación de una impresora QPrinter

Aunque los objetos QPrinter pueden ser construidos y configurados sin requerir la intervención del usuario, la impresión se realiza a menudo como resultado de una petición del usuario; por ejemplo, cuando el usuario selecciona el elemento de menú File|Print... en una aplicación GUI. En tales casos, un objeto QPrinter recién construido se suministra a QPrintDialog, permitiendo al usuario especificar la impresora a utilizar, el tamaño del papel y otras propiedades de impresión.

        QPrinter printer;

        QPrintDialog dialog(&printer, this);
        dialog.setWindowTitle(tr("Print Document"));
        if (editor->textCursor().hasSelection())
            dialog.addEnabledOption(QAbstractPrintDialog::PrintSelection);
        if (dialog.exec() != QDialog::Accepted)
            return;

También es posible establecer ciertas propiedades por defecto modificando el QPrinter antes de que sea suministrado al diálogo de impresión. Por ejemplo, las aplicaciones que generan lotes de informes para imprimir pueden configurar el QPrinter a write to a local file por defecto en lugar de a una impresora.

Pintar en una página

Una vez construido y configurado un objeto QPrinter, se puede utilizar QPainter para realizar operaciones de pintura sobre él. Podemos construir y configurar un pintor de la siguiente manera:

    QPrinter printer(QPrinter::HighResolution);
    printer.setOutputFileName("print.ps");
    QPainter painter;
    painter.begin(&printer);

    for (int page = 0; page < numberOfPages; ++page) {

        // Use the painter to draw on the page.

        if (page != lastPage)
            printer.newPage();
    }

    painter.end();

Como el QPrinter comienza con una página en blanco, sólo necesitamos llamar a la función newPage() después de dibujar cada página, excepto la última.

El documento se envía a la impresora, o se escribe en un archivo local, cuando llamamos a end().

Sistemas de coordenadas

QPrinter proporciona funciones que pueden utilizarse para obtener información sobre las dimensiones del papel (el rectángulo del papel) y las dimensiones del área imprimible (el rectángulo de la página). Éstas se dan en coordenadas lógicas del dispositivo que pueden diferir de las coordenadas físicas utilizadas por el propio dispositivo, lo que indica que la impresora es capaz de renderizar texto y gráficos a una resolución (normalmente mayor) que la pantalla del usuario.

Aunque no es necesario que nos encarguemos nosotros mismos de la conversión entre coordenadas lógicas y coordenadas físicas, sí es necesario aplicar transformaciones a las operaciones de pintado, ya que las medidas de los píxeles utilizadas para dibujar en pantalla suelen ser demasiado pequeñas para las resoluciones más altas de las impresoras habituales.

Sistemas de coordenadas de impresora y pintor Las funciones paperRect() y pageRect() proporcionan información sobre el tamaño del papel utilizado para imprimir y el área del mismo sobre la que se puede pintar. El rectángulo devuelto por pageRect() suele estar dentro del rectángulo devuelto por paperRect(). No es necesario tener en cuenta las posiciones y tamaños de estas áreas cuando se utiliza un QPainter con un QPrinter como dispositivo de pintura subyacente; el origen del sistema de coordenadas del pintor coincidirá con la esquina superior izquierda del rectángulo de la página, y las operaciones de pintura se recortarán a los límites de la parte dibujable de la página.

El sistema de pintura utiliza automáticamente las métricas de dispositivo correctas al pintar texto pero, si necesita posicionar texto utilizando la información obtenida de las métricas de fuente, deberá asegurarse de que se especifica el dispositivo de impresión al construir los objetos QFontMetrics y QFontMetricsF, o asegurarse de que cada QFont utilizado se construye utilizando la forma del constructor que acepta un argumento QPaintDevice.

Impresión de widgets

Para imprimir un widget, puede utilizar la función QWidget::render(). Como se ha mencionado, la resolución de la impresora suele ser mayor que la resolución de la pantalla, por lo que tendrás que escalar el pintor. También es posible que desee posicionar el widget en la página. El siguiente ejemplo de código muestra cómo puede quedar.

        QPainter painter;
        painter.begin(&printer);
        const auto pageLayout = printer.pageLayout();
        const auto pageRect = pageLayout.paintRectPixels(printer.resolution());
        const auto paperRect = pageLayout.fullRectPixels(printer.resolution());
        double xscale = pageRect.width() / double(myWidget->width());
        double yscale = pageRect.height() / double(myWidget->height());
        double scale = qMin(xscale, yscale);
        painter.translate(pageRect.x() + paperRect.width() / 2.,
                          pageRect.y() + paperRect.height() / 2.);
        painter.scale(scale, scale);
        painter.translate(-myWidget->width() / 2., -myWidget->height() / 2.);

        myWidget->render(&painter);

Esto centrará el widget en la página y lo escalará para que se ajuste a la página.

Impresión desde widgets complejos

Ciertos widgets, como QTextEdit y QGraphicsView, muestran contenido rico que normalmente es gestionado por instancias de otras clases, como QTextDocument y QGraphicsScene. Como resultado, son estas clases que manejan el contenido las que normalmente proporcionan la funcionalidad de impresión, ya sea a través de una función que se puede utilizar para realizar la tarea completa, o a través de una función que acepta un objeto QPainter existente. Algunos widgets proporcionan funciones de conveniencia para exponer las características de impresión subyacentes, evitando la necesidad de obtener el manejador de contenido sólo para llamar a una única función.

La siguiente tabla muestra qué clase y función son responsables de la impresión desde una selección de diferentes widgets. Para los widgets que no exponen la funcionalidad de impresión directamente, las clases de manejo de contenido que contienen esta funcionalidad pueden obtenerse a través de una función en la API del widget correspondiente.

QTextEdit requiere un QPrinter en lugar de un QPainter porque utiliza información sobre las dimensiones de página configuradas para insertar saltos de página en los lugares más apropiados de los documentos impresos.

Uso del módulo

Utilizar un módulo Qt requiere enlazar con la biblioteca del módulo, ya sea directamente o a través de otras dependencias. Varias herramientas de compilación tienen soporte dedicado para esto, incluyendo CMake y qmake.

Construir con CMake

Utilice el comando find_package() para localizar los componentes necesarios del módulo en el paquete Qt6:

find_package(Qt6 REQUIRED COMPONENTS PrintSupport)
target_link_libraries(mytarget PRIVATE Qt6::PrintSupport)

Véase también la descripción general de la compilación con CMake.

Construcción con qmake

Para configurar el módulo para su construcción con qmake, añada el módulo como valor de la variable QT en el archivo .pro del proyecto:

QT += printsupport

Evolución del módulo

Cambios en Qt Print Support enumera los cambios importantes en la API del módulo y la funcionalidad que se hicieron para la serie Qt 6 de Qt.

Licencias y Marcas Registradas

El módulo Qt Print Support está disponible bajo licencia comercial de The Qt Company. Además, está disponible bajo licencias de software libre: La Licencia Pública General Reducida de GNU, versión 3, o la Licencia Pública General de GNU, versión 2. Consulte Licencias de Qt para obtener más información.

Tenga en cuenta que ^Adobe® impone restricciones al uso de sus marcas comerciales (incluidos los logotipos) junto con PDF; por ejemplo, "Adobe PDF". Consulte las directrices en www.adobe.com.