13.1.13.4.1. Containers#

Containers do not hold a value of their own – they organise other controls. Each spans the full width of the form, and the controls listed inside it are built as a form of their own. There are two: group draws a labelled box, and tabs draws a tab strip.

All controls also accept the common keys (name, label, tooltip, enabled); see the overview.

13.1.13.4.1.1. group#

A labelled box around a set of controls. Optionally checkable, which turns the heading into a switch for everything inside it.

{
  "type": "group",
  "title": "Wi-Fi",
  "checkable": true,
  "name": "wifi_enabled",
  "value": true,
  "controls": [
    { "type": "lineedit", "name": "ssid", "label": "SSID" },
    { "type": "lineedit", "name": "password", "label": "Password", "password": true }
  ]
}

Arguments:

  • title (string) – the heading shown on the box.

  • checkable (boolean, default false) – when true, the heading carries a checkbox that enables or disables every control inside the box, and whose own on/off state is saved.

  • value (boolean, default true) – the initial state of that heading checkbox. Only meaningful when checkable is true.

  • controls (array) – the controls shown inside the box.

Saves: a boolean (the heading checkbox) when checkable is true; a plain group saves nothing of its own – only the controls inside it save their values.

13.1.13.4.1.2. tabs#

A tab strip. Each tab is a page with its own list of controls, so a long form can be split across Camera, Network, System, and so on.

{
  "type": "tabs",
  "tab_position": "north",
  "tabs": [
    {
      "title": "Camera",
      "tooltip": "Sensor settings",
      "controls": [
        { "type": "slider", "name": "gain", "label": "Gain" }
      ]
    },
    {
      "title": "Network",
      "controls": [
        { "type": "lineedit", "name": "hostname", "label": "Hostname" }
      ]
    }
  ]
}

Arguments:

  • tab_position (string, default "north") – which edge the tab bar sits on: "north", "south", "west", or "east".

  • tabs (array) – the tab pages, in order. Each page is an object with:

    • title (string) – the tab’s label.

    • tooltip (string) – hover text for the tab.

    • controls (array) – the controls shown on that page.

Saves: nothing of its own; the controls on each page save their own values.

13.1.13.4.1.3. Nesting#

Any control can go inside any container, to any depth. A group can contain a tabs, a tab page can contain group boxes, groups can nest inside groups. Every controls array – the top-level one, a group’s, and a tab page’s – takes the same control objects, so the rules on these pages apply the same at every level.

A checkable group nested inside a tab is a common shape: the tab holds a feature, the group’s checkbox turns the feature on or off, and the controls inside configure it.