MultiSelectionBox

MultiSelectionBox
	Standard (mandatory) widgets

Name

MultiSelectionBox — Selection box that allows selecton of multiple items

Synopsis

`MultiSelectionBox (`	string	`label` ,
	list	`items` `)`;

Parameters

string label
list items: the items initially contained in the selection box

Options

shrinkable

make the widget very small

Properties

string Label: The label above the list describing what it is all about
string CurrentItem: The item that currently has the keyboard focus
id_list SelectedItems: The items that are currently selected

Description

The MultiSelectionBox displays a ( scrollable ) list of items from which any number ( even nothing! ) can be selected. Use the MultiSelectionBox's SelectedItems property to find out which.

Each item can be specified either as a simple string or as `item( ... ) which includes an ( optional ) ID and an ( optional ) 'selected' flag that specifies the initial selected state ( 'not selected', i.e. 'false', is default ).

Usage

 	`MultiSelectionBox( `id( `topping ), "select pizza toppings:", [ "Salami", `item( `id( `cheese ), "Cheese", true ) ] )

Examples

          {
    // Simple MultiSelectionBox example:
    //
    // All items are simple strings, none has an ID, no item preselected.
    
    UI::OpenDialog(
	       `VBox( 
		     `MultiSelectionBox( "Select pizza toppings:",
					 [
					  "Cheese",
					  "Tomatoes",
					  "Mushrooms",
					  "Onions",
					  "Salami",
					  "Ham"
					 ] ),
		     `PushButton("&OK")
		     )
	       );
    UI::UserInput();
    UI::CloseDialog();
}

          {
    // More realistic MultiSelectionBox example:
    //
    // Items have IDs, some are preselected.
    // Notice 'false' is default anyway for the selection state,
    // so you may or may not explicitly specify that.
    
    UI::OpenDialog(
	       `VBox( 
		     `MultiSelectionBox( "Select pizza toppings:",
					 [
					  `item( `id(`cheese   	), "Cheese"	, true  ),
					  `item( `id(`tomatoes 	), "Tomatoes"	, true  ),
					  `item( `id(`mush     	), "Mushrooms"	, false ),
					  `item( `id(`onions	), "Onions" 	),
					  `item( `id(`sausage	), "Salami" 	),
					  `item( `id(`pork	), "Ham"	)
					 ] ),
		     `PushButton( `opt(`default), "&OK")
		     )
	       );
    UI::UserInput();
    UI::CloseDialog();
}

          {
    // Advanced MultiSelectionBox example:
    //
    // Retrieve the list of selected items and output it.
    
    UI::OpenDialog(
	       `VBox( 
		     `MultiSelectionBox( `id(`toppings), "Select pizza toppings:",
					 [
					  `item( `id(`cheese   	), "Cheese"	, true  ),
					  `item( `id(`tomatoes 	), "Tomatoes"	, true  ),
					  `item( `id(`mush     	), "Mushrooms"	, false ),
					  `item( `id(`onions	), "Onions" 	),
					  `item( `id(`sausage	), "Salami" 	),
					  `item( `id(`pork	), "Ham"	)
					 ] ),
		     `PushButton( `opt(`default), "&OK")
		     )
	       );
    UI::UserInput();
    list selected_items = (list) UI::QueryWidget( `id(`toppings), `SelectedItems );
    
    // Remember to retrieve the widget's data _before_ the dialog is closed,
    // i.e. before it is destroyed!
    
    UI::CloseDialog();

    
    
    // Concatenate the list of selected toppings to one multi-line string.
    
    string pizza_description = "";

    foreach ( `topping, selected_items, ``{
	pizza_description = sformat( "%1\n%2", pizza_description, topping );
    } );


    // Open a new dialog to echo the selection.
    
    UI::OpenDialog(
	       `VBox(
		     `Label( "Your pizza will come with:\n" ),
		     `Label( pizza_description ),
		     `PushButton( `opt(`default), "&OK" )
		     )
	       );
    UI::UserInput();
    UI::CloseDialog();
}


SelectionBox		ComboBox