Package docking.widgets

Class OptionDialogBuilder

  • public class OptionDialogBuilder
extends java.lang.Object
    Class for creating OptionDialogs using the builder pattern.

    At a minimum, an OptionDialog requires a title and a message. They can be specified in the constructor or set later.

    You can also, specify the messageType or an icon. The messageType is used to set the icon to one of several predefined ones appropriate for the message(ERROR, WARNING, etc.) You should not specify both, but if you do, the specified Icon will be used and the MessageType will be ignored.

    You can also add "options" which are custom buttons with the given text. Each option button is mapped to a different integer dialog result. The result values start at 1 for the first option and increment by 1 for each additional option. For example, if you add options "yes" and "no" in that order, then pressing the "yes" button will produce a dialog result of 1, and pressing the "no" button will produce a dialog result of 2. If no options are added, then an "OK" button will automatically be added.

    You can also set the default button by calling setDefaultButton(String) where the string is the text of the button (the option) that you want to be the default . For example, if you have the options "yes" and "no", you can make the "no" button the default by specifying "no" as the defaultOption.

    You can also add a Cancel button, which will return a result of 0 if pressed. Note that this is different than adding an option named "Cancel" which would return a result greater than 0, depending on where in the order it was added.

    A "Remember Option" can be added to OptionDialog to present the user with a choice for remembering a dialog result and automatically returning that result instead of showing the dialog or similar dialogs in the future. Note that for simple OK dialogs, there really isn't a meaningful result to remember, other than a decision was made not to show the dialog again.

    The "Remember Option" is represented as a checkBox at the bottom of an OptionDialog. The checkBox text will be either "Apply to all", "Remember my decision", or "Don't show again" depending on whether addApplyToAllOption(), addDontShowAgainOption(), or addRememberMyDecisionOption() method is called.

    If the user selects the checkBox, then the dialog result will be remembered. In future calls to display that dialog (or any dialog sharing the same DialogRememberChoice object), the dialog will first check if has a DialogRememberChoice object and that it has a remembered result, and if so, will just return the remembered result instead of showing the dialog.

    • Constructor Detail

      • OptionDialogBuilder

        public OptionDialogBuilder()
        Constructs an OptionDialogBuilder with not even the minimal information required. If this constructor is used, then both setTitle(String) and the setMessage(String) methods must be called or else the dialog will have no title or message.

      • OptionDialogBuilder

        public OptionDialogBuilder​(java.lang.String title)
        Constructs an OptionDialogBuilder with not even the minimal information required. If this constructor is used, then the setMessage(String) method must be called or else the dialog will be blank.
        Parameters:
        title - the title of the dialog

      • OptionDialogBuilder

        public OptionDialogBuilder​(java.lang.String title,
                           java.lang.String message)
        Constructs an OptionDialogBuilder with the minimal information required. If no other information is set, the builder will create the simplest dialog that has a title, message and an "Ok" button.
        Parameters:
        title - the title of the dialog.
        message - the main message to be displayed in the dialog.

    • Method Detail

      • setTitle

        public OptionDialogBuilder setTitle​(java.lang.String title)
        Sets the title for the OptionDialog.
        Parameters:
        title - the title for the dialog.
        Returns:
        this builder object.

      • setMessage

        public OptionDialogBuilder setMessage​(java.lang.String message)
        Sets the main message for the OptionDialog.
        Parameters:
        message - the main message for the dialog.
        Returns:
        this builder object.

      • setIcon

        public OptionDialogBuilder setIcon​(javax.swing.Icon icon)
        Sets the Icon for the OptionDialog.

        If both an Icon and a message type are specified, the icon will take precedence.

        Parameters:
        icon - the icon to display in the dialog.
        Returns:
        this builder object.

      • setMessageType

        public OptionDialogBuilder setMessageType​(int messageType)
        Sets the message type for the OptionDialog which will determine the icon that is in the dialog.
        Parameters:
        messageType - used to specify that this dialog is one of the set types. See OptionDialog for the list of defined messageTypes.
        Returns:
        this builder object.

      • addCancel

        public OptionDialogBuilder addCancel()
        Adds a cancel button to the OptionDialog.
        Returns:
        this builder object.

      • addOption

        public OptionDialogBuilder addOption​(java.lang.String optionName)
        Adds a button option to the dialog.
        Parameters:
        optionName - the name of the button to be added to the dialog
        Returns:
        this builder object.

      • setDefaultButton

        public OptionDialogBuilder setDefaultButton​(java.lang.String optionName)
        Sets the name of the button to be used as the default button.
        Parameters:
        optionName - the name of the option to be the default.
        Returns:
        this builder object.

      • addApplyToAllOption

        public OptionDialogBuilder addApplyToAllOption()
        Adds an "Apply to all" option to the dialog. See header documentation for details.

        This will replace any previously added "checkBox" options.

        Returns:
        this builder object.

      • addDontShowAgainOption

        public OptionDialogBuilder addDontShowAgainOption()
        Adds a "Don't show again" option to the dialog. See header documentation for details.

        This will replace any previously added "checkBox" options.

        Returns:
        this builder object.

      • addRememberMyDecisionOption

        public OptionDialogBuilder addRememberMyDecisionOption()
        Adds a "Remember my decision" option to the dialog. See header documentation for details.

        This will replace any previously added "checkBox" options.

        Returns:
        this builder object.

      • build

        public OptionDialog build()
        Builds an OptionDialog based on the values set in this builder.
        Returns:
        an OptionDialog built based on the values set in this builder.

      • show

        public int show()
        Builds and shows an OptionDialog based on the values set in this builder.
        Returns:
        the result returned from the OptionDialog after the user selected an option.

      • show

        public int show​(java.awt.Component parent)
        Builds and shows an OptionDialog based on the values set in this builder.
        Parameters:
        parent - the component to use as the OptionDialog's parent when displaying it.
        Returns:
        the result returned from the OptionDialog after the user selected an option.