Dialogs

Edit pageLast modified: 27 November 2024

UI Guidelines: Layout, Validation Errors

DialogWrapper

The DialogWrapper is the base class which is supposed to be used for all modal dialogs (and some non-modal dialogs) shown in IntelliJ Platform.

It provides the following features:

  • Button layout (platform-specific order of OK/Cancel buttons, macOS-specific Help button)

  • Context help

  • Remembering the size of the dialog

  • Non-modal validation (displaying an error message text when the data entered into the dialog is not valid)

  • Keyboard shortcuts:

    • Esc for closing the dialog

    • Left/Right for switching between buttons

    • Y/N for Yes/No actions if they exist in the dialog

  • Optional Do not ask again checkbox

tip

There's also a DSL-like API via DialogBuilder.

Usage

When using the DialogWrapper class for a dialog, follow these required steps:

  • Call the base class constructor and provide either a Project in the frame of which the dialog will be displayed, or a parent component for the dialog.

  • Call the setTitle() method to set the title for the dialog

  • Call the init() method from the constructor of the dialog class

  • Implement the createCenterPanel() method to return the component comprising the main contents of the dialog.

Optionally:

  • Override the getPreferredFocusedComponent() method and return the component that should be focused when the dialog is first displayed.

  • Override the getDimensionServiceKey() method to return the identifier which will be used for persisting the dialog dimensions.

  • Override the getHelpId() method to return the context help topic associated with the dialog (see Context Help).

Dialog Content

Use Kotlin UI DSL to provide the dialog's contents (see samples). Alternatively or when using Java, the DialogWrapper class can be used together with GUI Designer forms. In this case, bind a GUI Designer form to the class extending DialogWrapper, bind the top-level panel of the form to a field and return that field from the createCenterPanel() method.

tip

See Layout topic in UI Guidelines for recommendations on arranging UI controls in dialogs.

Existing dialogs can be inspected at runtime using UI Inspector, for example, to locate the underlying implementation of UI components.

Displaying the Dialog

To display the dialog, call the show() method and then use the getExitCode() method to check how the dialog was closed (see DialogWrapper#OK_EXIT_CODE, CANCEL_EXIT_CODE, CLOSE_EXIT_CODE). The showAndGet() method can be used to combine these two calls.

Customizing Buttons

To customize the buttons displayed in the dialog (replacing the standard OK/Cancel/Help set of buttons), override either the createActions() or createLeftActions() methods. Both of these methods return an array of Swing Action objects. If a button closes the dialog, use DialogWrapperExitAction as the base class for the action.

Use action.putValue(DialogWrapper.DEFAULT_ACTION, true) to set the default button and action.putValue(DialogWrapper.FOCUSED_ACTION, true) to set the focused button.

Input Validation

See also Validation Errors topic in UI Guidelines.

To validate the data entered into the dialog, override the doValidate() method. The method will be called automatically by timer. If the currently entered data is valid, return null. Otherwise, return a ValidationInfo object which encapsulates an error message, and an optional component associated with the invalid data. When specifying a component, an error icon will be displayed next to it, and it will be focused when the user tries to invoke the OK action.

Examples

Minimum sample of a DialogWrapper:

public class SampleDialogWrapper extends DialogWrapper {

  public SampleDialogWrapper() {
    super(true); // use current window as parent
    setTitle("Test DialogWrapper");
    init();
  }

  @Nullable
  @Override
  protected JComponent createCenterPanel() {
    JPanel dialogPanel = new JPanel(new BorderLayout());

    JLabel label = new JLabel("Testing");
    label.setPreferredSize(new Dimension(100, 100));
    dialogPanel.add(label, BorderLayout.CENTER);

    return dialogPanel;
  }
}

Show SampleDialogWrapper dialog when user clicks on button:

JButton testButton = new JButton();
testButton.addActionListener(actionEvent -> {
  if (new SampleDialogWrapper().showAndGet()) {
    // user pressed OK
  }
});

Kotlin

Dialogs using Kotlin UI DSL: