GitHub/Basalt2
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

deploy: 464314e219

Browse Source
This commit is contained in:
NoryiE
2025-09-30 12:42:49 +00:00
parent 00d69ebc07
commit 07009ca98b
9 changed files with 111 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/references/elements/BarChart.md
View File

@@ -1,4 +1,4 @@
# BarChart # BarChart
_The Bar Chart element is designed for visualizing data series as vertical bars. It displays multiple values as side-by-side bars where each bar's height represents its value._ _A data visualization element that represents numeric data through vertical bars. Each bar's height corresponds to its value, making it ideal for comparing quantities across categories or showing data changes over time. Supports multiple data series with customizable colors and styles._
Extends: `Graph` Extends: `Graph`

50
docs/references/elements/BaseElement.md
View File

@@ -1,5 +1,5 @@
# BaseElement # BaseElement
_The base class for all UI elements in Basalt. This class provides basic properties and event handling functionality._ _The fundamental base class for all UI elements in Basalt. It implements core functionality like event handling, property management, lifecycle hooks, and the observer pattern. Every UI component inherits from this class to ensure consistent behavior and interface._
Extends: `PropertySystem` Extends: `PropertySystem`
@@ -7,30 +7,30 @@ Extends: `PropertySystem`
|Property|Type|Default|Description| |Property|Type|Default|Description|
|---|---|---|---| |---|---|---|---|
|type|string|BaseElement|The type identifier of the element| |type|string|BaseElement|A hierarchical identifier of the element's type chain|
|id|string|BaseElement|The unique identifier for the element| |id|string|BaseElement|Auto-generated unique identifier for element lookup|
|name|string|BaseElement|The name of the element| |name|string|BaseElement|User-defined name for the element|
|eventCallbacks|table|BaseElement|The event callbacks for the element| |eventCallbacks|table|BaseElement|Collection of registered event handler functions|
|enabled|boolean|BaseElement|Whether the element is enabled or not| |enabled|boolean|BaseElement|Controls event processing for this element|
## Functions ## Functions
|Method|Returns|Description| |Method|Returns|Description|
|---|---|---| |---|---|---|
|[BaseElement.defineEvent](#baseelement-defineevent-class-eventname-requiredevent)|-|Registers a new event listener for the element (on class level)| |[BaseElement.defineEvent](#baseelement-defineevent-class-eventname-requiredevent)|-|Registers a new event listener for the element (on class level)|
|[BaseElement.registerEventCallback](#baseelement-registereventcallback-class-callbackname-string)|-|Registers a new event callback for the element (on class level)| |[BaseElement.registerEventCallback](#baseelement-registereventcallback-class-callbackname-string)|-|Registers a new event callback method with auto-registration|
|[BaseElement:isType](#baseelement-istype-type)|boolean|Checks if the element is a specific type| |[BaseElement:isType](#baseelement-istype-type)|boolean|Tests if element is of or inherits given type|
|[BaseElement:listenEvent](#baseelement-listenevent-eventname-enable)|table|Enables or disables event listening for a specific event| |[BaseElement:listenEvent](#baseelement-listenevent-eventname-enable)|table|Enables/disables event handling for this element|
|[BaseElement:registerCallback](#baseelement-registercallback-event-callback)|table|Registers a callback function| |[BaseElement:registerCallback](#baseelement-registercallback-event-callback)|table|Registers a function to handle specific events|
|[BaseElement:fireEvent](#baseelement-fireevent-event-any)|table|Triggers an event and calls all registered callbacks| |[BaseElement:fireEvent](#baseelement-fireevent-event-any)|table|Triggers event callbacks with provided arguments|
|[BaseElement:onChange](#baseelement-onchange-property-callback)|table|Observes a property and calls a callback when it changes| |[BaseElement:onChange](#baseelement-onchange-property-callback)|table|Watches property changes with callback notification|
|[BaseElement:getBaseFrame](#baseelement-getbaseframe)|BaseFrame|Returns the base frame of the element| |[BaseElement:getBaseFrame](#baseelement-getbaseframe)|BaseFrame|Retrieves the root frame of this element's tree|
|[BaseElement:destroy](#baseelement-destroy)|-|Destroys the element and cleans up all references| |[BaseElement:destroy](#baseelement-destroy)|-|Removes element and performs cleanup|
|[BaseElement:updateRender](#baseelement-updaterender)|table|Requests a render update for this element| |[BaseElement:updateRender](#baseelement-updaterender)|table|Requests UI update for this element|
## BaseElement.defineEvent(class, eventName, requiredEvent?) ## BaseElement.defineEvent(class, eventName, requiredEvent?)
Registers a new event listener for the element (on class level) Registers a class-level event listener with optional dependency
### Parameters ### Parameters
* `class` `table` The class to register * `class` `table` The class to register
@@ -39,7 +39,7 @@ Registers a new event listener for the element (on class level)
## BaseElement.registerEventCallback(class, callbackName, string) ## BaseElement.registerEventCallback(class, callbackName, string)
Registers a new event callback for the element (on class level) Defines a class-level event callback method with automatic event registration
### Parameters ### Parameters
* `class` `table` The class to register * `class` `table` The class to register
@@ -48,7 +48,7 @@ Registers a new event callback for the element (on class level)
## BaseElement:isType(type) ## BaseElement:isType(type)
Checks if the element is a specific type Checks if the element matches or inherits from the specified type
### Parameters ### Parameters
* `type` `string` The type to check for * `type` `string` The type to check for
@@ -58,7 +58,7 @@ Checks if the element is a specific type
## BaseElement:listenEvent(eventName, enable?) ## BaseElement:listenEvent(eventName, enable?)
Enables or disables event listening for a specific event Configures event listening behavior with automatic parent notification
### Parameters ### Parameters
* `eventName` `string` The name of the event to listen for * `eventName` `string` The name of the event to listen for
@@ -69,7 +69,7 @@ Enables or disables event listening for a specific event
## BaseElement:registerCallback(event, callback) ## BaseElement:registerCallback(event, callback)
Registers a callback function for an event Adds an event handler function with automatic event registration
### Parameters ### Parameters
* `event` `string` The event to register the callback for * `event` `string` The event to register the callback for
@@ -80,7 +80,7 @@ Registers a callback function for an event
## BaseElement:fireEvent(event, any) ## BaseElement:fireEvent(event, any)
Triggers an event and calls all registered callbacks Executes all registered callbacks for the specified event
### Parameters ### Parameters
* `event` `string` The event to fire * `event` `string` The event to fire
@@ -91,7 +91,7 @@ Triggers an event and calls all registered callbacks
## BaseElement:onChange(property, callback) ## BaseElement:onChange(property, callback)
Observes a property and calls a callback when it changes Sets up a property change observer with immediate callback registration
### Parameters ### Parameters
* `property` `string` The property to observe * `property` `string` The property to observe
@@ -102,18 +102,18 @@ Observes a property and calls a callback when it changes
## BaseElement:getBaseFrame() ## BaseElement:getBaseFrame()
Returns the base frame of the element Traverses parent chain to locate the root frame element
### Returns ### Returns
* `BaseFrame` `BaseFrame` The base frame of the element * `BaseFrame` `BaseFrame` The base frame of the element
## BaseElement:destroy() ## BaseElement:destroy()
Destroys the element and cleans up all references Removes the element from UI tree and cleans up resources
## BaseElement:updateRender() ## BaseElement:updateRender()
Requests a render update for this element Propagates render request up the element tree
### Returns ### Returns
* `table` `self` The BaseElement instance * `table` `self` The BaseElement instance

2
docs/references/elements/BaseFrame.md
View File

@@ -1,5 +1,5 @@
# BaseFrame # BaseFrame
_This is the base frame class. It is the root element of all elements and the only element without a parent._ _This is the root frame class that serves as the foundation for the UI hierarchy. It manages the rendering context and acts as the top-level container for all other elements. Unlike other elements, it renders directly to a terminal or monitor and does not require a parent element._
Extends: `Container` Extends: `Container`

6
docs/references/elements/BigFont.md
View File

@@ -1,5 +1,5 @@
# BigFont # BigFont
_The BigFont element is a text element that displays larger text. It uses Wojbie's BigFont API to render the text in a larger font size. Credits to Wojbie for the original API._ _A specialized text element that renders characters in larger sizes using Wojbie's BigFont API. Supports multiple font sizes and custom colors while maintaining the pixel-art style of ComputerCraft. Ideal for headers, titles, and emphasis text._
Extends: `VisualElement` Extends: `VisualElement`
@@ -7,5 +7,5 @@ Extends: `VisualElement`
|Property|Type|Default|Description| |Property|Type|Default|Description|
|---|---|---|---| |---|---|---|---|
|text|string|BigFont|BigFont text| |text|string|BigFont|The text string to display in enlarged format|
|fontSize|number|1|The font size of the BigFont| |fontSize|number|1|Scale factor for text size (1-3, where 1 is 3x3 pixels per character)|

4
docs/references/elements/Button.md
View File

@@ -1,5 +1,5 @@
# Button # Button
_The Button is a standard button element with click handling and state management._ _A clickable interface element that triggers actions when pressed. Supports text labels, custom styling, and automatic text centering. Commonly used for user interactions and form submissions._
Extends: `VisualElement` Extends: `VisualElement`
@@ -7,4 +7,4 @@ Extends: `VisualElement`
|Property|Type|Default|Description| |Property|Type|Default|Description|
|---|---|---|---| |---|---|---|---|
|text|string|Button|Button text| |text|string|Button|Label text displayed centered within the button|

10
docs/references/elements/CheckBox.md
View File

@@ -1,5 +1,5 @@
# CheckBox # CheckBox
_The CheckBox is a visual element that can be checked._ _A toggleable UI element that can be checked or unchecked. Displays different text based on its state and supports automatic sizing. Commonly used in forms and settings interfaces for boolean options._
Extends: `VisualElement` Extends: `VisualElement`
@@ -7,7 +7,7 @@ Extends: `VisualElement`
|Property|Type|Default|Description| |Property|Type|Default|Description|
|---|---|---|---| |---|---|---|---|
|checked|boolean|Whether|checkbox is checked| |checked|boolean|false|The current state of the checkbox (true=checked, false=unchecked)|
|text|string|empty|Text to display| |text|string|empty|Text shown when the checkbox is unchecked|
|checkedText|string|Text|when checked| |checkedText|string|x|Text shown when the checkbox is checked|
|autoSize|boolean|true|Whether to automatically size the checkbox| |autoSize|boolean|true|Automatically adjusts width based on text length|

24
docs/references/elements/ComboBox.md
View File

@@ -1,6 +1,6 @@
# ComboBox # ComboBox
_This is the ComboBox class. It extends the dropdown functionality with editable text input,_ _A hybrid input element that combines a text input field with a dropdown list. Users can either type directly or select from predefined options. _
_allowing users to either select from a list or type their own custom text._ _Supports auto-completion, custom styling, and both single and multi-selection modes._
Extends: `DropDown` Extends: `DropDown`
@@ -8,16 +8,16 @@ Extends: `DropDown`
|Property|Type|Default|Description| |Property|Type|Default|Description|
|---|---|---|---| |---|---|---|---|
|editable|boolean|true|Whether the ComboBox allows text input| |editable|boolean|true|Enables direct text input in the field|
|text|string|""|The current text content of the ComboBox| |text|string|""|The current text value of the input field|
|cursorPos|number|1|The current cursor position in the text| |cursorPos|number|1|Current cursor position in the text input|
|viewOffset|number|0|The horizontal scroll offset for viewing long text| |viewOffset|number|0|Horizontal scroll position for viewing long text|
|placeholder|string|"..."|Text to display when input is empty| |placeholder|string|"..."|Text shown when the input is empty|
|placeholderColor|color|gray|Color of the placeholder text| |placeholderColor|color|gray|Color used for placeholder text|
|focusedBackground|color|blue|Background color when ComboBox is focused| |focusedBackground|color|blue|Background color when input is focused|
|focusedForeground|color|white|Foreground color when ComboBox is focused | |focusedForeground|color|white|Text color when input is focused|
|autoComplete|boolean|false|Whether to enable auto-complete filtering when typing| |autoComplete|boolean|false|Enables filtering dropdown items while typing|
|manuallyOpened|boolean|false|Whether the dropdown was manually opened (not by auto-complete)| |manuallyOpened|boolean|false|Indicates if dropdown was opened by user action|
## Functions ## Functions

82
docs/references/elements/Container.md
View File

@@ -1,5 +1,11 @@
# Container # Container
_The Container class serves as a fundamental building block for organizing UI elements. It acts as a parent element that can hold and manage child elements._ _A fundamental layout element that manages child UI components. Containers handle element organization, event propagation, _
_rendering hierarchy, and coordinate space management. They serve as the backbone of Basalt's UI structure by providing:_
_- Child element management and organization_
_- Event bubbling and distribution_
_- Visibility calculations and clipping_
_- Focus management_
_- Coordinate space transformation_
Extends: `VisualElement` Extends: `VisualElement`
@@ -7,67 +13,67 @@ Extends: `VisualElement`
|Property|Type|Default|Description| |Property|Type|Default|Description|
|---|---|---|---| |---|---|---|---|
|children|table|{}|The children of the container| |children|table|{}|Collection of all child elements|
|childrenSorted|boolean|true|Whether the children are sorted| |childrenSorted|boolean|true|Indicates if children are sorted by z-index|
|childrenEventsSorted|boolean|true|Whether the children events are sorted| |childrenEventsSorted|boolean|true|Indicates if event handlers are properly sorted|
|childrenEvents|table|{}|The children events of the container| |childrenEvents|table|{}|Registered event handlers for all children|
|eventListenerCount|table|{}|The event listener count of the container| |eventListenerCount|table|{}|Number of listeners per event type|
|focusedChild|table|nil|The focused child of the container| |focusedChild|table|nil|Currently focused child element (receives keyboard events)|
|visibleChildren|table|{}|The visible children of the container| |visibleChildren|table|{}|Currently visible child elements (calculated based on viewport)|
|visibleChildrenEvents|table|{}|The visible children events of the container| |visibleChildrenEvents|table|{}|Event handlers for currently visible children|
|offsetX|number|0|Horizontal content offset| |offsetX|number|0|Horizontal scroll/content offset|
|offsetY|number|0|Vertical content offset| |offsetY|number|0|Vertical scroll/content offset|
## Functions ## Functions
|Method|Returns|Description| |Method|Returns|Description|
|---|---|---| |---|---|---|
|[Container:isChildVisible](#container-ischildvisible-child)|boolean|Returns whether a child is visible| |[Container:isChildVisible](#container-ischildvisible-child)|boolean|Checks if a child element is visible|
|[Container:addChild](#container-addchild-child)|Container|Adds a child to the container| |[Container:addChild](#container-addchild-child)|Container|Adds a child element to the container|
|[Container:clear](#container-clear)|Container|Clears the container| |[Container:clear](#container-clear)|Container|Removes all children and resets container|
|[Container:sortChildren](#container-sortchildren)|Container|Sorts the children of the container| |[Container:sortChildren](#container-sortchildren)|Container|Updates child element ordering|
|[Container:sortChildrenEvents](#container-sortchildrenevents-eventname)|Container|Sorts the children events of the container| |[Container:sortChildrenEvents](#container-sortchildrenevents-eventname)|Container|Sorts the children events of the container|
|[Container:registerChildrenEvents](#container-registerchildrenevents-child)|Container|Registers the children events of the container| |[Container:registerChildrenEvents](#container-registerchildrenevents-child)|Container|Registers the children events of the container|
|[Container:registerChildEvent](#container-registerchildevent-child-eventname)|Container|Registers the children events of the container| |[Container:registerChildEvent](#container-registerchildevent-child-eventname)|Container|Sets up event handling for a child|
|[Container:removeChildrenEvents](#container-removechildrenevents-child)|Container|Unregisters the children events of the container| |[Container:removeChildrenEvents](#container-removechildrenevents-child)|Container|Unregisters the children events of the container|
|[Container:unregisterChildEvent](#container-unregisterchildevent-child-eventname)|Container|Unregisters the children events of the container| |[Container:unregisterChildEvent](#container-unregisterchildevent-child-eventname)|Container|Unregisters the children events of the container|
|[Container:removeChild](#container-removechild-child)|Container|Removes a child from the container| |[Container:removeChild](#container-removechild-child)|Container|Removes a child element from the container|
|[Container:getChild](#container-getchild-path)|self|Removes a child from the container| |[Container:getChild](#container-getchild-path)|child|Finds a child element by its path|
|[Container:callChildrenEvent](#container-callchildrenevent-visibleonly-event)|boolean, child|Calls a event on all children| |[Container:callChildrenEvent](#container-callchildrenevent-visibleonly-event)|boolean, child|Calls a event on all children|
## Container:isChildVisible(child) ## Container:isChildVisible(child)
Returns whether a child is visible Tests whether a child element is currently visible within the container's viewport
### Parameters ### Parameters
* `child` `table` The child to check * `child` `table` The child element to check
### Returns ### Returns
* `boolean` `boolean` the child is visible * `boolean` `isVisible` Whether the child is within view bounds
## Container:addChild(child) ## Container:addChild(child)
Adds a child to the container Adds a new element to this container's hierarchy
### Parameters ### Parameters
* `child` `table` The child to add * `child` `table` The element to add as a child
### Returns ### Returns
* `Container` `self` The container instance * `Container` `self` For method chaining
## Container:clear() ## Container:clear()
Clears the container Removes all child elements and resets the container's state
### Returns ### Returns
* `Container` `self` The container instance * `Container` `self` For method chaining
## Container:sortChildren() ## Container:sortChildren()
Sorts the children of the container Re-sorts children by their z-index and updates visibility
### Returns ### Returns
* `Container` `self` The container instance * `Container` `self` For method chaining
## Container:sortChildrenEvents(eventName) ## Container:sortChildrenEvents(eventName)
@@ -91,14 +97,14 @@ Registers the children events of the container
## Container:registerChildEvent(child, eventName) ## Container:registerChildEvent(child, eventName)
Registers the children events of the container Registers an event handler for a specific child element
### Parameters ### Parameters
* `child` `table` The child to register events for * `child` `table` The child element to register events for
* `eventName` `string` The event name to register * `eventName` `string` The name of the event to register
### Returns ### Returns
* `Container` `self` The container instance * `Container` `self` For method chaining
## Container:removeChildrenEvents(child) ## Container:removeChildrenEvents(child)
@@ -123,23 +129,23 @@ Unregisters the children events of the container
## Container:removeChild(child) ## Container:removeChild(child)
Removes a child from the container Removes an element from this container's hierarchy and cleans up its events
### Parameters ### Parameters
* `child` `table` The child to remove * `child` `table` The element to remove
### Returns ### Returns
* `Container` `self` The container instance * `Container` `self` For method chaining
## Container:getChild(path) ## Container:getChild(path)
Removes a child from the container Locates a child element using a path-like syntax (e.g. "panel/button1")
### Parameters ### Parameters
* `path` `string` The path to the child to remove * `path` `string` Path to the child (e.g. "panel/button1", "header/title")
### Returns ### Returns
* `self` `The` container instance * `child` `The` found element or nil if not found
## Container:callChildrenEvent(visibleOnly, event) ## Container:callChildrenEvent(visibleOnly, event)

30
docs/references/elements/Display.md
View File

@@ -1,5 +1,11 @@
# Display # Display
_The Display is a special element where you can use the window (term) API to draw on the display, useful when you need to use external APIs._ _A specialized element that provides direct access to ComputerCraft's Window API. _
_It acts as a canvas where you can use standard CC terminal operations, making it ideal for:_
_- Integration with existing CC programs and APIs_
_- Custom drawing operations_
_- Terminal emulation_
_- Complex text manipulation_
_The Display maintains its own terminal buffer and can be manipulated using familiar CC terminal methods._
Extends: `VisualElement` Extends: `VisualElement`
@@ -7,26 +13,26 @@ Extends: `VisualElement`
|Method|Returns|Description| |Method|Returns|Description|
|---|---|---| |---|---|---|
|[Display:getWindow](#display-getwindow)|table|Returns the current window object| |[Display:getWindow](#display-getwindow)|table|Gets the CC window instance|
|[Display:write](#display-write-x-y-text-fg-bg)|Display|Writes text to the display| |[Display:write](#display-write-x-y-text-fg-bg)|Display|Writes colored text to the display|
## Display:getWindow() ## Display:getWindow()
Returns the current window object Retrieves the underlying ComputerCraft window object
### Returns ### Returns
* `table` `window` The current window object * `table` `window` A CC window object with all standard terminal methods
## Display:write(x, y, text, fg?, bg?) ## Display:write(x, y, text, fg?, bg?)
Writes text to the display at the given position with the given foreground and background colors Writes text directly to the display with optional colors
### Parameters ### Parameters
* `x` `number` The x position to write to * `x` `number` X position (1-based)
* `y` `number` The y position to write to * `y` `number` Y position (1-based)
* `text` `string` The text to write * `text` `string` Text to write
* `fg` *(optional)* `colors` The foreground color (optional) * `fg` *(optional)* `colors` Foreground color (optional)
* `bg` *(optional)* `colors` The background color (optional) * `bg` *(optional)* `colors` Background color (optional)
### Returns ### Returns
* `Display` `self` The display instance * `Display` `self` For method chaining