# Dialogs

> For the complete documentation index, see [llms.txt](https://plugins.jetbrains.com/docs/intellij/llms.txt).

> **TL;DR**
> UI Guidelines: [Layout](layout.html), [Validation Errors](validation-errors.html)

##  `DialogWrapper` 

The [DialogWrapper](https://github.com/JetBrains/intellij-community/tree/idea/262.10968.63/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) is the base class 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](https://github.com/JetBrains/intellij-community/tree/idea/262.10968.63/platform/platform-api/src/com/intellij/openapi/ui/DialogBuilder.java).

### Usage

When using the [DialogWrapper](https://github.com/JetBrains/intellij-community/tree/idea/262.10968.63/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) 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](ide-infrastructure.html#context-help)).

#### Dialog Content

Use [Kotlin UI DSL](kotlin-ui-dsl-version-2.html) to provide the dialog's contents (see [samples](#kotlin)). Alternatively or when using Java, the `DialogWrapper` class can be used together with [GUI Designer forms](https://www.jetbrains.com/help/idea/gui-designer-basics.html). 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 the [Layout](layout.html) topic in UI Guidelines for recommendations on arranging UI controls in dialogs.
>
>
>
> Existing dialogs can be inspected at runtime using [UI Inspector](internal-ui-inspector.html), for example, to locate the underlying implementation of UI components.

#### Displaying the Dialog

To display the dialog, call the `show()` method.

To get the exit code of a modal dialog, 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.

To execute some code after a non-modal dialog is closed, override the `doOKAction()`, `doCancelAction()`, or register a [disposable](disposers.html), for example:

```JAVA
Disposer.register(dialog.getDisposable(), () -> action());
```

#### 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](https://github.com/JetBrains/intellij-community/tree/idea/262.10968.63/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) 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](validation-errors.html) topic in UI Guidelines.

To validate the data entered into the dialog, call `initValidation()` in the dialog's constructor and override the `doValidate()` method to perform the actual validation. The method will be called automatically via a timer.

If the currently entered data is valid, return `null`. Otherwise, return a [ValidationInfo](https://github.com/JetBrains/intellij-community/tree/idea/262.10968.63/platform/ide-core/src/com/intellij/openapi/ui/ValidationInfo.java) 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](https://github.com/JetBrains/intellij-community/tree/idea/262.10968.63/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java):

```JAVA
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 the `SampleDialogWrapper` dialog when a user clicks a button:

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

### Kotlin

Dialogs using [Kotlin UI DSL](kotlin-ui-dsl-version-2.html):

* [AddActionDialog](https://github.com/JetBrains/intellij-community/tree/idea/262.10968.63/platform/platform-impl/src/com/intellij/ide/ui/customization/AddActionDialog.kt)

* [InvalidateCachesDialog](https://github.com/JetBrains/intellij-community/tree/idea/262.10968.63/platform/platform-impl/src/com/intellij/ide/actions/InvalidateCachesDialog.kt)