# Dialogs using the Tab widget

CWMTab is a widget for CWM that can be used for handling dialogs with multiple tabs. Its tasks are following:

- Switch the widgets (that are implemented via CWM) in the tab

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

The CWMTab widget is just a widget for CWM. It is limited to one instance in a single dialog.

Usage of the LeftTree-based dialog

            map<string,map<string,any>> widgets = $[
               "w1" : $[...],
               "w2" : $[...],
               "w3" : $[...],
               "w4" : $[...],
               "w5" : $[...],
            ];

            widgets = (map<string,map<string,any>>) union (widgets, $[
                "tab" : CWMTab::CreateWidget ($[
    (1)             "tab_order" : ["t1", "t2", "t3"],
    (2)             "tabs" : $[
                        "t1" : $[
                            "header" : "Tab1",
                            "contents" : `VBox ("w1", "w2"),
                            "widget_names" : ["w1", "w2"],
                        ],
                        "t2" : $[
                            "header" : "Tab2",
                            "contents" : `HBox ("w3", "w4"),
                            "widget_names" : ["w3", "w4"],
                        ],
                        "t3" : $[
                            "header" : "Tab3",
                            "contents" : `Empty (),
                            "widget_names" : [],
                        ],
                    ],
    (3)             "initial_tab" : "t2",
    (4)             "widget_descr" : $[...],
    (5)             "tab_help" : _("TabWidgetHelp"),
                ])
            ]);

            CWM::ShowAndRun (
                ["w5", "tab"],
                widgets,
                `VBox ("w5", "tab"),
                _("Dialog caption"),
                Label::BackButton (),
                Label::NextButton (),
                $[...]
            );

## Running the dialog with tab widget

Once the CWMTab widget is created, it can be used like any other CWM widget. The only difference is that once the tab is switched, the validation of the selected (before the switch) tab and store functions of all widgets inside the tab is run. To run any such dialog, use CWM::Run or CWM::ShowAndRun.

## Creating the tab widget

To create the CMWTab widget, all the widgets that are on any of the tabs must be created first (as they are one of the arguments of the `CWMTab::CreateWidget` function. The way to go is to create map of all other widgets first, then pass it to the functions that create the CWMTab widget (or multiple CWMTab widgets), and merge these two resulting maps.

The `CWMTab::CreateWidget` function has one argument, a map with all attributes. The map has following keys.

- `"tab_order" : list<string>` specifies the order of the tabs. It is a list of IDs of the tabs. For example, see , line (1).

- `"tabs" : map<string,map<string,any>>` is a map describing the tabs. See below for details.

- `"initial_tab" : string` specifies the initial tab. Contains a string, ID of the initial tab. If not specified, the first tab is the default. For example, see , line (3).

- `"widget_descr" : map<string,map<string,any>>` is map describing all widgets in all tabs. See and following for additional information about this stuff.

- `"tab_help" : string` contains optional help to the tab. It is displayed always, followed by the helps of widgets contained in the currently displayed tab.

- `"fallback_functions" : map<string,any>` is a map specifying handler functions common for all widgets the tabs, if they are not specified for the individual tabs or widgets.

## Specifying the tabs

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

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

- `"header" : string` is the tab header.

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

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

- `"fallback_functions" : map<string,any>` is a map specifying handler functions common for all widgets in this tab, if they are not specified for the individual widgets.