A pop-up menu which which synchronizes with a target object's string value by executing specified getter and setter functions.

Getter and Setter Functions

The setter and getter functions are used to synchronize the menu and target object.

  • the getter returns the string value that corresponds to the target state

  • the setter modifies the target state to correspond to the given string value

The menu is initially set to show the the target's current value, as given by the getter.

When a menu item is selected, the target is modified by calling the setter with the value corresponding to the selected choice.

Choices and Values

ChoiceControlBase has two (same-length) arrays:

  • The array of choices are the strings which are displayed in the menu. These should be localized (translated) strings.

  • The array of values are strings that correspond to each choice. The value is given to the setter function to change the target object.

No Selection State

A ChoiceControlBase can be in a state of 'no selection', which is indicated by index of –1 in setChoice or getChoice. In this case, the menu item shown is blank (no text is shown, just empty space). This happens when the value returned by the getter function is not among the array of ChoiceControlBase values.

When moving into a state of 'no selection', no notification is given via the specified setter function. When moving out of the 'no selection' state, the setter is called as normal.

Updating The Control

To keep the control in sync with the target object, call the observe method whenever a change in the value of the target object occurs. If the target object is a Subject then you can add this control as an Observer of the Subject.

Hierarchy (view full)



  • Parameters

    • choices: string[]

      an array of localized strings giving the names of the menu items.

    • values: string[]

      array of values corresponding to the choices, in string form; these values will be supplied to the setter function when the corresponding menu item is chosen

    • getter: (() => string)

      function that returns the value that corresponds to the target's current state

        • (): string
        • Returns string

    • setter: ((value) => void)

      function that modifies the target's state to be the given string value

        • (value): void
        • Parameters

          • value: string

          Returns void

    • Optional opt_label: null | string

      the text label to show besides this choice; if null or undefined or empty string then no label is made.

    Returns ChoiceControlBase


choices: string[]

The menu items shown to the user for each choice, an array of localized (translated) strings.

currentIndex_: number

the currently selected item, or -1 if no item selected


  • Returns the index of the currently selected choice, or -1 if no item selected. The first item has index zero. See setChoice.

    Returns number

    the index of the currently selected choice, or -1 if no item selected

  • Returns the top level Element of this control. For example, this might be a label Element that encloses an input Element.

    Returns HTMLElement

    the top level Element of this control

  • Notifies this Observer that a change has occurred in the Subject.


    • _event: SubjectEvent

      contains information about what has changed in the Subject: typically either a one-time GenericEvent, or a change to the value of a Parameter

    Returns void

  • Changes the menu item shown by this control, and sets the target to have the corresponding value by firing the setter function. An index of -1 causes this control to enter the "no selection" state.


    • index: number

      the index of the chosen item within array of choices, where the first item has index zero and -1 means no item is selected

    Returns void

  • Changes the array of choices and modifies the current choice to match the target's state. The setter function is not called.


    • choices: string[]

      the new set of choices to display

    • values: string[]

      the new set of values that correspond to the choices

    Returns void


    if choices and values have different length

  • Returns a minimal string representation of this object, usually giving just identity information like the class name and name of the object.

    For an object whose main purpose is to represent another Printable object, it is recommended to include the result of calling toStringShort on that other object. For example, calling toStringShort() on a DisplayShape might return something like this:


    Returns string

    a minimal string representation of this object.

Generated using TypeDoc