hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-29 17:57:53 +08:00
Code Issues Packages Projects Releases Wiki Activity

dialog_wrapper.md: formatting, updates

Browse Source
This commit is contained in:
Yann Cébron 2020-07-13 15:10:59 +02:00
parent 30f9e4eadb
commit 67bc7f19eb
1 changed files with 28 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
user_interface_components/dialog_wrapper.md
View File

@ -1,5 +1,5 @@
--- ---
title: DialogWrapper title: Dialogs
--- ---
<!-- Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. --> <!-- Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
@ -7,75 +7,63 @@ title: DialogWrapper
The The
[`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) [`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
is the base class which is supposed to be used for all modal dialogs (and some non-modal dialogs) shown in *IntelliJ Platform* plugins. 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: It provides the following features:
* Button layout (platform-specific order of `OK/Cancel` buttons, macOS-specific `Help` button) * Button layout (platform-specific order of _OK_/_Cancel_ buttons, macOS-specific `Help` button)
* Context help * Context help
* Remembering the size of the dialog * Remembering the size of the dialog
* Non-modal validation (displaying an error message text when the data entered into the dialog is not valid) * Non-modal validation (displaying an error message text when the data entered into the dialog is not valid)
* Keyboard shortcuts: * Keyboard shortcuts:
* <kbd>Esc</kbd> for closing the dialog
* `Esc` for closing the dialog * <kbd>Left/Right</kbd> for switching between buttons
* <kbd>Y</kbd>/<kbd>N</kbd> for _Yes_/_No_ actions if they exist in the dialog
* `Left/Right` for switching between buttons * Optional _Do not ask again_ checkbox
* `Y/N` for `Yes/No` actions if they exist in the dialog
* Optional `Do not ask again` checkbox
When using the When using the
[`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) [`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
class for your own dialog, you need to follow these steps: class for a dialog, follow these 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 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 `init()` method from the constructor of the dialog class
* Call the `init()` method from the constructor of your dialog class
* Call the `setTitle()` method to set the title for the dialog box * Call the `setTitle()` method to set the title for the dialog box
* Implement the `createCenterPanel()` method to return the component comprising the main contents of the dialog. * Implement the `createCenterPanel()` method to return the component comprising the main contents of the dialog.
* *Optional*: Override the `getPreferredFocusedComponent()` method and return the component that should be focused when the dialog is first displayed. * *Optional*: Override the `getPreferredFocusedComponent()` method and return the component that should be focused when the dialog is first displayed.
* *Optional*: Override the `getDimensionServiceKey()` method to return the identifier which will be used for persisting the dialog dimensions. * *Optional*: Override the `getDimensionServiceKey()` method to return the identifier which will be used for persisting the dialog dimensions.
* *Optional*: Override the `getHelpId()` method to return the context help topic associated with the dialog. * *Optional*: Override the `getHelpId()` method to return the context help topic associated with the dialog.
The The
[`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) [`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
class is often used together with UI Designer forms. class is often used together with [GUI Designer forms](https://www.jetbrains.com/help/idea/gui-designer-basics.html).
In this case, you bind a UI Designer form to your class extending In this case, bind a GUI Designer form to the class extending `DialogWrapper`,
[`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java),
bind the top-level panel of the form to a field and return that field from the `createCenterPanel()` method. bind the top-level panel of the form to a field and return that field from the `createCenterPanel()` method.
When using Kotlin, use [Kotlin UI DSL](kotlin_ui_dsl.md) to provide the dialog's contents.
> **TIP** Existing dialogs can be inspected at runtime using [UI Inspector](/reference_guide/internal_actions/internal_ui_inspector.md), e.g., to locate the underlying implementation of UI components.
To display the dialog, you call the `show()` method and then use the `getExitCode()` method to check how the dialog was closed. The `showAndGet()` method can be used to combine these two calls. To display the dialog, call the `show()` method and then use the `getExitCode()` method to check how the dialog was closed. The `showAndGet()` method can be used to combine these two calls.
To customize the buttons displayed in the dialog (replacing the standard `OK/Cancel/Help` set of buttons), you can override either the `createActions()` or `createLeftActions()` methods. 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. Both of these methods return an array of Swing Action objects.
If the button that you're adding closes the dialog, you can use If a button closes the dialog, use
[`DialogWrapperExitAction`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java), [`DialogWrapperExitAction`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
as the base class for your action. as the base class for the action.
Use `action.putValue(DialogWrapper.DEFAULT_ACTION, true)` to set the default button. Use `action.putValue(DialogWrapper.DEFAULT_ACTION, true)` to set the default button.
To validate the data entered into the dialog, you can override the `doValidate()` method. To validate the data entered into the dialog, override the `doValidate()` method.
The method will be called automatically by timer. The method will be called automatically by timer.
If the currently entered data is valid, you need to return `null` from your implementation. If the currently entered data is valid, return `null`.
Otherwise, you need to return a Otherwise, return a
[`ValidationInfo`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/ValidationInfo.java) [`ValidationInfo`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/ValidationInfo.java)
object which encapsulates an error message and an optional component associated with the invalid data. object which encapsulates an error message, and an optional component associated with the invalid data.
If you specify 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. 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.
## Example ## Example
Simple definition of a Simple definition of a [`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java):
[`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java):
```java ```java
public class SampleDialogWrapper extends DialogWrapper { public class SampleDialogWrapper extends DialogWrapper {
@ -100,14 +88,13 @@ public class SampleDialogWrapper extends DialogWrapper {
} }
``` ```
Usage of Usage of [`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java):
[`DialogWrapper`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java):
```java ```java
JButton testButton = new JButton(); JButton testButton = new JButton();
testButton.addActionListener(actionEvent -> { testButton.addActionListener(actionEvent -> {
if(new SampleDialogWrapper().showAndGet()) { if (new SampleDialogWrapper().showAndGet()) {
// user pressed ok // user pressed OK
} }
}); });
``` ```