diff --git a/images/ui/combo_box/combobox.png b/images/ui/combo_box/combobox.png new file mode 100644 index 000000000..628af3eef Binary files /dev/null and b/images/ui/combo_box/combobox.png differ diff --git a/images/ui/combo_box/combobox_dark.png b/images/ui/combo_box/combobox_dark.png new file mode 100644 index 000000000..ec8e7c93d Binary files /dev/null and b/images/ui/combo_box/combobox_dark.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_1_correct.png b/images/ui/combo_box/combobox_how_to_use_1_correct.png new file mode 100644 index 000000000..b835bdc08 Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_1_correct.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_1_correct_dark-1.png b/images/ui/combo_box/combobox_how_to_use_1_correct_dark-1.png new file mode 100644 index 000000000..3c3a8b1f3 Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_1_correct_dark-1.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_1_correct_dark.png b/images/ui/combo_box/combobox_how_to_use_1_correct_dark.png new file mode 100644 index 000000000..6a59bbba7 Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_1_correct_dark.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_1_incorrect.png b/images/ui/combo_box/combobox_how_to_use_1_incorrect.png new file mode 100644 index 000000000..67b21335a Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_1_incorrect.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_1_incorrect_dark-1.png b/images/ui/combo_box/combobox_how_to_use_1_incorrect_dark-1.png new file mode 100644 index 000000000..942c782d7 Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_1_incorrect_dark-1.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_1_incorrect_dark.png b/images/ui/combo_box/combobox_how_to_use_1_incorrect_dark.png new file mode 100644 index 000000000..960cdded8 Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_1_incorrect_dark.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_2_correct.png b/images/ui/combo_box/combobox_how_to_use_2_correct.png new file mode 100644 index 000000000..5062efba2 Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_2_correct.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_2_correct_dark.png b/images/ui/combo_box/combobox_how_to_use_2_correct_dark.png new file mode 100644 index 000000000..3c3a8b1f3 Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_2_correct_dark.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_2_incorrect.png b/images/ui/combo_box/combobox_how_to_use_2_incorrect.png new file mode 100644 index 000000000..43c92f8d2 Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_2_incorrect.png differ diff --git a/images/ui/combo_box/combobox_how_to_use_2_incorrect_dark.png b/images/ui/combo_box/combobox_how_to_use_2_incorrect_dark.png new file mode 100644 index 000000000..942c782d7 Binary files /dev/null and b/images/ui/combo_box/combobox_how_to_use_2_incorrect_dark.png differ diff --git a/images/ui/combo_box/combobox_menu_items_1.png b/images/ui/combo_box/combobox_menu_items_1.png new file mode 100644 index 000000000..cf2a02d0c Binary files /dev/null and b/images/ui/combo_box/combobox_menu_items_1.png differ diff --git a/images/ui/combo_box/combobox_menu_items_1_dark.png b/images/ui/combo_box/combobox_menu_items_1_dark.png new file mode 100644 index 000000000..aa11ddce5 Binary files /dev/null and b/images/ui/combo_box/combobox_menu_items_1_dark.png differ diff --git a/images/ui/combo_box/combobox_menu_items_2.png b/images/ui/combo_box/combobox_menu_items_2.png new file mode 100644 index 000000000..170520a09 Binary files /dev/null and b/images/ui/combo_box/combobox_menu_items_2.png differ diff --git a/images/ui/combo_box/combobox_menu_items_2_dark.png b/images/ui/combo_box/combobox_menu_items_2_dark.png new file mode 100644 index 000000000..a9126dc9c Binary files /dev/null and b/images/ui/combo_box/combobox_menu_items_2_dark.png differ diff --git a/images/ui/combo_box/combobox_validation.png b/images/ui/combo_box/combobox_validation.png new file mode 100644 index 000000000..98667e567 Binary files /dev/null and b/images/ui/combo_box/combobox_validation.png differ diff --git a/images/ui/combo_box/combobox_validation_dark.png b/images/ui/combo_box/combobox_validation_dark.png new file mode 100644 index 000000000..a5cfcc99f Binary files /dev/null and b/images/ui/combo_box/combobox_validation_dark.png differ diff --git a/images/ui/combo_box/combobox_when_not_to_use_1.png b/images/ui/combo_box/combobox_when_not_to_use_1.png new file mode 100644 index 000000000..a6401533b Binary files /dev/null and b/images/ui/combo_box/combobox_when_not_to_use_1.png differ diff --git a/images/ui/combo_box/combobox_when_not_to_use_1_dark.png b/images/ui/combo_box/combobox_when_not_to_use_1_dark.png new file mode 100644 index 000000000..3aff30cac Binary files /dev/null and b/images/ui/combo_box/combobox_when_not_to_use_1_dark.png differ diff --git a/images/ui/combo_box/combobox_when_not_to_use_2.png b/images/ui/combo_box/combobox_when_not_to_use_2.png new file mode 100644 index 000000000..d7cbc58be Binary files /dev/null and b/images/ui/combo_box/combobox_when_not_to_use_2.png differ diff --git a/images/ui/combo_box/combobox_when_not_to_use_2_dark.png b/images/ui/combo_box/combobox_when_not_to_use_2_dark.png new file mode 100644 index 000000000..51ab015e0 Binary files /dev/null and b/images/ui/combo_box/combobox_when_not_to_use_2_dark.png differ diff --git a/images/ui/combo_box/combobox_when_not_to_use_3.png b/images/ui/combo_box/combobox_when_not_to_use_3.png new file mode 100644 index 000000000..3708c3637 Binary files /dev/null and b/images/ui/combo_box/combobox_when_not_to_use_3.png differ diff --git a/images/ui/combo_box/combobox_when_not_to_use_3_dark.png b/images/ui/combo_box/combobox_when_not_to_use_3_dark.png new file mode 100644 index 000000000..3f52bb0c5 Binary files /dev/null and b/images/ui/combo_box/combobox_when_not_to_use_3_dark.png differ diff --git a/images/ui/combo_box/combobox_when_to_use_1.png b/images/ui/combo_box/combobox_when_to_use_1.png new file mode 100644 index 000000000..9a5264af3 Binary files /dev/null and b/images/ui/combo_box/combobox_when_to_use_1.png differ diff --git a/images/ui/combo_box/combobox_when_to_use_1_dark.png b/images/ui/combo_box/combobox_when_to_use_1_dark.png new file mode 100644 index 000000000..0dba07733 Binary files /dev/null and b/images/ui/combo_box/combobox_when_to_use_1_dark.png differ diff --git a/images/ui/combo_box/combobox_when_to_use_2.png b/images/ui/combo_box/combobox_when_to_use_2.png new file mode 100644 index 000000000..2c25fcacc Binary files /dev/null and b/images/ui/combo_box/combobox_when_to_use_2.png differ diff --git a/images/ui/combo_box/combobox_when_to_use_2_dark.png b/images/ui/combo_box/combobox_when_to_use_2_dark.png new file mode 100644 index 000000000..a812c4ef2 Binary files /dev/null and b/images/ui/combo_box/combobox_when_to_use_2_dark.png differ diff --git a/topics/ui/controls/combo_box.md b/topics/ui/controls/combo_box.md index c7f13b446..318ab80ae 100644 --- a/topics/ui/controls/combo_box.md +++ b/topics/ui/controls/combo_box.md @@ -10,9 +10,9 @@ -A combo box combines a [drop-down list](drop_down.md) and an [input field](input_field.md), allowing the user to select a value from the list or enter a custom value. +A combo box combines a [drop down list](drop_down.md) and an [input field](input_field.md), allowing the user to select a value from the list or enter a custom value. -![](combo_box_example.png){width=328} +![A preview of a combo box](combobox.png){width=706} Use [`ComboBox`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/ComboBox.java) instead of `javax.swing.JComboBox`. To make combo box editable invoke: @@ -23,80 +23,119 @@ comboBox.setEditable(true); ## When to use -Use a combo box if: -* The user needs to select a value or enter a custom value. +### Select value or enter custom - ![](combo_box_font_size.png){width=165} +When the user needs to select a value or enter a custom value, use the combo box: -* The possible choices are objects or states. +![A font size that allows selecting predefined values as well as entering a custom value](combobox_when_to_use_1.png){width=706} +### Return to previous states +If the user may need to return to previous values, use the combo box. For example, save previously entered paths, so the user can quickly select them later: -* The user may need to return to previous values. For example, save previously entered paths, so the user can quickly - select them later: +![A with an open menu with previously selected values](combobox_when_to_use_2.png){width=706} - ![](maven.png){width=413} +## When not to use -### When not to use +### The number of options is finite -If the number of options is finite, and there’s no need to enter custom values. In this case, use a [drop-down list](drop_down.md) or [radio buttons](radio_button.md). +If the number of options is finite, and there is no need to enter custom values. In this case, use a [dropdown list](drop_down.md) or [radio buttons](radio_button.md): -If it’s not possible to list the most likely choices. In this case, use an [input field](input_field.md) instead. +![The Theme dropdown with a predefined list of values](combobox_when_not_to_use_1.png){width="706"} -![](prefill.png){width=152} +### Impossible to list values -If the list is big, and the user knows what value they need and won’t review the list. In this case, use an input field with completion. +If it is not possible to list the most likely choices. In this case, use an [input field](input_field.md) instead: -![](input_field_completion.png){width=509} +![A port number input](combobox_when_not_to_use_2.png){width=706} + +### Large list with expected values + +If the list is big, and the user knows what value they need and won’t review the list, use an input field with completion: + +![An input field with a completion popup](combobox_when_not_to_use_3.png){width=706} ## How to use +### Label and default value + For the [label](drop_down.md#label) and the [default value](drop_down.md#default-value) apply the same rules as for the -[drop-down list](drop_down.md). +[dropdown list](drop_down.md). + +### Initial state If there are no values in the list initially, replace the combo box with an input field. This way, users won't waste their time clicking the empty combo box to find out that there are no options available. -| Incorrect | Correct | -|-----------------------------------------------------|-----------------------------------------------------| -| ![](combo_box_empty.png){width="221"} | ![](replace_with_iput_field.png){width="216"} | + + + + + +
+ IncorrectAn incorrect example of a repository input field without values + + CorrectA correct example of a repository input field without values +
-Replace the input field with a combo box after a value has been entered and confirmed. +Replace the input field with a combo box after a value has been entered and confirmed: -### Menu + + + + + +
+ IncorrectAn incorrect example of a repository input field without values + + CorrectA correct example of a repository input field without values +
-#### Control +### Menu items -Open the combo box menu by clicking the arrow button on the right or pressing the Down arrow key when the combo box is focused. -The menu opens down by default. If there is not enough space, the menu opens up. +#### Predefined options -When the menu opens, select the element that was shown in the closed combo box. If a custom value is entered, then do not select a value in the list. +Show the predefined or most likely options in the list. Follow the rules for [dropdown menu items](drop_down.md#menu-items). -Move the selection in the menu and update the value in the combo box by pressing the Up and Down arrow keys. -On mouse hover, move the selection to an item the cursor is pointing to and update the value by clicking the mouse button or pressing Enter. +#### Previous inputs -The menu remains opened until the user clicks the item in the list, presses Enter or Esc, clicks outside the menu, -or switches to another app. +If the user needs to return to previous inputs, add such values to the end of the list when clicking the confirmation button in the dialog: -#### Menu items +![A combo box with previously entered values in the menu](combobox_menu_items_1.png){width=706} -The menu list contains predefined or the most likely options. Follow the rules for [drop-down menu items](drop_down.md#menu-items). - -If the user needs to return to previous inputs, add such values to the end of the list when clicking the confirmation button in the dialog. - -![](maven.png){width=413} +#### Built-in button Use [built-in buttons](built_in_button.md) to add values or expand the combo box, e.g., the browse button: -![](built_in_button.png){width=384} +![A combo box with the browse built-in button](combobox_menu_items_2.png){width=706} ## Validation If the user enters an invalid value, highlight the combo box with red and show an error message in a tooltip. For -more details, see [Validation errors](validation_errors.md). +more details, see [validation errors](validation_errors.md). -![](validation.png){width=235} +![A combo box with an error message](combobox_validation.png){width=706} -## Sizes and placement +## How to layout -Follow the [drop-down guidelines](drop_down.md#sizes-and-placement). +Follow the [labeled input controls](layout.md#labeled-input-controls). + +## Build-in behaviour + +### Opening the menu + +The combo box menu opens by clicking on the arrow button on the right or pressing the Down arrow key when the combo box is focused. + The menu opens down by default. If there is not enough space, the menu opens up. + +### Selected value + +The value that was shown in the closed combo box is selected in the open menu. A value in the list is not selected if a custom value was entered. + +### Moving the selection + +The selection is moved and the value in the combo box is updated by pressing the Up and Down arrow keys. When using a mouse, the selection is changed on mouse hover, the value is updated by clicking the mouse button or pressing Enter. + +### Closing the menu + +The menu remains opened until the user clicks the item in the list, presses Enter or Esc, clicks outside the menu, + or switches to another app.