Kotlin UI DSL Version 1

Layout Structure

tip

See Layout topic in IntelliJ Platform 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

label("Sample text")

buttonGroup(mySettings::providerType) {
  row { radioButton("In native Keychain", ProviderType.KEYCHAIN) }
  row { radioButton("In KeePass", ProviderType.KEEPASS) }
}

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) }
}

row("Username:") {
    textField(settings::userName)
}

intTextField(uiSettings::editorTabLimit, columns = 4, range = EDITOR_TABS_RANGE)

val passwordField = JPasswordField()
val panel = panel {
  // ...
  row { passwordField() }
}

val userField = JTextField(credentials?.userName)
val panel = panel {
  row("Username:") { userField().growPolicy(GrowPolicy.SHORT_TEXT) }
}

comboBox(DefaultComboBoxModel<Int>(tabPlacements), uiSettings::editorTabPlacement)

comboBox<PgpKey>(
  pgpListModel,
  { getSelectedPgpKey() ?: pgpListModel.items.firstOrNull() },
  { mySettings.state.pgpKeyId = if (usePgpKey.isSelected) it?.keyId else null })

spinner(retypeOptions::retypeDelay, minValue = 0, maxValue = 5000, step = 50)

link("Forgot password?") {
  // handle click, e.g. showing dialog
}

browserLink("Open Homepage", "https://www.jetbrains.com")

titledRow("Appearance") {
  row { checkBox(...) }
}

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.

return panel {
  row("Target class name:") {
    textField(::className).focused()
  }
}

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 button

• selectedValueIs and selectedValueMatches 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:

FAQ