121 lines
2.9 KiB
Markdown
121 lines
2.9 KiB
Markdown
# Properties in Basalt
|
|
|
|
Properties are the foundation of how Basalt elements store and manage their attributes. Understanding how properties work is key to effectively using Basalt.
|
|
|
|
## Basic Usage
|
|
|
|
Every element in Basalt has properties that can be accessed and modified:
|
|
|
|
```lua
|
|
local button = main:addButton()
|
|
:setPosition(5, 5) -- Set position property
|
|
:setSize(10, 3) -- Set size property
|
|
:setText("Click me") -- Set text property
|
|
```
|
|
|
|
## Dynamic Properties
|
|
|
|
Properties can be dynamic using strings or functions:
|
|
|
|
```lua
|
|
-- String-based dynamic properties
|
|
button:setPosition("{parent.width - 10}", 5) -- 10 pixels from right edge
|
|
|
|
-- Function-based dynamic properties
|
|
button:setPosition(function(self)
|
|
return self:getParent():getWidth() - 10
|
|
end, 5)
|
|
```
|
|
|
|
## Property Types
|
|
|
|
### Position Properties
|
|
- `x`, `y` - Element position
|
|
- `width`, `height` - Element size
|
|
- `z` - Layer order (higher numbers = on top)
|
|
|
|
### Visual Properties
|
|
- `background` - Background color
|
|
- `foreground` - Text color
|
|
- `visible` - Whether element is shown
|
|
- `text` - Element's text content
|
|
|
|
### State Properties
|
|
- `focused` - Has keyboard focus
|
|
- `clicked` - Currently being clicked
|
|
- `enabled` - Can receive input
|
|
|
|
## Combined Properties
|
|
|
|
Some properties can be set together:
|
|
|
|
```lua
|
|
button:setSize(10, 3) -- Individual
|
|
button:setPosition(5, 5) -- Individual
|
|
|
|
-- OR combined:
|
|
button:setSize({10, 3}) -- Combined
|
|
button:setPosition({5, 5}) -- Combined
|
|
```
|
|
|
|
## Property Inheritance
|
|
|
|
Elements inherit properties from their parent containers:
|
|
|
|
```lua
|
|
local frame = main:addFrame()
|
|
:setBackground(colors.blue) -- All children inherit this background
|
|
|
|
frame:addButton() -- Button has blue background unless overridden
|
|
```
|
|
|
|
## Property Events
|
|
|
|
You can react to property changes:
|
|
|
|
```lua
|
|
button:onChange("text", function(self, newText)
|
|
-- Called when text property changes
|
|
end)
|
|
```
|
|
|
|
## Tips & Best Practices
|
|
|
|
1. **Dynamic Updates**
|
|
- Use dynamic properties for responsive layouts
|
|
- Avoid expensive calculations in property functions
|
|
- Chain property setters for cleaner code
|
|
|
|
2. **Performance**
|
|
- Only update properties when needed
|
|
- Use combined setters when changing multiple related properties
|
|
- Consider using states for complex property management
|
|
|
|
3. **Organization**
|
|
- Group related property changes together
|
|
- Initialize all important properties at creation
|
|
- Use meaningful values for better readability
|
|
|
|
## Common Patterns
|
|
|
|
### Responsive Layout
|
|
```lua
|
|
element:setPosition(2, 2)
|
|
:setSize("{parent.width - 4}", "{parent.height - 4}")
|
|
```
|
|
|
|
### Conditional Styling
|
|
```lua
|
|
button:setBackground(function(self)
|
|
return self.clicked and colors.gray or colors.lightGray
|
|
end)
|
|
```
|
|
|
|
### Layout Calculations
|
|
```lua
|
|
element:setPosition(function(self)
|
|
local parent = self:getParent()
|
|
return math.floor((parent:getWidth() - self:getWidth()) / 2)
|
|
end)
|
|
|