94 lines
2.6 KiB
Markdown
94 lines
2.6 KiB
Markdown
# State Management in Basalt
|
|
|
|
States provide a powerful way to manage data and UI synchronization in your Basalt applications.
|
|
|
|
## Core Concepts
|
|
|
|
- **States**: Named values stored in frames
|
|
- **Computed States**: States that depend on other states
|
|
- **State Changes**: Automatic UI updates when states change
|
|
- **State Listeners**: React to state changes
|
|
|
|
## Basic State Methods
|
|
|
|
```lua
|
|
-- Initialize states
|
|
frame:initializeState("name", defaultValue, triggerRender)
|
|
frame:setState("name", newValue)
|
|
frame:getState("name")
|
|
|
|
-- Computed states
|
|
frame:computed("name", function(self)
|
|
-- Calculate and return value based on other states
|
|
end)
|
|
|
|
-- Listen to changes
|
|
frame:onStateChange("name", function(self, newValue)
|
|
-- React to state changes
|
|
end)
|
|
```
|
|
|
|
## Complete Form Example
|
|
|
|
Here's a comprehensive example showing state management in a form:
|
|
|
|
```lua
|
|
local main = basalt.getMainFrame()
|
|
local form = main:addFrame()
|
|
:setSize("{parent.width - 4}", "{parent.height - 4}")
|
|
-- Initialize multiple states
|
|
:initializeState("username", "")
|
|
:initializeState("email", "")
|
|
:initializeState("age", 0)
|
|
:initializeState("submitted", false)
|
|
-- Add computed validation state
|
|
:computed("isValid", function(self)
|
|
local username = self:getState("username")
|
|
local email = self:getState("email")
|
|
local age = self:getState("age")
|
|
return #username > 0 and email:match(".+@.+") and age > 0
|
|
end)
|
|
|
|
-- Input with state binding
|
|
form:addInput()
|
|
:onChange(function(self, value)
|
|
form:setState("username", value)
|
|
end)
|
|
|
|
-- Button reacting to computed state
|
|
form:addButton()
|
|
:onStateChange("isValid", function(self, isValid)
|
|
self:setBackground(isValid and colors.lime or colors.gray)
|
|
end)
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **State Initialization**
|
|
- Initialize all states at component creation
|
|
- Use meaningful default values
|
|
- Consider whether state changes should trigger renders
|
|
|
|
2. **Computed States**
|
|
- Use for values that depend on multiple states
|
|
- Keep computations simple and efficient
|
|
- Avoid circular dependencies
|
|
|
|
3. **State Updates**
|
|
- Update states through setState, not directly
|
|
- Use onStateChange for side effects
|
|
- Consider batching multiple state updates
|
|
|
|
4. **Form Validation**
|
|
- Use computed states for form validation
|
|
- Update UI elements based on validation state
|
|
- Trigger actions only when validation passes
|
|
|
|
## Tips
|
|
|
|
- Use states for data that affects multiple components
|
|
- Consider using tables for complex state
|
|
- Keep state updates minimal and efficient
|
|
- Use meaningful state names
|
|
- Document state dependencies
|