Name

Tree — Scrollable tree selection

Synopsis

Tree ( string  label ,
  itemList  items );

Parameters

string label

Optional Arguments

itemList items

the items contained in the tree

              
	itemList ::= 
		[ 
			item 
			[ , item ] 
			[ , item ] 
			... 
		] 
	item ::= 
		string | 
		`item( 
			[ `id( string  ),] 
			string 
			[ , true | false ] 
			[ , itemList ] 
		)  

The boolean parameter inside `item() indicates whether or not the respective tree item should be opened by default - if it has any subitems and if the respective UI is capable of closing and opening subtrees. If the UI cannot handle this, all subtrees will always be open.

Properties

string Label

the label above the Tree

itemId CurrentItem

the currently selected item

OpenItems a

map of open items - can only be queried, not set

Description

A tree widget provides a selection from a hierarchical tree structure. The semantics are very much like those of a SelectionBox. Unlike the SelectionBox, however, tree items may have subitems that in turn may have subitems etc.

Each item has a label string, optionally preceded by an ID. If the item has subitems, they are specified as a list of items after the string.

The tree widget will not perform any sorting on its own: The items are always sorted by insertion order. The application needs to handle sorting itself, if desired.

Usage

 	`Tree( `id( `treeID ), "treeLabel", [ "top1", "top2", "top3" ] );

Examples

          {
    UI::OpenDialog(
	       `VBox(
		     `Tree(`id(`dest_dir),
				   "Select destination directory:",
				   [
				    `item(`id(`root), "/" , true,
					  [
					   `item(`id(`etc), "etc",
						 [
						  `item("opt"),
						  `item("SuSEconfig"),
						  `item("X11")
						 ]
						 ),
					   `item("usr", false, 
						 [
						  "bin",
						  "lib",
						  `item("share",
						       [
							"man",
							"info",
							"emacs"
							]
						       ),
						  `item(`id(`usr_local),"local"),
						  `item("X11R6",
							[
							 "bin",
							 "lib",
							 "share",
							 "man",
							 "etc"
							 ]
							)
						  ]
						 ),
					   `item(`id(`opt), "opt", true,
						 [
						  "kde",
						  "netscape",
						  "Office51"
						  ]
						 ),
					   `item("home"),
					   "work",
					   `item(`id(`other), "<other>")
					   ]
					  )
				   ] ),
		     `HBox(
			   `PushButton(`id(`sel_opt),		`opt(`hstretch), "/&opt" ),
			   `PushButton(`id(`sel_usr),		`opt(`hstretch), "/&usr" ),
			   `PushButton(`id(`sel_usr_local),	`opt(`hstretch), "/usr/&local" )
			   ),
		     `PushButton(`id(`ok), `opt(`default), "&OK")
		     )
	       );

    any id = nil;

    repeat
	{
	    id = UI::UserInput();

	    if      ( id == `sel_usr)		UI::ChangeWidget( `id( `dest_dir ), `CurrentItem, "usr"  );
	    else if ( id == `sel_usr_local)	UI::ChangeWidget( `id( `dest_dir ), `CurrentItem, `usr_local );
	    else if ( id == `sel_opt) 		UI::ChangeWidget( `id( `dest_dir ), `CurrentItem, `opt );
	} until ( id == `ok );

    // Get the input from the tree.
    //
    // Notice: The return value of UI::UserInput() does NOT return this value!
    // Rather, it returns the ID of the widget (normally the PushButton)
    // that caused UI::UserInput() to return.
    string dest_dir = (string) UI::QueryWidget(`id(`dest_dir), `CurrentItem);

    if ( dest_dir == nil )
	dest_dir = "";

    // Close the dialog.
    // Remember to read values from the dialog's widgets BEFORE closing it!
    UI::CloseDialog();


    // Pop up a new dialog to echo the selection.
    UI::OpenDialog(
	       `VBox(
		     `Label("Selected destination directory: " + dest_dir),
		     `PushButton(`opt(`default), "&OK")
		     )
	       );
    UI::UserInput();

    UI::CloseDialog();
}

        
          {
    // Build a dialog with a tree for directory selection, three
    // buttons with common values and a label that directly echoes any
    // selected directory.
    //
    // The tree in this example uses the `notify option that makes
    // UI::UserInput() return immediately as soon as the user selects a
    // tree item rather than the default behaviour which waits for the
    // user to activate a button.
    
    UI::OpenDialog(
	       `VBox(
		     `Tree(`id(`dest_dir),
			   `opt(`notify),
				   "Select destination directory:",
				   [
				    `item(`id(`root), "/" , true,
					  [
					   `item(`id(`etc), "etc",
						 [
						  `item("opt"),
						  `item("SuSEconfig"),
						  `item("X11")
						 ]
						 ),
					   `item("usr", false, 
						 [
						  "bin",
						  "lib",
						  `item("share",
						       [
							"man",
							"info",
							"emacs"
							]
						       ),
						  `item(`id(`usr_local),"local"),
						  `item("X11R6",
							[
							 "bin",
							 "lib",
							 "share",
							 "man",
							 "etc"
							 ]
							)
						  ]
						 ),
					   `item(`id(`opt), "opt", true,
						 [
						  "kde",
						  "netscape",
						  "Office51"
						  ]
						 ),
					   `item("home"),
					   "work",
					   `item(`id(`other), "<other>")
					   ]
					  )
				   ] ),
		     `HBox(
			   `PushButton(`id(`sel_opt),		`opt(`hstretch), "/&opt" ),
			   `PushButton(`id(`sel_usr),		`opt(`hstretch), "/&usr" ),
			   `PushButton(`id(`sel_usr_local),	`opt(`hstretch), "/usr/&local" )
			   ),
		     `HBox(
			   `Label("Current Value:"),
			   `Label(`id(`echo), `opt(`outputField), "?????????")
			   ),
		     `PushButton(`id(`ok), `opt(`default), "&OK")
		     )
	       );

    any id = nil;

    repeat
	{
	    id = UI::UserInput();

	    if      ( id == `sel_usr)		UI::ChangeWidget( `id( `dest_dir ), `CurrentItem, "usr"  );
	    else if ( id == `sel_usr_local)	UI::ChangeWidget( `id( `dest_dir ), `CurrentItem, `usr_local );
	    else if ( id == `sel_opt) 		UI::ChangeWidget( `id( `dest_dir ), `CurrentItem, `opt );
	    else if ( id == `dest_dir)
	    {
		UI::ChangeWidget( `id( `echo ), `Value, "hello");
		any current_dir = UI::QueryWidget(`id(`dest_dir), `CurrentItem);

		if ( current_dir != nil )
		    UI::ChangeWidget( `id( `echo ), `Value, sformat( "%1", current_dir ) );
	    }

	    y2milestone( "Items:\n%1", UI::QueryWidget(`dest_dir, `Items ) );
	    y2milestone( "OpenItems:\n%1", UI::QueryWidget(`dest_dir, `OpenItems ) );
	} until ( id == `ok );


    // Close the dialog.
    // Remember to read values from the dialog's widgets BEFORE closing it!
    UI::CloseDialog();

}