Package swingtree.dialogs

Class OptionsDialog<E extends Enum<E>>

java.lang.Object
swingtree.dialogs.OptionsDialog<E>
public final class OptionsDialog<E extends Enum<E>> extends Object
An immutable builder class for creating simple enum based option dialogs where the user can select one of the enum options.

This class is intended to be used as part of the UI API by calling the UIFactoryMethods.choice(String, Enum[]) or UIFactoryMethods.choice(String, Var) factory methods.

Here a simple usage example: 


      // In your view model:
      public enum MyOptions { YES, NO, CANCEL }
      private final Var<MyOptions> selectedOption = Var.of(MyOptions.YES);
      // In your view:
      UI.choice("Select an option:", vm.selectedOption())
      .parent(this)
      .showAsQuestion( o -> switch(o) {
          case YES    -> "Yes, please!";
          case NO     -> "No, thank you!";
          case CANCEL -> "Cancel";
      });
In this example, the user will be presented with a dialog containing the message "Select an option:" and the enum options "YES", "NO" and "CANCEL" presented as "Yes, please!", "No, thank you!" and "Cancel" respectively. The dialog will know the available options from the Var instance "selectedOption".

Note that this API translates to the JOptionPane.showOptionDialog(Component, Object, String, int, int, Icon, Object[], Object) method.

  • Method Details

    • offering

      public static <E extends Enum<E>> OptionsDialog<E> offering(String message, E... options)
      Creates a new OptionsDialog instance with the specified message and options.
      Type Parameters:
      E - The type of the Enum options.
      Parameters:
      message - The message of the dialog presenting various options to the user.
      options - The Enum options that the user can select from.
      Returns:
      A new OptionsDialog instance with the specified message and options.

    • offering

      public static <E extends Enum<E>> OptionsDialog<E> offering(String message, sprouts.Var<E> property)
      Creates a new OptionsDialog instance with the specified message and enum property from which the options, default option and selected option will be derived.
      Type Parameters:
      E - The type of the Enum options.
      Parameters:
      message - The message of the dialog presenting various options to the user.
      property - The property to which the selected option will be assigned.
      Returns:
      A new OptionsDialog instance with the specified message and options.

    • titled

      public OptionsDialog<E> titled(String title)
      Creates an updated options dialog config with the specified title which will used as the window title of the dialog when it is shown to the user.
      Parameters:
      title - The title of the dialog.
      Returns:
      A new OptionsDialog instance with the specified title.

    • defaultOption

      public OptionsDialog<E> defaultOption(E defaultOption)
      Creates an updated options dialog config with the specified default option, which will be the option with the initial focus when the dialog is shown. If the user presses the enter key, this option will be selected automatically.
      Parameters:
      defaultOption - The default option of the dialog. This option will be selected by default.
      Returns:
      A new OptionsDialog instance with the specified default option.

    • icon

      public OptionsDialog<E> icon(IconDeclaration icon)
      Allows you to specify an icon declaration for an icon that will be displayed in the dialog window. An icon declaration is a constant that simply holds the location of the icon resource. This is the preferred way to specify an icon for the dialog.
      Parameters:
      icon - The icon declaration for an icon that will be displayed in the dialog window.
      Returns:
      A new OptionsDialog instance with the specified icon.

    • icon

      public OptionsDialog<E> icon(Icon icon)
      Creates an updated options dialog config with the specified icon, which will be displayed in the dialog window. Consider using the icon(IconDeclaration) method instead, as it is the preferred way to specify an icon for the dialog.
      Parameters:
      icon - The icon of the dialog.
      Returns:
      A new OptionsDialog instance with the specified icon.

    • icon

      public OptionsDialog<E> icon(String path)
      Creates an updated options dialog config with the specified icon path leading to the icon that will be displayed in the dialog window. The icon will be loaded using the UIFactoryMethods.findIcon(String) method. But consider using the icon(IconDeclaration) method instead of this, as it is the preferred way to specify an icon for the dialog.
      Parameters:
      path - The path to the icon of the dialog.
      Returns:
      A new OptionsDialog instance with the specified icon.

    • parent

      public OptionsDialog<E> parent(Component parent)
      You may specify a reference to a parent component for the dialog, which will be used to center the dialog on the parent component. See JOptionPane.showOptionDialog(Component, Object, String, int, int, Icon, Object[], Object) for more information.
      Parameters:
      parent - The parent component of the dialog.
      Returns:
      A new OptionsDialog instance with the specified parent component.

    • showAsQuestion

      public Optional<E> showAsQuestion()
      Shows the options dialog as a question dialog (see JOptionPane.QUESTION_MESSAGE) and returns the Enum answer that the user selected from the existing options. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • showAsQuestion

      public Optional<E> showAsQuestion(Function<E,String> presenter)
      Shows the options dialog as a question dialog (see JOptionPane.QUESTION_MESSAGE) and returns the Enum answer that the user selected from the existing options. The presenter function is used to convert the enum options to strings that will be displayed in the dialog for the user to select from.
      This is useful when your enum constant naming adheres to a specific naming convention, like capitalized snake case, and you want to present the options in a more user-centric format. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • showAsError

      public Optional<E> showAsError()
      Shows the options dialog as an error dialog (see JOptionPane.ERROR_MESSAGE) and returns the Enum answer that the user selected from the existing options. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • showAsError

      public Optional<E> showAsError(Function<E,String> presenter)
      Shows the options dialog as an error dialog (see JOptionPane.ERROR_MESSAGE) and returns the Enum answer that the user selected from the existing options. The presenter function is used to convert the enum options to strings that will be displayed in the dialog for the user to select from.
      This is useful when your enum constant naming adheres to a specific naming convention, like capitalized snake case, and you want to present the options in a more user-centric format. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • showAsWarning

      public Optional<E> showAsWarning()
      Shows the options dialog as a warning dialog (see JOptionPane.WARNING_MESSAGE) and returns the Enum answer that the user selected from the existing options. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • showAsWarning

      public Optional<E> showAsWarning(Function<E,String> presenter)
      Shows the options dialog as a warning dialog (see JOptionPane.WARNING_MESSAGE) and returns the Enum answer that the user selected from the existing options. The presenter function is used to convert the enum options to strings that will be displayed in the dialog for the user to select from.
      This is useful when your enum constant naming adheres to a specific naming convention, like capitalized snake case, and you want to present the options in a more user-centric format. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • showAsInfo

      public Optional<E> showAsInfo()
      Shows the options dialog as an information dialog (see JOptionPane.INFORMATION_MESSAGE) and returns the Enum answer that the user selected from the existing options. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • showAsInfo

      public Optional<E> showAsInfo(Function<E,String> presenter)
      Shows the options dialog as an information dialog (see JOptionPane.INFORMATION_MESSAGE) and returns the Enum answer that the user selected from the existing options. The presenter function is used to convert the enum options to strings that will be displayed in the dialog for the user to select from.
      This is useful when your enum constant naming adheres to a specific naming convention, like capitalized snake case, and you want to present the options in a more user-centric format. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • showAsPlain

      public Optional<E> showAsPlain()
      Shows the options dialog as a plain dialog (see JOptionPane.PLAIN_MESSAGE) and returns the Enum answer that the user selected from the existing options. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • showAsPlain

      public Optional<E> showAsPlain(Function<E,String> presenter)
      Shows the options dialog as a plain dialog (see JOptionPane.PLAIN_MESSAGE) and returns the Enum answer that the user selected from the existing options. The presenter function is used to convert the enum options to strings that will be displayed in the dialog for the user to select from.
      This is useful when your enum constant naming adheres to a specific naming convention, like capitalized snake case, and you want to present the options in a more user-centric format. Note that this method is blocking and will only return when the user has selected an option in the dialog.
      Returns:
      The Enum instance that the user selected in the dialog.

    • show

      public Optional<E> show()
      Calling this method causes the dialog to be shown to the user. The method is blocking and will only return when the user has selected an option or closed the dialog. If the dialog is closed, the method will return an empty Optional, otherwise it will return the Enum that the user selected.
      Returns:
      The Enum that the user selected in the dialog wrapped in an Optional or an empty Optional if the user closed the dialog.

    • show

      public Optional<E> show(Function<E,String> presenter)
      Calling this method causes the dialog to be shown to the user. The method is blocking and will only return when the user has selected an option or closed the dialog. If the dialog is closed, the method will return an empty Optional, otherwise it will return the Enum that the user selected. The presenter function is used to convert the enum options to strings that will be displayed in the dialog for the user to select from.
      This is useful when your enum constant naming adheres to a specific naming convention, like capitalized snake case, and you want to present the options in a more user-centric format.
      Returns:
      The Enum that the user selected in the dialog wrapped in an Optional or an empty Optional if the user closed the dialog.