Whenever the user changes the selection in a list box, the list box’s callback procedure is called. A callback procedure is provided as an initialization argument when each list box is created.

A list box can have multiple columns with optional column headers. An item in the list corresponds to a row that spans all columns. When column headers are displayed, the column widths can be changed by a user. In addition, columns can optionally support dragging by the user to change the display order of columns, while the logical order remains fixed.

List box rows and columns are indexed from 0.

See also choice%.

If & occurs in label, it is specially parsed as for button%.

The choices list specifies the initial list of items to appear in the list box. If the list box has multiple columns, choices determines the content of the first column, and other columns are initialized to the empty string.

The callback procedure is called when the user changes the list box selection, by either selecting, re-selecting, deselecting, or double-clicking an item. The type of the event provided to the callback is 'list-box-dclick when the user double-clicks on an item, or 'list-box otherwise.

The columns list determines the number of columns in the list box. The column titles in columns are shown only if style includes 'column-headers. If style also includes 'clickable-headers, then a click on a header triggers a call to callback with a column-control-event% argument whose event type is 'list-box-column.

If style includes 'vertical-label, then the list box is created with a label above the control; if style does not include 'vertical-label (and optionally includes 'horizontal-label), then the label is created to the left of the list box. If style includes 'deleted, then the list box is created as hidden, and it does not affect its parent’s geometry; the list box can be made active later by calling parent’s add-child method.

If style includes 'variable-columns, then the number of columns in the list box can be changed via append-column and delete-column.

If selection is an integer, it is passed to set-selection to set the initial selection. The selection must be less than the length of choices.

The font argument determines the font for the control content, and label-font determines the font for the control label. For information about the enabled argument, see window<%>. For information about the horiz-margin and vert-margin arguments, see subarea<%>. For information about the min-width, min-height, stretchable-width, and stretchable-height arguments, see area<%>.

It the column-order argument is not #f, it determines the order in which logical columns are initially displayed. See set-column-order for more information. If style includes 'column-headers and 'reorderable-headers, then a user can reorder columns as displayed (but the display order does not change the logical order of the columns).

See also append in list-control<%>.

Selected items that are not deleted remain selected, and no other items are selected.

See also set-column-order.

The result includes the column’s current width as well as its minimum and maximum widths to constrain the column size as adjusted by a user.

See also set-column-width.

See also append and set-data.

For single-selection lists, the result is always either null or a list containing one number.

A list box’s selection can be changed by the user clicking the control, and such changes do not go through this method; use the control callback procedure (provided as an initialization argument) to monitor selection changes.

If select? is #f, the item indexed by n is deselected; otherwise it is selected. List box rows are indexed from 0. If n is equal to or larger than the number of choices, an exn:fail:contract exception is raised.

A list box’s selection can be changed by the user clicking the control, and such changes do not go through this method; use the control callback procedure (provided as an initialization argument) to monitor selection changes.

The control’s callback procedure is not invoked.

See also get-column-order.

The width argument sets the current display width, while min-width and max-width constrain the width of the column when the user resizes it. The width argument must be no less than min-width and no more than max-width.

The default width of a column is platform-specific, and the last column of a list box may extend to the end of the control independent of its requested size.

See also get-column-width.

See also append.

A list box’s scroll position can be changed by the user clicking the control, and such changes do not go through this method. A program cannot detect when the scroll position changes except by polling get-first-visible-item.