ComboBox¶

Overview¶

Scenery-based combo box. Composed of a button and a popup 'list box' of items. ComboBox has no interaction of its own, all interaction is handled by its subcomponents. The list box is displayed when the button is pressed, and dismissed when an item is selected, the user clicks on the button, or the user clicks outside the list. The list can be displayed either above or below the button.

The supporting types and classes are:

ComboBoxItem - items provided to ComboBox constructor ComboBoxButton - the button ComboBoxListBox - the list box ComboBoxListItemNode - an item in the list box

For info on ComboBox UI design, including a11y, see https://github.com/phetsims/sun/blob/main/doc/ComboBox.md

@author Chris Malley (PixelZoom, Inc.)

Class ComboBox¶

import { ComboBox } from 'scenerystack/sun';

Constructor¶

new ComboBox( property : PhetioProperty<T>, items : ComboBoxItem<T>[], listParent : Node, providedOptions? : ComboBoxOptions )¶

Instance Methods¶

dispose()¶

showListBox()¶

Shows the list box.

hideListBox()¶

Hides the list box.

setItemVisible( value : T, visible : boolean )¶

Sets the visibility of items that correspond to a value. If the selected item has this value, it's your responsibility to change the Property value to something else. Otherwise, the combo box button will continue to display this value. @param value - the value associated with the ComboBoxItem @param visible

isItemVisible( value : T ) : boolean¶

Is the item that corresponds to a value visible when the listbox is popped up? @param value - the value associated with the ComboBoxItem

setInputEnabledProperty( newTarget : TReadOnlyProperty<boolean> | null ) : this¶

Instance Properties¶

nodes : Node[]¶

(readonly)

List of nodes created from ComboBoxItems to be displayed with their corresponding value. See ComboBoxItem.createNode().

button : ComboBoxButton<T>¶

button that shows the current selection (internal)

Static Methods¶

getMaxItemWidthProperty( nodes : Node[] ) : TReadOnlyProperty<number>¶

getMaxItemHeightProperty( nodes : Node[] ) : TReadOnlyProperty<number>¶

Static Properties¶

ComboBoxIO : IOType¶

Type ComboBoxAlign¶

import type { ComboBoxAlign } from 'scenerystack/sun';

"left" | "right" | "center"

Type ComboBoxItem¶

import type { ComboBoxItem } from 'scenerystack/sun';

• value: T
  the value associated with the item
• soundPlayer?: TSoundPlayer | null
  Sound that will be played when this item is selected. If set to null a default sound will be used that is based on this item's position in the combo box list. A value of nullSoundPlayer can be used to disable.
• accessibleName?: PDOMValueType | null
  pdom - the label for this item's associated Node in the combo box
• comboBoxListItemNodeOptions?: ComboBoxListItemNodeOptions
  Options passed to ComboBoxListItemNode, the Node that appears in the listBox
• & GroupItemOptions

Type ComboBoxItemNoNode¶

Most usages of the items should not be able to create the Node, but rather should use the corresponding nodes array, hence the type name "No Node".

import type { ComboBoxItemNoNode } from 'scenerystack/sun';

StrictOmit<ComboBoxItem<T>, "createNode">

Type ComboBoxListPosition¶

import type { ComboBoxListPosition } from 'scenerystack/sun';

"above" | "below"

Type ComboBoxOptions¶

import type { ComboBoxOptions } from 'scenerystack/sun';

• align?: ComboBoxAlign
• listPosition?: ComboBoxListPosition
• labelXSpacing?: number
  horizontal space between label and combo box
• disabledOpacity?: number
  opacity used to make the control look disabled, 0-1
• cornerRadius?: number
  applied to button, listBox, and item highlights
• highlightFill?: TPaint
  highlight behind items in the list
• xMargin?: number
  Margins around the edges of the button and listbox when highlight is invisible. Highlight margins around the items in the list are set to ½ of these values. These values must be > 0.
• yMargin?: number
• buttonFill?: TColor
  button
• buttonStroke?: TPaint
• buttonLineWidth?: number
• buttonTouchAreaXDilation?: number
• buttonTouchAreaYDilation?: number
• buttonMouseAreaXDilation?: number
• buttonMouseAreaYDilation?: number
• listFill?: TPaint
  list
• listStroke?: TPaint
• listLineWidth?: number
• openedSoundPlayer?: TSoundPlayer
  Sound generators for when combo box is opened and for when it is closed with no change (closing with a change is handled elsewhere).
• closedNoChangeSoundPlayer?: TSoundPlayer
• buttonLabelTagName?: string
  pdom The tag name for the label of the ComboBox. The AccessibleNameBehavior forwards the name to the ComboBoxButton, so if you need a different tag name for the ComboBox, set it here. See the ACCESSIBLE_NAME_BEHAVIOR functions for ComboBox and ComboBoxButton.
• comboBoxVoicingNameResponsePattern?: TReadOnlyProperty<string> | string
  Voicing ComboBox does not mix Voicing, so it creates custom options to pass to composed Voicing Nodes. The pattern for the name response string, must include {{value}} so that the selected value string can be filled in.
• comboBoxVoicingContextResponse?: ( () => string | null ) | null
  most context responses are dynamic to the current state of the sim, so lazily create them when needed.
• comboBoxVoicingHintResponse?: SpeakableResolvedResponse | null
  string for the voicing response
• & StrictOmit<TrimParallelDOMOptions<ParentOptions>, "children">

Source Code¶

See the source for ComboBox.ts in the sun repository.