| ||
superclass: object% | ||
|
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 & 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.
'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.
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
item : label-string? data : any/c = #f
See also append in list-control<%>.
method
(send a-list-box append-column label) → void?
label : label-string?
method
n : exact-nonnegative-integer?
Selected items that are not deleted remain selected, and no other items are selected.
method
(send a-list-box delete-column n) → void?
n : exact-nonnegative-integer?
method
(send a-list-box get-column-labels)
→ (cons/c label-string? (listof label-string?))
method
(send a-list-box get-column-order)
→ (listof exact-nonnegative-integer?)
See also set-column-order.
method
(send a-list-box get-column-width column)
→
(integer-in 0 10000) (integer-in 0 10000) (integer-in 0 10000) column : exact-nonnegative-integer?
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.
method
n : exact-nonnegative-integer?
method
(send a-list-box get-first-visible-item)
→ exact-nonnegative-integer?
method
(send a-list-box get-label-font) → (is-a?/c font%)
method
(send a-list-box get-selections)
→ (listof exact-nonnegative-integer?)
For single-selection lists, the result is always either null or a list containing one number.
method
(send a-list-box is-selected? n) → boolean?
n : exact-nonnegative-integer?
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.
method
(send a-list-box number-of-visible-items)
→ exact-positive-integer?
method
n : exact-nonnegative-integer? select? : any/c = #t
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.
method
choices : (listof label-string?)
method
(send a-list-box set-column-label column label) → void? column : exact-nonnegative-integer? label : label-string?
method
(send a-list-box set-column-order column-order) → void?
column-order : (listof exact-nonnegative-integer?)
See also get-column-order.
method
(send a-list-box set-column-width column width min-width max-width) → void? column : exact-nonnegative-integer? width : (integer-in 0 10000) min-width : (integer-in 0 10000) max-width : (integer-in 0 10000)
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.
method
n : exact-nonnegative-integer? data : any/c
See also append.
method
(send a-list-box set-first-visible-item n) → void?
n : exact-nonnegative-integer?
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.
method
(send a-list-box set-string n label [column]) → void?
n : exact-nonnegative-integer? label : label-string? column : exact-nonnegative-integer? = 0