DeprecatedKotlin UI DSL Version 1
Edit pageLast modified: 02 July 2024UI Guidelines: Layout
warning
Kotlin UI SDL Version 1 vs 2When targeting IntelliJ Platform 2021.3 and later only use Kotlin UI DSL Version 2.
The version documented on this page is deprecated and will be removed in future platform releases.
Please note breaking changes can occur for this API between major releases.
Kotlin UI DSL allows creating UI forms with input components bound to state objects. The forms are built by using a declarative Kotlin syntax. It shares similarities with Jetpack Compose for Android and is intended to build UI forms or part of forms for, e.g. dialogs and settings pages.
The Kotlin UI DSL is not intended to build general UIs, like tool windows controls that trigger some actions and do not contain any input components bound to state objects. For this purpose, use custom Swing components from the IntelliJ Platform or the standard ones.
This document covers the Kotlin UI DSL in IntelliJ Platform 2019.2. A lot of the features described in this document are not available for plugins targeting earlier versions.
The Kotlin UI DSL Version 1 functions are located in the com.intellij.ui.layout
package.
Layout Structure
tip
See Layout topic in UI Guidelines for recommendations on arranging UI controls in dialogs.
Use panel
to create UI:
panel {
row {
// child components
}
}
Rows are created vertically from top to bottom, in the same order as lines of code that call row
. Inside one row, you add components from left to right in the same order calls to factory method or ()
appear in each row. Every component is effectively placed in its own grid cell.
The label for the row can be specified as a parameter for the row
method:
row("Parameters") { ... }
Rows can be nested. Components in a nested row block are considered to be subordinate to the containing row and are indented accordingly.
row {
checkBox(...)
row {
textField(...) // indented relatively to the checkbox above
}
}
To put multiple components in the same grid cell, wrap them in a cell
method:
row {
// These two components will occupy two columns in the grid
label(...)
textField(...)
// These two components will be placed in the same grid cell
cell {
label(...)
textField(...)
}
}
To put a component on the right side of a grid row, use the right
method:
row {
rememberCheckBox()
right {
link("Forgot password")
}
}
tip
To visually debug layout, enable UI DSL Debug Mode from Internal Actions - UI Submenu.
Adding Components
There are two ways to add child components. The recommended way is to use factory methods label
, button
, radioButton
, link
, etc. It allows you to create consistent UI and reuse common patterns.
These methods also support property bindings, allowing you to automatically load the value displayed in the component from a property and to store it back. The easiest way to do that is to pass a reference to a Kotlin bound property:
checkBox("Show tabs in single row", uiSettings::scrollTabLayoutInEditor)
Note that the bound property reference syntax also can be used to reference Java fields, but not getter/setter pairs.
Alternatively, many factory methods support specifying a getter/setter pair for cases when a property mapping is more complicated:
checkBox(
"Show file extensions in editor tabs",
{ !uiSettings.hideKnownExtensionInTabs },
{ uiSettings.hideKnownExtensionInTabs = !it })
If you want to add a component for which there are no factory methods, you can simply invoke an instance of your component, using the ()
overloaded operator:
val customComponent = MyCustomComponent()
panel {
row { customComponent() }
}
Supported Components
Labels
Use the label
method:
label("Sample text")
Checkboxes
See examples above.
Radio Buttons
Radio button groups are created using the buttonGroup
block. There are two ways to use it. If the selected radio button corresponds to a specific value of a single property, pass the property binding to the buttonGroup
method and the specific values to radioButton
functions:
buttonGroup(mySettings::providerType) {
row { radioButton("In native Keychain", ProviderType.KEYCHAIN) }
row { radioButton("In KeePass", ProviderType.KEEPASS) }
}
If the selected radio button is controlled by multiple boolean properties, use buttonGroup
with no binding and specify property bindings for all but one of the radio buttons:
buttonGroup {
row { radioButton("The tab on the left") }
row { radioButton("The tab on the right", uiSettings::activeRightEditorOnClose) }
row { radioButton("Most recently opened tab", uiSettings::activeMruEditorOnClose) }
}
Text Fields
Use the textField
method for a simple text field:
row("Username:") {
textField(settings::userName)
}
For entering numbers, use intTextField
:
intTextField(uiSettings::editorTabLimit, columns = 4, range = EDITOR_TABS_RANGE)
For password text fields, there is no factory function available, so you need to use ()
:
val passwordField = JPasswordField()
val panel = panel {
// ...
row { passwordField() }
}
To specify the size of a text field, either pass the columns
parameter as shown in the intTextField
example above, or use growPolicy()
:
val userField = JTextField(credentials?.userName)
val panel = panel {
row("Username:") { userField().growPolicy(GrowPolicy.SHORT_TEXT) }
}
Combo Boxes
Use the comboBox
method with either a bound property, or a getter/setter pair:
comboBox(DefaultComboBoxModel<Int>(tabPlacements), uiSettings::editorTabPlacement)
comboBox<PgpKey>(
pgpListModel,
{ getSelectedPgpKey() ?: pgpListModel.items.firstOrNull() },
{ mySettings.state.pgpKeyId = if (usePgpKey.isSelected) it?.keyId else null })
Spinners
Use the spinner
method:
spinner(retypeOptions::retypeDelay, minValue = 0, maxValue = 5000, step = 50)
Link Label
Use the link
method:
link("Forgot password?") {
// handle click, e.g. showing dialog
}
To open URL in the browser, use browserLink
:
browserLink("Open Homepage", "https://www.jetbrains.com")
Separators
Use the titledRow
method and put the controls under the separator into the nested block:
titledRow("Appearance") {
row { checkBox(...) }
}
Explanatory Text
Use the comment
parameter:
checkBox(message("checkbox.smart.tab.reuse"),
uiSettings::reuseNotModifiedTabs,
comment = message("checkbox.smart.tab.reuse.inline.help"))
Integrating Panels with Property Bindings
A panel returned by the panel
method is an instance of DialogPanel
. This base class supports the standard apply()
, reset()
, and isModified()
methods.
Dialogs
Reference: DialogWrapper
If you're using a DialogPanel
as the main panel of a DialogWrapper
, the apply()
method will be automatically called when the dialog is closed using OK action. The other methods are unused in this case.
Use the focused()
method to specify which control should be focused when the dialog is initialized:
return panel {
row("Target class name:") {
textField(::className).focused()
}
}
Configurables
Reference: Settings Guide
If you're using the UI DSL to implement a Configurable
, use BoundConfigurable
as the base class. In this case, the Configurable
methods will be automatically delegated to the panel.
Enabling and Disabling Controls
Use the enableIf
method to bind the enabled state of a control to the values entered in other controls. The parameter of the method is a predicate.
checkBox("Show tabs in single row", uiSettings::scrollTabLayoutInEditor)
.enableIf(myEditorTabPlacement.selectedValueIs(SwingConstants.TOP))
The available predicates are:
selected
to check the selected state of a checkbox or radio buttonselectedValueIs
andselectedValueMatches
to check the selected item in a combo box.
Predicates can be combined with and
and or
infix functions:
checkBox("Hide tabs if there is no space", uiSettings::hideTabsIfNeed)
.enableIf(myEditorTabPlacement.selectedValueMatches { it != UISettings.TABS_NONE } and
myScrollTabLayoutInEditorCheckBox.selected)
Examples
Sample usages in IntelliJ Platform IDEs:
User Interface | Implementation |
---|---|
Settings | Editor | Reader Mode | |
New Branch dialog in Git (Manage Git branches) | |
Settings | Tools | Diff & Merge | |
Settings | Editor | General | Editor Tabs |
tip
To understand how a component visible in the IDE is created in code, see the component's
added-at
property in the UI Inspector. Note that it is not limited only to components created with Kotlin UI DSL, but helps to understand the creation of any visible Swing component.
FAQ
One Cell Is Minimum, Second One Is Maximum
Set CCFlags.growX
and CCFlags.pushX
for some component in the second cell.
Thanks for your feedback!