Support for themes in forms

[jpgaribotti]

Widgets created through loadWidgetsFromFile can only have renderers defined in the file itself. Even if you import a theme in gui-builder, it only copies the theme into the form. If a default theme is set, they won't pick up the default theme, and won't support "hot reloading" if you load a different theme like programatically created widgets do. This makes development somewhat less convenient, and requires duplicating the theme in every form and keeping them up to date as they are modified.

It would be nice to be able to pass a theme to loadWidgetsFromFile and have the widgets either pick the renderer for their type from there, or be able to reference (with the & syntax or a specific syntax) renderers from the theme.

I currently use a workaround for this that after loading from file walks through every widget and sets renderers (I store theme renderer names in UserData if I want something other than the default), but this is not ideal.

I could send a PR if this is something you'd be interested in supporting.

[texus]

One of the issues of storing a theme in a form file is that the location of the theme file will be different for the Gui Builder and for your application.

The form definitely needs some annotation for whether to load from the runtime theme or from the custom hardcoded renderers inside the form, to make certain that you can support e.g. labels of multiple colors. Ideally it should still be possible to use multiple themes in a single form file. This however quickly leads to further issues like what to do when using multiple themes that have the same name but are from different folders.

Suppose you have a form like this:

Renderer.1 {
}
Renderer.2 {
}

Button.Button1 {
    Renderer = &1;
}
Button.Button2 {
    Renderer = &1;
}
EditBox.EditBox1 {
    Renderer = &2;
}
EditBox.EditBox2 {
    Renderer = {
    }
}

Maybe a new section could be added that looks like this: (this is just a quick idea, I don't know how easy it would be to adjust and maybe there are better alternatives)

Theme.White
{
    Button = &1;
    EditBox = &2;
}

Then loadWidgetsFromFile could optionally replace the renderers with a runtime theme when a map like {"White": runtimeTheme1, "Black": runtimeTheme2} is passed. In this example EditBox2 would keep it's custom theme since it isn't linked with the theme. The form is still self-contained like this, if no themes are passed to loadWidgetsFromFile then the form still has renderers for all widgets.

So there are multiple issues that need to be sorted out in order to properly support themes in form files. If you have a proposed solution then I'll definitely be interested in it.

[jpgaribotti]

I had initially considered only applying the "default" theme, but you raise good points. Working on a design doc to address them, will share when I complete it for you to review.

[jpgaribotti]

So I have an initial proposal. It does require a new section like you describe and a bit of new syntax (@ to reference Theme sections) but it otherwise has fairly small impact. It does not address how gui-builder's interface would have to change to support it, that could be a secondary proposal for later. I would also like to add support for custom widgets to gui-builder anyway (perhaps some plugin support so you provide a shared object that knows about the new widgets).

1. Requirements

1.1 Principal requirement: multiple themes per form

• A single form file must be able to reference multiple themes.
• Widgets may take their renderer from different themes (e.g. one theme for primary UI, another for a “dark” subsection).
• When runtime themes are provided at load time, widgets bound to a theme should use the corresponding runtime theme’s renderer (and benefit from hot-reload and default-theme behavior). Widgets not bound to any theme should keep their form-local renderer.

1.2 Self-contained forms

• If no runtime themes are passed to loadWidgetsFromFile, the form must still load and display correctly using only the renderers defined in the form (current behavior preserved).
• Forms must remain usable in the Gui Builder and in applications that do not use the new theme API.

1.3 Explicit choice: theme vs form-local renderer

• The form must explicitly indicate whether a widget uses a theme-derived renderer or a form-local (hardcoded) renderer.
• This allows, for example, “labels of multiple colors” in the same form: some labels use a theme, others use form-local Renderer.N definitions.

1.4 Disambiguation of themes

• Same logical name, different locations: Two themes might have the same logical name (e.g. "Black") but come from different paths (e.g. themes/Black.txt vs assets/ui/Black.txt). The form syntax must allow the form to refer to them distinctly so the application can pass different Theme instances for each.
• Same section names across themes: Different theme files may define sections with identical names (e.g. both have Button). Binding must be per-theme so that “use theme A’s Button” and “use theme B’s Button” are unambiguous.

1.5 Default theme for widgets without a Renderer

• When a widget does not define a Renderer property, the loader should be able to apply the current default theme (so form-loaded widgets match programmatic widgets and support hot-reload). This is opt-in via a flag so that existing forms and call sites keep current behavior (backwards compatibility).

1.6 Custom theme sections

• Themes can define arbitrarily named sections (not only widget types). Widgets must be able to specify either "use the section that matches my type" or "use this specific section name" from a theme (e.g. a custom HighlightBox section).

1.7 API

• loadWidgetsFromFile (and the underlying loading path) should accept: (1) an optional mapping from theme alias (as used in the form) to runtime theme object (e.g. std::shared_ptr<Theme>); (2) an optional flag (e.g. applyDefaultTheme) that, when set, causes widgets with no Renderer property to use the current default theme (see 2.5).

1.8 Backward compatibility

• Existing form files that do not use the new theme sections must behave exactly as today (no theme binding, only form-local renderers).

---

2. Proposed form syntax

2.1 Theme sections in the form

Introduce a theme binding section that:

1. Declares a theme identifier (used in the form and in the API map).
2. Optionally binds widget types to form-local renderer references (&N) for the self-contained case (when no runtime theme is provided).

The maintainer’s idea is followed and extended:

Theme.<ThemeId>
{
    <WidgetType> = &<RendererId>;
    ...
}

• ThemeId: string identifier chosen by the form author (e.g. White, Black, Dialogs). Used as the key when the application passes the map to loadWidgetsFromFile.
• WidgetType: TGUI widget type (e.g. Button, EditBox, Label) or an arbitrary section name for custom theme sections (see 2.4). For widgets bound to this theme, the runtime theme’s renderer for that type is used when a theme is supplied; otherwise the form uses the given &RendererId from the form’s Renderer.N sections.

So the form defines a “default” mapping (form-local) per widget type or custom section per theme; at load time, if the application provides a theme for that ThemeId, the loader substitutes the runtime theme’s renderer for that type/section instead of the form-local one.

Example:

Renderer.1 { ... }
Renderer.2 { ... }

Theme.White
{
    Button = &1;
    EditBox = &2;
}

Theme.Black
{
    Button = &1;
    EditBox = &2;
}

Button.Button1 { Renderer = @White; }
Button.Button2 { Renderer = @White; }
EditBox.EditBox1 { Renderer = @Black; }
EditBox.EditBox2
{
    Renderer = { ... }
}

• Button1, Button2: use theme White (runtime theme for White if provided, else form’s &1).
• EditBox1: use theme Black (runtime theme for Black if provided, else form’s &2).
• EditBox2: form-local inline renderer; not bound to any theme, so it never gets replaced by a runtime theme.

2.2 Binding a widget to a theme

• New syntax for “use theme”: To bind a widget to a theme we need a distinct marker. Proposed: Renderer = @<ThemeId> or Renderer = @<ThemeId>.<Section> (see 2.4).
  • @ is used to mean “renderer from theme with id ThemeId”. This is distinct from Renderer = &N (form-local renderer reference) and Renderer = { ... } (inline form-local renderer).

2.3 Distinguishing themes with the same name (different locations)

Paths are not encoded in the form. The form defines an alias for each theme it uses; the application maps that alias to a theme object at load time. Paths can differ between the Gui Builder and the application, or change over time, so encoding the path in the form would be insufficiently flexible.

• In the form: The form author defines short, unique aliases (e.g. Theme.BlackMain { ... } and Theme.BlackDialogs { ... }). Both might conceptually be “Black” from different folders; the form does not care about paths.
• In the API: The application passes a map from alias to theme instance (e.g. BlackMain -> theme1, BlackDialogs -> theme2). Where each theme is loaded from (which path) is entirely the application’s concern.
• This gives a unique theme identifier per theme instance in the form and in the loadWidgetsFromFile map, without tying the form to any filesystem path.

2.4 Custom theme sections

Themes can define arbitrarily named sections (not only widget type names like Button or EditBox). Widgets should be able to request either the section that matches their widget type or a specific named section.

Proposed syntax:

• Renderer = @ThemeName — Use the section that matches the widget’s type from the given theme (e.g. a Button gets the Button section of ThemeName). This is the “default” theme binding.
• Renderer = @ThemeName.Section — Use the explicitly named section from that theme (e.g. Renderer = @MyTheme.HighlightBox). The section name is arbitrary and need not match the widget type; the theme may define custom sections like HighlightBox, Card, etc.

So the dot separates theme alias from optional section name; if no dot is present, the widget type is used as the section name.

2.5 Explicit default-theme reference

When a form uses multiple named themes (e.g. @White, @Black) but a widget should use the application’s default theme (whatever is set via Theme::setDefault()), the form needs an explicit way to request that. Otherwise there is no syntax for “use the default theme for this widget” distinct from “use named theme X” or “no Renderer” (which only gets the default when applyDefaultTheme is true).

Proposed syntax:

• Renderer = @default — Use the application’s default theme (Theme::getDefault()) for the widget’s type. The loader uses the theme that was default at the start of the load (saved before temporarily clearing it, if applicable).
• Renderer = @default.Section — Use the default theme’s explicitly named section (e.g. Renderer = @default.HighlightBox).

No Theme.default block is needed in the form; the default theme is always the runtime default. The reserved alias default is not looked up in the theme map; it is handled specially by the loader. This allows mixing e.g. @White, @Black, and @default in the same form.

2.6 Default theme (widget with no Renderer)

When a widget does not define a Renderer property at all, it should be possible for it to use the application's default theme (so it participates in hot-reload and consistent styling like programmatically created widgets). Today, the loading code temporarily unsets the default theme for the duration of the load (Theme::setDefault(nullptr) before loading, then restores it afterward), so widgets created during load do not receive the application default theme when they omit a renderer.

The load API accepts a flag (e.g. applyDefaultTheme) that instructs the loader to not temporarily unset the default theme during load. When the flag is true, the application's default theme remains in effect; widgets constructed during load then get their renderer from Theme::getDefault() in the usual way (as when adding widgets programmatically), and widgets with no Renderer property in the form keep that default-theme renderer. When the flag is false (default), the loader keeps the current behavior (default theme is unset during load), so widgets with no Renderer continue to behave as today. Implementation is a small change (conditionally skip the save/clear/restore of the default theme when the flag is set), and behavior is predictable and matches adding widgets programmatically.

Backwards compatibility: when the flag is false or not passed, existing forms and call sites are unchanged.

2.7 Summary of form syntax

Syntax	Meaning
(no Renderer)	Use current default theme for this widget type if applyDefaultTheme is true at load time; otherwise current behavior (default theme is not applied during form load).
Renderer = &N	Use form-local renderer with id N (unchanged).
Renderer = { ... }	Use inline form-local renderer (unchanged).
Renderer = @<ThemeId>	Use section matching widget type from theme <ThemeId>. If that theme is in the runtime map, use its renderer; otherwise use the form-local renderer specified in Theme.<ThemeId> for this widget type.
Renderer = @<ThemeId>.<Section>	Use the explicitly named <Section> from theme <ThemeId> (custom section; need not match widget type). Same fallback to form-local when theme not in runtime map (requires fallback for custom sections in Theme.<ThemeId>, e.g. <Section> = &N).
Renderer = @default	Use the application’s default theme for the widget’s type. Reserved alias; no theme map lookup, no Theme.default block.
Renderer = @default.<Section>	Use the default theme’s explicitly named section.
Theme.<ThemeId> { Button = &1; ... }	Declare theme alias and fallback (form-local) renderer per widget type (and optionally per custom section) when no runtime theme is provided for <ThemeId>.

---

3. Load-time behavior (outline)

1. Parse the form as today; collect all Renderer.N and Theme.<ThemeId> sections. Save the current default theme (e.g. Theme::getDefault()) at the start of load so it can be used for @default even when the default is temporarily unset during load.
2. Build the usual availableRenderers from Renderer.N (and resolve &N for form-local refs).
3. For each widget:
   • No Renderer property: When applyDefaultTheme is true, the loader does not temporarily unset the default theme during load, so widgets get their renderer from Theme::getDefault() at construction (same as programmatic widgets). When the flag is false, current behavior (default theme unset during load) applies.
   • Renderer = @ThemeId: Look up ThemeId in the runtime theme map. If present, set the widget renderer to runtimeTheme->getRenderer(widgetType). If not present, resolve the fallback from Theme.<ThemeId> for this widget type (e.g. Button = &1) and use that form-local renderer.
   • Renderer = @ThemeId.Section: Same as above, but use the explicitly named Section instead of the widget type when calling getRenderer(Section) and when resolving the fallback from Theme.<ThemeId> (e.g. HighlightBox = &3).
   • Renderer = @default or Renderer = @default.Section: Use the application’s default theme (the theme that was Theme::getDefault() at the start of the load). The loader uses the saved default theme for these widgets; no theme map or form fallback. Reserved alias default is not looked up in the theme map.
   • Renderer = &N or Renderer = { ... }: Keep current behavior (form-local only).
4. When no runtime theme map is passed, all @ThemeId and @ThemeId.Section bindings fall back to the form-local renderers defined in the corresponding Theme.<ThemeId> block, so the form remains self-contained.

[texus]

It looks good, but I wonder if the new @ symbol is really needed.
The Renderer = @ThemeId is just a shorthand syntax for Renderer = @ThemeId.Section. Since the files are practically always generated, maybe we don't need to support the shorter version. In which case we could maybe just use & instead of @. When a value contains &something then it refers to a renderer, if it contains contains a . like &theme.something then it refers to a section of a theme instead of a renderer section.

I have a slight preference to not introduce a new @ symbol if it isn't needed. However if it's easier to implement with the additional symbol (or if I overlooked something and you have another argument in favor for it) then I'm ok with it being added and implemented as described.

[jpgaribotti]

I think from an implementation perspective, the @ syymbol will make the parsing of the file considerably simpler. With @, the moment you see the symbol you know you're dealing with a theme, and you can go down the correct branch immediately. With & the parser needs to look ahead to determine, which makes for a more complex parsing algorithm. Given this is a relatively simple serialization format, and we don't have a lot of pressure on symbols, I would lean towards the @.

Another advantage of the separate symbol syntax is that @theme would be a valid way of stating "use the default for this widget type" and let TGUI look up the widget inheritance rules for custom widgets which call tgui::Theme::addRendererInheritanceParent. Without it, if you're writing them, you need to keep those aligned, as there might not be a MyWidget section in the theme but there could be a BaseWidget section.

[texus]

If you want to then you can go ahead and implement it using @. I currently don't have the time to really examine the code and determine how much simpler or harder either option would be.

Note that the DataIO parser is not only used for widget forms, but also theme files (which have the same syntax). You have to make certain that the implementation still works for both, but for theme files the new functionality will probably be useless and wouldn't be used. Maybe that's an argument in favor of @: if an @ appears in a theme file then you immediately know it is invalid (unless in the future we add e.g. the possibility for one theme to refer to another theme somehow).

Without it, if you're writing them, you need to keep those aligned, as there might not be a MyWidget section in the theme but there could be a BaseWidget section.

I would imagine that specifying @theme.MyWidget should still fall back to the BaseWidget section if MyWidget is missing.