モジュール javafx.controls
パッケージ javafx.scene.control

クラスDialog<R>

  • 型パラメータ:
    R - resultプロパティを介するダイアログの戻り値の型。
    すべての実装されたインタフェース:
    EventTarget
    直系の既知のサブクラス:
    Alert, ChoiceDialog, TextInputDialog
    public class Dialog<R>
extends Object
implements EventTarget
    JavaFXにおけるDialogはDialogPaneをラップし、それをエンド・ユーザーに表示するために必要なAPIを提供します。 JavaFX 8u40では、これはDialogPaneがStage内部のユーザーに表示されることを意味しますが、将来のリリースでは('lightweight'ダイアログや'internal'ダイアログなどの)別のオプションが提供される可能性があります。 したがって、このAPIは基礎となる実装を認識しないように設計されており、考えられるすべての実装で共通のAPIを表示しようとします。

    Dialogクラスには、resultプロパティの型(また、result converter Callbackを使用してButtonTypeからRへ変換する方法)を表すために使用される単一の汎用型Rがあります。

    重要な注意事項: Dialogクラスを拡張して独自のダイアログを作成するすべての開発者は、result converterプロパティの重要性を理解しておくことが重要です。 R型がVoidでもButtonTypeでもない場合は、必ずresult converterを設定する必要があります。 これを怠った開発者には、result converterを介してButtonTypeから変換できなかったことを示すClassCastExceptionsがコードで返されます。

    ほとんどの開発者にとっては、Alertクラス(事前定義された通知形式のアラート用)か、2つの事前作成済ダイアログ(TextInputDialogおよびChoiceDialog)のいずれかをニーズに応じて使用するほうが便利です。

    Dialogがインスタンス化されたら、次の手順はDialogを構成することです。 DialogのほとんどすべてのプロパティはDialogのコンテンツに関連していませんが、contentTextProperty()、headerTextProperty()およびgraphicProperty()プロパティは例外で、dialog paneプロパティに格納されたDialogPaneの個々のプロパティにAPIを転送するのみです。 この3つのプロパティは、開発者の便宜上、DialogPaneから転送されます。 ダイアログを構成しようとする開発者は、多くの場合、コードをdialog.getDialogPane().setExpandableContent(node)の行とともに使用する必要があります。

    これらのプロパティを構成した後は、(ButtonTypeおよびDialogPane.createButton(ButtonType)メソッドを使用して作成した)ボタンを完全に構成するかどうかを考慮するだけです。 ButtonTypeクラスを使用した場合、開発者が構成できる範囲は多くありません。 これは意図されたことですが、ButtonTypeで作成した指定のボタンを開発者が変更できないということではありません。 変更するには、開発者はDialogPane.lookupButton(ButtonType)メソッドをButtonTypeとともに呼び出すだけです(DialogPane.getButtonTypes()リストですでに設定されている場合)。 返されるNodeは通常はButton型ですが、DialogPane.createButton(ButtonType)メソッドがオーバーライドされているかどうかによって異なります。 したがって、通常のアプローチは次の行のようになります。 

    ButtonType loginButtonType = new ButtonType("Login", ButtonData.OK_DONE);
 Dialog<String> dialog = new Dialog<>();
 dialog.getDialogPane().getButtonTypes().add(loginButtonType);
 boolean disabled = false; // computed based on content of text fields, for example
 dialog.getDialogPane().lookupButton(loginButtonType).setDisable(disabled);

    Dialogがインスタンス化されて完全に構成されたら、次の手順はDialogを表示することです。 通常、アラートはモーダルなブロッキング形式で表示されます。 'モーダル'とは、ダイアログの表示中はユーザーが所有アプリケーションを操作できないことを意味し、'ブロッキング'とは、ダイアログが表示された時点でコード実行が停止されることを意味します。 つまり、ダイアログを表示し、ユーザー・レスポンスを待機してから、showコールの直後のコードから実行を続行できるため、開発者はダイアログからのユーザー入力にすぐに対応することができます(関連する場合)。

    JavaFXダイアログは、デフォルトでモーダルです(これは、initModality(javafx.stage.Modality) APIを使用して変更できます)。 ブロッキング・ダイアログまたは非ブロッキング・ダイアログを指定するには、開発者が(それぞれ) showAndWait()またはshow()を呼び出すことを選択します。 このような状況でのコーディングを容易にするために、ほとんどの開発者がデフォルトでshowAndWait()を選択する必要があります。 次の3つのコード・スニペットは、ダイアログを表示するための方法を示したもので、3つとも等しく有効です。

    オプション1: '従来型'のアプローチ 

    Optional<ButtonType> result = dialog.showAndWait();
 if (result.isPresent() && result.get() == ButtonType.OK) {
     formatSystem();
 }

    オプション2: 従来型+オプションのアプローチ 

    dialog.showAndWait().ifPresent(response -> {
     if (response == ButtonType.OK) {
         formatSystem();
     }
 });

    オプション3: 完全なラムダ式アプローチ 

    dialog.showAndWait()
      .filter(response -> response == ButtonType.OK)
      .ifPresent(response -> formatSystem());

    上の3つのオプションに優劣はないので、開発者は自分の好きなスタイルで作業できます。 上のオプションを示した目的は、開発者にOptional APIを紹介することにあります。これはJava 8で新しく導入されたものであり、多くの開発者には馴染みがないと思われます。

    ダイアログ検証/ボタン・アクションのインターセプト

    状況によっては、ダイアログの局面が内部的に整合する(たとえば、ダイアログ内のフォームのすべてのフィールドが有効な状態になる)までダイアログを閉じないようにする方が望ましいことがあります。 このためには、ダイアログAPIのユーザーがDialogPane.lookupButton(ButtonType)メソッドについてよく理解する必要があります。 (すでにbutton typesリスト内に設定されている)ButtonTypeを渡すことにより、通常はButton型であるNodeがユーザーに返されます(ただし、これはDialogPane.createButton(ButtonType)メソッドがオーバーライドされているかどうかによって異なります)。 このボタンを使用すると、ユーザーは、ボタンが通常のイベント処理を行う前に呼び出されるイベント・フィルタを追加して、イベントをconsumingすることによりイベント処理を回避できます。 簡単な例を次に示します。 

    final Button btOk = (Button) dlg.getDialogPane().lookupButton(ButtonType.OK);
 btOk.addEventFilter(ActionEvent.ACTION, event -> {
     if (!validateAndStore()) {
         event.consume();
     }
 });

    ダイアログを閉じるルール

    Dialogを閉じたときに行われる処理と、特に異常クローズの状況(ダイアログのタイトル・バーで'X'ボタンがクリックされた場合や、オペレーティング・システムに固有のキーボード・ショートカット(Windowsでの[Alt]+[F4]など)が入力された場合など)でDialogを閉じる方法を理解しておくことが重要です。 次の箇条書きでまとめるように、これらの状況における結果は明確に定義されています。

    • JavaFXダイアログを(前述の定義のとおり)'正常でない状況で'閉じることができるのは、次の2つの場合のみです。
      1. ダイアログにボタンが1つのみ含まれる場合、または
      2. ダイアログに複数のボタンが含まれる場合(そのうち1つが次の要件の1つを満たしていることが前提):
        1. ボタンにButtonTypeがあり、そのButtonBar.ButtonDataの型がButtonBar.ButtonData.CANCEL_CLOSEである。
        2. ボタンにButtonTypeがあり、ButtonBar.ButtonData.isCancelButton()が呼び出されるとそのButtonBar.ButtonDataがtrueを返す。
    • それ以外の場合、ダイアログはすべての閉じるリクエストへの応答を拒否し、ユーザーがダイアログのDialogPane領域内の使用可能なボタンのいずれかをクリックするまでは開いたままになります。
    • ダイアログが異常クローズし、かつダイアログに前述の2つのいずれかの条件を満たすボタンが含まれる場合、そのダイアログはresultプロパティを、最初に一致するButtonTypeを使用してresult converterを呼び出すことにより返された値に設定しようとします。
    • なんらかの理由によって結果コンバータがnullを返した場合、または取消以外のボタン1つのみが存在するときにダイアログが閉じられた場合、resultプロパティはnullになり、showAndWait()メソッドはOptional.empty()を返します。 この後者の意味は、(このクラス説明で前述したように)オプション2かオプション3のいずれかを使用する場合、Optional.ifPresent(java.util.function.Consumer)ラムダが呼び出されることはなく、ダイアログが何も値を返していない場合と同様にコードの実行が続行されるということです。
    導入されたバージョン:
    JavaFX 8u40
    関連項目:
    Alert、TextInputDialog、ChoiceDialog

    • コンストラクタの詳細

      • Dialog

        public Dialog()
        所有者を指定せずにダイアログを作成します。

    • メソッドの詳細

      • show

        public final void show()
        ダイアログを表示しますが、ユーザー・レスポンスを待機しません(つまり、非ブロッキング・ダイアログを開きます)。 このAPIのユーザーはresult propertyをポーリングするか、設定されたタイミングで通知を受けるリスナーをresult propertyに追加する必要があります。
        例外:
        IllegalStateException - このメソッドがJavaFXアプリケーション・スレッド以外のスレッドで呼び出された場合。

      • showAndWait

        public final Optional<R> showAndWait()
        ダイアログを表示し、ユーザー・レスポンスを待機します(つまり、ユーザーが入力した戻り値とともにブロッキング・ダイアログを開きます)。

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

        戻り値:
        resultを含むOptional。 詳細は、Dialogクラスの説明を参照してください。
        例外:
        IllegalStateException - このメソッドがJavaFXアプリケーション・スレッド以外のスレッドで呼び出された場合。
        IllegalStateException - このメソッドがアニメーションまたはレイアウト処理中に呼び出された場合。

      • close

        public final void close()
        このDialogを閉じます。 この呼び出しはhide()と同じです。

      • hide

        public final void hide()
        このDialogを非表示にします。

      • initModality

        public final void initModality​(Modality modality)
        このダイアログのモダリティを指定します。 これは、ダイアログを表示可能にする前に実行する必要があります。 モダリティは、Modality.NONE、Modality.WINDOW_MODALまたはModality.APPLICATION_MODALのいずれかになります。
        デフォルト値:
        Modality.APPLICATION_MODAL
        パラメータ:
        modality - このダイアログのモダリティ。
        例外:
        IllegalStateException - ダイアログが表示可能になった後にこのプロパティが設定された場合。

      • getModality

        public final Modality getModality()
        このダイアログのモダリティ属性を取得します。
        戻り値:
        モダリティ。

      • initStyle

        public final void initStyle​(StageStyle style)
        このダイアログのスタイルを指定します。 これは、ダイアログを表示可能にする前に実行する必要があります。 スタイルは、StageStyle.DECORATED、StageStyle.UNDECORATED、StageStyle.TRANSPARENT、StageStyle.UTILITYまたはStageStyle.UNIFIEDのいずれかになります。
        デフォルト値:
        StageStyle.DECORATED
        パラメータ:
        style - このダイアログのスタイル。
        例外:
        IllegalStateException - ダイアログが表示可能になった後にこのプロパティが設定された場合。

      • initOwner

        public final void initOwner​(Window window)
        このダイアログの所有者Windowを指定するか、または最上位で所有者のいないダイアログの場合はnullとなります。 これは、ダイアログを表示可能にする前に実行する必要があります。
        デフォルト値:
        null
        パラメータ:
        window - このダイアログの所有者Window。
        例外:
        IllegalStateException - ダイアログが表示可能になった後にこのプロパティが設定された場合。

      • getOwner

        public final Window getOwner()
        このダイアログの所有者Windowを取得するか、または所有者がいないダイアログの場合はnullとなります。
        戻り値:
        所有者Window。

      • dialogPaneProperty

        public final ObjectProperty<DialogPane> dialogPaneProperty()
        ダイアログのルート・ノード。DialogPaneには、このダイアログに表示されるすべての視覚的要素が含まれます。 そのため、既存のダイアログ・ペインを変更するか、新規作成するかして、ダイアログの表示を完全に調整することが可能です。
        関連項目:
        getDialogPane()、setDialogPane(DialogPane)

      • getDialogPane

        public final DialogPane getDialogPane()
        プロパティdialogPaneの値を取得します。
        プロパティの説明:
        ダイアログのルート・ノード。DialogPaneには、このダイアログに表示されるすべての視覚的要素が含まれます。 そのため、既存のダイアログ・ペインを変更するか、新規作成するかして、ダイアログの表示を完全に調整することが可能です。

      • setDialogPane

        public final void setDialogPane​(DialogPane value)
        プロパティdialogPaneの値を設定します。
        プロパティの説明:
        ダイアログのルート・ノード。DialogPaneには、このダイアログに表示されるすべての視覚的要素が含まれます。 そのため、既存のダイアログ・ペインを変更するか、新規作成するかして、ダイアログの表示を完全に調整することが可能です。

      • contentTextProperty

        public final StringProperty contentTextProperty()
        ダイアログ・ペインのコンテンツ・テキストを表すプロパティ。 コンテンツ・テキストの優先順位はcontent nodeよりも低いため、コンテンツ・ノードとcontentTextプロパティの両方が設定されている場合、デフォルトのDialogPaneインスタンスではコンテンツ・テキストは表示されません。
        関連項目:
        getContentText()、setContentText(String)

      • getContentText

        public final String getContentText()
        このDialogPaneに現在設定されているコンテンツ・テキストを返します。
        戻り値:
        このDialogPaneの現在設定されているコンテンツ・テキスト

      • setContentText

        public final void setContentText​(String contentText)
        ダイアログのコンテンツ領域に表示する文字列を設定します。 コンテンツ・テキストの優先順位はcontent nodeよりも低いため、コンテンツ・ノードとcontentTextプロパティの両方が設定されている場合、デフォルトのDialogPaneインスタンスではコンテンツ・テキストは表示されないことに注意してください。
        パラメータ:
        contentText - ダイアログ・コンテンツ領域に表示する文字列

      • headerTextProperty

        public final StringProperty headerTextProperty()
        ダイアログ・ペインのヘッダー・テキストを表すプロパティ。 ヘッダー・テキストの優先順位はheader nodeよりも低いため、ヘッダー・ノードとheaderTextプロパティの両方が設定されている場合、デフォルトのDialogPaneインスタンスではヘッダー・テキストは表示されません。
        関連項目:
        getHeaderText()、setHeaderText(String)

      • getHeaderText

        public final String getHeaderText()
        このDialogPaneに現在設定されているヘッダー・テキストを返します。
        戻り値:
        このDialogPaneの現在設定されているヘッダー・テキスト

      • setHeaderText

        public final void setHeaderText​(String headerText)
        ダイアログのヘッダー領域に表示する文字列を設定します。 ヘッダー・テキストの優先順位はheader nodeよりも低いため、ヘッダー・ノードとheaderTextプロパティの両方が設定されている場合、デフォルトのDialogPaneインスタンスではヘッダー・テキストは表示されないことに注意してください。
        パラメータ:
        headerText - ダイアログ・ヘッダー領域に表示する文字列

      • getGraphic

        public final Node getGraphic()
        プロパティgraphicの値を取得します。
        プロパティの説明:
        ヘッダー(ヘッダーが表示されている場合)またはcontentの左側に表示されるダイアログ・グラフィック。

      • setGraphic

        public final void setGraphic​(Node graphic)
        ヘッダー(ヘッダーが表示されている場合)またはcontentの左側に表示されるダイアログ・グラフィックを設定します。
        パラメータ:
        graphic - 新しいダイアログ・グラフィックか、グラフィックを表示しない場合はnull。

      • resultProperty

        public final ObjectProperty<R> resultProperty()
        ダイアログから返された内容を表すプロパティ。 結果は、ユーザーがクリックしたButtonTypeをR型の値に変換するresult converterを介して生成されます。 詳細は、DialogクラスのJavaDocを参照してください。
        関連項目:
        getResult()、setResult(R)

      • getResult

        public final R getResult()
        プロパティresultの値を取得します。
        プロパティの説明:
        ダイアログから返された内容を表すプロパティ。 結果は、ユーザーがクリックしたButtonTypeをR型の値に変換するresult converterを介して生成されます。 詳細は、DialogクラスのJavaDocを参照してください。

      • setResult

        public final void setResult​(R value)
        プロパティresultの値を設定します。
        プロパティの説明:
        ダイアログから返された内容を表すプロパティ。 結果は、ユーザーがクリックしたButtonTypeをR型の値に変換するresult converterを介して生成されます。 詳細は、DialogクラスのJavaDocを参照してください。

      • resultConverterProperty

        public final ObjectProperty<Callback<ButtonType,R>> resultConverterProperty()
        ユーザーがクリックしたButtonTypeを、resultプロパティを介して戻せる結果に変換するAPI。 これが必要なのは、ButtonTypeはダイアログ内のビジュアル・ボタンを表し、結果コンバータを使用して(ダイアログ実装の要件である)自身を有効な結果にマップする方法を認識しないためです。 Dialogサブクラスの結果型がButtonTypeであり、結果コンバータがnullになる可能性がある場合もあれば、結果型RがButtonTypeでもVoidでもなく、このコールバックを指定する必要がある場合もあります。
        関連項目:
        getResultConverter()、setResultConverter(Callback)

      • getResultConverter

        public final Callback<ButtonType,R> getResultConverter()
        プロパティresultConverterの値を取得します。
        プロパティの説明:
        ユーザーがクリックしたButtonTypeを、resultプロパティを介して戻せる結果に変換するAPI。 これが必要なのは、ButtonTypeはダイアログ内のビジュアル・ボタンを表し、結果コンバータを使用して(ダイアログ実装の要件である)自身を有効な結果にマップする方法を認識しないためです。 Dialogサブクラスの結果型がButtonTypeであり、結果コンバータがnullになる可能性がある場合もあれば、結果型RがButtonTypeでもVoidでもなく、このコールバックを指定する必要がある場合もあります。

      • setResultConverter

        public final void setResultConverter​(Callback<ButtonType,R> value)
        プロパティresultConverterの値を設定します。
        プロパティの説明:
        ユーザーがクリックしたButtonTypeを、resultプロパティを介して戻せる結果に変換するAPI。 これが必要なのは、ButtonTypeはダイアログ内のビジュアル・ボタンを表し、結果コンバータを使用して(ダイアログ実装の要件である)自身を有効な結果にマップする方法を認識しないためです。 Dialogサブクラスの結果型がButtonTypeであり、結果コンバータがnullになる可能性がある場合もあれば、結果型RがButtonTypeでもVoidでもなく、このコールバックを指定する必要がある場合もあります。

      • showingProperty

        public final ReadOnlyBooleanProperty showingProperty()
        ダイアログが現在表示されているかどうかを表します。
        関連項目:
        isShowing()

      • isShowing

        public final boolean isShowing()
        ダイアログが表示されているかどうかを返します。
        戻り値:
        ダイアログが表示されている場合はtrue。

      • isResizable

        public final boolean isResizable()
        ダイアログのサイズを変更できるかどうかを返します。
        戻り値:
        ダイアログのサイズ変更が可能な場合はtrue。

      • setResizable

        public final void setResizable​(boolean resizable)
        ユーザーがダイアログのサイズを変更できるかどうかを設定します。 サイズ変更が可能なダイアログは最大化することもできます(最大化ボタンが表示可能になります)
        パラメータ:
        resizable - ダイアログのサイズ変更を可能にする場合はtrue。

      • getWidth

        public final double getWidth()
        ダイアログの幅を返します。
        戻り値:
        ダイアログの幅

      • setWidth

        public final void setWidth​(double width)
        ダイアログの幅を設定します。
        パラメータ:
        width - ダイアログの幅

      • getHeight

        public final double getHeight()
        ダイアログの高さを返します。
        戻り値:
        ダイアログの高さ

      • setHeight

        public final void setHeight​(double height)
        ダイアログの高さを設定します。
        パラメータ:
        height - ダイアログの高さ

      • getTitle

        public final String getTitle()
        ダイアログのタイトルを返します。
        戻り値:
        ダイアログのタイトル

      • setTitle

        public final void setTitle​(String title)
        ダイアログのタイトルを変更します。
        パラメータ:
        title - ダイアログのタイトル

      • getX

        public final double getX()
        プロパティxの値を取得します。
        プロパティの説明:
        このDialogの水平位置。 この属性を変更すると、Dialogが水平方向に移動します。

      • setX

        public final void setX​(double x)
        プロパティxの値を設定します。
        プロパティの説明:
        このDialogの水平位置。 この属性を変更すると、Dialogが水平方向に移動します。

      • xProperty

        public final ReadOnlyDoubleProperty xProperty()
        このDialogの水平位置。 この属性を変更すると、Dialogが水平方向に移動します。
        関連項目:
        getX()、setX(double)

      • getY

        public final double getY()
        プロパティyの値を取得します。
        プロパティの説明:
        このDialogの垂直位置。 この属性を変更すると、Dialogが垂直方向に移動します。

      • setY

        public final void setY​(double y)
        プロパティyの値を設定します。
        プロパティの説明:
        このDialogの垂直位置。 この属性を変更すると、Dialogが垂直方向に移動します。

      • yProperty

        public final ReadOnlyDoubleProperty yProperty()
        このDialogの垂直位置。 この属性を変更すると、Dialogが垂直方向に移動します。
        関連項目:
        getY()、setY(double)

      • setOnShowing

        public final void setOnShowing​(EventHandler<DialogEvent> value)
        プロパティonShowingの値を設定します。
        プロパティの説明:
        Dialogが表示される直前に呼び出されます。

      • getOnShowing

        public final EventHandler<DialogEvent> getOnShowing()
        プロパティonShowingの値を取得します。
        プロパティの説明:
        Dialogが表示される直前に呼び出されます。

      • setOnShown

        public final void setOnShown​(EventHandler<DialogEvent> value)
        プロパティonShownの値を設定します。
        プロパティの説明:
        Dialogが表示された直後に呼び出されます。

      • getOnShown

        public final EventHandler<DialogEvent> getOnShown()
        プロパティonShownの値を取得します。
        プロパティの説明:
        Dialogが表示された直後に呼び出されます。

      • setOnHiding

        public final void setOnHiding​(EventHandler<DialogEvent> value)
        プロパティonHidingの値を設定します。
        プロパティの説明:
        Dialogが非表示になる直前に呼び出されます。

      • getOnHiding

        public final EventHandler<DialogEvent> getOnHiding()
        プロパティonHidingの値を取得します。
        プロパティの説明:
        Dialogが非表示になる直前に呼び出されます。

      • setOnHidden

        public final void setOnHidden​(EventHandler<DialogEvent> value)
        プロパティonHiddenの値を設定します。
        プロパティの説明:
        Dialogが非表示になった直後に呼び出されます。 Dialogが非表示の場合、このイベント・ハンドラが呼び出され、開発者はAlertが閉じられたときにリソースをクリーンアップしたり、その他のタスクを実行できます。

      • getOnHidden

        public final EventHandler<DialogEvent> getOnHidden()
        プロパティonHiddenの値を取得します。
        プロパティの説明:
        Dialogが非表示になった直後に呼び出されます。 Dialogが非表示の場合、このイベント・ハンドラが呼び出され、開発者はAlertが閉じられたときにリソースをクリーンアップしたり、その他のタスクを実行できます。

      • onHiddenProperty

        public final ObjectProperty<EventHandler<DialogEvent>> onHiddenProperty()
        Dialogが非表示になった直後に呼び出されます。 Dialogが非表示の場合、このイベント・ハンドラが呼び出され、開発者はAlertが閉じられたときにリソースをクリーンアップしたり、その他のタスクを実行できます。
        関連項目:
        getOnHidden()、setOnHidden(EventHandler)

      • setOnCloseRequest

        public final void setOnCloseRequest​(EventHandler<DialogEvent> value)
        プロパティonCloseRequestの値を設定します。
        プロパティの説明:
        このDialogを閉じる外部リクエストがあると呼び出されます。 インストールされたイベント・ハンドラは、受け取ったイベントを使用することで、ダイアログが閉じられることを回避できます。

      • getOnCloseRequest

        public final EventHandler<DialogEvent> getOnCloseRequest()
        プロパティonCloseRequestの値を取得します。
        プロパティの説明:
        このDialogを閉じる外部リクエストがあると呼び出されます。 インストールされたイベント・ハンドラは、受け取ったイベントを使用することで、ダイアログが閉じられることを回避できます。