The ListBox window body element defines a list box in a Maplet application. This is a list of objects from which the user can select zero or more entries.

In a running a Maplet application, the value of a ListBox is the comma-separated list of entries selected by the user.  When returned, it can be converted to an expression sequence of strings by using the Maplets[Tools][ListBoxSplit] command.  The behavior of a list box is:

Selecting an item clears previously selected items.

Selecting an item while holding the CTRL key selects that item and previously selected items.

Selecting an item while holding the SHIFT key clears previously selected items and selects all items between, and including, the two most recently selected items.

The ListBox element features can be modified by using options. To simplify specifying options in the Maplets package, certain options and contents can be set without using an equation. The following table lists elements, symbols, and types (in the left column) and the corresponding option or content (in the right column) to which inputs of this type are, by default, assigned.

A ListBox element can contain Item elements. A ListBox element can contain Action or command elements to specify the onchange option and a Font element to specify the font option.

A ListBox element can be contained in a Maplet or BoxLayout element, or Maplet element in a nested list representing a box layout.

The following table describes the control and use of the ListBox element options.

An x in the I column indicates that the option can be initialized, that is, specified in the calling sequence (element definition).

An x in the R column indicates that the option is required in the calling sequence.

An x in the G column indicates that the option can be read, that is, retrieved by using the Get tool.

An x in the S column indicates that the option can be written, that is, set by using the SetOption element or the Set tool.

* appenditem appends an item to the list of items in the list box. Its syntax is refID(appenditem)="text", where refID is a reference to the list box.

* itemlist overwrites the existing list.  It can be set during the execution of an Evaluate command using the Maplets:-Tools:-Set(refID(itemlist)=[item1, item2, ..., itemn]) command, where refID is a reference to the list box and item1, item2, ..., itemn are the new items for the list box.

The opts argument can contain one or more of the following equations that set Maplet application options.

background = color

The color of the list box.  This can be a recognized color name, an RGB color structure, or a string of the form "#RRGGBB" where each pair is a two-digit hexadecimal number.

enabled = true or false

Whether an item from the list box can be selected.  If enabled is set to false, the list box is dimmed, and any action associated with it cannot be initiated.  By default, the value is true.

font = Font element or reference to a Font element (name or string)

The text font in the list box.

foreground = color

The color of the text in the list box.  This can be a recognized color name, an RGB color structure, or a string of the form "#RRGGBB" where each pair is a two-digit hexadecimal number.

halign = left, center, or right

Specifies the horizontal alignment for the list box contents. By default this is left.

onchange = Action or command element, or reference to an Action element (name or string)

The action that occurs when the value of the list box changes.

reference = name or string

A reference for the ListBox element.

If the reference is specified by both an index, for example, ListBox[refID], and a reference in the calling sequence, the index reference takes precedence.

tooltip = string

The text that appears in the tooltip help window.

valign = top, center, or bottom

Specifies the vertical alignment for the list box contents.

value = string or symbol

The initial value of the list box.  If no value is specified, or if the value is not an item in the list box, the initial value is the first item specified in list_box_content.

visible = true or false

Whether the list box is visible to the user.  By default, the value is true.

width = posint

The width in pixels. By default the list box is sized to fit its content.

$\mathrm{with}\left(\mathrm{Maplets}\left[\mathrm{Elements}\right]\right)\:$

$\mathrm{maplet}≔\mathrm{Maplet}\left(\left[\left[''Pick\; a\; color:''\,\mathrm{ListBox}\left['\mathrm{LB1}'\right]\left(\mathrm{sort}\left(\left[''blue''\,''red''\,''wheat''\,''yellow''\,''brown''\,''gold''\,''plum''\,''orange''\,''pink''\,''khaki''\,''magenta''\,''maroon''\,''white''\,''green''\,''aquamarine''\,''black''\,''gray''\,''navy''\,''coral''\,''cyan''\,''sienna''\,''tan''\,''turquoise''\,''violet''\right]\,\mathrm{lexorder}\right)\right)\right]\,\left[\mathrm{Button}\left(''OK''\,\mathrm{Shutdown}\left(\left['\mathrm{LB1}'\right]\right)\right)\,\mathrm{Button}\left(''Cancel''\,\mathrm{Shutdown}\left(\right)\right)\right]\right]\right)\:$

$\mathrm{result}≔\mathrm{Maplets}\left[\mathrm{Display}\right]\left(\mathrm{maplet}\right)\:$

$$\begin{gathered} \mathbf{if}\mathrm{type}\left(\mathrm{result}\,\left['\mathrm{string}'\right]\right)\mathbf{then} \\ \mathrm{Maplets}\left[\mathrm{Tools}\right]\left[\mathrm{ListBoxSplit}\right]\left(\mathrm{result}\left[1\right]\right) \\ \mathbf{end}\mathbf{if} \end{gathered}$$