150 lines
4.4 KiB
Markdown
150 lines
4.4 KiB
Markdown
# State Management in Basalt
|
|
|
|
States provide a new way to manage data and UI synchronization in your Basalt applications.
|
|
|
|
## Detailed State Methods
|
|
|
|
### initializeState
|
|
```lua
|
|
BaseFrame:initializeState("name", defaultValue, persistent, path?)
|
|
```
|
|
Creates a new state in a BaseFrame:
|
|
- `name`: Name of the state (string)
|
|
- `defaultValue`: Initial value of the state (any type)
|
|
- `persistent?`: Boolean that determines if the state should be stored into a file
|
|
- `path?`: The path the state should be stored to (default: states/BaseFrameNAME.state)
|
|
- Returns: self (for method chaining)
|
|
|
|
### setState
|
|
```lua
|
|
element:setState("name", newValue)
|
|
```
|
|
Updates an existing state's value:
|
|
- `name`: Name of the state to update
|
|
- `newValue`: New value to set
|
|
- Automatically triggers UI updates if triggerRender=true
|
|
- Returns: self (for method chaining)
|
|
|
|
### getState
|
|
```lua
|
|
local value = element:getState("name")
|
|
```
|
|
Retrieves the current value of a state:
|
|
- `name`: Name of the state to get
|
|
- Returns: Current value of the state
|
|
|
|
### computed
|
|
```lua
|
|
element:computed("name", function(self)
|
|
local otherState = self:getState("otherState")
|
|
return someCalculation(otherState)
|
|
end)
|
|
```
|
|
Creates a computed state that depends on other states:
|
|
- `name`: Name of the computed state
|
|
- `function`: Function that calculates the value
|
|
- Automatically recalculates when dependent states change
|
|
- Returns: self (for method chaining)
|
|
|
|
### onStateChange
|
|
```lua
|
|
element:onStateChange("name", function(self, newValue)
|
|
-- React to changes
|
|
self:someAction(newValue)
|
|
end)
|
|
```
|
|
Registers a listener for state changes:
|
|
- `name`: Name of the state to watch
|
|
- `function`: Callback function receiving the new value
|
|
- Executes whenever the state changes
|
|
- Returns: self (for method chaining)
|
|
|
|
### bind
|
|
```lua
|
|
local name = form:addInput():bind("text", "name")
|
|
```
|
|
Binds a property to a state
|
|
- `propertyName`: The name of the property
|
|
- `stateName`: The name of the state
|
|
- Returns: self (for method chaining)
|
|
|
|
## Example: Form Validation
|
|
|
|
Here's a comprehensive example showing state management in a form:
|
|
|
|
```lua
|
|
local main = basalt.getMainFrame()
|
|
-- Initialize form states
|
|
:initializeState("username", "", true) -- make them persistent
|
|
:initializeState("password", "", true) -- make them persistent
|
|
:initializeState("confirmPassword", "", true) -- make them persistent
|
|
|
|
local form = main:addFrame()
|
|
:setSize("{parent.width - 4}", "{parent.height - 4}")
|
|
:setPosition(3, 3)
|
|
|
|
-- Add computed validation state
|
|
form:computed("isValid", function(self)
|
|
local username = self:getState("username")
|
|
local password = self:getState("password")
|
|
local confirmPass = self:getState("confirmPassword")
|
|
return #username >= 3 and #password >= 6 and password == confirmPass
|
|
end)
|
|
|
|
-- Create labels
|
|
form:addLabel({text="Username:", x = 2, y = 2, foreground = colors.lightGray})
|
|
form:addLabel({text="Password:", x = 2, y = 4, foreground = colors.lightGray})
|
|
form:addLabel({text="Confirm:", x = 2, y = 6, foreground = colors.lightGray})
|
|
|
|
local userInput = form:addInput({x = 11, y = 2, width = 20, height = 1}):bind("text", "username")
|
|
local passwordInput = form:addInput({x = 11, y = 4, width = 20, height = 1}):bind("text", "password")
|
|
local confirmInput = form:addInput({x = 11, y = 6, width = 20, height = 1}):bind("text", "confirmPassword")
|
|
|
|
-- Submit button
|
|
local submitBtn = form:addButton()
|
|
:setText("Submit")
|
|
:setPosition(2, 8)
|
|
:setSize(29, 1)
|
|
|
|
-- Status label
|
|
local statusLabel = form:addLabel()
|
|
:setPosition(2, 10)
|
|
:setSize(29, 1)
|
|
|
|
|
|
form:onStateChange("isValid", function(self, isValid)
|
|
if isValid then
|
|
statusLabel:setText("Form is valid!")
|
|
:setForeground(colors.green)
|
|
submitBtn:setBackground(colors.green)
|
|
else
|
|
statusLabel:setText("Please fill all fields correctly")
|
|
:setForeground(colors.red)
|
|
submitBtn:setBackground(colors.red)
|
|
end
|
|
end)
|
|
```
|
|
|
|
## Tips
|
|
|
|
1. **State Initialization**
|
|
- Always initialize states at component creation
|
|
- Use descriptive state names
|
|
- Consider carefully whether updates should trigger renders
|
|
|
|
2. **Computed States**
|
|
- Use for values derived from other states
|
|
- Keep calculations simple and performant
|
|
- Avoid circular dependencies
|
|
|
|
3. **State Updates**
|
|
- Only modify states through setState
|
|
- Use onStateChange for side effects
|
|
- Batch multiple updates when possible
|
|
|
|
4. **Common Patterns**
|
|
- Form validation
|
|
- UI state management
|
|
- Data synchronization
|
|
- Component communication
|