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

<TBD>

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.