# Dialogs based on the tree on the left (for English)

DialogTree is a set of functions to help using CWM in the dialogs that have the Tree widget on the left side. Its tasks are following:

- Switch the dialogs (that are implemented via CWM)

- Create the tree widget

- Handle different GUIs (supporting or not supporting the Wizard widget)

Usage of the DialogTree-based dialog

            import "DialogTree";

            DialogTree::ShowAndRun ($[
    (1)         "screens" : $[
                    "s1" : $[
    		    "caption" : "Module X - Screen 1",
    		    "tree_label" : "Screen1",
    		    "widget_list" : [ "w1", "w2" ],
    		    "contents" : `VBox ("w1", "w2"),
    		],
                    "s2" : $[
    		    ...
    		],
                    "s3" : $[
    		    "caption" : "S3",
    		    ...
    		],
                ],
    (2)         "ids_order" : ["s1", "s2", "s3"],
    (3)         "initial_screen" : "s2",
                "widget_descr" : $[...],
    (4)         "back_button" : "",
                "next_button" : "NextButton",
                "abort_button" : "AbortButton",
                "functions" : $[...]
            ]);

## Running the dialog

The dialog is started via one function call. This function processes all needed operations, this means to open a new Wizard screen with the tree on the left, runs event loop, and closes the newly open Wizard screen.

It takes one map as parameter. It contains all the needed information for creating and running the dialog. Return value is a symbol for the wizard sequencer.

## Specifying the screens

The screens are specified as a map, where key is the screen name and value is a map describing the screen. The map must be of type map<string,map<string,any>>. See , line (1) and following for example.

For every screen description map, the following keys must be defined:

- `"widget_names" : list<string>` contains the list of widget IDs of all widgets in the screen. The widgets will be handled in the same order as they are specified (also valid for help texts merging).

- `"contents" : term` contains the term with the screen. All widget IDs are patched before the screen is displayed.

- `"caption" : string` is the dialog caption. Will be used as the caption of the dialog when the screen is shown, and also as caption for the label to the tree widget the `"tree_item_label"` key is missing.

- `"tree_item_label" : string` is the label of the screen in the tree widget. Is used only if the screens are ordered via a list (see below).

## Ordering the screens

The screens can be specified in two ways. The easier way is just to provide a list of the screens. This way, all the screens are in the same level.

The other way is to construct the tree via a callback function. This way, the component developer can fully control how the tree is created.

If both list of screens and tree creator callback are specified, then the callback is used.

### Flat list of screens

To make a flat list of screens in the dialog tree, just specify the key `"ids_order"` and give it as value a list of strings containing the IDs of all screens. See , line (2) for example.

### Multi-level tree of screens

To create a multi-level tree of screens, specify a callback that creates the whole tree. To add items to the tree, use `Wizard::AddTreeItem`. The `"tree_creator"` entry of the map must be a reference to a function of type `list<map>()`. This function creates a list of widgets via the `Wizard::AddTreeItem` and returns the output of the last call.

Create the wizard tree function

    define list<map> CreateWizardTree () {
        list<map> Tree = [];
        Tree = Wizard::AddTreeItem (Tree, "",  _("S1_label"), "s1");
        Tree = Wizard::AddTreeItem (Tree, "",  _("S2_label"), "s2");
        Tree = Wizard::AddTreeItem (Tree, "",  _("S3_label"), "s3");
        return Tree;
    }

## Specifying the initial screen

To specify the screen that will be shown after the dialog is displayed, use the `"initial_screen"` key. Its value is a string contains the key of the screen that is wanted to be displayed as the first. If not specified and order of the screens is specified by the list, the first is used. If not specified and the order is specified via a callback, the default is undefined.

See , line (3) for example.

## Widgets description map

To specify the widgets description map, use the `"widget_descr"`. See and following for additional information about this stuff.

## Button labels

To specify labels of the buttons on the bottom of the dialog, use the keys `"next_button"`, `"back_button"` and `"abort_button"`. To hide any particular button, just set the value to nil or empty string. In case of NCurses UI (where no wizard widget is available), Help button is automatically added. See , line (4) and following for example.

## Fallback functions

To specify the fallback handlers of the widgets and functions for handling abort and back events, use the `"functions"`. See and following for additional information about this stuff.