.. SPDX-FileCopyrightText: 2026 James Turner .. SPDX-License-Identifier: GPL-2.0-or-later ======= Dialogs ======= Dialogs are defined via a declarative XML syntax. Familiarty with the XML syntax for expressions, conditions and bindings is assumed, since these are used to drive most functionality. Identifiers =========== Each widget can and should be assigned a unique ``name`` in its dialog. This is useful for debugging, but also allows lookup from Nasal for imperative control, via the ``getElementById`` function. Layout Concepts =============== Dialogs are composed of widgets, some of which have children (for example a group box or frame). Each widget can have an optional layout which controls the position of its children automatically. The layout types are a vertical or horizontal box, or a grid. Note this layout model is almost identical to that used in many other UI toolkits, and should be familiar to anyone used to those. Each widget within a layout can define its size policy, which defines how it uses extra space in each direction. Some widgets can meaningfully use extra space, while others cannot. In addition, the **layout** defines stretch factors for children, which control how extra space is allocated. Again this mechanism is copied from other UI toolkits and should be familiar. Versioning ========== Dialogs should be declared with the UI version they are designed for, to allow maintaining compatibility as the XML syntax evovles. Translation =========== Common properties ================= ``visible`` Whether the widget is visible. This is typically bound to a ``condition`` ``enabled`` Whether the widget is enabled. This is a boolean property, so it can be bound to a condition or expression. Widgets ======= ``text`` A single- or multi-line string, which is displayed. .. note:: Rich-text markup and clickable links are currently not supported, but will be added soon once Pango support is merged. ``button`` A standard button, which can be clicked. Buttons can have ``legend`` property, which specifies the text (usually translated) to display. Alternatively, they can specify ``role``, and the text (and icon if appropriate) will be derived from the role. ``textbox`` A multi=line text box, which supports scrolling internally. Container Widgets ----------------- ``group`` A group has no visual appearance, but allows a hierarchy of layouts to be defined. Disabling or hiding a group will affect all its children. ``frame`` A visible frame containing a layout. Frames can options have a title specified, and a checkbox. Because the frame has some visible border, the contents are indented, compared to using a ``group``. .. note:: Frames and especially the handling of check-boxes with titles is still work in progress. The intention is to make this fully supported but testing is needed. ``button-box`` A horizontal box containing buttons. This is mostly commonly used at the bottom of a dialog to provude standard buttons based on their ``role``, but additional buttons can be added as needed. The sorting of buttons is controlled by their role, to allow OS-specific UI conventions on button ordering to be respected. ``tabs`` A series of tabs, each of which contains a layout. Each tab has a translateable title. The visible page is controlled by the ``value`` property, as an integer index. .. note:: Should consider allowing a tab ID to be set as the widget value, and looking up the corresponding index.