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();
}