LTheme Class
#include <Layers/ltheme.h>
Public Functions
| LTheme() | |
| LTheme(const std::filesystem::path& path) | |
| LTheme(const LString& name, bool editable = true) | |
| LTheme(const LString& name, const LString& uuid, bool editable) | |
| void | append_to_lineage(const LString& theme_id) |
| void | clear() |
| std::filesystem::path | directory() const |
| LString | display_id() const |
| bool | editable() const |
| LThemeItem* | find_item(const LString& path) |
| LThemeItem* | find_item(const std::deque<LString>& name_list) |
| bool | has_implementation(const LString& app_display_id) const |
| std::vector<LString> | lineage() const |
| void | load(const LString& app_display_id) |
| LString | name() const |
| LString | publisher() const |
| LThemeItem* | root_item() const |
| void | save() |
| void | save_meta_file() |
| void | set_dir(const std::filesystem::path& dir) |
| void | set_name(const LString& new_name) |
| void | set_publisher(const LString& publisher) |
| LString | uuid() const |
Detailed Description
An LTheme stores data to change the appearance of LThemeable objects, known as themeable widgets.
Themes store data using LThemeItem objects which handle the hierarchical structure of themes. The root item can be obtained using root_item().
Display-ID
A theme's display-ID is composed of the theme's name followed by either the theme's UUID or publisher placed in parentheses (). The following are two examples:
Traffic Cone (75609c4d-4db3-48a4-b8c8-0a840d555001)
Blue (The Layers Project)The display-ID can be obtained using display_id().
Theme Directory Structure
A theme is stored on the local system as a collection of JSON files, known as theme files, stored within a directory, known as a theme directory.
A theme directory is labeled with the display-ID.
The following shows how a theme directory is structured:
Theme Name (Theme UUID/Publisher)/ - Theme directory
App1 Name (App1 Publisher)/ - Implementation set for App1
Layers/ - Implementation set for Layers
... - Other implementation sets for other apps
app.json - App theme file
meta.json - Theme metadata file
Implementation Sets
A collection of theme files that implement the theme for a specific application is called an implementation set. Implementation sets are stored in subdirectories at the top-level of the theme directory.
Metadata File
The theme's metadata is stored within a theme file labeled meta.json found at the top-level of the theme directory. It contains data regarding the theme's name, UUID, publisher, and lineage. This file is used to partially load a theme without loading other theme files.
Loading Themes
Themes initialized from directories are only partially loaded at first. Only the theme's metadata is loaded while none of the implementation sets get loaded until they are needed. This partial-loading is performed to save system resources.
Managing Attribute Links
Once implementation sets have been loaded, theme attributes with valid link paths have their links resolved. See LAttribute for more information on attribute linking.
Lineage Tracking
When a new theme is created, it starts as a copy of another theme, referred to as the parent theme. The display-ID of the parent theme is tracked as part of the new theme's lineage. The new theme also inherits the parent theme's lineage.
Themes that make up the lineage are called ancestor themes.
This feature may be useful in the future to aid in compatibility.
Member Function Documentation
LTheme()
Constructs an empty, nameless theme.
LTheme(const std::filesystem::path& path)
Constructs a theme from a directory.
Metadata is loaded from the theme's meta.json file.
LTheme(const LString& name, bool editable = true)
Constructs a theme with the given name and editable status. A new UUID is generated.
Constructs a theme with the given name, uuid, and editable status.
void append_to_lineage(const LString& theme_id)
Adds theme_id to the lineage of this theme.
void clear()
Clears out any loaded implementation data.
The root item becomes nullptr after calling this function.
std::filesystem::path directory() const
Returns a path to the directory of this theme.
LString display_id() const
Returns the display-ID of this theme.
bool editable() const
Returns a boolean value determining whether or not the theme is editable.
LThemeItem* find_item(const LString& path)
Returns the child item identified by path.
This function operates recursively down the theme's hierarchy, starting at the root item. If no item is found, then nullptr is returned.
LThemeItem* find_item(const std::deque<LString>& name_list)
Returns the child item identified by name_list.
This function operates recursively down the theme's hierarchy, starting at the root item. If no item is found, then nullptr is returned.
bool has_implementation(const LString& app_display_id) const
Returns true if the theme directory contains an implementation set for the given app_display_id, false otherwise.
std::vector<LString> lineage() const
Returns a list containing the display-IDs of the ancestor themes in the theme's lineage.
void load(const LString& app_display_id)
Loads the relevant implementation sets of the theme.
LString name() const
Returns the name of the theme.
LString publisher() const
Returns the name of the publisher of the theme.
LThemeItem* root_item() const
Returns a pointer to the theme's root item.
void save()
Saves the theme.
The currently loaded theme data is separated into corresponding theme files which are stored in the theme directory.
void save_meta_file()
Saves the metadata file to the theme directory.
The file is labeled meta.json.
void set_dir(const std::filesystem::path& dir)
Sets the theme directory.
void set_name(const LString& new_name)
Sets the theme's name.
void set_publisher(const LString& publisher)
Sets the theme's publisher.
LString uuid() const
Returns the theme's UUID.