2.27 list-box%

class
list-box% : class?

superclass: object%

extends:

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.

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

constructor
(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]
    [columns columns]
    [column-order column-order]])
→ (is-a?/c list-box%)
  label : (or/c label-string? #f)
  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 (or/c 'single 'multiple 'extended
              'vertical-label 'horizontal-label
              'variable-columns 'column-headers
              'clickable-headers 'reorderable-headers
              'deleted))
= '(single)
  selection : (or/c exact-nonnegative-integer? #f) = #f
  font : (is-a?/c font%) = view-control-font
  label-font : (is-a?/c font%) = 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
   columns : (cons/c label-string? (listof label-string?))
= '("Column")
   column-order : (or/c #f (listof exact-nonnegative-integer?))
= #f

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

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

method
(send a-list-box append item [data]) → void?
item : label-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.

1	Windowing
2	Windowing Classes
3	Windowing Functions
4	Editors
5	Snip and Style Classes
6	Editor Classes
7	Editor Functions
8	WXME Decoding
9	Preferences
10	Dynamic Loading
11	Startup Actions
12	Platform Dependencies
	Index

2.1	area<%>
2.2	area-container<%>
2.3	area-container-window<%>
2.4	button%
2.5	canvas<%>
2.6	canvas%
2.7	check-box%
2.8	checkable-menu-item%
2.9	choice%
2.10	clipboard-client%
2.11	clipboard<%>
2.12	combo-field%
2.13	control<%>
2.14	column-control-event%
2.15	control-event%
2.16	cursor%
2.17	dialog%
2.18	event%
2.19	frame%
2.20	gauge%
2.21	group-box-panel%
2.22	grow-box-spacer-pane%
2.23	horizontal-pane%
2.24	horizontal-panel%
2.25	key-event%
2.26	labelled-menu-item<%>
2.27	list-box%
2.28	list-control<%>
2.29	menu%
2.30	menu-bar%
2.31	menu-item<%>
2.32	menu-item%
2.33	menu-item-container<%>
2.34	message%
2.35	mouse-event%
2.36	pane%
2.37	panel%
2.38	popup-menu%
2.39	printer-dc%
2.40	radio-box%
2.41	selectable-menu-item<%>
2.42	separator-menu-item%
2.43	scroll-event%
2.44	slider%
2.45	subarea<%>
2.46	subwindow<%>
2.47	tab-panel%
2.48	text-field%
2.49	timer%
2.50	top-level-window<%>
2.51	vertical-pane%
2.52	vertical-panel%
2.53	window<%>