# Available widgets

Note: in all examples additional parameters can be present, see .

## Empty Widget

Displays nothing but still can handle events.

widget

  `empty

Empty Widget

    map<string,map<string,any> > widget_descr = $[
      "HANDLER" : $[
        "widget" : `empty,
        "handle" : GlobalEventhandler,
      ],
    ]

## Check Box

widget

  `checkbox

label

  The checkbox label, shown to the right of it

Check Box

    map<string,map<string,any> > widget_descr = $[
      "CHECKBOX" : $[
        "label" : _("&Checkbox"),
        "widget" : `checkbox,
      ],
    ]

## Combo Box

Parameters:

- "widget" : must be set as `combobox

- "label" : label shown above the combobox

- "items" : list of two-item-lists of [id, label], each item represents one item of the Combobox. Both id and label must be strings.

Combo Box

    map<string,map<string,any> > widget_descr = $[
      "COMBOBOX" : $[
        "label" : _("&Combobox"),
        "widget" : `combobox,
        "items" : [
            [ "item1", _("Label1") ],
            [ "item2", _("Label2") ]
        ],
      ],
      ....
    ]

## Selection Box

Parameters:

- "widget" : must be set as `selection_box

- "label" : label shown above the selection_box

- "items" : list of two-item-lists of [id, label], each item represents one item of the selection box. Both id and label must be strings.

Usage is similar to Combo Box.

## MultiSelection Box

Parameters:

- "widget" : must be set as `multi_selection_box

- "label" : label shown above the selection box

- "items" : list of two-item-lists of [id, label], each item represents one item of the selection box. Both id and label must be strings.

Usage is similar to Combo Box.

## Text Entry

Parameters:

- "widget" : must be set as `textentry

- "label" : label shown above the text entry

- "valid_chars" : list of characters that are valid for the text entry, if missing, all characters are valid

Text Entry

    map<string,map<string,any> > widget_descr = $[
      "TEXTENTRY" : $[
        "label" : _("&TextEntry"),
        "widget" : `textentry,
        "valid_chars" : "0123456789AaBbCcDdEeFfXx",
            // for hexadecimal numbers
      ],
      ....
    ]

## Int Field

Parameters:

- "widget" : must be set as `intfield

- "label" : label shown above the int field

- "minimum" : minimal value of the int field, if not set, then 0 is used

- "maximum" : maximal value of the int field, if not set, then 2^31 - 1 is used

Int Field

    map<string,map<string,any> > widget_descr = $[
      "INTFIELD" : $[
        "label" : _("&Intfield"),
        "widget" : `intfield,
        "minimum" : -1,
        "maximum" : 10,
      ],
      ....
    ]

## Radio Buttons

Parameters:

- "widget" : must be set as `radio_buttons

- "label" : label of the frame around the radio buttons

- "items" : list of two-item-lists of [id, label], each item represents one radio button. Both id and label must be strings.

- "hspacing" : FIXME

- "vspacing" : FIXME

- "orientation" : says if the radio buttons should be oriented horizontally or vertically. Allowed values are `horizontal and `vertical, default is `vertical. FIXME: NOT IMPLEMENTED

Radio Buttons

    map<string,map<string,any> > widget_descr = $[
      "RADIO_BUTTONS" : $[
        "label" : _("RadioButtonGroup"),
        "widget" : `radio_buttons,
        "items" : [
            [ "item1", _("&Label1") ],
            [ "item2", _("La&bel2") ],
        ],
        "orientation" : `horizontal,
      ],
      ....
    ]

## Radio Button

This is the elementary radio button, for use in complex layouts where radio_buttons is not enough.

Parameters:

- "widget" : must be set as `radio_button

- "label" : label shown to the right of the radio button

Radio Button

    map<string,map<string,any> > widget_descr = $[
      "RADIOBUTTON" : $[
        "label" : _("&Radio Button"),
        "widget" : `radio_button,
      ],
    ]

## Push Button

Parameters:

- "widget" : must be set as `push_button

- "label" : push button label

Push Button

    map<string,map<string,any> > widget_descr = $[
      "PUSH_BUTTON" : $[
        "widget" : `push_button,
        "label" : _("Push Button"),
      ],
      ....
    ]

## Menu Button

widget

  `menu_button

label

  The menu button label

items

  List of string pairs [id, label] for the menu items

Menu Button

    map<string,map<string,any> > widget_descr = $[
      "MENUBUTTON" : $[
        "label" : _("&Advanced"),
        "widget" : `menu_button,
        "items" : [
            [ "FIXIT", _("&Fix Everything") ],
            [ "CRASH", _("&Crash now") ]
        ],
      ],
      ....
    ]

## Multi-Line Edit Box

Parameters:

- "widget" : must be set as `multi_line_edit

- "label" : title of the multiline widget

Push Button

    map<string,map<string,any> > widget_descr = $[
      "MULTI_EDIT" : $[
        "widget" : `multi_line_edit,
        "label" : _("Text editor"),
      ],
      ....
    ]

## Rich Text Field

Parameters:

- "widget" : must be set as `richtext

Rich Text

    map<string,map<string,any> > widget_descr = $[
      "RICH_TEXT" : $[
        "widget" : `richtext,
      ],
      ....
    ]

To fill the contents of the rich text, initialization function calling `UI::ChangeWidget` must be defined.

## Custom widget

Parameters:

- "widget" : must be set as `custom

- "custom_widget" : term describing the widget

Custom widget

    map<string,map<string,any> > widget_descr = $[
      "PUSH_BUTTON" : $[
        "widget" : `custom,
        "custom_widget" : `PushButton (
                                `id (`push_button),
                                _("Push Button")),
      ],
      ....
    ]

## Widget Description Map Reference

widget

  Kind of the widget. See . ## The term to be passed to UI.

  All

  symbol ## Internal.

  FIXME use a different key for the resulting term.

ui_timeout

  How long to wait for user input before an idle event is generated (FIXME which).

  All

  integer

init

  Function that initializes widgets. The parameter is the id of the widget. All widgets are initialized before the event loop.

  All

  void (string)

  See: fallback_functions in ShowAndRun

handle

  Function that handles events. All widgets that have this function defined are handled on each event. The parameters are the id of the widget and the event map. It should return nil to continue processing or a symbol to be returned from the dialog.

  All

  symbol (string, map)

  See: fallback_functions in ShowAndRun

handle_events

  Limits calling of the handle function to a certain list of widget ids.

  All

  list <any>

store

  Function that saves the values of widgets. The parameters are the id of the widget and a map of the event that caused the dialog to end. All widgets are saved after the event loop unless `back or `abort is returned.

  All

  void (string, map)

  See: fallback_functions in ShowAndRun

cleanup

  Function that cleans up widgets. The parameter is the id of the widget. All widgets are cleaned up before the dialog ends, after they (would) have been saved.

  All

  void (string)

  See: fallback_functions in ShowAndRun

custom_widget

  A UI term ready to be placed to the dialog.

  widget == `custom

  term

widget_func

  A function that returns a UI term ready to be placed to the dialog.

  widget == `func

  term ()

opt

  Options to be placed to the `opt term of the widget.

  All except `empty, `custom and `func

  list <any>

label

  Widget label.

  All except `empty, `custom and `func (and why `richtext?)

items

  List of items for some widgets, in pairs [id, label].

  `combobox, `selection_box, `multi_selection_box, `radio_buttons, `menu_button

minimum

  Minimum value for integer fields.

  `intfield

  integer

maximum

  Maximum value for integer fields.

  `intfield

  integer

hspacing

  Horizontal padding and spacing between the radio buttons.

  `radio_buttons

  integer (FIXME float?, not validated)

vspacing

  Vertical padding and spacing between the radio buttons.

  `radio_buttons

  integer (FIXME float?, not validated)

validate_type

  `function, `function_no_popup, `regexp` or `list. All widgets that have this defined are validated before the dialog would be successfully exited and saved. Actually not all, only until the first failure.

  All

  symbol

validate_function

  Function that validates the widget. The parameters are the widget key and the map of the event that causes the dialog to exit. In case of validation failure, for `function, it should pop up an error by itself , and for `function_no_popup, CWM will pop up an error (using validate_help if present).

  validate_type == `function or `function_no_popup

  boolean (string, map)

validate_condition

  validate_type == `regexp or `list

  string or list

  FIXME, does not seem to work because of `_tp_value

validate_help

  validate_type != `function

  string

  Contents of error popup shown if a widget fails to validate

help

  Widget help

  All

  string

no_help

  If present, no error about missing help will be given. FIXME: use help:nil instead

  All

  any