Module  javafx.controls
软件包  javafx.scene.control

Class Dialog<R>

  • 参数类型
    R - 对话框的返回类型，通过 result属性。
    All Implemented Interfaces:
    EventTarget
    已知直接子类：
    Alert ， ChoiceDialog ， TextInputDialog 

    public class Dialog<R>
extends Object
implements EventTarget
    JavaFX中的Dialog包装了一个DialogPane，并提供了必要的API来将其呈现给最终用户。 在JavaFX 8u40中，这基本上意味着DialogPane向用户显示了一个Stage ，但将来的版本可能会提供其他选项（如“轻量级”或“内部”对话框）。 因此，此API故意无知底层实现，并尝试为所有可能的实现呈现一个通用API。

    Dialog类有一个通用类型R，用于表示result属性的类型（以及如何通过使用result converter Callback从ButtonType转换为R）。

    重要注意事项：通过扩展Dialog类了解result converter属性的重要性，所有选择创建自己对话框的开发人员至关重要。 每当R型不是Void或ButtonType时，必须始终设置结果转换器。 如果不加注意，开发者会发现，他们得到的ClassCastExceptions在他们的代码，未能从转换ButtonType通过result converter 。

    大多数开发人员可能会使用Alert类（用于预定义的通知类型的警报）或两个预构建的对话框（ TextInputDialog和ChoiceDialog ）中的任何一个，取决于他们的需要。

    一旦对话框被实例化，下一步是配置它。 几乎在所有对话属性不相关的对话框的内容，唯一的例外是contentTextProperty() ， headerTextProperty() ，并graphicProperty() ，这些性质简单地转发到API的各种特性DialogPane存储在dialog pane财产。 这三个属性从DialogPane转发，以便开发人员方便。 对于想要配置对话框的开发人员，在许多情况下，需要使用符合dialog.getDialogPane().setExpandableContent(node)代码。

    配置这些属性后，所有这些属性都是考虑是否完全配置按钮（使用ButtonType和DialogPane.createButton(ButtonType)创建）。 开发人员将很快发现通过ButtonType类提供的可配置性的数量很少。 这是有意的，但并不意味着开发人员不能修改由指定的ButtonType创建的按钮。 为此，开发人员只需使用ButtonType调用DialogPane.lookupButton(ButtonType)方法（假设它已经在DialogPane.getButtonTypes()列表中设置），返回的节点通常是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);

    一旦对话框被实例化和完全配置，下一步就是显示它。 通常情况下，对话框以模态和阻止的方式显示。 'Modal'意味着该对话框可以防止用户在显示时与所拥有的应用程序进行交互，而'blocking'意味着代码执行在显示对话框的时候停止。 这意味着您可以显示一个对话框，等待用户响应，然后继续运行直接在show调用之后的代码，使开发人员能够立即处理来自对话框的用户输入（如果相关）。

    默认情况下，JavaFX对话框是模态的（您可以通过initModality(javafx.stage.Modality) API更改此对话框 ）。 要指定是否要阻止或不阻止对话框，开发人员只需选择分别调用showAndWait()或show() 。 默认情况下，大多数开发人员应该选择使用showAndWait() ，因为在这些情况下易于编码。 下面显示了三个代码片段，显示了三个显示对话框的同样有效的方法：

    选项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：完全lambda方法 

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

    上面列出的三个选项没有更好或更差的选择，所以鼓励开发人员自己设计风格偏好。 显示上述内容的目的是帮助开发人员将其引入到Optional API中，这是Java 8中的新增功能，可能对许多开发人员来说是外来的。

    对话验证/拦截按钮操作

    在某些情况下，希望防止对话框关闭，直到对话框的某些方面变得内部一致（例如，对话框内的表单具有有效状态的所有字段）。 为此，对话框API的用户应该熟悉DialogPane.lookupButton(ButtonType)方法。 通过传递ButtonType （已经在button types列表中设置），用户将返回一个通常为Button类型的节点 （但这取决于DialogPane.createButton(ButtonType)方法是否被覆盖）。 使用此按钮，用户可以添加在按钮执行其常规事件处理之前调用的事件过滤器，因此用户可以防止事件处理consuming 。 这是一个简化的例子： 

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

    对话框关闭规则

    重要的是要了解当对话框关闭时会发生什么，以及如何关闭对话框，特别是在异常关闭情况下（例如在对话框标题栏中单击“X”按钮时，或操作系统特定键盘时）输入快捷键（如Windows上的alt-F4）。 幸运的是，在这些情况下，结果是明确的，可以在以下几个方面进行总结：

    从以下版本开始：
    JavaFX 8u40
    另请参见：
    Alert ， TextInputDialog ， ChoiceDialog

    • 构造方法详细信息

      • Dialog

        public Dialog​()
        创建一个没有指定所有者的对话框。

    • 方法详细信息

      • show

        public final void show​()
        显示对话框，但不等待用户响应（换句话说，这会打开一个非阻塞对话框）。 该API的用户必须轮询result property ，否则将添加一个监听器到结果属性，以便被通知何时被设置。
        异常
        IllegalStateException - 如果在除JavaFX应用程序线程之外的线程上调用此方法。

      • showAndWait

        public final Optional<R> showAndWait​()
        显示对话框并等待用户响应（换句话说，显示阻止对话框，用户输入的返回值）。

        必须在JavaFX应用程序线程上调用此方法。 另外，它必须从输入事件处理程序或从Runnable的run方法调用传递给Platform.runLater 。 在动画或布局处理过程中不得调用它。

        结果
        一个Optional ，其中包含result 。 有关详细信息，请参阅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。
        Default value:
        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。
        Default value:
        StageStyle.DECORATED
        参数
        style - 此对话框的样式。
        异常
        IllegalStateException - 如果在对话框显示之后设置了此属性。

      • initOwner

        public final void initOwner​(Window window)
        指定此对话框的所有者Window ，或者为顶级的未知对话框指定null。 这必须在使对话框可见之前完成。
        Default value:
        空值
        参数
        window - 该对话框的所有者Window 。
        异常
        IllegalStateException - 如果在对话框显示之后设置了此属性。

      • getOwner

        public final Window getOwner​()
        检索该对话框的所有者窗口，或者取消未知对话框的null。
        结果
        所有者窗口。

      • getDialogPane

        public final DialogPane getDialogPane​()
        获取属性dialogPane的值。
        Property description:
        对话框的根节点 ， DialogPane包含对话框中显示的所有可视元素。 因此，可以通过修改现有的对话窗格或创建新的对话框来完全调整对话框的显示。

      • setDialogPane

        public final void setDialogPane​(DialogPane value)
        设置属性dialogPane的值。
        Property description:
        对话框的根节点 ， 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​()
        获取属性图形的值。
        Property description:
        对话图形，在标题中显示，如果显示，或 content的左侧。

      • setGraphic

        public final void setGraphic​(Node graphic)
        设置对话框图形，将显示在标题中，如果显示，或 content的左侧。
        参数
        graphic - 新的对话框图形，如果不显示图形，则为null。

      • getResult

        public final R getResult​()
        获取属性结果的值。
        Property description:
        表示从对话框返回的属性的属性。 结果是通过result converter生成的，其目的是从用户点击的ButtonType转换为类型R的值。有关更多详细信息，请参阅Dialog类JavaDoc。

      • setResult

        public final void setResult​(R value)
        设置属性结果的值。
        Property description:
        表示从对话框返回的属性的属性。 结果是通过result converter生成的，其目的是将用户点击的ButtonType转换为R类型的值。有关更多详细信息，请参阅Dialog JavaDoc类。

      • resultConverterProperty

        public final ObjectProperty<Callback<ButtonType,R>> resultConverterProperty​()
        API将用户点击的ButtonType转换为可通过result属性返回的结果。 这是必需的，因为ButtonType表示对话框中的可视化按钮，并且不知道如何将自己映射到有效的结果 - 这是通过使用结果转换器来执行对话框的要求。 在某些情况下，Dialog子类的结果类型是ButtonType（这意味着结果转换器可以为null），但在某些情况下（结果类型为R，不是ButtonType或Void），则必须指定此回调。
        另请参见：
        getResultConverter() ， setResultConverter(Callback)

      • getResultConverter

        public final Callback<ButtonType,R> getResultConverter​()
        获取属性resultConverter的值。
        Property description:
        API将用户点击的ButtonType转换为可以通过result属性返回的结果。 这是必要的，因为ButtonType表示对话框中的可视化按钮，并且不知道如何将自己映射到有效的结果 - 这是通过使用结果转换器来执行对话框的要求。 在某些情况下，Dialog子类的结果类型是ButtonType（这意味着结果转换器可以为null），但在某些情况下（结果类型为R，不是ButtonType或Void），则必须指定此回调。

      • setResultConverter

        public final void setResultConverter​(Callback<ButtonType,R> value)
        设置属性resultConverter的值。
        Property description:
        API将用户点击的ButtonType转换为可通过result属性返回的结果。 这是必要的，因为ButtonType表示对话框中的可视化按钮，并且不知道如何将自己映射到有效的结果 - 这是通过使用结果转换器来执行对话框的要求。 在某些情况下，Dialog子类的结果类型是ButtonType（这意味着结果转换器可以为null），但在某些情况下（结果类型为R，不是ButtonType或Void），则必须指定此回调。

      • isShowing

        public final boolean isShowing​()
        返回对话框是否显示。
        结果
        如果显示对话框，则为true。

      • isResizable

        public final boolean isResizable​()
        返回对话框是否可调整大小。
        结果
        如果对话框可调整大小，则为true

      • setResizable

        public final void setResizable​(boolean resizable)
        设置对话框是否可以由用户调整大小。 可调整大小的对话框也可以最大化（最大化按钮变得可见）
        参数
        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的值。
        Property description:
        这个Dialog的水平位置。 更改此属性将水平移动Dialog 。

      • setX

        public final void setX​(double x)
        设置属性x的值。
        Property description:
        这个水平位置这个Dialog 。 更改此属性将水平移动Dialog 。

      • getY

        public final double getY​()
        获取属性y的值。
        Property description:
        这个Dialog的垂直位置。 更改此属性将垂直移动Dialog 。

      • setY

        public final void setY​(double y)
        设置属性y的值。
        Property description:
        这个Dialog的垂直位置。 更改此属性将垂直移动Dialog 。

      • buildEventDispatchChain

        public EventDispatchChain buildEventDispatchChain​(EventDispatchChain tail)
        为此目标构建事件调度链。 事件调度链包含可能对处理针对EventTarget的事件感兴趣的事件调度EventTarget 。 此事件目标不会自动添加到链中，因此如果要处理事件，则需要为链接添加一个EventDispatcher 。

        在事件目标是某些层次结构的一部分的情况下，它的链通常是从从层次结构的根被收集到事件目标的事件分派器构建的。

        事件调度链是通过修改提供的初始事件调度链来构建的。 返回的链应该在其末端具有初始链，所以调度员应该放在初始链上。

        调用者不应该假定初始链条保持不变，也不会返回值引用不同的链。

        Specified by:
        buildEventDispatchChain在接口 EventTarget
        参数
        tail - 建立起来的初始链
        结果
        此目标的结果事件调度链

      • setOnShowing

        public final void setOnShowing​(EventHandler<DialogEvent> value)
        设置属性onShowing的值。
        Property description:
        在对话框显示之前调用。

      • getOnShowing

        public final EventHandler<DialogEvent> getOnShowing​()
        获取属性onShowing的值。
        Property description:
        在对话框显示之前调用。

      • setOnShown

        public final void setOnShown​(EventHandler<DialogEvent> value)
        设置属性onShown的值。
        Property description:
        在对话框显示之后调用。

      • getOnShown

        public final EventHandler<DialogEvent> getOnShown​()
        获取onShown属性的值。
        Property description:
        在对话框显示之后调用。

      • setOnHiding

        public final void setOnHiding​(EventHandler<DialogEvent> value)
        设置属性onHiding的值。
        Property description:
        在对话框被隐藏之前调用。

      • getOnHiding

        public final EventHandler<DialogEvent> getOnHiding​()
        获取属性onHiding的值。
        Property description:
        在对话框被隐藏之前调用。

      • setOnHidden

        public final void setOnHidden​(EventHandler<DialogEvent> value)
        设置属性onHidden的值。
        Property description:
        Dialog已被隐藏之后调用。 当隐藏Dialog ，将调用此事件处理程序，以允许开发人员在Alert关闭时清理资源或执行其他任务。

      • getOnHidden

        public final EventHandler<DialogEvent> getOnHidden​()
        获取属性onHidden的值。
        Property description:
        Dialog已被隐藏之后调用。 当隐藏Dialog ，调用此事件处理程序，允许开发人员在Alert关闭时清理资源或执行其他任务。

      • setOnCloseRequest

        public final void setOnCloseRequest​(EventHandler<DialogEvent> value)
        设置属性onCloseRequest的值。
        Property description:
        当有外部请求关闭此Dialog 。 安装的事件处理程序可以通过消耗接收的事件来阻止对话关闭。

      • getOnCloseRequest

        public final EventHandler<DialogEvent> getOnCloseRequest​()
        获取属性onCloseRequest的值。
        Property description:
        当有外部请求关闭此Dialog 。 安装的事件处理程序可以通过消耗接收的事件来阻止对话关闭。