3.27  list-box%

Implements: 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 _) (choices _) (parent _) [(callback _)] [(style _)] [(selection _)] [(font _)] [(label-font _)] [(enabled _)] [(vert-margin _)] [(horiz-margin _)] [(min-width _)] [(min-height _)] [(stretchable-width _)] [(stretchable-height _)]) -> list-box% object
     label : string (up to 200 characters) or #f
   choices : list of strings (up to 200 characters each)
     parent : frame%, dialog%, panel%, or pane% object
     callback = (lambda (lb e) (void)) : procedure of two arguments: a list-box% object and a control-event% object
     style = '(single) : list of symbols in '(single multiple extended vertical-label horizontal-label deleted)
   selection = #f : exact non-negative integer or #f
   font = view-control-font : font% object
     label-font = normal-control-font : font% object
     enabled = #t : boolean
     vert-margin = 2 : exact integer in [0, 1000]
     horiz-margin = 2 : exact integer in [0, 1000]
     min-width = graphical minimum width : exact integer in [0, 10000]
     min-height = graphical minimum height : exact integer in [0, 10000]
     stretchable-width = #t : boolean
     stretchable-height = #t : boolean

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

  If an ampersand (``&'') occurs in label, it is specially parsed; under Windows and X, the character following an ampersand is underlined in the displayed control to indicate a keyboard mnemonic. (Under Mac OS X, mnemonic underlines are not shown.) The underlined mnemonic character must be a letter or a digit. The user can move the keyboard focus to the list box by typing the mnemonic when the control's top-level-window contains the keyboard focus. The user must also hold down the Meta or Alt key if the keyboard focus is currently in a control that handles normal alphanumeric input. The ampersand itself is removed from label before it is displayed for the control; a double-ampersand in label is converted to a single ampersand (with no mnemonic underlining). Under Mac OS X, a parenthesized mnemonic character is removed (along with any surrounding space) before the label is displayed, since a parenthesized mnemonic is often used for non-Roman languages. Finally, any text after a tab character is removed on all platforms. Mnemonic keyboard events are handled by on-traverse-char (but not under Mac OS X).

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

  
  

Methods
    append
    delete
    get-data
    get-first-visible-item
    get-label-font
    get-selections
    is-selected?
    number-of-visible-items
    select
    set
    set-data
    set-first-visible-item
    set-string

All Methods
    accept-drop-files from window<%>
    append from list-box%
        overrides append from list-control<%>
    clear from list-control<%>
    client->screen from window<%>
    command from control<%>
    delete from list-box%
    enable from window<%>
    find-string from list-control<%>
    focus from window<%>
    get-client-size from window<%>
    get-cursor from window<%>
    get-data from list-box%
    get-first-visible-item from list-box%
    get-font from control<%>
    get-graphical-min-size from area<%>
    get-handle from window<%>
    get-height from window<%>
    get-label from window<%>
    get-label-font from list-box%
    get-number from list-control<%>
    get-parent from area<%>
    get-plain-label from window<%>
    get-selection from list-control<%>
    get-selections from list-box%
    get-size from window<%>
    get-string from list-control<%>
    get-string-selection from list-control<%>
    get-top-level-window from area<%>
    get-width from window<%>
    get-x from window<%>
    get-y from window<%>
    has-focus? from window<%>
    horiz-margin from subarea<%>
    is-enabled? from window<%>
    is-selected? from list-box%
    is-shown? from window<%>
    min-height from area<%>
    min-width from area<%>
    number-of-visible-items from list-box%
    on-drop-file from window<%>
    on-focus from window<%>
    on-move from window<%>
    on-size from window<%>
    on-subwindow-char from window<%>
    on-subwindow-event from window<%>
    on-superwindow-enable from window<%>
    on-superwindow-show from window<%>
    popup-menu from window<%>
    refresh from window<%>
    screen->client from window<%>
    select from list-box%
    set from list-box%
    set-cursor from window<%>
    set-data from list-box%
    set-first-visible-item from list-box%
    set-label from window<%>
    set-selection from list-control<%>
    set-string from list-box%
    set-string-selection from list-control<%>
    show from window<%>
    stretchable-height from area<%>
    stretchable-width from area<%>
    vert-margin from subarea<%>