list-box%

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

• (make-object list-box% label choices parent callback style) -> list-box% object
      label : string or #f
      choices : list of strings
      parent : frame%, dialog%, panel%, or pane% object
      callback : procedure of two arguments: a list-box% object and a control-event% object
      style = '(single) : list of symbols in '(single multiple extended)

  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 MacOS, 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). Mnemonic keyboard events are handled by on-traverse-char (but not under MacOS).

  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 even 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 the selection. 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.

  In addition to the selection style, the style list can include one or more of the following:

  • 'always-sb -- Creates the vertical scrollbar immediately (otherwise, in Windows, the scrollbar is not created until it is necessary).
  • 'hscroll -- Creates a horizontal scrollbar if the item strings are two wide (otherwise the string items are clipped).

  
  

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

• 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-graphical-min-size from area<%>
• get-height from window<%>
• get-label from window<%>
• 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<%>
• 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<%>