5.3 DUIM-Sheets Module

choose-from-dialog

Generic function

Summary

Prompt the user to choose from a collection of items, using a dialog box.

Signature

choose-from-dialog items 
  #key frame owner title value default-item label-key value-key 
       selection-mode gadget-class gadget-options width height 
       foreground background text-style 
=> value success?

Arguments

items: An instance of type-union(<sequence>, <menu>).
frame: An instance of type <frame>. Default value: #f.
owner: An instance of type <sheet>. Default value: #f.
title: An instance of type <string>.
default-item: An instance of type <object>.
label-key: An instance of type <function>. Default value: identity.
value-key: An instance of type <function>. Default value: identity.
selection-mode: An instance of <symbol>. Default value: #"single".
gadget-class: An instance of type <gadget>.
gadget-options: An instance of type <sequence>.
foreground: An instance of type <ink>.
background: An instance of type <ink>.
text-style: An instance of type <text-style>.

Values

value: An instance of type <object>.
success?: An instance of type <boolean>.

Library

duim-sheets

Module

duim-sheets

Description

Prompt the user to choose from a collection of items, using a dialog box. This generic function is similar to choose-from-menu.

The function returns the values chosen by the user, and a boolean value: #t if a value was chosen, #f if nothing was chosen. Unlike choose-from-menu, the user can choose several values if desired, depending on the value of selection-mode, described below.

At its most basic, choose-from-dialog can be passed a simple sequence of items, as follows:

  choose-from-dialog(range(from: 1, to: 10));

However, any of a large number of keywords can be supplied to specify more clearly the dialog that is created. A range of typical options can be chosen: The frame keyword specifies a frame whose top level sheet becomes the owner of the menu. Alternatively, you can specify this top level sheet explicitly using owner. The title keyword lets you choose a title for the dialog. By default, each of these values is #f.

In addition, choose-from-dialog offers options similar to collection gadgets, that can act upon the items specified. The default-item keyword lets you specify an item that is returned by default if no value is chosen explicitly (thereby ensuring that success? will always be #t). You can also specify a value-key or label-key for the items in the menu. The selection-mode keyword is used to make the dialog box single-selection (the user can only choose one value) or multiple-selection (the user can return any number of values). The default value of selection-mode is #"single". By specifying selection-mode: #"multiple", the user can choose several values from the dialog box. The gadget-class keyword lets you specify which type of collection gadget is displayed in the dialog box. This lets you, for example, display a list of check boxes or radio boxes. Finally, gadget-options let you specify a set of options to be applied to the collection gadgets in the dialog box.

You can also configure the appearance of the menu itself. The width and height keywords let you set the size of the menu. The foreground and background keywords let you set the text color and the menu color respectively. The text-style keyword lets you specify a font to display the menu items.