UX-2323: Drop-down Guideline — updated images and reworked text

topics/ui/controls/drop_down.md

@@ -10,55 +10,134 @@
 
 </tldr>
 
-A drop-down list is a type of button that appears in dialogs. It shows a list of choices on clicking it and allows selecting one option.
+A drop-down list is a type of control that shows a list of choices when clicking on it and allows selecting one option.
 
-![](drop_down_example.png){width=134}
+![Example of a Theme drop-down with options: Light (selected in light), Dark (selected in dark), Light with Light Header, High Contrast, Darcula, and an option to get more themes](dropdown.png){width=706}
 
 ## When to use
 
-Use a drop-down list if:
+### Single option
 
-A single option should be selected.
+Use when a single option should be selected.
+
+![Interface language drop-down with options: English (selected), German, Dutch, Chinese (Simplified), and an option to get more languages](dropdown_when_to_1.png){width="706"}
+
+### Choices are objects or states
 
 The possible choices are objects or states.
 
-![](output_level.png){width=182}
+![Output level drop-down with options: Debug, Info (selected), Warn, Error, and Warning](dropdown_when_to_2.png){width=706}
 
-The number of choices is more than 4.
+### More than four options
 
-The screen space is limited, so there is not enough room for radio buttons.
+The number of options is more than four.
 
-The default value is recommended for the most users. A drop-down is a good way to hide unpopular alternatives.
+![Regions drop-down with options: Africa, Americas, Asia except China Mainland, Europe (selected), Middle East, Oceania](dropdown_when_to_3.png){width="706"}
 
-![](antialiasing.png){width=228}
+### Space is limited
 
-*"Subpixels" is the best choice for most users.*
+The screen space is limited, so there is not enough room for [radio buttons](radio_button.md).
 
-If there are other drop-downs in the same window and these options are not more important than others. A list of radio buttons is more noticeable than the drop-down.
+![Settings | Appearence dialog that has a complex layout with multiple drop-downs: Theme, Zoom, and Custom font](dropdown_when_to_4.png){width="706"}
 
-If a layout combines various UI elements for one setting, use a drop-down even if there are 4 options or fewer:
+### Default value is the most used
 
-![](complex_layout.png){width=523}
+The default value is recommended for most users. A drop-down is a good way to hide unpopular alternatives.
 
-### When not to use
+![Antialiasing drop-down with options: Subpixels (selected), Greyscale, Not antialiasing](dropdown_when_to_5.png){width=706}
 
-If multiple selections are possible, use checkboxes.
+### Combined controls
 
-If there is a list of actions, use a menu or a split button:
+If a control combines various UI elements as one setting, use a drop-down even if there are four options or fewer:
 
-![](drop_down_menu_button.png){width=136}
+![Combined control with a checkbox 'Automatically check updated for' and a drop-down with 'Early access program' selected, following by a button 'Check now'](dropdown_when_to_6.png){width=706}
 
-If there are 4 options or fewer, use radio buttons.
+## When not to use
 
-![](radio_buttons.png){width=255}
+### Four or less options
 
-If users may need to enter a value not currently in the list, use a combo box.
+If there are four options or fewer, use [radio buttons](radio_button.md).
 
-![](combo_box_font_size.png){width=165}
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+      <format color="369650" style="bold">Correct</format>
+      <img src="dropdown_when_not_to_3_correct.png" alt="'Open project in' radio group with options: 'New window', 'Current window', and 'Ask'" width="378"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="dropdown_when_not_to_3_incorrect.png" alt="'Open project in' drop-down with options: 'New window' (selected), 'Current window', and 'Ask'" width="378"/>
+    </td>
+  </tr>
+</table>
+
+### Multiple selection
+
+If multiple selections are possible, use [checkboxes](checkbox.topic).
+
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+      <format color="369650" style="bold">Correct</format>
+      <img src="dropdown_when_not_to_1_correct.png" alt="'UI Options' checkbox group with options: 'Smooth scrolling' (checked), 'Display icons in menu items' (checked), and 'Enable mnemonics in menu'" width="378"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="dropdown_when_not_to_1_incorrect.png" alt="'UI Options' drop-down with options: 'Smooth scrolling' (checked), 'Display icons in menu items' (checked), and 'Enable mnemonics in menu'" width="378"/>
+    </td>
+  </tr>
+</table>
+
+### List of actions
+
+If there is a list of actions, use a menu or a [split button](split_button.md).
+
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+      <format color="369650" style="bold">Correct</format>
+      <img src="dropdown_when_not_to_2_correct.png" alt="Split-button 'Commit' and options: 'Commit and Push', 'Commit and Push Silently' (focused), and 'Create Patch'" width="378"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="dropdown_when_not_to_2_incorrect.png" alt="Drop-down 'Commit' with options: 'Commit' (focused), 'Commit and Push', 'Commit and Push Silently', and 'Create Patch'" width="378"/>
+    </td>
+  </tr>
+</table>
+
+### Adding values
+
+If users may need to enter a value not currently in the list, use a [combo box](combo_box.md).
+
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+      <format color="369650" style="bold">Correct</format>
+      <img src="dropdown_when_not_to_4_correct.png" alt="A combo box for selecting font size and entering a custom value is open, displaying options ranging from 20 to 72. The current selection is 20" width="378"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="dropdown_when_not_to_4_incorrect.png" alt="A dropdown menu for selecting font size is open, displaying options ranging from 20 to 72. The current selection is 20" width="378"/>
+    </td>
+  </tr>
+</table>
+
+### On a toolbar
 
 If a drop-down appears on a toolbar, use [toolbar drop-down](toolbar_drop_down.md) instead.
 
-![](toolbar_main.png){width=209}
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+      <format color="369650" style="bold">Correct</format>
+      <img src="dropdown_when_not_to_5_correct.png" alt="Run/debug widget in the main toolbar with multiple icon buttons, and a toolbar drop-down with selected 'StandAlone' option" width="378"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="dropdown_when_not_to_5_incorrect.png" alt="Run/debug widget in the main toolbar with multiple icon buttons, and a drop-down with selected 'StandAlone' option" width="378"/>
+    </td>
+  </tr>
+</table>
 
 ## How to use
 
@@ -66,155 +145,218 @@ If a drop-down appears on a toolbar, use [toolbar drop-down](toolbar_drop_down.m
 
 Follow the rules for the [input field](input_field.md#label).
 
-![](labels.png){width=490}
+![Drop-down menu labeled 'Placement' with the selected option set to 'Left'.](dropdown_how_to_1.png){width=706}
 
 ### Default value
 
-Select the most likely or the safest value by default.
+Select the most likely or the safest value by default. For example, the safest value is <control>Ask</control>, the behavior will not be unexpected to users:
 
-![](imports.png){width=298 style=block}
-*The safest value is "Ask", the behavior will not be unexpected to the user.*
+![Drop-down menu labeled 'Insert imports on paste' with options 'All', 'Ask', and 'None'. The selected option set to 'Ask'.](dropdown_how_to_2.png){width=706}
 
 Do **not** use an empty value as the default value. If no values are added to a drop-down yet, replace it with a button to add values.
 
-<table>
+<table style="none" border="false">
   <tr>
-        <td width="50%"><format color="Red" style="bold">Incorrect</format></td>
-        <td width="50%"><format color="Green" style="bold">Correct</format></td>
-    </tr>
-    <tr>
-        <td><img src="drop_down_empty.png" alt="" width="221" /></td>
-        <td><img src="button.png" alt="" width="190" /></td>
+    <td width="378">
+      <format color="369650" style="bold">Correct</format>
+      <img src="dropdown_how_to_3_correct.png" alt="Secondary button 'Add Settings Repository' which opens a dialog" width="378"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="dropdown_how_to_3_incorrect.png" alt="Drop-down 'Repository' with no selected option" width="378"/>
+    </td>
   </tr>
 </table>
 
-## Menu {id="menu_1"}
-
-### Control
-
-A drop-down menu opens on clicking the drop-down button anywhere or pressing the Down key when the drop-down is
-focused.
-The menu opens down by default. If there is not enough space, the menu opens up.
-
-When the menu opens, the default option (displayed when the menu is closed) is selected.
-
-Move the selection in the menu by pressing Up and Down arrows when an item is hovered. On hovering the cursor over the item just move selection and do not update the value.
-
-<!-- * Filter items in the list on typing:
-
-    ![](filter.png)
--->
-
-The menu remains opened until the user selects an item, clicks outside the menu, presses the <shortcut>Esc</shortcut> key or
-switches to another app.
-
-Allow single-click activation using mouse: click on a drop-down, the drop-down opens, select an item by hovering, close the drop-down with the new item selected by releasing the mouse button.
-
 ### Menu items
 
-Use sentence-style capitalization for each menu item.
+#### Capitalization
 
-![](browser.png){width=251}
+Use [sentence-style capitalization](capitalization.md#sentence) for each menu item.
 
-Avoid repeating words in drop-down list items. Move repeating words to the label or after the drop-down.
-
-![](refresh_changes.png){width=274}
-
-Sort items in one of the following orders:
-
-* Logical order, for example, in a spatial relationship:
-
-  ![](order_logical.png){width=172}
-
-* Alphabetical or numeric order if the options are equivalent to make it easier to find items:
-
-  ![](order_alphabetical.png){width=267}
-
-* Place the most common options first. If there are more than 10 options, separate the most popular options with a line:
-
-  ![](order_popular.png){width=254}
-
-Group related options, add a separator and group header if possible:
-
-![](drop_down_group.png){width=216}
-
-If there are actions related to the drop-down, put them under the gear icon on the right:
-
-![](scheme.png){width=336}
-
-Enclose meta-options in pointy brackets and place meta-options at the beginning or at the end if they are secondary.
-
-![](run_tests.png){width=263}
-
-*<control>&lt;Choose per test></control> is a meta-options because it’s not a real runner.*
-
-Do **not** assign special meanings to numeric or string values, use meta-options instead. It can be unclear that either 0 or an empty string are used to disable an option.
-
-<table>
+<table style="none" border="false">
   <tr>
-        <td width="50%"><format color="Red" style="bold">Incorrect</format></td>
-        <td width="50%"><format color="Green" style="bold">Correct</format></td>
-    </tr>
-    <tr>
-        <td><img src="version_incorrect.png" alt="" width="262" /></td>
-        <td><img src="version_correct.png" alt="" width="262" /></td>
+    <td width="378">
+      <format color="369650" style="bold">Correct</format>
+      <img src="dropdown_how_to_4_correct.png" alt="Drop-down menu labeled 'Default browser' with options 'System default', 'First listed', and 'Custom path'. The selected option set to 'System default'" width="378"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="dropdown_how_to_4_incorrect.png" alt="Drop-down menu labeled 'Default browser' with options 'System Default', 'First Listed', and 'Custom Path'. The selected option set to 'System Default'" width="378"/>
+    </td>
   </tr>
 </table>
 
-  <p><em>In the incorrect example an empty string is used to set <control>&lt;Same
-  as language level&gt;</control>, which is unclear.</em></p>
-  <p>Replace the <control>&lt;None&gt;</control> option with a checkbox if it does not make the layout more complex:</p>
+#### No repeated words in items
 
-<format color="Red" style="bold">Incorrect</format>
+Avoid repeating words in drop-down list items. Move repeating words to the label or after the drop-down.
 
-![](none_incorrect.png){width=288}
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+      <format color="369650" style="bold">Correct</format>
+      <img src="dropdown_how_to_5_correct.png" alt="Drop-down menu labeled 'Refresh every [selection] minutes' with options '10', '15', and '30'. The selected option set to '10'" width="378"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="dropdown_how_to_5_incorrect.png" alt="Drop-down menu labeled 'Refresh every' with options '10 minutes', '15 minutes', and '30 minutes'. The selected option set to '10 minutes'" width="378"/>
+    </td>
+  </tr>
+</table>
 
+#### Sorting items
+
+Sort items in one of the following orders:
+
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+      <img src="dropdown_how_to_6_1.png" alt="Drop-down menu labeled 'Placement' with options 'Left', 'Top', 'Right', and 'Bottom'. The selected option set to 'Top'"/>
+    </td>
+    <td>
+      <p>Logical order, for example, in a spatial relationship.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="378">
+      <img src="dropdown_how_to_6_2.png" alt="Drop-down menu labeled 'Global SQL dialect' with options '<None>', '<Generic SQL>', 'ClickHouse', 'DB2', 'Derby', 'Exasol', and other options available when scrolling. The selected option set to '<None>'"/>
+    </td>
+    <td>
+      <p>Alphabetical or numeric order if the options are equivalent to make it easier to find items.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="378">
+      <img src="dropdown_how_to_6_3.png" alt="Drop-down menu labeled 'Global encoding' with multiple options grouped in two groups and divided: popular options and the rest"/>
+    </td>
+    <td>
+      <p>Place the most common options first. If there are more than 10 options, separate the most popular options with a line.</p>
+    </td>
+  </tr>
+</table>
+
+#### Grouping
+
+Group related options, use a separator and add group headers if possible.
+
+![Drop-down menu labeled 'Scheme' with two groups of options that have group titles and divided by a divider'](dropdown_how_to_7.png){width=706}
+
+#### Actions related to a drop-down
+
+If there are actions related to the drop-down, put them under the gear icon on the right:
+
+![Drop-down menu 'Color Scheme' followed by a Settings icon-button related to the drop-down](dropdown_how_to_8.png){width=706}
+
+
+#### Meta-options
+
+Enclose meta-options in pointy brackets and place meta-options at the beginning or at the end if they are secondary.
+
+![Drop-down menu labeled 'Run tests with' with options 'Platform test runner', 'Gradle test runner', and '<Choose per test>'. The selected option set to '<Choose per test>'](dropdown_how_to_9.png){width=706}
+
+Do **not** assign special meanings to numeric or string values, use meta-options instead. It can be unclear that either 0 or an empty string are used to disable an option.
+
+<table style="none" border="false">
+    <tr>
+        <td width="50%">
             <format color="Green" style="bold">Correct</format>
+            <img src="dropdown_how_to_10_correct.png" alt="Drop-down menu labeled 'Version' with options ranging from 1.5 to 1.9, and a meta-option 'Same as language version'" width="372"/>
+        </td>
+        <td width="50%">
+            <format color="Red" style="bold">Incorrect</format>
+            <img src="dropdown_how_to_10_incorrect.png" alt="Drop-down menu labeled 'Version' with options ranging from 1.5 to 1.9, and an option '0'" width="372"/>
+        </td>
+    </tr>
+</table>
 
-![](none_correct.png){width=277}
+#### 'None' in simple layouts
 
-Preview list items with images if they are associated with well-known icons. Use formatting for a list of fonts. It will help users make a choice.
+Replace the <control>&lt;None&gt;</control> option with a checkbox if it doesn't make the layout more complex.
 
-![](preview.png){width=609}
+<table style="none" border="false">
+    <tr>
+        <td width="50%">
+            <format color="Green" style="bold">Correct</format>
+            <img src="dropdown_how_to_11_correct.png" alt="Checkbox 'Show close button at' followed by two radio buttons 'Right' and 'Left'" width="372"/>
+        </td>
+        <td width="50%">
+            <format color="Red" style="bold">Incorrect</format>
+            <img src="dropdown_how_to_11_incorrect.png" alt="Drop-down 'Close button position' with options 'Left', 'Right', '<None>'. The selected options is '<None>'" width="372"/>
+        </td>
+    </tr>
+</table>
 
-Use **bold** font to show default values, <format color="#2600FF">blue</format> font for values changed from the default,
-and <format color="#787878">grey</format> font to add a hint.
+#### Use previews in the list
 
-![](blue_text.png){width=188 style=block}
-*Default and Darcula are bundled schemes, Default is blue because it’s customized.*
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+      <img src="dropdown_how_to_12_1.png" alt="Drop-down 'Run on' with multiple options that have icons related to their meanings"/>
+    </td>
+    <td>
+      <p>Preview list items with <control>images</control> or <control>icons</control> if they are associated with well-known icons.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="378">
+      <img src="dropdown_how_to_12_2.png" alt="Drop-down 'Font' with multiple options that are showed in different fonts"/>
+    </td>
+    <td>
+      <p>Use <control>font formatting</control> for a list of fonts. It will help users make a choice.</p>
+    </td>
+  </tr>
+</table>
 
-![](grey_text.png){width=529}
+#### Default and changed values
 
-Submenus are not supported for the drop-down list. Use a tree view instead:
+<table style="none" border="false">
+  <tr>
+    <td width="378">
+      <img src="dropdown_how_to_13_2.png" alt="Drop-down 'Editor color scheme' with multiple options. Option 'Light (Theme default)' has 'Light' in blue color and 'Theme default' in grey color"/>
+    </td>
+    <td>
+        <ul>
+            <li>Use a <format color="#3574F0">blue</format> font for values changed from the default.</li>
+            <li>Use a <format color="#787878">secondary text</format> to mark an option as default.</li>
+        </ul>
+    </td>
+  </tr>
+</table>
 
-![](hierarchy.png){width=169}
+#### Submenus are not supported
 
-## Sizes and placement
+Submenus are not supported for the drop-down list. Use a tree view instead
 
-### Width
+![Drop-down 'Keymap' with multiple options in a tree view showing dependencies in options](dropdown_how_to_14.png){width=706}
 
-A drop-down width is fixed and does not change depending on the selected value.
+## Built-in behaviour
 
-![](drop_down_width.png){width=133}
+#### Opening the menu
 
-A drop-down width should be enough to fit the longest option plus 20px, but not less than 72px.
+A drop-down menu opens on clicking the drop-down button anywhere or pressing the <shortcut>Down</shortcut> key when the drop-down is
+focused.
 
-![](width_sizes.png){width=157}
+The menu opens **down** by default. If there is not enough space, the menu opens **up**.
 
-### Menu
+#### Selected value
 
-The width of a drop-down menu can either equal the drop-down control width, or be wider to fit longer items.
+When the menu opens, the default option (displayed when the menu is closed) is selected.
 
-![](menu_width.png){width=100}
+#### Moving the selection
 
-Choose a list length that eliminates unnecessary vertical scrolling. The minimum height of the list with scrolling is 200px. Expand the list to 600px if space is not constrained and the list does not hide meaningful information under it, e.g., the information that can be important to make a choice.
+Selection in the menu is moved by pressing <shortcut>Up</shortcut> and <shortcut>Down</shortcut> arrows when an item is hovered. Selection is moved as well when hovering the cursor over an item but it doesn't update the value.
 
-![](menu_height.png){width=225}
+#### Closing the menu
 
-[//]: # (TODO: For sizes inside the menu list see [Menu list]&#40;menu_list.md&#41;.)
+The menu remains opened until the user selects an item, clicks outside the menu, presses the <shortcut>Esc</shortcut> key or switches to another app.
 
-### Placement
+#### Single-click activation
 
-Follow the rules for the [input field](#placement).
+Single-click activation using a mouse should be allowed:
+1. Clicking on a drop-down.
+2. The drop-down opens, selecting an item by hovering.
+3. When releasing the mouse button, the drop-down closes with the new item selected.
 
+## How to layout
 
+Follow the [labeled input controls](layout.md#labeled-input-controls) guideline.