モジュール javafx.graphics
パッケージ javafx.print

クラスPrinterJob


  • public final class PrinterJob
extends Object
    PrinterJobは、JavaFXシーングラフ印刷の出発点となります。

    これには、次のものが含まれます

    • プリンタの検出
    • ジョブの作成
    • サポートされるプリンタの機能に基づいたジョブの構成
    • ページの設定
    • ノード階層のページへのレンダリング。

    単一ノードを印刷する、非常に単純な例を次に示します。 

     Node node = new Circle(100, 200, 200);
 PrinterJob job = PrinterJob.createPrinterJob();
 if (job != null) {
    boolean success = job.printPage(node);
    if (success) {
        job.endJob();
    }
 }
    注意点

    前述の例では、ノードはシーンに追加されていません。 ほとんどの印刷シナリオでは、まったく表示されていないか、別途準備してフォーマットする必要のあるコンテンツを印刷するため、これで問題はありません。

    現在シーンの一部として表示されているコンテンツを印刷する場合は、ジョブの印刷が(ジョブの単一ページの印刷であっても)複数のスクリーン「パルス」(フレーム)にまたがる可能性があるため、アプリケーションでは、印刷対象のノードが印刷処理中に更新されないようにすることが重要です。そうしないと、レンダリングが部分的にしか行われなかったり、レンダリング結果が崩れたりすることが考えられます。

    表示されていないノードにも同じことが当てはまるのは明らかであるため、印刷と並行してノードを更新するのは避けてください。

    FXアプリケーション・スレッドで印刷を実行する際の必要条件はありません。 ノードの印刷準備やジョブの呼出しはどのスレッドでも行うことができます。 ただし、アプリケーションUIの応答性に影響が及ばないように、FXアプリケーション・スレッドで実行される処理の量を最小限に抑えるのが一般的に望ましいと言えます。 したがって、印刷は新しいスレッドで実行し、実装内部のスケジューリングによって、FXスレッドで実行する必要のあるすべてのタスクがそのスレッドで実行されるようにすることをお薦めします。

    導入されたバージョン:
    JavaFX 8.0

    • メソッドの詳細

      • createPrinterJob

        public static final PrinterJob createPrinterJob​()
        ジョブを作成するファクトリ・メソッド。 使用可能なプリンタがない場合は、nullを返します。 一部のプラットフォームでは、ドキュメントを作成する疑似プリンタが用意されていることがあります。 これらは、プラットフォームでもプリンタと同様に列挙されるかぎり、ここで列挙されます。
        戻り値:
        新しいPrinterJobインスタンスまたはnull。
        例外:
        SecurityException - ジョブに印刷ジョブを開始するためのアクセス権がない場合。

      • createPrinterJob

        public static final PrinterJob createPrinterJob​(Printer printer)
        指定されたプリンタのジョブを作成するファクトリ・メソッド。

        printer引数によって初期プリンタが決定されます

        パラメータ:
        printer - ジョブに使用。 現在プリンタが使用できない(オフラインなど)の場合は、nullを返します。
        戻り値:
        新しいPrinterJobまたはnull。
        例外:
        SecurityException - ジョブに印刷ジョブを開始するためのアクセス権がない場合。

      • getPrinter

        public Printer getPrinter​()
        現在このジョブに関連付けられているプリンタを取得します。
        戻り値:
        ジョブのプリンタ。

      • setPrinter

        public void setPrinter​(Printer printer)
        このジョブのプリンタを変更します。 新しいプリンタが現在のジョブ設定をサポートしていない場合(たとえば、DUPLEX印刷がリクエストされたが、新しいプリンタがこれをサポートしていない場合)、値は新しいプリンタのデフォルト(場合によって同様の値)にリセットされます。 たとえば、REVERSE_LANDSCAPEがLANDSCAPEに更新される場合がこれに当たりますが、この実装の最適化は許可されているものの、必須ではありません。

        前述の処理は、このメソッドを呼び出すことでプリンタが直接変更されたのか、印刷ダイアログでのユーザー操作の副次的作用としてなのかにかかわらず適用されます。

        プリンタとしてnull値を設定すると、デフォルト・プリンタがインストールされます。 現在のプリンタを設定することは無効です。

        パラメータ:
        printer - この印刷ジョブに使用。

      • getJobSettings

        public JobSettings getJobSettings​()
        JobSettingsは、APIでサポートされるすべてのジョブ構成オプション(部数、丁合いオプション、両面オプションなど)をカプセル化します。初期値は、初期プリンタの現在の設定に基づいています。
        戻り値:
        現在のジョブ設定。

      • showPrintDialog

        public boolean showPrintDialog​(Window owner)
        印刷ダイアログを表示します。 ユーザーがプリンタや設定などのジョブ状態を更新できます。 これらの変更は、印刷ダイアログが戻った後、該当するプロパティで使用可能になります。 印刷ダイアログは一般に、ユーザーが印刷に進むことを確認する目的でも使用されます。 これはアプリケーションにとって義務ではありませんが、基本的には従ってください。

        使用可能なUIがない場合、このメソッドは、ユーザーが印刷に進むことを確認した場合と同様に、オプションを変更することなくtrueを返します。

        ジョブがダイアログを表示できる状態にない場合(すでに印刷中、取消し済、完了など)、ダイアログは表示されず、メソッドはfalseを返します。

        ウィンドウのownerはnullでもかまいませんが、表示されるウィンドウの場合は親として使用されます。

        このメソッドは、任意のスレッドから呼び出すことができます。 JavaFXアプリケーション・スレッドから呼び出された場合は、入力イベント・ハンドラから呼び出すか、Platform.runLaterに渡されたRunnableのrunメソッドから呼び出す必要があります。 アニメーションやレイアウトの処理中に呼び出されてはなりません。

        パラメータ:
        owner - 入力をブロックする対象、またはnull。
        戻り値:
        ユーザーが印刷の取消しを選択した場合、またはジョブが新規状態にない場合はfalse。 つまり、すでに開始されている場合、失敗した場合、取り消された場合、終了した場合です。
        例外:
        IllegalStateException - このメソッドがアニメーションまたはレイアウト処理中に呼び出された場合。

      • showPageSetupDialog

        public boolean showPageSetupDialog​(Window owner)
        ページ設定ダイアログを表示します。 ページ設定ダイアログは主に、エンド・ユーザーがページのレイアウトを構成できるようにするためのものです。 その中でも、用紙サイズと向きが最もよく使用される、最も重要な要素です。

        この目的に最も適した使用可能なダイアログが表示されます。 ただし、現在のプリンタの変更など、他の設定にアクセスすることも可能です。 したがって、このダイアログ表示メソッドの副次的作用として、それや他の現在のジョブ設定が更新されることがあります。 このメソッドは、変更を行われたかどうかに関係なく、ユーザーがダイアログを確定した場合にtrueを返します。

        ジョブがダイアログを表示できる状態にない場合(すでに印刷中、取消し済、完了など)、ダイアログは表示されず、メソッドはfalseを返します。

        ウィンドウのownerはnullでもかまいませんが、表示されるウィンドウの場合は親として使用されます。

        このメソッドは、任意のスレッドから呼び出すことができます。 FXアプリケーション・スレッドから呼び出された場合は、入力イベント・ハンドラから呼び出すか、Platform.runLaterに渡されたRunnableのrunメソッドから呼び出す必要があります。 アニメーションやレイアウトの処理中に呼び出されてはなりません。

        パラメータ:
        owner - 入力をブロックする対象、またはnull。
        戻り値:
        ユーザーがダイアログの取消しを選択した場合、またはジョブが新規状態にない場合はfalse。 つまり、すでに開始されている場合、失敗した場合、取り消された場合、終了した場合です。
        例外:
        IllegalStateException - このメソッドがアニメーションまたはレイアウト処理中に呼び出された場合。

      • printPage

        public boolean printPage​(PageLayout pageLayout,
                         Node node)
        指定されたページ・レイアウトを使用して、指定されたノードを印刷します。 ページ・レイアウトは、このページについてのみ、ジョブのデフォルトをオーバーライドします。 ジョブの状態がCANCELED、ERRORまたはDONEの場合、このメソッドはfalseを返します。

        このメソッドは、任意のスレッドから呼び出すことができます。 FXアプリケーション・スレッドから呼び出された場合は、入力イベント・ハンドラから呼び出すか、Platform.runLaterに渡されたRunnableのrunメソッドから呼び出す必要があります。 アニメーションやレイアウトの処理中に呼び出されてはなりません。

        パラメータ:
        pageLayout - このページのレイアウト。
        node - 印刷するノード。
        戻り値:
        レンダリングに成功したかどうか。
        例外:
        NullPointerException - いずれかのパラメータがnullの場合。
        IllegalStateException - このメソッドがアニメーションまたはレイアウト処理中に呼び出された場合。

      • printPage

        public boolean printPage​(Node node)
        指定されたノードを印刷します。 ページ・レイアウトはジョブのデフォルトです。 ジョブの状態がCANCELED、ERRORまたはDONEの場合、このメソッドはfalseを返します。
        パラメータ:
        node - 印刷するノード。
        戻り値:
        レンダリングに成功したかどうか。
        例外:
        NullPointerException - nodeパラメータがnullの場合。

      • getJobStatus

        public PrinterJob.JobStatus getJobStatus​()
        ジョブの現在のステータスを取得します。
        戻り値:
        現在のJobStatus

      • cancelJob

        public void cancelJob​()
        基礎となる印刷ジョブを速やかに取り消します。 FXユーザー・スレッドを一定期間ブロックすることのないように、ジョブの取消しが完了するまで待たずに、ただちに戻る場合もあります。 その時点で印刷が進行中の場合は、現在のページのレンダリング後に取り消されるのが一般的です。 ジョブのステータスは、それが完了して初めて、CANCELEDに更新されます。 そのため、ジョブがCANCELEDであることを判別するにはジョブのステータスを監視することが必要になります。

        ジョブのCANCELEDへの変更がすでにリクエストされている場合、またはジョブがERRORまたはDONE状態にある場合、呼出しは無効です。 たとえば、すでに印刷のためにスプールされているジョブはプリンタからデキューされません。 ジョブの取消し後は、新しいコンテンツをレンダリングしたり、ジョブ状態を変更したりするメソッドの呼出しは無効です。

      • endJob

        public boolean endJob​()
        ジョブをプリンタのキューに正常にスプールできる場合は、trueを返します。 注意: これは、実装可能であっても、ジョブがすでに印刷済であることを意味しません(印刷済の場合は数分以上待つことになります)。

        戻り値がfalseの場合、ジョブをスプールできなかったか、ジョブがすでに完了していたことを意味します。

        正常に完了した場合も、ジョブのステータスはDONEに更新され、その時点でそのジョブは使用できなくなります。

        ページが印刷されていないジョブに対してendJob()を呼び出すことは、{code cancelJob()}を呼び出すことと同等です。

        戻り値:
        ジョブがスプールされている場合はtrue、スプールされていない場合、またはジョブがすでに完了状態にあった場合はfalse。

      • toString

        public String toString​()
        次のクラスからコピーされた説明: Object
        オブジェクトの文字列表現を返します。 一般に、toStringメソッドは、このオブジェクトをテキストで表す文字列を返します。 この結果は、人間が読める簡潔で有益な情報であるべきです。 すべてのサブクラスで、このメソッドをオーバーライドすることをお勧めします。

        クラスObjectのtoStringメソッドは、オブジェクトがインスタンスになっている元のクラスの名前、アットマーク文字@、およびオブジェクトのハッシュ・コードの符号なし16進数表現から構成される文字列を返します。 つまり、このメソッドは次の値と等しい文字列を返します。 

         getClass().getName() + '@' + Integer.toHexString(hashCode())
        オーバーライド:
        toString 、クラス:  Object
        戻り値:
        このオブジェクトの文字列表現