Skip to content

Visual Themes

Visual Themes

The Theme subsystem provides a convenient way to centrally store visual settings. The subsystem is designed to display application controls in a single view and easily centralize the ability to change the current theme on the fly.

The subsystem provides handy helpers for working with themes. These helpers operate with a singleton that all application controls use by default. The subsystem allows you to load a theme from json, which can be stored on disk or be a Windows application resource.

Example json file containing visual parameters of the main controllers.

Although the application always has a default theme, you can create your own custom theme and specify any control to use it. In this case, the control will be displayed according to your theme.

Below are the main helpers for centralizing the application theme. These helpers essentially represent access to the default theme instance singleton of the application.

Helpers

namespace wui
{

/// Set and get the current theme
#ifdef _WIN32
bool set_default_theme_from_resource(std::string_view name, int32_t resource_index, std::string_view resource_section);
#endif
bool set_default_theme_from_json(std::string_view name, std::string_view json);
bool set_default_theme_from_file(std::string_view name, std::string_view file_name);
void set_default_theme_empty(std::string_view name);

/// Return the pointer to current default theme instance
std::shared_ptr<i_theme> get_default_theme();

/// Make the custom theme for the some control
std::shared_ptr<i_theme> make_custom_theme(std::string_view name = "");
std::shared_ptr<i_theme> make_custom_theme(std::string_view name, std::string_view json);

/// Return the item's color by current theme
color theme_color(std::string_view control, std::string_view value, std::shared_ptr<i_theme> theme_ = nullptr);

/// Return the item's dimension by current theme
int32_t theme_dimension(std::string_view control, std::string_view value, std::shared_ptr<i_theme> theme_ = nullptr);

/// Return the item's string value by current theme
const std::string &theme_string(std::string_view control, std::string_view value, std::shared_ptr<i_theme> theme_ = nullptr);

/// Return the item's font value by current theme
font theme_font(std::string_view control, std::string_view value, std::shared_ptr<i_theme> theme_ = nullptr);

const std::vector<uint8_t> &theme_image(std::string_view name, std::shared_ptr<i_theme> theme_ = nullptr);

set_default_theme_from_resource (Windows only)

Input parameters

  • std::string_view name - theme name, e.g. "dark"
  • int32_t resource_index - resource ID
  • std::string_view resource_section - resource section, e.g. "JSONS"

Return value

  • true if successful

Function that loads the default application theme from a json file stored in the application resource.

Example:

#ifdef _WIN32
auto ok = wui::set_default_theme_from_resource("dark", TXT_DARK_THEME, "JSONS");
if (!ok)
{
    std::cerr << "can't load theme" << std::endl;
    return -1;
}
#endif

set_default_theme_from_json

Input parameters

  • std::string_view name - theme name
  • std::string_view json - string containing the theme json

Return value

  • true if successful

Function loading default application theme from json string

set_default_theme_from_file

Input parameters

  • std::string_view name - theme name
  • std::string_view file_name - path to the theme json file

Return value

  • true if successful

Function loading default application theme from json file

Example:

#ifdef _WIN32
...
#else
auto ok = wui::set_default_theme_from_file("dark", "res/dark.json");
if (!ok)
{
    std::cerr << "can't load theme" << std::endl;
    return -1;
}
#endif

set_default_theme_empty

Input parameters

  • std::string_view name - theme name

Sets the current theme to an empty theme, e.g. to customize it later using instance setters.

get_default_theme

Return value

  • std::shared_ptr<i_theme> - pointer to the default theme instance

Returns a pointer to the default instance of the topic

make_custom_theme

Input parameters

  • std::string_view name - theme name

Return value

  • std::shared_ptr<i_theme> - pointer to the instance of the created theme

Creates and returns a pointer to an empty custom theme. Intended for use in an individual control or a group of controls.

make_custom_theme

Input parameters

  • std::string_view name - theme name
  • std::string_view json - string containing the theme json

Return value

  • std::shared_ptr<i_theme> - pointer to the instance of the created theme

Creates and returns a pointer to a custom theme loaded from json. Designed to be used in a single control or a group of controls.

theme_color

Input parameters

  • std::string_view control - control name, e.g. "button"
  • std::string_view value - color name, e.g. "active"
  • std::shared_ptr<i_theme> theme_ = nullptr - pointer to the theme instance, if nullptr - the default theme is taken

Return value

  • color - requested color

Returns the color for the value of the control control. The theme_ parameter may contain the custom theme instance or be omitted, in which case the color from the default theme will be taken.

Example:

auto fill_color = enabled_ ? (active || turned_ ? theme_color(tcn, tv_active, theme_) : theme_color(tcn, tv_calm, theme_)) : theme_color(tcn, tv_disabled, theme_);

Where:

tcn = "button";
tv_active = "active";
tv_calm = "calm";
tv_disabled = "disabled";

A fragment of the theme's json:

{
  "type": "button",
  "calm": "#06a5df",
  "active": "#1aafe9",
  "disabled": "#a5a5a0"
}

theme_dimension

Input parameters

  • std::string_view control - control name, e.g. "button"
  • std::string_view value - dimension name, e.g. "border_width"
  • std::shared_ptr<i_theme> theme_ = nullptr - pointer to the theme instance, if nullptr - the default theme is taken

Return value

  • int32_t - requested dimension

Returns the size for the value of the control control. The theme_ parameter can contain the custom theme instance or be omitted, in which case the size will be taken from the default theme.

theme_string

Input parameters

  • std::string_view control - control name
  • std::string_view value - string name
  • std::shared_ptr<i_theme> theme_ = nullptr - pointer to the theme instance, if nullptr - the default theme is taken

Return value

  • const std::string & - link to the requested string

Returns a string for the value of the control control. The theme_ parameter can contain the custom theme instance or be omitted, in which case the string from the default theme will be taken.

theme_font

Input parameters

  • std::string_view control - control name
  • std::string_view value - font name, e.g. "caption_font"
  • std::shared_ptr<i_theme> theme_ = nullptr - pointer to the theme instance, if nullptr - the default theme is taken

Return value

  • font - requested font

Returns the font for the value of the control control. The theme_ parameter can contain the custom theme instance or be omitted, in which case the font from the default theme will b

theme_image

Input parameters

  • std::string_view name - image name
  • std::shared_ptr<i_theme> theme_ = nullptr - pointer to the theme instance, if nullptr - the default theme is taken

Return value

  • const std::vector<uint8_t>& - requested image

Returns a byte array containing the theme image for the value of the control control. The theme supports storing images in json as an escaped array. The array can also be loaded into the theme by the instance setter.

Example json:

"images": [
{ "window_expand": "0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00, 0x19, 0x00, 0x00, 0x00, 0x19, 0x08, 0x06, 0x00, 0x00, 0x00, 0xC4, 0xE9, 0x85, 0x63, 0x00, 0x00, 0x00, 0x09, 0x70, 0x48, 0x59, 0x73, 0x00, 0x00, 0x0B, 0x13, 0x00, 0x00, 0x0B, 0x13, 0x01, 0x00, 0x9A, 0x9C, 0x18, 0x00, 0x00, 0x00, 0x19, 0x74, 0x45, 0x58, 0x74, 0x53, 0x6F, 0x66, 0x74, 0x77, 0x61, 0x72, 0x65, 0x00, 0x41, 0x64, 0x6F, 0x62, 0x65, 0x20, 0x49, 0x6D, 0x61, 0x67, 0x65, 0x52, 0x65, 0x61, 0x64, 0x79, 0x71, 0xC9, 0x65, 0x3C, 0x00, 0x00, 0x00, 0x64, 0x49, 0x44, 0x41, 0x54, 0x78, 0xDA, 0x62, 0xFC, 0xFF, 0xFF, 0x3F, 0x03, 0xAD, 0x01, 0x13, 0x03, 0x1D, 0xC0, 0xA8, 0x25, 0x23, 0xD4, 0x12, 0x16, 0x6C, 0x82, 0x17, 0x2E, 0x9D, 0x9B, 0x00, 0xA4, 0x0C, 0x48, 0x35, 0xCC, 0x40, 0xCF, 0xC8, 0x81, 0x14, 0x9F, 0x18, 0x90, 0x68, 0x89, 0x02, 0x10, 0xDB, 0x93, 0xE4, 0x13, 0x98, 0x87, 0x70, 0xB9, 0x0C, 0x8B, 0xCF, 0x1B, 0x80, 0x54, 0xFD, 0x68, 0xEA, 0x1A, 0xB5, 0x64, 0x90, 0x64, 0x46, 0x58, 0xDA, 0x87, 0x26, 0x4D, 0x62, 0x80, 0x03, 0xB9, 0x96, 0xC8, 0xE3, 0x4B, 0xFB, 0xA4, 0x00, 0xC6, 0xD1, 0x9A, 0x71, 0xD4, 0x92, 0xA1, 0x6D, 0x09, 0x40, 0x80, 0x01, 0x00, 0x94, 0xC7, 0x13, 0xEF, 0xA5, 0x34, 0x2A, 0xAF, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4E, 0x44, 0xAE, 0x42, 0x60, 0x82" }
]

The interface of the theme instance

class i_theme
{
public:
    virtual std::string get_name() const = 0;

    virtual void set_color(std::string_view control, std::string_view value, color color_) = 0;
    virtual color get_color(std::string_view control, std::string_view value) const = 0;

    virtual void set_dimension(std::string_view control, std::string_view value, int32_t dimension) = 0;
    virtual int32_t get_dimension(std::string_view control, std::string_view value) const = 0;

    virtual void set_string(std::string_view control, std::string_view value, std::string_view str) = 0;
    virtual const std::string &get_string(std::string_view control, std::string_view value) const = 0;

    virtual void set_font(std::string_view control, std::string_view value, const font &font_) = 0;
    virtual font get_font(std::string_view control, std::string_view value) const = 0;

    virtual void set_image(std::string_view name, const std::vector<uint8_t> &data) = 0;
    virtual const std::vector<uint8_t> &get_image(std::string_view name) = 0;

#ifdef _WIN32
    virtual void load_resource(int32_t resource_index, std::string_view resource_section) = 0;
#endif
    virtual void load_json(std::string_view json) = 0;
    virtual void load_file(std::string_view file_name) = 0;
    virtual void load_theme(const i_theme &theme_) = 0;

    virtual error get_error() const = 0;

    virtual ~i_theme() {}
};

Each control accepts this interface in order to receive the visual parameters of its display

get_name

Return value

  • const std::string - theme instance name Returns the character name of the theme, for example `"dark" or "light"

set_color

Input parameters

  • std::string_view control - control name, e.g. "button"
  • std::string_view value - color name, e.g. "active"
  • color color_ - settable color

Sets the color for the value of the control control

Example:

auto redButtonTheme = wui::make_custom_theme(); // Creating a new custom theme
redButtonTheme->load_theme(*wui::get_default_theme()); // Load it from the default so that we don't have to set all the values

redButtonTheme->set_color(wui::button::tc, wui::button::tv_calm, wui::make_color(205, 15, 20)); // Set the fill color of the button in the idle mode

... Use a new theme when creating a button or apply it to an existing one

Where:

wui::button::tc = "button";
wui::button::tv_calm = "calm";

Which means this color will be applied to the control named "button" in the "calm" state.

get_color

Input parameters

  • std::string_view control - control name
  • std::string_view value - color name

Return value

  • color - requested color

Returns the color for the value of the control control

set_dimension

Input parameters

  • std::string_view control - control name
  • std::string_view value - dimension name
  • int32_t dimension - setted dimension

Sets the size for the value of the control control

get_dimension

Input parameters

  • std::string_view control - control name
  • std::string_view value - dimension name

Return value

  • int32_t - requested dimension

Returns the size for the value of the control control

set_string

Input parameters

  • std::string_view control - control name
  • std::string_view value - string name
  • std::string_view str - setted string

Sets the string for the value of the control control

get_string

Input parameters

  • std::string_view control - control name
  • std::string_view value - string name

Return value

  • const std::string & - link to the requested string

Returns a string for the value of the control control

set_font

Input parameters

  • std::string_view control - control name
  • std::string_view value - font name
  • const font &font_ - setted font

Sets the font for the value of the control control

get_font

Input parameters

  • std::string_view control - control name
  • std::string_view value - font name

Return value

  • font - requested font

Returns the font for the value of the control control

set_image

Input parameters

  • std::string_view name - image name
  • const std::vector<uint8_t> &data - setted image

Sets the image named name from the data byte array

get_image

Input parameters

  • std::string_view name - image name

Return value

  • const std::vector<uint8_t> & - requested image

Returns a link to a byte array containing the subject image for the value of the control control

load_resource (Windows only)

Input parameters

  • int32_t resource_index - recource ID
  • std::string_view resource_section - resource section, e.g. "JSONS"

Function loading a theme from a json file stored in the application resource

load_json

Input parameters

  • std::string_view json - json string

Function loading theme from json string

load_file

Input parameters

  • std::string_view file_name - json file path

Function loading theme from json file

load_theme

Input parameters

  • const i_theme &theme_ - link to another theme

Function loading a theme from another theme instance

get_error

Returns an error; use get_error().is_ok() and get_error().str().

After loading a default theme, call window->update_theme(). A control with an explicit custom theme retains it when updated without an argument. Pass another theme explicitly to replace it. Font values are JSON objects with name, size and optional decorations; they are not names of a separate font registry.