Qt Print Support

Qt Print Support モジュールは、印刷機能に対する広範なクロスプラットフォーム対応を提供します。各プラットフォームの印刷システムを利用することで、Qtアプリケーションは接続されたプリンタへの印刷や、ネットワーク経由でのリモートプリンタへの印刷を行うことができます。また、この印刷システムはPDFファイルの生成もサポートしており、基本的なレポート生成機能の基盤を提供します。

Qt Print Support 以下のプラットフォームでは利用できません：

• Android™
• iOS

印刷をサポートするクラス

以下のクラスは、プリンタの選択や設定、および印刷出力をサポートしています。

ペイントデバイスと印刷

プリンタは、QPrinter によって表されます。これは、複数ページのサポートや両面出力など、印刷に特有の機能を提供するペイントデバイスです。その結果、印刷では、カスタムウィジェットや画像に描画するのと同じように、QPainter を使用して一連のページに描画することになります。

QPrinterの作成

QPrinter オブジェクトは、ユーザー入力なしでも生成・設定できますが、印刷は多くの場合、ユーザーからの要求に応じて実行されます。たとえば、GUI アプリケーションでユーザーが「File|Print... 」メニュー項目を選択した場合などです。 そのような場合、新しく生成されたQPrinter オブジェクトがQPrintDialog に渡され、ユーザーは使用するプリンタ、用紙サイズ、その他の印刷プロパティを指定できるようになります。

        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;

また、QPrinter を印刷ダイアログに渡す前に変更することで、特定のプロパティをデフォルト値として設定することも可能です。たとえば、印刷用のレポートをバッチ処理で生成するアプリケーションでは、QPrinter をプリンタではなく、デフォルトでwrite to a local file に設定することができます。

ページへの描画

QPrinter オブジェクトが構築され、設定されると、QPainter を使用してそのオブジェクト上で描画操作を実行できます。ペインターの構築と設定は、次のように行います。

    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();

QPrinter は空白のページから始まるため、最後のページを除き、各ページの描画後にnewPage()関数を呼び出すだけで済みます。

end() を呼び出すと、ドキュメントはプリンタに送信されるか、ローカルファイルに書き込まれます。

座標系

QPrinter には、用紙の寸法（用紙矩形）や印刷可能領域の寸法（ページ矩形）に関する情報を取得するために使用できる関数が用意されています。 これらは論理デバイス座標で指定されますが、デバイス自体が使用する物理座標とは異なる場合があります。これは、プリンタがユーザーのディスプレイよりも（通常は高い）解像度でテキストやグラフィックをレンダリングできることを示しています。

論理座標と物理座標間の変換を自分で処理する必要はありませんが、画面上に描画するために使用されるピクセル単位の寸法は、一般的なプリンタの高解像度には小さすぎる場合が多いため、描画操作には変換を適用する必要があります。

プリンタとペインタの座標系 paperRect() およびpageRect() 関数は、印刷に使用される用紙のサイズや、その上で描画可能な領域に関する情報を提供します。 pageRect() が返す矩形は、通常、paperRect() が返す矩形の内側に位置します。QPainter を、QPrinter を基底の描画デバイスとして使用する場合、これらの領域の位置やサイズを考慮する必要はありません。描画者の座標系の原点はページの矩形の左上隅と一致し、描画操作はページの描画可能部分の境界にクリップされます。

ペイントシステムは、テキストを描画する際に自動的に正しいデバイスメトリックを使用しますが、フォントメトリックから得られた情報を使用してテキストを配置する必要がある場合は、QFontMetrics およびQFontMetricsF オブジェクトを生成する際に印刷デバイスが指定されていることを確認するか、使用する各QFont がQPaintDevice 引数を受け入れる形式のコンストラクタを使用して生成されていることを確認する必要があります。

ウィジェットの印刷

ウィジェットを印刷するには、QWidget::render() 関数を使用できます。前述の通り、プリンタの解像度は通常、画面の解像度よりも高いため、ペインターをスケーリングする必要があります。また、ウィジェットをページ上の特定の位置に配置したい場合もあるでしょう。以下のコードサンプルは、その実装例を示しています。

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

これにより、ウィジェットがページの中央に配置され、ページに収まるように拡大縮小されます。

複雑なウィジェットからの印刷

QTextEdit やQGraphicsView などの特定のウィジェットは、通常、QTextDocument やQGraphicsScene といった他のクラスのインスタンスによって管理されるリッチコンテンツを表示します。その結果、印刷機能を提供するのは通常、これらのコンテンツ処理クラスであり、タスク全体を実行するための関数、あるいは既存のQPainter オブジェクトを受け取る関数のいずれかを通じて提供されます。 一部のウィジェットでは、基盤となる印刷機能を公開するための便利な関数が提供されており、単一の関数を呼び出すためだけにコンテンツハンドラを取得する必要がなくなります。

以下の表は、さまざまなウィジェットの中から、それぞれどのクラスおよび関数が印刷を担当しているかを示しています。印刷機能を直接公開していないウィジェットについては、対応するウィジェットのAPIにある関数を通じて、この機能を含むコンテンツ処理クラスを取得することができます。

QTextEdit は、印刷文書内の最適な場所に改ページを挿入するために、設定されたページの寸法に関する情報を使用するため、QPainter ではなくQPrinter が必要です。

モジュールの使用

Qt モジュールを使用するには、直接、あるいは他の依存関係を通じて、モジュールライブラリにリンクする必要があります。CMakeやqmake など、いくつかのビルドツールには、これを専用にサポートする機能があります。

CMake を使用したビルド

find_package() コマンドを使用して、Qt6 パッケージ内の必要なモジュールコンポーネントを指定します。

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

「CMake によるビルド」の概要も参照してください。

qmake を使用したビルド

qmake を使用してモジュールをビルドするように設定するには、プロジェクトの .pro ファイル内で、QT 変数の値としてモジュールを追加します：

QT += printsupport

モジュールの進化

「Qt Print Support 」の変更点には、Qt 6シリーズ向けに実施されたモジュールのAPIおよび機能に関する重要な変更が記載されています。

ライセンスおよび商標

Qt Print Support モジュールは、The Qt Companyから商用ライセンスの下で提供されています。さらに、フリーソフトウェアライセンスであるGNU Lesser General Public License（バージョン3） またはGNU General Public License（バージョン2）の下でも利用可能です。詳細については、「Qtのライセンス」を参照してください。

なお、^{Adobe® は}、PDF に関連して同社の商標（ロゴを含む）の使用に制限を設けています。例：「Adobe PDF」。ガイドラインについては、www.adobe.comを参照してください。