Package docking.widgets

# Class OptionDialogBuilder

java.lang.Object
docking.widgets.OptionDialogBuilder

public class OptionDialogBuilder extends 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. Each of these methods called will overwrite the previously called method.

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 Summary

  Constructors
  Constructor
  Description
  `OptionDialogBuilder()`
  Constructs an OptionDialogBuilder with not even the minimal information required.
  `OptionDialogBuilder(String title)`
  Constructs an OptionDialogBuilder with not even the minimal information required.
  `OptionDialogBuilder(String title, String message)`
  Constructs an OptionDialogBuilder with the minimal information required.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `OptionDialogBuilder`
  `addApplyToAllOption()`
  Adds an "Apply to all" option to the dialog.
  `OptionDialogBuilder`
  `addCancel()`
  Adds a cancel button to the OptionDialog.
  `OptionDialogBuilder`
  `addDontShowAgainOption()`
  Adds a "Don't show again" option to the dialog.
  `OptionDialogBuilder`
  `addOption(String optionName)`
  Adds a button option to the dialog.
  `OptionDialogBuilder`
  `addRememberMyDecisionOption()`
  Adds a "Remember my decision" option to the dialog.
  `OptionDialog`
  `build()`
  Builds an OptionDialog based on the values set in this builder.
  `OptionDialogBuilder`
  `setDefaultButton(String optionName)`
  Sets the name of the button to be used as the default button.
  `OptionDialogBuilder`
  `setIcon(Icon icon)`
  Sets the Icon for the OptionDialog.
  `OptionDialogBuilder`
  `setMessage(String message)`
  Sets the main message for the OptionDialog.
  `OptionDialogBuilder`
  `setMessageType(int messageType)`
  Sets the message type for the OptionDialog which will determine the icon that is in the dialog.
  `OptionDialogBuilder`
  `setTitle(String title)`
  Sets the title for the OptionDialog.
  `int`
  `show()`
  Builds and shows an OptionDialog based on the values set in this builder.
  `int`
  `show(Component parent)`
  Builds and shows an OptionDialog based on the values set in this builder.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### 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(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(String title, 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 Details

  - ### setTitle

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

  - ### setMessage

    public OptionDialogBuilder setMessage(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(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(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(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(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.