Public Functions
Detailed Description
Represents a UI element style in the Layers theme framework.
Styles compose attributes and child styles to define the appearance of UI components.
Most styles are defined in JSON files rather than created programmatically. For JSON syntax and concepts, see the Layers README. This documentation covers the C++ interface for working with styles in code.
Consider the following style:
LStyle* btn = new LStyle("Button");
Styles contain attributes that define visual properties.
Create attributes using the lMake<T>() factory function to ensure the
parent-child relationship is established properly:
lMake<LAttribute>(btn, "Fill", "#ffffff");
lMake<LAttribute>(btn, "Radius", 5.0);
Find attributes with find_attribute():
LAttribute* btn_fill =
btn->find_attribute("Fill");
LString f = btn_fill->as<LString>();
// f = "#ffffff"
You can iterate through all attributes():
cout << "Button Attributes:" << endl;
for (auto& [name, attr] : btn->attributes())
cout << " - " << name << endl;
Styles can contain child styles representing sub-elements.
Also create child styles using the lMake<T>() factory function:
lMake<LStyle>(btn, "Icon Label");
lMake<LStyle>(btn, "Text Label");
Find them with find_item():
LStyle* btn_icon =
btn->find_item("Icon Label");
LStyle* btn_text =
btn->find_item("Text Label");
You can also iterate through all children():
cout << "Button Child Styles:" << endl;
for (auto& [name, child] : btn->children())
cout << " - " << name << endl;
Like attributes, every style has a path identifying its location in the hierarchy:
btn->path();
// "Button"
btn_icon->path();
// "Button/Icon Label"
btn_icon->find_attribute("Svg Color")->path();
// "Button/Icon Label/Svg Color"
Styles can inherit() from a base style and acquire its attributes and
children:
LStyle* exit_btn = new LStyle("Exit Button");
lMake<LAttribute>(exit_btn, "Fill", "#ab5050");
exit_btn->inherit(btn);
Since Exit Button has its own Fill, it doesn't inherit Button/Fill.
Get a list of all dependencies(), which are all of the base styles
inherited by the caller and its children:
LStyle* lbl = new LStyle("Label");
btn_icon->inherit(lbl);
btn_text->inherit(lbl);
auto deps = names(exit_btn->dependencies());
// deps = { "Button", "Label" }
User styles are toggleable customizations that override styles:
// Create user style that removes rounded corners:
LStyle* no_radius = new LStyle("No Radius");
lMake<LAttribute>(no_radius, "Radius", 0.0);
// Then apply it:
btn->apply_style(no_radius);
If you want to restore back to the original:
btn->clear_style();
You can also register a callback to detect when styles are applied:
btn->on_style_applied([]()
{ cout << "Style changed!" << endl; });
Extensions store arbitrary data with a style:
if (btn->has_extension("tooltip"))
{
json tooltip = btn->extension("tooltip");
// Use tooltip data
}
Extensions can only be added in JSON since there is currently no public interface for adding them in code.
Member Function Documentation
LStyle()
Constructs an empty style.
LStyle(const LString & name)
Constructs a style with a name.
LStyle(const LString & name, const json & value, const std::filesystem::path & file_path)
Constructs a style from JSON data.
The name parameter identifies the style, value contains the JSON definition, and file_path indicates where the style was loaded from.
~LStyle()
No description available.
void apply_style(LStyle * style_def)
Applies the properties of another style to this style.
This is used for user styles and custom style overrides.
std::vector<LString> attribute_group_names()
Returns the names of all attribute groups in this style.
std::map<LString, LAttribute *> attributes(int type_index = -1)
Returns a map of all attributes in this style.
If type_index is specified, only returns attributes of that variant type.
LStyle * base()
Returns the base style this style inherits from.
Returns nullptr if this style has no base.
LString base_name()
Returns the name of the base style.
LStyle * child(int index)
Returns the child style at the given index.
Returns nullptr if the index is out of bounds.
size_t child_count()
Returns the number of child styles.
void clear_style()
Clears the applied custom style, restoring default values.
void clone_to(LObject * parent)
No description available.
std::set<LStyle *> dependencies()
Returns a set of all styles this style depends on.
Returns the value of a custom extension property.
Extensions allow storing arbitrary JSON data with a style.
const json & extensions()
Returns all extension properties for this style.
LString file_name()
Returns the filename this style was loaded from.
void finalize()
Finalizes the style after loading and inheritance resolution.
This locks the style structure and prepares it for use.
LAttribute * find_attribute(const LString & attr_name)
Finds an attribute by name within this style.
Returns nullptr if the attribute is not found.
Lookups are served from a per-style name map that is rebuilt only when the style's child set changes (see LObject::children_version), so repeated lookups — the render hot path — cost one map find instead of a scan over freshly-enumerated children. The string_view overload is the implementation; the LString/const char* overloads delegate to it (the latter also keeps string-literal calls unambiguous).
LAttribute * find_attribute(std::string_view attr_name)
No description available.
LAttribute * find_attribute(const char * attr_name)
No description available.
Finds a child style by path.
The path uses '/' as a separator for nested styles.
bool has_extension(const LString & key)
Returns true if this style has the specified extension property.
bool has_unresolved_base()
Returns true if this style has a base style that hasn't been resolved yet.
int index()
Returns this style's index among its siblings.
void on_style_applied(std::function<void ()> callback)
Registers a callback to be invoked when a custom style is applied.
LStyle * namespace_root()
Returns the top-level ancestor of this style — the direct child of the controller root that this style descends from (its "namespace" node). Reference resolution tries this scope before the global root, so styles under one library namespace ("Vortex/...") don't collide with another's.
Returns this style itself when it is already top-level.
LString path()
Returns the full path of this style.
LStyle * parent()
Returns the parent style in the hierarchy.
Returns nullptr if this is a root style.
LString publisher()
Returns the publisher name for this style.
void resolve_links()
Resolves all attribute links within this style.
void inherit(LStyle * base_style)
Sets the base style for inheritance.
void set_publisher(const LString & publisher)
Sets the publisher name for this style.
LStyle * style()
Returns the custom style that has been applied to this style.
Returns nullptr if no custom style is applied.
json to_json_object()
Converts this style to a JSON object representation.