Merge pull request #1401
* UX-2323 Update existing UI Guidelines: the Combo-box guideline update…
BIN
images/ui/combo_box/combobox.png
Normal file
After Width: | Height: | Size: 25 KiB |
BIN
images/ui/combo_box/combobox_dark.png
Normal file
After Width: | Height: | Size: 68 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_1_correct.png
Normal file
After Width: | Height: | Size: 5.7 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_1_correct_dark-1.png
Normal file
After Width: | Height: | Size: 59 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_1_correct_dark.png
Normal file
After Width: | Height: | Size: 5.5 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_1_incorrect.png
Normal file
After Width: | Height: | Size: 14 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_1_incorrect_dark-1.png
Normal file
After Width: | Height: | Size: 7.5 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_1_incorrect_dark.png
Normal file
After Width: | Height: | Size: 47 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_2_correct.png
Normal file
After Width: | Height: | Size: 23 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_2_correct_dark.png
Normal file
After Width: | Height: | Size: 59 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_2_incorrect.png
Normal file
After Width: | Height: | Size: 8.2 KiB |
BIN
images/ui/combo_box/combobox_how_to_use_2_incorrect_dark.png
Normal file
After Width: | Height: | Size: 7.5 KiB |
BIN
images/ui/combo_box/combobox_menu_items_1.png
Normal file
After Width: | Height: | Size: 29 KiB |
BIN
images/ui/combo_box/combobox_menu_items_1_dark.png
Normal file
After Width: | Height: | Size: 74 KiB |
BIN
images/ui/combo_box/combobox_menu_items_2.png
Normal file
After Width: | Height: | Size: 17 KiB |
BIN
images/ui/combo_box/combobox_menu_items_2_dark.png
Normal file
After Width: | Height: | Size: 18 KiB |
BIN
images/ui/combo_box/combobox_validation.png
Normal file
After Width: | Height: | Size: 20 KiB |
BIN
images/ui/combo_box/combobox_validation_dark.png
Normal file
After Width: | Height: | Size: 22 KiB |
BIN
images/ui/combo_box/combobox_when_not_to_use_1.png
Normal file
After Width: | Height: | Size: 31 KiB |
BIN
images/ui/combo_box/combobox_when_not_to_use_1_dark.png
Normal file
After Width: | Height: | Size: 91 KiB |
BIN
images/ui/combo_box/combobox_when_not_to_use_2.png
Normal file
After Width: | Height: | Size: 5.9 KiB |
BIN
images/ui/combo_box/combobox_when_not_to_use_2_dark.png
Normal file
After Width: | Height: | Size: 5.6 KiB |
BIN
images/ui/combo_box/combobox_when_not_to_use_3.png
Normal file
After Width: | Height: | Size: 34 KiB |
BIN
images/ui/combo_box/combobox_when_not_to_use_3_dark.png
Normal file
After Width: | Height: | Size: 76 KiB |
BIN
images/ui/combo_box/combobox_when_to_use_1.png
Normal file
After Width: | Height: | Size: 25 KiB |
BIN
images/ui/combo_box/combobox_when_to_use_1_dark.png
Normal file
After Width: | Height: | Size: 70 KiB |
BIN
images/ui/combo_box/combobox_when_to_use_2.png
Normal file
After Width: | Height: | Size: 29 KiB |
BIN
images/ui/combo_box/combobox_when_to_use_2_dark.png
Normal file
After Width: | Height: | Size: 74 KiB |
@ -10,9 +10,9 @@
|
|||||||
|
|
||||||
</tldr>
|
</tldr>
|
||||||
|
|
||||||
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.
|
||||||
|
|
||||||
{width=328}
|
{width=706}
|
||||||
|
|
||||||
Use [`ComboBox`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/ComboBox.java) instead of `javax.swing.JComboBox`.
|
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:
|
To make combo box editable invoke:
|
||||||
@ -23,80 +23,119 @@ comboBox.setEditable(true);
|
|||||||
|
|
||||||
## When to use
|
## 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
|
||||||
|
|
||||||
{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.
|
{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
|
{width=706}
|
||||||
select them later:
|
|
||||||
|
|
||||||
{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.
|
{width="706"}
|
||||||
|
|
||||||
{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:
|
||||||
|
|
||||||
{width=509}
|
{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:
|
||||||
|
|
||||||
|
{width=706}
|
||||||
|
|
||||||
## How to use
|
## 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
|
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.
|
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.
|
This way, users won't waste their time clicking the empty combo box to find out that there are no options available.
|
||||||
|
|
||||||
| <format color="Red" style="bold">Incorrect</format> | <format color="Green" style="bold">Correct</format> |
|
<table style="none" border="false">
|
||||||
|-----------------------------------------------------|-----------------------------------------------------|
|
<tr>
|
||||||
| {width="221"} | {width="216"} |
|
<td width="50%">
|
||||||
|
<format color="Red" style="bold">Incorrect</format><img src="combobox_how_to_use_1_incorrect.png" alt="An incorrect example of a repository input field without values"/>
|
||||||
|
</td>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="Green" style="bold">Correct</format><img src="combobox_how_to_use_1_correct.png" alt="A correct example of a repository input field without values"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
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
|
<table style="none" border="false">
|
||||||
|
<tr>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="Red" style="bold">Incorrect</format><img src="combobox_how_to_use_2_incorrect.png" alt="An incorrect example of a repository input field without values"/>
|
||||||
|
</td>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="Green" style="bold">Correct</format><img src="combobox_how_to_use_2_correct.png" alt="A correct example of a repository input field without values"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
#### Control
|
### Menu items
|
||||||
|
|
||||||
Open the combo box menu by clicking the arrow button on the right or pressing the <shortcut>Down</shortcut> arrow key when the combo box is focused.
|
#### Predefined options
|
||||||
The menu opens down by default. If there is not enough space, the menu opens up.
|
|
||||||
|
|
||||||
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 <control>Up</control> and <control>Down</control> arrow keys.
|
#### Previous inputs
|
||||||
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 <shortcut>Enter</shortcut>.
|
|
||||||
|
|
||||||
The menu remains opened until the user clicks the item in the list, presses <shortcut>Enter</shortcut> or <shortcut>Esc</shortcut>, clicks outside the menu,
|
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:
|
||||||
or switches to another app.
|
|
||||||
|
|
||||||
#### Menu items
|
{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).
|
#### Built-in button
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
{width=413}
|
|
||||||
|
|
||||||
Use [built-in buttons](built_in_button.md) to add values or expand the combo box, e.g., the browse button:
|
Use [built-in buttons](built_in_button.md) to add values or expand the combo box, e.g., the browse button:
|
||||||
|
|
||||||
{width=384}
|
{width=706}
|
||||||
|
|
||||||
## Validation
|
## Validation
|
||||||
|
|
||||||
If the user enters an invalid value, highlight the combo box with red and show an error message in a tooltip. For
|
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).
|
||||||
|
|
||||||
{width=235}
|
{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 <shortcut>Down</shortcut> 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 <control>Up</control> and <control>Down</control> arrow keys. When using a mouse, the selection is changed on mouse hover, the value is updated by clicking the mouse button or pressing <shortcut>Enter</shortcut>.
|
||||||
|
|
||||||
|
### Closing the menu
|
||||||
|
|
||||||
|
The menu remains opened until the user clicks the item in the list, presses <shortcut>Enter</shortcut> or <shortcut>Esc</shortcut>, clicks outside the menu,
|
||||||
|
or switches to another app.
|
||||||
|