The BasicElement class is the fundamental building block class in Basalt, from which all other elements are derived. You can think of it as the “origin” of all elements within the framework. The BasicElement class provides essential functions that are common to all derived elements, such as adding and removing event listeners and managing inheritance and relationships between elements.
In simple terms, the BasicElement class is like a common ancestor that passes down basic functions and properties to all subsequent elements. This makes it easier to keep the behavior of elements throughout the framework consistent and predictable.
| Property | Type | Description |
|---|---|---|
| enabled | boolean | Controls whether the event listeners are active. When set to true, event operations related to the element are processed. |
| parent | Container | References the parent element that this element is nested within, if any. |
| events | table | A table storing event handlers associated with this element. |
| propertyObservers | table | A table holding observer functions that get triggered when specific properties of the element change. Useful for reactivity and updating related UI elements. |
| name | string | A unique identifier or label for the element, which can be useful for debugging or for referencing the element programmatically. |
| type | string | Describes the kind or category of the element, such as "button", "input", "label", etc. |
| z | number | Represents the elements's depth or layering order in the UI. Higher values will render the element on top of those with lower values, allowing for control over overlapping elements. |
| Method | Returns | Description |
|---|---|---|
| getProperty | any | Returns a property value. |
| setProperty | self | Sets a property's value. |
| hasProperty | boolean | Checks if a property exists for the element. |
| setProperties | self | Sets multiple properties for a element at once. |
| getProperties | table | Retrieves all properties and their values for a element. |
| getPropertyType | string | Retrieves the data type of a specified property for a element. |
| addPropertyObserver | self | Adds an observer function to monitor changes to a specific property of a element. |
| removePropertyObserver | self | Removes an observer function from monitoring changes to a specific property of a element. |
| forcePropertyObserverUpdate | self | Forces an update of all property observers for a element. |
| fireEvent | self | Fires an event associated with the element. |
| isType | boolean | Checks if the element belongs to a specified type. |
| updateEvents | self | Updates all events associated with the element. |
Retrieves the value of a specified property for a element.
string the name of the propertyany the value of the specified property. The type of the returned value depends on the nature of the property (e.g., it could be a string, number, table, etc.).local main = basalt.getMainFrame()
local button = main:addButton()
-- Retrieve and print the 'name' property of the button
local propertyName = button:getProperty("name")
basalt.debug(propertyName)Sets the value of a specified property for a element.
string The name of the property you wish to set.anyThe value you want to assign to the specified property. The type of this parameter should match the expected type for the property in question (e.g., string, number, table, etc.).local main = basalt.getMainFrame()
local button = main:addButton()
-- Set the 'name' property of the button to a new value
button:setProperty("name", "MyButton")
-- For demonstration, retrieve and print the updated 'name' property
local updatedPropertyName = button:getProperty("name")
basalt.debug(updatedPropertyName)Checks if a property exists for the element.
boolean true if the property exists, false otherwise.local main = basalt.getMainFrame()
local button = main:addButton()
-- Check if the 'name' property exists for the button
local hasNameProperty = button:hasProperty("name")
basalt.debug(hasNameProperty)Sets multiple properties for an element at once.
table A table containing key-value pairs of properties and their corresponding values.self The element itself.local main = basalt.getMainFrame()
local button = main:addButton()
-- Set multiple properties for the button
button:setProperties({
name = "MyButton",
x = 3,
y = 5,
width = 16,
height = 3,
})Retrieves all properties and their values for an element.
table Retrieves all properties and their values for an element.local main = basalt.getMainFrame()
local button = main:addButton()
-- Retrieve all properties and their values for the button
local properties = button:getProperties()
basalt.debug(properties) -- Output: {name = uuid, enabled = true, x = 1, y = 1, width = 12, height = 3, ...}Retrieves the data type of a specified property for an element.
string The name of the property.string The data type of the specified propertylocal main = basalt.getMainFrame()
local button = main:addButton()
-- Retrieve the data type of the 'background' property for the button
local propertyType = button:getPropertyType("background")
basalt.debug(propertyType) -- Output: "color"Adds an observer function to monitor changes to a specific property of an element. The Observer System is mainly used by the dynamic values extension.
string The name of the property to observe.function The observer function to call when the property changes.self The element itself.local main = basalt.getMainFrame()
local button = main:addButton()
-- Define an observer function
local function backgroundObserver(value)
basalt.debug("Button background changed to: " .. tostring(value))
end
-- Add the observer function to monitor changes to the 'background' property of the button
button:addPropertyObserver("background", backgroundObserver)
-- Now, whenever the 'background' property of the button changes, the observer function will be called
button:setProperty("background", colors.red) -- Output: "Button background changed to: 16384"Removes an observer function from monitoring changes to a specific property of an element.
string The name of the property being observed.function|number The observer function to remove, or the index in the table.self The element itself.-- Assuming 'backgroundObserver' was previously added as an observer for the 'background' property of the button
button:removePropertyObserver("background", backgroundObserver)Forces an update of all property observers for an element. This can be used by users, but it is mainly meant for internal usage.
self The element itself.button:forcePropertyObserverUpdate()Fires an event associated with the element
string The name of the event to fire.self The element itself.button:fireEvent("mouse_click")Checks if the element belongs to a specified type.
string The type to check against.boolean true if the element belongs to the specified type, false otherwise.local main = basalt.getMainFrame()
local frame = main:addFrame()
basalt.debug(frame:isType("Container")) -- Output: trueThis will register all events to the parent. Mainly used internal. For example this is beeing called when we switch the parent frame.
self The element itself.button:updateEvents()