<?xml version="1.0" encoding="utf-8"?>
<theme version="1"
       xmlns:xi="http://www.w3.org/2003/XInclude">

  <layout type="grid" id="main-window-grid">

    <!-- ... -->

  </layout>

  <factory type="grid" id="button-row">

    <!-- ... -->

  </layout>

  <layout type="book" id="formatting-options">


    <!-- ... -->

  </layout>

  <factory type="book" id="formatting-generic-options">

    <!-- ... -->

  </layout>
</theme>

The XML document's root element is a theme element. For future compatibility, its version attribute should be 1. The theme element contains layout and factory elements. Their id attributes must be unique, and serve as means of referring to each layout and factory element by name. Only the first layout and factory with a unique id takes effect, second and subsequent layouts and factorys with the same id get ignored. In all other respects the relative order of layouts and factorys doesn't matter, and together with XInclude this makes it possible to implement a theme file with shared layouts and factorys, and then include it from other theme files, extending and/or overriding parts of it.

The theme file's XML document also contains several other elements, like dims, colors, borders, and appearance, with their own ids that work the same way.

The element contents of layouts or a factorys depend on their type. The widget content effectively translates to invoking the corresponding methods of a layout manager or a factory:

layouts with a type of book: The element contents of this layout invoke the corresponding methods of a book layout manager.
layouts with a type of editable_combobox: The element contents of this layout invoke the corresponding methods of a editable combo-box layout manager.
layouts with a type of grid: The element contents of this layout invoke the corresponding methods of a grid layout manager.
layouts with a type of list: The element contents of this layout invoke the corresponding methods of a list layout manager.
layouts with a type of menubar: The element contents of this layout invoke the corresponding methods of a book layout manager.
layouts with a type of pane: The element contents of this layout invoke the corresponding methods of a pane layout manager.
layouts with a type of peephole: This is a placeholder for the corresponding methods of a peephole layout manager. All functionality related to the peephole layout manager comes from the config element of the container that creates a container managed by the peephole layout manager.
layouts with a type of standard_combobox: The element contents of this layout invoke the corresponding methods of a standard combo-box layout manager.
layouts with a type of table: The element contents of this layout invoke the corresponding methods of a table layout manager.
factorys with a type of book: The element contents of this layout invoke the corresponding methods of a book page factory.
factorys with a type of grid: The element contents of this layout invoke the corresponding methods of a grid factory.
factorys with a type of menubar: The element contents of this layout invoke the corresponding methods of a menu bar factory.
factorys with a type of pane: The element contents of this layout invoke the corresponding methods of a pane factory.

Creating generic widgets using named callbacks

#include <x/w/uielements.H>
#include <x/w/uigenerators.H>

x::w::gridlayoutmanager grid_layout=container->get_layoutmanager();

x::w::const_uigenerators generators=x::w::uigenerators::create("layouts.xml");

x::w::labelptr created_label;
x::w::buttonptr created_button;

x::w::uielements creators{
    {
          {"label",
           [&]
           (const INSERT_LIBX_NAMESPACE::w::factory &f)
           {
               created_label=f->create_label("Lorem ipsum");
           }
          },
          {"button",
           [&]
           (const INSERT_LIBX_NAMESPACE::w::factory &f)
           {
               created_button=f->create_button("Lorem ipsum");
           }
          },
    }
};

Creating widgets using a theme file is a three step process:

create() an x::w::const_uigenerators object. This loads the theme file and effectively compiles it into an internal representation, a reference-counted object. create() returns a x::w::const_uigenerators handle, a reference to a const object object (the compiled theme file object remains constant after it's created).
Create an x::w::uielements object. The x::w::uielements gets created in automatic scope, and this individual object is no longer required after the widgets get generate()d. The x::w::const_uigenerators contains multiple layout specifications, is constant, and can be used multiple times.
An x::w::uielements servers a dual purpose. Its first member, factories is a map. The map key's is a text string, a label. The keys' values are lambdas, or callable objects. The lambdas receive a factory as their parameter. It's expected that each lambda uses the factory to create a single widget.
Invoke a layout manager's generate() to execute the compiled theme file, and create its contents.
```
grid_layout->generate("main-window-grid", generator, creators);
```
A grid layout manager's generate() generates the contents of the contents of the layout manager from the theme file. The first parameter gives the name of a layout whose type must be “grid”, and have a matching id (“main-window-grid”, in this example). This executes the specification for this layout from the compiled theme file.

x::w::uielements's second purpose is to store widgets and other objects that generate() creates. x::w::uielements's various methods return different kinds of objects created by generate().

Note

These "other objects" also include layout managers and factories created by generate(). As explained in the section called “Layout managers”, instantiated layout manager (and factories) bring the connection thread to a screeching halt. x::w::uielements should be created in automatic scope, initialized, and used to generate() stuff.

Afterwords if any follow-up work is needed with any generated objects: they should be fetched out of the x::w::uilements object, and everything should then go out of automatic scope and get destroyed after all business gets taken care of.

Prev		Next
Using XInclude with SXG files	Table Of Contents	Creating widgets directly from an XML theme file