State Management in Basalt

Basalt provides a powerful state management system that allows elements to respond to different interaction states (hover, clicked, focused, etc.) with automatic property changes. This system makes it easy to create interactive UIs without manual event handling.

Understanding States

States are named conditions that elements can be in. When a state becomes active, the element can automatically change its appearance or behavior. States have priorities, allowing you to control which state takes precedence when multiple states are active.

Core State Methods

registerState

element:registerState(stateName, condition?, priority?)

Registers a new state with optional auto-activation condition:

• stateName: Name of the state (string)
• condition?: Optional function that returns true when state should be active: function(element) return boolean end
• priority?: Priority value (higher = more important, default: 0)
• Returns: self (for method chaining)

setState

element:setState(stateName, priority?)

Manually activates a state:

• stateName: Name of the state to activate
• priority?: Optional priority override
• Returns: self (for method chaining)

Example:

button:setState("clicked")
button:setState("error", 300) -- High priority error state

unsetState

element:unsetState(stateName)

Deactivates a state:

• stateName: Name of the state to deactivate
• Returns: self (for method chaining)

Example:

button:unsetState("clicked")

hasState

local isActive = element:hasState(stateName)

Checks if a state is currently active:

• stateName: Name of the state to check
• Returns: boolean

Example:

if button:hasState("hover") then
    basalt.LOGGER.debug("Button is being hovered!")
end

getCurrentState

local state = element:getCurrentState()

Gets the state with highest priority:

• Returns: string (state name) or nil

Example:

local currentState = button:getCurrentState()
-- Returns "clicked" if clicked state has highest priority

getActiveStates

local states = element:getActiveStates()

Gets all active states sorted by priority:

• Returns: array of {name, priority} tables

Example:

local states = button:getActiveStates()
-- Returns: {{name="clicked", priority=200}, {name="hover", priority=100}}

updateConditionalStates

element:updateConditionalStates()

Updates all states that have auto-conditions:

• Evaluates condition functions for all registered states
• Automatically activates/deactivates states based on conditions
• Returns: self (for method chaining)

unregisterState

element:unregisterState(stateName)

Removes a state from the registry:

• stateName: Name of the state to remove
• Also deactivates the state if currently active
• Returns: self (for method chaining)

State-Bound Properties

Properties can be bound to states, allowing automatic property changes when states activate.

Setting State Properties

Use the set<Property>State methods to define property values for specific states:

-- Set background color for different states
button:setBackgroundState("clicked", colors.blue)

-- Set text for different states
button:setText("Click Me")
button:setTextState("clicked", "Clicked!")

Getting State Properties

local value = element:get<Property>State(stateName)

Example:

local clickedBg = button:getBackgroundState("clicked")

How State Properties Work

1. When a state activates, the element looks for bound properties
2. The property automatically changes to the state-bound value
3. When the state deactivates, the property returns to its base value (or next highest priority state)
4. Higher priority states override lower priority states

Built-in Interactive States

Many elements automatically register common interaction states:

Button States

• hover (priority: 100) - Mouse is over the button
• clicked (priority: 200) - Button is being clicked

Input States

• focused (priority: 100) - Input has focus

Custom States

You can create any custom state names for your own logic:

button:registerState("loading")
button:registerState("success")
button:registerState("error")

Using States with Reactive Expressions

States integrate seamlessly with the reactive system:

-- State values can be used in expressions
label:setText("{parent.clicked and 'Clicked!' or 'Click Me'}")

Complete Examples

Example: Interactive Button

local button = main:addButton()
    :setText("Click Me!")
    :setPosition(10, 5)
    :setSize(20, 3)

-- Register states (they're auto-registered by Button, but shown for clarity)
button:registerState("clicked", nil, 200)

-- Set appearance for each state
button:setBackgroundState("clicked", colors.blue)
button:setForegroundState("clicked", colors.white)
button:setTextState("clicked", "Clicked!")

-- Normal state
button:setBackground(colors.gray)
button:setForeground(colors.black)

State Priorities

When multiple states are active, the highest priority wins:

button:registerState("hover", nil, 100)
button:registerState("clicked", nil, 200)
button:registerState("disabled", nil, 300)

-- Set different backgrounds
button:setBackgroundState("hover", colors.lightGray)
button:setBackgroundState("clicked", colors.blue)
button:setBackgroundState("disabled", colors.gray)

-- If both hover and clicked are active, clicked wins (higher priority)
-- If disabled is active, it always wins (highest priority)

State Integration with XML

States can be configured in XML:

<button text="Click Me">
    <state name="hover">
        <background>lightGray</background>
        <foreground>white</foreground>
    </state>
    <state name="clicked">
        <background value="blue" />
        <text value="Clicked!" />
    </state>
</button>

Or using inline attributes:

<button 
    text="Click Me"
    backgroundState:hover="lightGray"
    textState:clicked="Clicked!"
/>