list-box% : class?

superclass: object%

extends:  list-control<%>

A list box allows the user to select one or more string items from a scrolling list. A list box is either a single-selection control (if an item is selected, the previous selection is removed) or a multiple-selection control (clicking an item toggles the item on or off independently of other selections).

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.

List box items are indexed from 0.

See also choice%.

(new list-box%   [label label]       [choices choices]       [parent parent]      [ [callback callback]       [style style]       [selection selection]       [font font]       [label-font label-font]       [enabled enabled]       [vert-margin vert-margin]       [horiz-margin horiz-margin]       [min-width min-width]       [min-height min-height]       [stretchable-width stretchable-width]       [stretchable-height stretchable-height]])

→ (is-a?/c list-box%)

label : (or/c label-string? false/c)

choices : (listof label-string?)

parent   :   (or/c (is-a?/c frame%) (is-a?/c dialog%)       (is-a?/c panel%) (is-a?/c pane%))

callback   :   ((is-a?/c list-box%) (is-a?/c control-event%) . -> . any)       =   (lambda (c e) (void))

style   :   (listof (one-of/c 'single 'multiple 'extended                   'vertical-label 'horizontal-label                   'deleted))       =   '(single)

selection : (or/c nonnegative-exact-integer? false/c) = #f

font : (is-a?/c font%) = (scheme view-control-font)

label-font : (is-a?/c font%) = (scheme normal-control-font)

enabled : any/c = #t

vert-margin : (integer-in 0 1000) = 2

horiz-margin : (integer-in 0 1000) = 2

min-width : (integer-in 0 10000) = graphical-minimum-width

min-height : (integer-in 0 10000) = graphical-minimum-height

stretchable-width : any/c = #t

stretchable-height : any/c = #t

If label is not #f, it is used as the list box label. Otherwise, the list box will not display its label.

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.

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 style specification must include exactly one of the following:

• 'single – Creates a single-selection list.

• 'multiple – Creates a multiple-selection list where a single click deselects other items and selects a new item. Use this style for a list when single-selection is common, but multiple selections are allowed.

• 'extended – Creates a multiple-selection list where a single click extends or contracts the selection by toggling the clicked item. Use this style for a list when multiple selections are the rule rather than the exception.

The 'multiple and 'extended styles determine a platform-independent interpretation of unmodified mouse clicks, but dragging, shift-clicking, control-clicking, etc. have platform-standard interpretations. Whatever the platform-specific interface, the user can always select disjoint sets of items or deselect items (and leave no items selected). On some platforms, the user can deselect the (sole) selected item in a 'single list box.

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 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<%>.

(send a-list-box append item [data]) → void?

item : string

data : any/c = #f

Overrides append in list-control<%>.

Adds a new item to the list box with an associated “data” object. The data object is not displayed in the list box; it is provided merely as a convenience for use with get-data, possibly allowing a programmer to avoid managing a separate item-to-data mapping in addition to the list box control.

See also append in list-control<%>.

(send a-list-box delete n) → void?

n : nonnegative-exact-integer?

Deletes the item indexed by n. List box items are indexed from 0. If n is equal to or larger than the number of items in the control, an exn:fail:contract exception is raised.

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

(send a-list-box get-data n) → any/c

n : nonnegative-exact-integer?

Returns the data for the item indexed by n, or #f if there is no associated data. List box items are indexed from 0. If n is equal to or larger than the number of choices, an exn:fail:contract exception is raised.

See also append and set-data.

(send a-list-box get-first-visible-item)

→ nonnegative-exact-integer?

Reports the index of the item currently scrolled to the top of the list box. List box items are indexed from 0.

(send a-list-box get-label-font) → (is-a?/c font%)

Returns the font used for the control’s label, which is optionally supplied when a list box is created.

(send a-list-box get-selections)

→ (listof nonnegative-exact-integer?)

Returns a list of indices for all currently selected items. List box items are indexed from 0.

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

(send a-list-box is-selected? n) → boolean?

n : nonnegative-exact-integer?

Returns #t if the item index by n is selected, #f otherwise. List box items 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 controlcallback procedure (provided as an initialization argument) to monitor selection changes.

(send a-list-box number-of-visible-items)

→ positive-exact-integer?

Returns the maximum number of items in the list box that are visible to the user with the control’s current size (rounding down if the exact answer is fractional, but returning at least 1).

(send a-list-box select n [select?]) → void?

n : nonnegative-exact-integer?

select? : any/c = #t

Selects or deselects an item. For selection in a single-selection list box, if a different choice is currently selected, it is automatically deselected. For selection in a multiple-selection list box, other selections are preserved, unlike set-selection.

If select? is #f, the item indexed by n is deselected; otherwise it is selected. List box items 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 controlcallback procedure (provided as an initialization argument) to monitor selection changes.

The control’s callback procedure is not invoked.

(send a-list-box set choices) → void?

choices : (listof label-string?)

Clears the list box and installs a new list of items.

(send a-list-box set-data n data) → void?

n : nonnegative-exact-integer?

data : any/c

Sets the associated data for item indexed by n. List box items are indexed from 0. If n is equal to or larger than the number of choices, an exn:fail:contract exception is raised.

See also append.

(send a-list-box set-first-visible-item n) → void?

n : nonnegative-exact-integer?

Scrolls the list box so that the item indexed by n is at the top of the list box display. List box items 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 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.

(send a-list-box set-string n label) → void?

n : nonnegative-exact-integer?

label : label-string?

Sets the item indexed by n. List box items are indexed from 0. If n is equal to or larger than the number of choices, an exn:fail:contract exception is raised.