Author: Dusan Pavlica

1. Introduction

This document is the user experience specification for the JavaFX ComboBox control.

2. Overview

A ComboBox is a control that contains info part on the left side and drop down arrow on the right side. User can click the arrow to invoke the list of choices. If the list is too long then scrollbar appears. Currently selected item appears next to the drop down arrow and it can be editable or non editable.

A "Drop Down List" UI control or "Non-editable Combo Box" terms are used instead of a Combo Box sometimes, so let's take a look at the following examples of Drop Down list/Combo Box UI control to get a general idea what types exist on web, TV and desktop platform:

Figure 1: Combo Box in Swing. There is non editable Combo Box/ Drop Down list on the left hand side.

Figure 2: JavaFX Drop Down List experimental implementation (Author calls it Combo Box)

Figure 3: Editable Combo Box on Windows 7 platform

3. Interaction Design - Implemented Features

3.1 Introduction

A combo box is a combination of a list box and a single-line textbox, allowing the user to either type a value directly into the control or choose from the list of existing options. Also it allows user to add a new value if it doesn't exist in the list.

The term "combo box" is sometimes, incorrectly, used to mean "drop-down list". This distinction between "combo box" and "drop down list" is clarified with terms such as "non-editable combo box" (or something similar). Combo boxes are often applied to provide autocomplete or autotype functionality in a convenient way to the user. Let's look at the following basic UI elements of combo box:

Figure 4: Basic look of Editable Combo Box

There is editable text box area on the top left hand side and drop-down button placed next to it. If user clicks the button the drop-down list is invoked. User can choose an item from the list and it will be populated in the text field area. Or he can add a value into textfield manually.

3.2 Detailed Behavior

Basic Features

• Combo Box - Combo Box can exist in the following different states:
  
  

  	Normal state
  	Focused state	User can get to the Focused state by Tab Traversal or by clicking the textfield area. Then there is a focus indication around the Combo box Also a key cursor is displayed because the Combo box switches into Edit state right after it gets focus.
  	Disabled state	User can't edit the text or expand dropdown list if the Combo Box is disabled. The Combo Box isn't focusable in that state and user can't use it.
  	Expanded state	Drop-down list appears when user clicks the button. Also there is selection and hover indications visible in the drop down list. User confirms a selection in the dropdown list by mouse click or by dragging from the drop-down arrow to the selection and releasing the mouse button.
  	Hover (Mouse Over) state	This visual indication appears when user points his mouse cursor above the drop down button in the Combo Box.
  	Pressed/Armed state	User clicks the drop down button.
  	Edit state - different position of the cursor	User can edit value in the Combo Box. User confirms the edited value by pressing Enter key.
  	Edit state - the whole value is selected	User can select the whole text in the textfield by pressing Ctrl+A or by double click.

  
  
  

• Textfield - There has to be clear indication that textfield is editable in case of Combo Box and non-editable in case of Drop Down list. That distinction is typically expressed by showing the textfield as a separated UI element or by standard background color of the editable textfield (color of button in case of non-editable Combo Box). 
  
   
  Some implementations of Combo Box display visual separator if user hovers the Combo Box (try to hover the Combo Box below):
  
  
• Prompt message inside the textfield area (a simple label or combined with a shortcut too)
  A prompt is a label or short instruction placed inside a textfield as its default value.
  It can be just static text in case of non-editable Combo Box:
  
  
  
  Or some kind of hint that disappears once users type something into the textfield or it gets focus. Then typical color of the text is grey instead of black one:
  
  
  
  
• Drop Down button
  Drop-down button is typically placed on the right hand side to textfield and clearly visually separated if the textfield is editable. We should allow to customize it (by CSS), so it can look more like a part of the textfield, e.g.:
  
  
  
  Or it can be placed on the left side of the textfield:
  
  

• Drop Down list area (preview, items in the list, separators, custom cells, scroll bar/arrows) 
• Text items - There are just text items in the expanded Combo Box list and user can choose one item by Up/Down arrow keys or by mouse. The selected item is highlighted by different color then focused one and it's populated to the textfield area. User makes confirmation of the focused item by Space or Enter Key. He can cancel the drop down list by Esc key or upon clicking on the drop down button.

• Scroll Bar is being displayed when there are more items in the drop down list than the defined max. The maximum visible amount can be customized. We use Up & Down arrow buttons instead of Scrollbar for Choice Box UI control or for Menu UI control and it's ok because they are expected to contain only limited amount of items. 
  
  
  
  
• Items with icons - There can be icons placed next to the items in the drop down list. Then the textfield typically contains only the text information.
  
  
  
  
• Complex Custom Cells - Items in the list can be visualized as complex custom cells instead of simple labels with icons. When an item is selected then just the main text information is populated into the textfield.
  
  
  
  
• Preview (Many items in the list, Simple Drop Down list, Editable textfield and Autocompletion, Simple text as a value) - The whole dropdown list area works as a preview for the value in the textfield or every item in the drop down list is showing a preview of items and their own values (e.g. Combo Box showing list of fonts).
  
  
  
  
• Autocomplete functionality (Many items in the list, Simple Drop Down list - Search results, Editable textfield, Simple text as a value. E.g. Google, Firefox, or Adobe tools) - Drop down list appears automatically when user starts to type a text in the textfield and it will display list of suggestions. Autocomplete enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering. Filed as a feature request RT-18130.
  
  
  

4. Navigation

Mouse Support

The following table describes actions that are performed when users click on:

Touch Support

The following table describes actions that are performed when users tap on:

Directional Keys + OK/Select Support

The following table describes actions that are performed when users navigate to the Combo box using the arrow keys and press:

Please note that Editable Combo box is not supported on platforms with lack of keyboard.

Keyboard Support

The following table describes how keystrokes should be processed in case Combo box has focus on Win and Mac platforms: