Represents a named value within the Layers theme framework.

Attributes are the building blocks of themes and styles. They store numbers, strings, booleans, or arrays through the LVariant type.

Most attributes are defined in JSON themes and styles rather than created programmatically. For JSON syntax and concepts, see the Layers README. This documentation covers the C++ interface for working with attributes in code.

Values

Create attributes with different value types:

LAttribute* fill =
    new LAttribute("Fill", "#ffffff");

LAttribute* thickness =
    new LAttribute("Thickness", 5.0);

Access values with as<T>():

LString f = fill->as<LString>();
// f = "#ffffff"

double t = thickness->as<double>();
// t = 5.0

For safe access, as_if<T>() returns nullptr if the type doesn't match:

if (const auto* f = fill->as_if<LString>())
    // fill must be an LString

Paths

Since attributes are owned, they exist within an object hierarchy.

Every attribute has a path identifying its location in the hierarchy.

Paths use / to separate between object names:

// Assume fill belongs to a button
"Button/Fill"

Linking

Linking lets one attribute reference another, further known as the link attribute. When linked, valuation returns the link attribute's value:

LAttribute* primary =
    new LAttribute("Primary", "#001122");

fill->create_link(primary);

f = fill->as<LString>();
// f = #001122 (value indirectly from primary)

An attribute that links to another is known as a dependent attribute.

You can acquire a list of dependent attributes:

LAttributeList deps = primary->dependent_attributes();
// deps contains the fill attribute

Remember to break links when they are no longer needed. When a link is broken, the attribute copies its value:

fill->break_link();

f = fill->as<LString>();
// f = #001122 (same value directly from fill now)

LAttributeList deps = primary->dependent_attributes();
// deps no longer contains the fill attribute

States

States let attributes have multiple values, accessed conditionally.

States are just sub-attributes in the object hierarchy:

lMake<LAttribute>(fill, "Selected", "#445566");
// fill is a parent receiving a "Selected" state

You can access a state value directly:

f = fill->state("Hovered")->as<LString>();
// f = #445566 (state value accessed directly)

However, prefer passing a state variable when accessing the parent's value:

// State variable, subject to change
LString state = "Selected";

f = fill->as<LString>(state);
// f = #445566 (state value accessed through fill)

You can check if an attribute has any states:

if (fill->has_states())
    // fill must have states

Change Notifications

Register callbacks to detect value changes:

LConnectionID conn = fill->on_change([]()
    { cout << "Fill changed!" << endl; });

// Remember to disconnect when it's no longer needed
fill->disconnect_change(conn);