From 4d286ad0c1506739cd40d6a051eb58d3f05e5d40 Mon Sep 17 00:00:00 2001 From: NoryiE Date: Sat, 27 Sep 2025 20:42:40 +0000 Subject: [PATCH 01/17] deploy: e836fc797880d3bf1c7cb400a855a5fb0db5beb5 --- docs/references/elements/TextBox.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/references/elements/TextBox.md b/docs/references/elements/TextBox.md index 07ba83d..b766c8d 100644 --- a/docs/references/elements/TextBox.md +++ b/docs/references/elements/TextBox.md @@ -15,6 +15,26 @@ Extends: `VisualElement` |editable|boolean|true|Whether text can be edited| |syntaxPatterns|table|{}|Syntax highlighting patterns| |cursorColor|number|nil|Color of the cursor| +|autoCompleteEnabled|boolean|false|Whether autocomplete suggestions are enabled| +|autoCompleteItems|table|{}|List of suggestions used when no provider is supplied| +|autoCompleteProvider|function|nil|Optional suggestion provider returning a list for the current prefix| +|autoCompleteMinChars|number|1|Minimum characters required before showing suggestions| +|autoCompleteMaxItems|number|6|Maximum number of visible suggestions| +|autoCompleteCaseInsensitive|boolean|true|Whether suggestions should match case-insensitively| +|autoCompleteTokenPattern|string|"[%w_]+"|Pattern used to extract the current token for suggestions| +|autoCompleteOffsetX|number|0|Horizontal offset applied to the popup frame relative to the TextBox| +|autoCompleteOffsetY|number|1|Vertical offset applied to the popup frame relative to the TextBox bottom edge| +|autoCompleteZOffset|number|1|Z-index offset applied to the popup frame| +|autoCompleteMaxWidth|number|0|Maximum width of the autocomplete popup (0 uses the textbox width)| +|autoCompleteShowBorder|boolean|true|Whether to render a character border around the popup| +|autoCompleteBorderColor|color|black|Color of the popup border when enabled| +|autoCompleteBackground|color|lightGray|Background color of the suggestion popup| +|autoCompleteForeground|color|black|Foreground color of the suggestion popup| +|autoCompleteSelectedBackground|color|gray|Background color for the selected suggestion| +|autoCompleteSelectedForeground|color|white|Foreground color for the selected suggestion| +|autoCompleteAcceptOnEnter|boolean|true|Whether pressing Enter accepts the current suggestion| +|autoCompleteAcceptOnClick|boolean|true|Whether clicking a suggestion accepts it immediately| +|autoCompleteCloseOnEscape|boolean|true|Whether pressing Escape closes the popup| ## Functions From 4483e01c0f070affe86580835d9f0796f4e776f3 Mon Sep 17 00:00:00 2001 From: NoryiE Date: Sun, 28 Sep 2025 13:05:59 +0000 Subject: [PATCH 02/17] deploy: 7fcf7ec3670b5277e948d741c3d0bdae7862de8b --- docs/references/elements/TextBox.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/references/elements/TextBox.md b/docs/references/elements/TextBox.md index b766c8d..a835b0e 100644 --- a/docs/references/elements/TextBox.md +++ b/docs/references/elements/TextBox.md @@ -15,6 +15,11 @@ Extends: `VisualElement` |editable|boolean|true|Whether text can be edited| |syntaxPatterns|table|{}|Syntax highlighting patterns| |cursorColor|number|nil|Color of the cursor| +|autoPairEnabled|boolean|true|Whether automatic bracket/quote pairing is enabled| +|autoPairCharacters|table|{|["("]=")", ["["]="]", ["{"]="}", ['"']='"', ['\'']='\'', ['`']='`'} Mapping of opening to closing characters for auto pairing| +|autoPairSkipClosing|boolean|true|Skip inserting a closing char if the same one is already at cursor| +|autoPairOverType|boolean|true|When pressing a closing char that matches the next char, move over it instead of inserting| +|autoPairNewlineIndent|boolean|true|On Enter between matching braces, create blank line and keep closing aligned| |autoCompleteEnabled|boolean|false|Whether autocomplete suggestions are enabled| |autoCompleteItems|table|{}|List of suggestions used when no provider is supplied| |autoCompleteProvider|function|nil|Optional suggestion provider returning a list for the current prefix| From 00d69ebc07b96d2eabe95a64a149382bb09cb0cd Mon Sep 17 00:00:00 2001 From: NoryiE Date: Mon, 29 Sep 2025 18:10:10 +0000 Subject: [PATCH 03/17] deploy: 80b66db3250795d64da568c91f8671a787d0cd8c --- docs/references/elements/VisualElement.md | 28 +++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/references/elements/VisualElement.md b/docs/references/elements/VisualElement.md index efb254b..4194944 100644 --- a/docs/references/elements/VisualElement.md +++ b/docs/references/elements/VisualElement.md @@ -18,6 +18,11 @@ Extends: `BaseElement` |clicked|boolean|false|Whether the element is currently clicked| |hover|boolean|false|Whether the mouse is currently hover over the element (Craftos-PC only)| |backgroundEnabled|boolean|true|Whether to render the background| +|borderTop|boolean|false|Draw top border| +|borderBottom|boolean|false|Draw bottom border| +|borderLeft|boolean|false|Draw left border| +|borderRight|boolean|false|Draw right border| +|borderColor|color|white|Border color| |focused|boolean|false|Whether the element has input focus| |visible|boolean|true|Whether the element is visible| |ignoreOffset|boolean|false|Whether to ignore the parent's offset| @@ -33,6 +38,10 @@ Extends: `BaseElement` |Method|Returns|Description| |---|---|---| |[VisualElement:isInBounds](#visualelement-isinbounds-x-y)|boolean|Checks if point is within bounds| +|[VisualElement:addBorder](#visualelement-addborder-colororoptions)|VisualElement|Adds or updates a drawable character border around the element using the canvas plugin. +The border will automatically adapt to size/background changes because the command +reads current properties each render.| +|[VisualElement:removeBorder](#visualelement-removeborder)|VisualElement|Removes the previously added border (if any)| |[VisualElement:calculatePosition](#visualelement-calculateposition)|number, number|Calculates the position of the element| |[VisualElement:getAbsolutePosition](#visualelement-getabsoluteposition-x-y)|number, number|Returns the absolute position of the element| |[VisualElement:getRelativePosition](#visualelement-getrelativeposition-x-y)|number, number|Returns the relative position of the element| @@ -49,6 +58,25 @@ Checks if the specified coordinates are within the bounds of the element ### Returns * `boolean` `isInBounds` Whether the coordinates are within the bounds of the element +## VisualElement:addBorder(colorOrOptions) + +Adds or updates a drawable character border around the element using the canvas plugin. +The border will automatically adapt to size/background changes because the command +reads current properties each render. + +### Parameters +* `colorOrOptions` `any` Border color or options table + +### Returns +* `VisualElement` self + +## VisualElement:removeBorder() + +Removes the previously added border (if any) + +### Returns +* `VisualElement` self + ## VisualElement:calculatePosition() Calculates the position of the element relative to its parent From 07009ca98b1955c3ab1dc3a2d5714250c7a1879c Mon Sep 17 00:00:00 2001 From: NoryiE Date: Tue, 30 Sep 2025 12:42:49 +0000 Subject: [PATCH 04/17] deploy: 464314e219b07de9038f44fcba66f23c0b248c69 --- docs/references/elements/BarChart.md | 2 +- docs/references/elements/BaseElement.md | 50 +++++++-------- docs/references/elements/BaseFrame.md | 2 +- docs/references/elements/BigFont.md | 6 +- docs/references/elements/Button.md | 4 +- docs/references/elements/CheckBox.md | 10 +-- docs/references/elements/ComboBox.md | 24 ++++---- docs/references/elements/Container.md | 82 +++++++++++++------------ docs/references/elements/Display.md | 30 +++++---- 9 files changed, 111 insertions(+), 99 deletions(-) diff --git a/docs/references/elements/BarChart.md b/docs/references/elements/BarChart.md index 7e9110f..977a870 100644 --- a/docs/references/elements/BarChart.md +++ b/docs/references/elements/BarChart.md @@ -1,4 +1,4 @@ # 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` diff --git a/docs/references/elements/BaseElement.md b/docs/references/elements/BaseElement.md index 8d865bb..68f7499 100644 --- a/docs/references/elements/BaseElement.md +++ b/docs/references/elements/BaseElement.md @@ -1,5 +1,5 @@ # 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` @@ -7,30 +7,30 @@ Extends: `PropertySystem` |Property|Type|Default|Description| |---|---|---|---| -|type|string|BaseElement|The type identifier of the element| -|id|string|BaseElement|The unique identifier for the element| -|name|string|BaseElement|The name of the element| -|eventCallbacks|table|BaseElement|The event callbacks for the element| -|enabled|boolean|BaseElement|Whether the element is enabled or not| +|type|string|BaseElement|A hierarchical identifier of the element's type chain| +|id|string|BaseElement|Auto-generated unique identifier for element lookup| +|name|string|BaseElement|User-defined name for the element| +|eventCallbacks|table|BaseElement|Collection of registered event handler functions| +|enabled|boolean|BaseElement|Controls event processing for this element| ## Functions |Method|Returns|Description| |---|---|---| |[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:isType](#baseelement-istype-type)|boolean|Checks if the element is a specific type| -|[BaseElement:listenEvent](#baseelement-listenevent-eventname-enable)|table|Enables or disables event listening for a specific event| -|[BaseElement:registerCallback](#baseelement-registercallback-event-callback)|table|Registers a callback function| -|[BaseElement:fireEvent](#baseelement-fireevent-event-any)|table|Triggers an event and calls all registered callbacks| -|[BaseElement:onChange](#baseelement-onchange-property-callback)|table|Observes a property and calls a callback when it changes| -|[BaseElement:getBaseFrame](#baseelement-getbaseframe)|BaseFrame|Returns the base frame of the element| -|[BaseElement:destroy](#baseelement-destroy)|-|Destroys the element and cleans up all references| -|[BaseElement:updateRender](#baseelement-updaterender)|table|Requests a render update for this element| +|[BaseElement.registerEventCallback](#baseelement-registereventcallback-class-callbackname-string)|-|Registers a new event callback method with auto-registration| +|[BaseElement:isType](#baseelement-istype-type)|boolean|Tests if element is of or inherits given type| +|[BaseElement:listenEvent](#baseelement-listenevent-eventname-enable)|table|Enables/disables event handling for this element| +|[BaseElement:registerCallback](#baseelement-registercallback-event-callback)|table|Registers a function to handle specific events| +|[BaseElement:fireEvent](#baseelement-fireevent-event-any)|table|Triggers event callbacks with provided arguments| +|[BaseElement:onChange](#baseelement-onchange-property-callback)|table|Watches property changes with callback notification| +|[BaseElement:getBaseFrame](#baseelement-getbaseframe)|BaseFrame|Retrieves the root frame of this element's tree| +|[BaseElement:destroy](#baseelement-destroy)|-|Removes element and performs cleanup| +|[BaseElement:updateRender](#baseelement-updaterender)|table|Requests UI update for this element| ## 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 * `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) -Registers a new event callback for the element (on class level) +Defines a class-level event callback method with automatic event registration ### Parameters * `class` `table` The class to register @@ -48,7 +48,7 @@ Registers a new event callback for the element (on class level) ## BaseElement:isType(type) -Checks if the element is a specific type +Checks if the element matches or inherits from the specified type ### Parameters * `type` `string` The type to check for @@ -58,7 +58,7 @@ Checks if the element is a specific type ## BaseElement:listenEvent(eventName, enable?) -Enables or disables event listening for a specific event +Configures event listening behavior with automatic parent notification ### Parameters * `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) -Registers a callback function for an event +Adds an event handler function with automatic event registration ### Parameters * `event` `string` The event to register the callback for @@ -80,7 +80,7 @@ Registers a callback function for an event ## BaseElement:fireEvent(event, any) -Triggers an event and calls all registered callbacks +Executes all registered callbacks for the specified event ### Parameters * `event` `string` The event to fire @@ -91,7 +91,7 @@ Triggers an event and calls all registered callbacks ## 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 * `property` `string` The property to observe @@ -102,18 +102,18 @@ Observes a property and calls a callback when it changes ## BaseElement:getBaseFrame() -Returns the base frame of the element +Traverses parent chain to locate the root frame element ### Returns * `BaseFrame` `BaseFrame` The base frame of the element ## BaseElement:destroy() -Destroys the element and cleans up all references +Removes the element from UI tree and cleans up resources ## BaseElement:updateRender() -Requests a render update for this element +Propagates render request up the element tree ### Returns * `table` `self` The BaseElement instance diff --git a/docs/references/elements/BaseFrame.md b/docs/references/elements/BaseFrame.md index 141da39..488a68a 100644 --- a/docs/references/elements/BaseFrame.md +++ b/docs/references/elements/BaseFrame.md @@ -1,5 +1,5 @@ # 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` diff --git a/docs/references/elements/BigFont.md b/docs/references/elements/BigFont.md index 5b69c21..24ee292 100644 --- a/docs/references/elements/BigFont.md +++ b/docs/references/elements/BigFont.md @@ -1,5 +1,5 @@ # 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` @@ -7,5 +7,5 @@ Extends: `VisualElement` |Property|Type|Default|Description| |---|---|---|---| -|text|string|BigFont|BigFont text| -|fontSize|number|1|The font size of the BigFont| +|text|string|BigFont|The text string to display in enlarged format| +|fontSize|number|1|Scale factor for text size (1-3, where 1 is 3x3 pixels per character)| diff --git a/docs/references/elements/Button.md b/docs/references/elements/Button.md index 4186b86..709ef40 100644 --- a/docs/references/elements/Button.md +++ b/docs/references/elements/Button.md @@ -1,5 +1,5 @@ # 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` @@ -7,4 +7,4 @@ Extends: `VisualElement` |Property|Type|Default|Description| |---|---|---|---| -|text|string|Button|Button text| +|text|string|Button|Label text displayed centered within the button| diff --git a/docs/references/elements/CheckBox.md b/docs/references/elements/CheckBox.md index 1a2770a..747e0e0 100644 --- a/docs/references/elements/CheckBox.md +++ b/docs/references/elements/CheckBox.md @@ -1,5 +1,5 @@ # 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` @@ -7,7 +7,7 @@ Extends: `VisualElement` |Property|Type|Default|Description| |---|---|---|---| -|checked|boolean|Whether|checkbox is checked| -|text|string|empty|Text to display| -|checkedText|string|Text|when checked| -|autoSize|boolean|true|Whether to automatically size the checkbox| +|checked|boolean|false|The current state of the checkbox (true=checked, false=unchecked)| +|text|string|empty|Text shown when the checkbox is unchecked| +|checkedText|string|x|Text shown when the checkbox is checked| +|autoSize|boolean|true|Automatically adjusts width based on text length| diff --git a/docs/references/elements/ComboBox.md b/docs/references/elements/ComboBox.md index 2f7a270..bce4d8e 100644 --- a/docs/references/elements/ComboBox.md +++ b/docs/references/elements/ComboBox.md @@ -1,6 +1,6 @@ # ComboBox -_This is the ComboBox class. It extends the dropdown functionality with editable text input,_ -_allowing users to either select from a list or type their own custom text._ +_A hybrid input element that combines a text input field with a dropdown list. Users can either type directly or select from predefined options. _ +_Supports auto-completion, custom styling, and both single and multi-selection modes._ Extends: `DropDown` @@ -8,16 +8,16 @@ Extends: `DropDown` |Property|Type|Default|Description| |---|---|---|---| -|editable|boolean|true|Whether the ComboBox allows text input| -|text|string|""|The current text content of the ComboBox| -|cursorPos|number|1|The current cursor position in the text| -|viewOffset|number|0|The horizontal scroll offset for viewing long text| -|placeholder|string|"..."|Text to display when input is empty| -|placeholderColor|color|gray|Color of the placeholder text| -|focusedBackground|color|blue|Background color when ComboBox is focused| -|focusedForeground|color|white|Foreground color when ComboBox is focused | -|autoComplete|boolean|false|Whether to enable auto-complete filtering when typing| -|manuallyOpened|boolean|false|Whether the dropdown was manually opened (not by auto-complete)| +|editable|boolean|true|Enables direct text input in the field| +|text|string|""|The current text value of the input field| +|cursorPos|number|1|Current cursor position in the text input| +|viewOffset|number|0|Horizontal scroll position for viewing long text| +|placeholder|string|"..."|Text shown when the input is empty| +|placeholderColor|color|gray|Color used for placeholder text| +|focusedBackground|color|blue|Background color when input is focused| +|focusedForeground|color|white|Text color when input is focused| +|autoComplete|boolean|false|Enables filtering dropdown items while typing| +|manuallyOpened|boolean|false|Indicates if dropdown was opened by user action| ## Functions diff --git a/docs/references/elements/Container.md b/docs/references/elements/Container.md index bdd16b2..de8db44 100644 --- a/docs/references/elements/Container.md +++ b/docs/references/elements/Container.md @@ -1,5 +1,11 @@ # 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` @@ -7,67 +13,67 @@ Extends: `VisualElement` |Property|Type|Default|Description| |---|---|---|---| -|children|table|{}|The children of the container| -|childrenSorted|boolean|true|Whether the children are sorted| -|childrenEventsSorted|boolean|true|Whether the children events are sorted| -|childrenEvents|table|{}|The children events of the container| -|eventListenerCount|table|{}|The event listener count of the container| -|focusedChild|table|nil|The focused child of the container| -|visibleChildren|table|{}|The visible children of the container| -|visibleChildrenEvents|table|{}|The visible children events of the container| -|offsetX|number|0|Horizontal content offset| -|offsetY|number|0|Vertical content offset| +|children|table|{}|Collection of all child elements| +|childrenSorted|boolean|true|Indicates if children are sorted by z-index| +|childrenEventsSorted|boolean|true|Indicates if event handlers are properly sorted| +|childrenEvents|table|{}|Registered event handlers for all children| +|eventListenerCount|table|{}|Number of listeners per event type| +|focusedChild|table|nil|Currently focused child element (receives keyboard events)| +|visibleChildren|table|{}|Currently visible child elements (calculated based on viewport)| +|visibleChildrenEvents|table|{}|Event handlers for currently visible children| +|offsetX|number|0|Horizontal scroll/content offset| +|offsetY|number|0|Vertical scroll/content offset| ## Functions |Method|Returns|Description| |---|---|---| -|[Container:isChildVisible](#container-ischildvisible-child)|boolean|Returns whether a child is visible| -|[Container:addChild](#container-addchild-child)|Container|Adds a child to the container| -|[Container:clear](#container-clear)|Container|Clears the container| -|[Container:sortChildren](#container-sortchildren)|Container|Sorts the children of the container| +|[Container:isChildVisible](#container-ischildvisible-child)|boolean|Checks if a child element is visible| +|[Container:addChild](#container-addchild-child)|Container|Adds a child element to the container| +|[Container:clear](#container-clear)|Container|Removes all children and resets container| +|[Container:sortChildren](#container-sortchildren)|Container|Updates child element ordering| |[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: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: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:getChild](#container-getchild-path)|self|Removes a child from the container| +|[Container:removeChild](#container-removechild-child)|Container|Removes a child element 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:isChildVisible(child) -Returns whether a child is visible +Tests whether a child element is currently visible within the container's viewport ### Parameters -* `child` `table` The child to check +* `child` `table` The child element to check ### Returns -* `boolean` `boolean` the child is visible +* `boolean` `isVisible` Whether the child is within view bounds ## Container:addChild(child) -Adds a child to the container +Adds a new element to this container's hierarchy ### Parameters -* `child` `table` The child to add +* `child` `table` The element to add as a child ### Returns -* `Container` `self` The container instance +* `Container` `self` For method chaining ## Container:clear() -Clears the container +Removes all child elements and resets the container's state ### Returns -* `Container` `self` The container instance +* `Container` `self` For method chaining ## Container:sortChildren() -Sorts the children of the container +Re-sorts children by their z-index and updates visibility ### Returns -* `Container` `self` The container instance +* `Container` `self` For method chaining ## Container:sortChildrenEvents(eventName) @@ -91,14 +97,14 @@ Registers the children events of the container ## Container:registerChildEvent(child, eventName) -Registers the children events of the container +Registers an event handler for a specific child element ### Parameters -* `child` `table` The child to register events for -* `eventName` `string` The event name to register +* `child` `table` The child element to register events for +* `eventName` `string` The name of the event to register ### Returns -* `Container` `self` The container instance +* `Container` `self` For method chaining ## Container:removeChildrenEvents(child) @@ -123,23 +129,23 @@ Unregisters the children events of the container ## Container:removeChild(child) -Removes a child from the container +Removes an element from this container's hierarchy and cleans up its events ### Parameters -* `child` `table` The child to remove +* `child` `table` The element to remove ### Returns -* `Container` `self` The container instance +* `Container` `self` For method chaining ## Container:getChild(path) -Removes a child from the container +Locates a child element using a path-like syntax (e.g. "panel/button1") ### Parameters -* `path` `string` The path to the child to remove +* `path` `string` Path to the child (e.g. "panel/button1", "header/title") ### Returns -* `self` `The` container instance +* `child` `The` found element or nil if not found ## Container:callChildrenEvent(visibleOnly, event) diff --git a/docs/references/elements/Display.md b/docs/references/elements/Display.md index 7ccb450..8344ad6 100644 --- a/docs/references/elements/Display.md +++ b/docs/references/elements/Display.md @@ -1,5 +1,11 @@ # 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` @@ -7,26 +13,26 @@ Extends: `VisualElement` |Method|Returns|Description| |---|---|---| -|[Display:getWindow](#display-getwindow)|table|Returns the current window object| -|[Display:write](#display-write-x-y-text-fg-bg)|Display|Writes text to the display| +|[Display:getWindow](#display-getwindow)|table|Gets the CC window instance| +|[Display:write](#display-write-x-y-text-fg-bg)|Display|Writes colored text to the display| ## Display:getWindow() -Returns the current window object +Retrieves the underlying ComputerCraft window object ### 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?) -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 -* `x` `number` The x position to write to -* `y` `number` The y position to write to -* `text` `string` The text to write -* `fg` *(optional)* `colors` The foreground color (optional) -* `bg` *(optional)* `colors` The background color (optional) +* `x` `number` X position (1-based) +* `y` `number` Y position (1-based) +* `text` `string` Text to write +* `fg` *(optional)* `colors` Foreground color (optional) +* `bg` *(optional)* `colors` Background color (optional) ### Returns -* `Display` `self` The display instance +* `Display` `self` For method chaining From 085a5531ba82b127254ec45860958ec6fbd4d7de Mon Sep 17 00:00:00 2001 From: NoryiE Date: Fri, 3 Oct 2025 01:26:35 +0000 Subject: [PATCH 05/17] deploy: a774e11f3bece0c50133133ffe1348cb41f6f565 --- docs/references/elements/DropDown.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/references/elements/DropDown.md b/docs/references/elements/DropDown.md index a2b90f9..4e5d180 100644 --- a/docs/references/elements/DropDown.md +++ b/docs/references/elements/DropDown.md @@ -1,5 +1,5 @@ # DropDown -_This is the DropDown class. It is a visual element that can show a list of selectable items in a DropDown menu._ +_A collapsible selection menu that expands to show multiple options when clicked. Supports single and multi-selection modes, custom item styling, separators, and item callbacks._ Extends: `List` @@ -7,7 +7,7 @@ Extends: `List` |Property|Type|Default|Description| |---|---|---|---| -|isOpen|boolean|false|Whether the DropDown menu is currently open| -|dropdownHeight|number|5|Maximum height of the DropDown menu when open| -|selectedText|string|""|The text to show when no item is selected| -|dropSymbol|string|"\31"|The symbol to show for DropDown indication| +|isOpen|boolean|false|Controls the expanded/collapsed state| +|dropdownHeight|number|5|Maximum visible items when expanded| +|selectedText|string|""|Text shown when no selection made| +|dropSymbol|string|"\31"|Indicator for dropdown state| From 8578c8bfd1a29d8828512da27c62e168156efd01 Mon Sep 17 00:00:00 2001 From: NoryiE Date: Mon, 6 Oct 2025 19:46:11 +0000 Subject: [PATCH 06/17] deploy: f868e03f85518b5dd88a6f47fe6071c7973f79e6 --- docs/references/elements/Tree.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/references/elements/Tree.md b/docs/references/elements/Tree.md index 335a3e7..24dae79 100644 --- a/docs/references/elements/Tree.md +++ b/docs/references/elements/Tree.md @@ -12,8 +12,8 @@ Extends: `VisualElement` |expandedNodes|table|{}|Table of nodes that are currently expanded| |scrollOffset|number|0|Current vertical scroll position| |horizontalOffset|number|0|Current horizontal scroll position| -|nodeColor|color|white|Color of unselected nodes| -|selectedColor|color|lightBlue|Background color of selected node| +|selectedForegroundColor|color|white|foreground color of selected node| +|selectedBackgroundColor|color|lightBlue|background color of selected node| ## Functions From 9557ae3e4dbde93a11ef9cc4f84bc207b7085c1c Mon Sep 17 00:00:00 2001 From: NoryiE Date: Mon, 6 Oct 2025 22:16:12 +0000 Subject: [PATCH 07/17] deploy: f47ae21fbef4e965c4dbf0cb4462fc8577b680fb --- docs/references/elements/TabControl.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/references/elements/TabControl.md b/docs/references/elements/TabControl.md index 21ff6ec..b7342c7 100644 --- a/docs/references/elements/TabControl.md +++ b/docs/references/elements/TabControl.md @@ -13,6 +13,8 @@ Extends: `Container` |headerBackground|color|Background|color for the tab header area| |activeTabBackground|color|Background|color for the active tab| |activeTabTextColor|color|Foreground|color for the active tab text| +|scrollableTab|boolean|Enables|scroll mode for tabs if they exceed width| +|tabScrollOffset|number|Current|scroll offset for tabs in scrollable mode| ## Functions @@ -22,6 +24,7 @@ Extends: `Container` |[TabControl:setTab](#tabcontrol-settab-element-tabid)|TabControl|Sets an element to belong to a specific tab| |[TabControl:addElement](#tabcontrol-addelement-elementtype-tabid)|table|Adds an element to the TabControl and assigns it to the active tab| |[TabControl:setActiveTab](#tabcontrol-setactivetab-tabid)|-|Sets the active tab| +|[TabControl:scrollTabs](#tabcontrol-scrolltabs-direction)|TabControl|Scrolls the tab header left or right if scrollableTab is enabled| |[TabControl:setCursor](#tabcontrol-setcursor)|-|Sets the cursor position; accounts for tab header offset when delegating to parent| ## TabControl:newTab(title) @@ -54,4 +57,14 @@ returns a proxy for adding elements to the tab ### Parameters * `tabId` `number` The ID of the tab to activate +## TabControl:scrollTabs(direction) + +Scrolls the tab header left or right if scrollableTab is enabled + +### Parameters +* `direction` `number` -1 to scroll left, 1 to scroll right + +### Returns +* `TabControl` `self` For method chaining + ## TabControl:setCursor() \ No newline at end of file From 6b3c0f111e76bfb5d8622429ffae352987aa49bb Mon Sep 17 00:00:00 2001 From: NoryiE Date: Mon, 6 Oct 2025 22:21:31 +0000 Subject: [PATCH 08/17] deploy: 0ef6065399b9ca010cf275c5b2bf58579b9b1b35 --- docs/references/elements/TabControl.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/references/elements/TabControl.md b/docs/references/elements/TabControl.md index b7342c7..a981b3c 100644 --- a/docs/references/elements/TabControl.md +++ b/docs/references/elements/TabControl.md @@ -13,8 +13,8 @@ Extends: `Container` |headerBackground|color|Background|color for the tab header area| |activeTabBackground|color|Background|color for the active tab| |activeTabTextColor|color|Foreground|color for the active tab text| -|scrollableTab|boolean|Enables|scroll mode for tabs if they exceed width| -|tabScrollOffset|number|Current|scroll offset for tabs in scrollable mode| +|scrollableTab|boolean|false|Enables scroll mode for tabs if they exceed width| +|tabScrollOffset|number|0|Current scroll offset for tabs in scrollable mode| ## Functions From bd2b0106262548052f0388282c73379191fac174 Mon Sep 17 00:00:00 2001 From: NoryiE Date: Mon, 6 Oct 2025 22:22:25 +0000 Subject: [PATCH 09/17] deploy: 62bfd24ea66825f649ba218a1e99e0aaa951532b --- docs/references/elements/TabControl.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/references/elements/TabControl.md b/docs/references/elements/TabControl.md index a981b3c..9dabe11 100644 --- a/docs/references/elements/TabControl.md +++ b/docs/references/elements/TabControl.md @@ -7,12 +7,12 @@ Extends: `Container` |Property|Type|Default|Description| |---|---|---|---| -|activeTab|number|The|currently active tab ID| -|tabHeight|number|Height|of the tab header area| -|tabs|table|List|of tab definitions| -|headerBackground|color|Background|color for the tab header area| -|activeTabBackground|color|Background|color for the active tab| -|activeTabTextColor|color|Foreground|color for the active tab text| +|activeTab|number|nil|The currently active tab ID| +|tabHeight|number|1|Height of the tab header area| +|tabs|table|{}|List of tab definitions| +|headerBackground|color|gray|Background color for the tab header area| +|activeTabBackground|color|white|Background color for the active tab| +|activeTabTextColor|color|black|Foreground color for the active tab text| |scrollableTab|boolean|false|Enables scroll mode for tabs if they exceed width| |tabScrollOffset|number|0|Current scroll offset for tabs in scrollable mode| From 1fc2fa088af801ef36829083a53c28315d7b29f7 Mon Sep 17 00:00:00 2001 From: NoryiE Date: Thu, 9 Oct 2025 20:17:03 +0000 Subject: [PATCH 10/17] deploy: 57f8da9a901ec0a7e3d07a860cee6216b1999ef8 --- docs/references/elements/SideNav.md | 70 +++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/references/elements/SideNav.md diff --git a/docs/references/elements/SideNav.md b/docs/references/elements/SideNav.md new file mode 100644 index 0000000..89fe9a5 --- /dev/null +++ b/docs/references/elements/SideNav.md @@ -0,0 +1,70 @@ +# SideNav +_The SideNav is a container that provides sidebar navigation functionality_ + +Extends: `Container` + +## Properties + +|Property|Type|Default|Description| +|---|---|---|---| +|activeTab|number|nil|The currently active navigation item ID| +|sidebarWidth|number|12|Width of the sidebar navigation area| +|tabs|table|{}|List of navigation item definitions| +|sidebarBackground|color|gray|Background color for the sidebar area| +|activeTabBackground|color|white|Background color for the active navigation item| +|activeTabTextColor|color|black|Foreground color for the active navigation item text| +|sidebarScrollOffset|number|0|Current scroll offset for navigation items in scrollable mode| +|sidebarPosition|string|"left"|Position of the sidebar ("left" or "right")| + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[SideNav:newTab](#sidenav-newtab-title)|table|Creates a new navigation item handler proxy| +|[SideNav:setTab](#sidenav-settab-element-tabid)|SideNav|Sets an element to belong to a specific navigation item| +|[SideNav:addElement](#sidenav-addelement-elementtype-tabid)|table|Adds an element to the SideNav and assigns it to the active navigation item| +|[SideNav:setActiveTab](#sidenav-setactivetab-tabid)|-|Sets the active navigation item| +|[SideNav:scrollSidebar](#sidenav-scrollsidebar-direction)|SideNav|Scrolls the sidebar up or down| +|[SideNav:setCursor](#sidenav-setcursor)|-|Sets the cursor position; accounts for sidebar offset when delegating to parent| + +## SideNav:newTab(title) + +returns a proxy for adding elements to the navigation item + +### Parameters +* `title` `string` The title of the navigation item + +### Returns +* `table` `tabHandler` The navigation item handler proxy for adding elements + +## SideNav:setTab(element, tabId) +### Parameters +* `element` `table` The element to assign to a navigation item +* `tabId` `number` The ID of the navigation item to assign the element to + +### Returns +* `SideNav` `self` For method chaining + +## SideNav:addElement(elementType, tabId) +### Parameters +* `elementType` `string` The type of element to add +* `tabId` `number` Optional navigation item ID, defaults to active item + +### Returns +* `table` `element` The created element + +## SideNav:setActiveTab(tabId) +### Parameters +* `tabId` `number` The ID of the navigation item to activate + +## SideNav:scrollSidebar(direction) + +Scrolls the sidebar up or down + +### Parameters +* `direction` `number` -1 to scroll up, 1 to scroll down + +### Returns +* `SideNav` `self` For method chaining + +## SideNav:setCursor() \ No newline at end of file From 308f444ef869032033711b78b349cf10f341dd61 Mon Sep 17 00:00:00 2001 From: Robert Jelic <36573031+NoryiE@users.noreply.github.com> Date: Fri, 10 Oct 2025 18:25:42 +0200 Subject: [PATCH 11/17] Update config.mts Added SideNav --- docs/.vitepress/config.mts | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index a314d3d..7f07dac 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -116,6 +116,7 @@ export default defineConfig({ items: [ { text: 'BaseFrame', link: 'references/elements/BaseFrame' }, { text: 'Frame', link: 'references/elements/Frame' }, + { text: 'SideNav', link: 'references/elements/SideNav' }, { text: 'TabControl', link: 'references/elements/TabControl' }, ], }, From d0a444a77220ec04fc13c63d10b7475a23cbb1d6 Mon Sep 17 00:00:00 2001 From: NoryiE Date: Sun, 12 Oct 2025 20:37:37 +0000 Subject: [PATCH 12/17] deploy: d6f0ec65dbef82cb70c9d932409293a076729718 --- docs/references/elements/SideNav.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/elements/SideNav.md b/docs/references/elements/SideNav.md index 89fe9a5..bd4b0de 100644 --- a/docs/references/elements/SideNav.md +++ b/docs/references/elements/SideNav.md @@ -14,7 +14,7 @@ Extends: `Container` |activeTabBackground|color|white|Background color for the active navigation item| |activeTabTextColor|color|black|Foreground color for the active navigation item text| |sidebarScrollOffset|number|0|Current scroll offset for navigation items in scrollable mode| -|sidebarPosition|string|"left"|Position of the sidebar ("left" or "right")| +|sidebarPosition|string|left|Position of the sidebar ("left" or "right")| ## Functions From 44c80f074fa1ae397efb5d9d873c7236e98b3065 Mon Sep 17 00:00:00 2001 From: NoryiE Date: Mon, 27 Oct 2025 07:26:29 +0000 Subject: [PATCH 13/17] deploy: b96875a3e9edeb9b94715d1a26a94d6bfb3f26ff --- docs/references/elementManager.md | 84 +++++ docs/references/elements/BaseElement.md | 83 +++++ docs/references/elements/Collection.md | 107 ++++++ docs/references/elements/ComboBox.md | 47 --- docs/references/elements/DropDown.md | 1 - docs/references/elements/Input.md | 2 - docs/references/elements/List.md | 74 +--- docs/references/elements/VisualElement.md | 372 ++++++++++++++++++- docs/references/libraries/collectionentry.md | 1 + docs/references/main.md | 59 +++ 10 files changed, 704 insertions(+), 126 deletions(-) create mode 100644 docs/references/elements/Collection.md create mode 100644 docs/references/libraries/collectionentry.md diff --git a/docs/references/elementManager.md b/docs/references/elementManager.md index 8f759b0..4e0278d 100644 --- a/docs/references/elementManager.md +++ b/docs/references/elementManager.md @@ -6,10 +6,51 @@ _and then applies the plugins to the elements. It also provides a way to get ele |Method|Returns|Description| |---|---|---| +|[ElementManager.configure](#elementmanager-configure-config)|-|Configures the ElementManager| +|[ElementManager.registerDiskMount](#elementmanager-registerdiskmount-mountpath)|-|Registers a disk mount point for loading elements| +|[ElementManager.registerRemoteSource](#elementmanager-registerremotesource-elementname-url)|-|Registers a remote source for an element| +|[ElementManager.tryAutoLoad](#elementmanager-tryautoload-name)|boolean|Tries to load an element from any available source| |[ElementManager.loadElement](#elementmanager-loadelement-name)|-|Loads an element by name. This will load the element and apply any plugins to it.| |[ElementManager.getElement](#elementmanager-getelement-name)|table|Gets an element by name. If the element is not loaded, it will try to load it first.| |[ElementManager.getElementList](#elementmanager-getelementlist)|table|Gets a list of all elements| |[ElementManager.getAPI](#elementmanager-getapi-name)|table|Gets an Plugin API by name| +|[ElementManager.hasElement](#elementmanager-haselement-name)|boolean|Checks if an element exists (is registered)| +|[ElementManager.isElementLoaded](#elementmanager-iselementloaded-name)|boolean|Checks if an element is loaded| +|[ElementManager.clearGlobalCache](#elementmanager-clearglobalcache)|-|Clears the global cache (_G)| +|[ElementManager.getCacheStats](#elementmanager-getcachestats)|table|Gets cache statistics| +|[ElementManager.preloadElements](#elementmanager-preloadelements-elementnames)|-|Preloads elements into the global cache| + +## ElementManager.configure(config) + +Configures the ElementManager + +### Parameters +* `config` `table` Configuration options + +## ElementManager.registerDiskMount(mountPath) + +Registers a disk mount point for loading elements + +### Parameters +* `mountPath` `string` The path to the disk mount + +## ElementManager.registerRemoteSource(elementName, url) + +Registers a remote source for an element + +### Parameters +* `elementName` `string` The name of the element +* `url` `string` The URL to load the element from + +## ElementManager.tryAutoLoad(name) + +Tries to load an element from any available source + +### Parameters +* `name` `string` The element name + +### Returns +* `boolean` `success` Whether the element was loaded ## ElementManager.loadElement(name) @@ -49,3 +90,46 @@ Gets an Plugin API by name ### Returns * `table` `API` The API + +## ElementManager.hasElement(name) + +Checks if an element exists (is registered) + +### Parameters +* `name` `string` The element name + +### Returns +* `boolean` `exists` Whether the element exists + +## ElementManager.isElementLoaded(name) + +Checks if an element is loaded + +### Parameters +* `name` `string` The element name + +### Returns +* `boolean` `loaded` Whether the element is loaded + +## ElementManager.clearGlobalCache() + +Clears the global cache (_G) + +### Usage +```lua +ElementManager.clearGlobalCache() +``` + +## ElementManager.getCacheStats() + +Gets cache statistics + +### Returns +* `table` `stats` Cache statistics with size and element names + +## ElementManager.preloadElements(elementNames) + +Preloads elements into the global cache + +### Parameters +* `elementNames` `table` List of element names to preload diff --git a/docs/references/elements/BaseElement.md b/docs/references/elements/BaseElement.md index 68f7499..73ce16d 100644 --- a/docs/references/elements/BaseElement.md +++ b/docs/references/elements/BaseElement.md @@ -12,6 +12,7 @@ Extends: `PropertySystem` |name|string|BaseElement|User-defined name for the element| |eventCallbacks|table|BaseElement|Collection of registered event handler functions| |enabled|boolean|BaseElement|Controls event processing for this element| +|states|table|{}|Table of currently active states with their priorities| ## Functions @@ -22,6 +23,14 @@ Extends: `PropertySystem` |[BaseElement:isType](#baseelement-istype-type)|boolean|Tests if element is of or inherits given type| |[BaseElement:listenEvent](#baseelement-listenevent-eventname-enable)|table|Enables/disables event handling for this element| |[BaseElement:registerCallback](#baseelement-registercallback-event-callback)|table|Registers a function to handle specific events| +|[BaseElement:registerState](#baseelement-registerstate-statename-condition-priority)|BaseElement|Registers a state| +|[BaseElement:setState](#baseelement-setstate-statename-priority)|BaseElement|Activates a state| +|[BaseElement:unsetState](#baseelement-unsetstate-statename)|BaseElement|Deactivates a state| +|[BaseElement:hasState](#baseelement-hasstate-statename)|boolean|Checks if state is active| +|[BaseElement:getCurrentState](#baseelement-getcurrentstate)|string|nil|Gets current primary state| +|[BaseElement:getActiveStates](#baseelement-getactivestates)|table|Gets all active states| +|[BaseElement:updateConditionalStates](#baseelement-updateconditionalstates)|BaseElement|Updates conditional states| +|[BaseElement:unregisterState](#baseelement-unregisterstate-statename)|BaseElement|Removes state definition| |[BaseElement:fireEvent](#baseelement-fireevent-event-any)|table|Triggers event callbacks with provided arguments| |[BaseElement:onChange](#baseelement-onchange-property-callback)|table|Watches property changes with callback notification| |[BaseElement:getBaseFrame](#baseelement-getbaseframe)|BaseFrame|Retrieves the root frame of this element's tree| @@ -78,6 +87,80 @@ Adds an event handler function with automatic event registration ### Returns * `table` `self` The BaseElement instance +## BaseElement:registerState(stateName, condition?, priority?) + +Registers a new state with optional auto-condition + +### Parameters +* `stateName` `string` The name of the state +* `condition` *(optional)* `function` Optional: Function that returns true if state is active: function(element) return boolean end +* `priority` *(optional)* `number` Priority (higher = more important, default: 0) + +### Returns +* `BaseElement` `self` The BaseElement instance + +## BaseElement:setState(stateName, priority?) + +Manually activates a state + +### Parameters +* `stateName` `string` The state to activate +* `priority` *(optional)* `number` Optional priority override + +### Returns +* `BaseElement` self + +## BaseElement:unsetState(stateName) + +Manually deactivates a state + +### Parameters +* `stateName` `string` The state to deactivate + +### Returns +* `BaseElement` self + +## BaseElement:hasState(stateName) + +Checks if a state is currently active + +### Parameters +* `stateName` `string` The state to check + +### Returns +* `boolean` isActive + +## BaseElement:getCurrentState() + +Gets the highest priority active state + +### Returns +* `string|nil` `currentState` The state with highest priority + +## BaseElement:getActiveStates() + +Gets all currently active states sorted by priority + +### Returns +* `table` `states` Array of {name, priority} sorted by priority + +## BaseElement:updateConditionalStates() + +Updates all states that have auto-conditions + +### Returns +* `BaseElement` self + +## BaseElement:unregisterState(stateName) + +Removes a state from the registry + +### Parameters +* `stateName` `string` The state to remove + +### Returns +* `BaseElement` self + ## BaseElement:fireEvent(event, any) Executes all registered callbacks for the specified event diff --git a/docs/references/elements/Collection.md b/docs/references/elements/Collection.md new file mode 100644 index 0000000..725aae9 --- /dev/null +++ b/docs/references/elements/Collection.md @@ -0,0 +1,107 @@ +# Collection +_This is the Collection class. It provides a collection of items_ + +Extends: `VisualElement` + +## Properties + +|Property|Type|Default|Description| +|---|---|---|---| +|selectable|boolean|true|Whether items can be selected| +|multiSelection|boolean|false|Whether multiple items can be selected at once| +|selectedBackground|color|blue|Background color for selected items| +|selectedForeground|color|white|Text color for selected items| + +## Events + +|Event|Parameters|Description| +|---|---|---| +|onSelect|`index number, item table`|Fired when an item is selected| + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[Collection:addItem](#collection-additem-text)|Collection|Adds an item to the Collection| +|[Collection:removeItem](#collection-removeitem-index)|Collection|Removes an item from the Collection| +|[Collection:clear](#collection-clear)|Collection|Clears all items from the Collection| +|[Collection:getSelectedItems](#collection-getselecteditems)|table|Gets the currently selected items| +|[Collection:getSelectedItem](#collection-getselecteditem)|selected|Gets first selected item| +|[Collection:onSelect](#collection-onselect-callback)|Collection|Registers a callback for the select event| + +## Collection:addItem(text) + +Adds an item to the Collection + +### Parameters +* `text` `string|table` The item to add (string or item table) + +### Returns +* `Collection` `self` The Collection instance + +### Usage +```lua +Collection:addItem("New Item") +Collection:addItem({text="Item", callback=function() end}) +``` + +## Collection:removeItem(index) + +Removes an item from the Collection + +### Parameters +* `index` `number` The index of the item to remove + +### Returns +* `Collection` `self` The Collection instance + +### Usage +```lua +Collection:removeItem(1) +``` + +## Collection:clear() + +Clears all items from the Collection + +### Returns +* `Collection` `self` The Collection instance + +### Usage +```lua +Collection:clear() +``` + +## Collection:getSelectedItems() + +Gets the currently selected items + +### Returns +* `table` `selected` Collection of selected items + +### Usage +```lua +local selected = Collection:getSelectedItems() +``` + +## Collection:getSelectedItem() + +Gets first selected item + +### Returns +* `selected` `The` first item + +## Collection:onSelect(callback) + +Registers a callback for the select event + +### Parameters +* `callback` `function` The callback function to register + +### Returns +* `Collection` `self` The Collection instance + +### Usage +```lua +Collection:onSelect(function(index, item) print("Selected item:", index, item) end) +``` diff --git a/docs/references/elements/ComboBox.md b/docs/references/elements/ComboBox.md index bce4d8e..28d087e 100644 --- a/docs/references/elements/ComboBox.md +++ b/docs/references/elements/ComboBox.md @@ -14,8 +14,6 @@ Extends: `DropDown` |viewOffset|number|0|Horizontal scroll position for viewing long text| |placeholder|string|"..."|Text shown when the input is empty| |placeholderColor|color|gray|Color used for placeholder text| -|focusedBackground|color|blue|Background color when input is focused| -|focusedForeground|color|white|Text color when input is focused| |autoComplete|boolean|false|Enables filtering dropdown items while typing| |manuallyOpened|boolean|false|Indicates if dropdown was opened by user action| @@ -24,14 +22,8 @@ Extends: `DropDown` |Method|Returns|Description| |---|---|---| |[ComboBox.new](#combobox-new)|ComboBox|Creates a new ComboBox instance| -|[ComboBox:setText](#combobox-settext-text)|ComboBox|Sets the text content| -|[ComboBox:getText](#combobox-gettext)|string|Gets the text content| -|[ComboBox:setEditable](#combobox-seteditable-editable)|ComboBox|Sets editable state| |[ComboBox:char](#combobox-char-char)|-|Handles character input| |[ComboBox:key](#combobox-key-key-held)|-|Handles key input| -|[ComboBox:render](#combobox-render)|-|Renders the ComboBox| -|[ComboBox:focus](#combobox-focus)|-|Called when gaining focus| -|[ComboBox:blur](#combobox-blur)|-|Called when losing focus| ## ComboBox.new() @@ -40,33 +32,6 @@ Creates a new ComboBox instance ### Returns * `ComboBox` `self` The newly created ComboBox instance -## ComboBox:setText(text) - -Sets the text content of the ComboBox - -### Parameters -* `text` `string` The text to set - -### Returns -* `ComboBox` self - -## ComboBox:getText() - -Gets the current text content - -### Returns -* `string` `text` The current text - -## ComboBox:setEditable(editable) - -Sets whether the ComboBox is editable - -### Parameters -* `editable` `boolean` Whether the ComboBox should be editable - -### Returns -* `ComboBox` self - ## ComboBox:char(char) Handles character input when editable @@ -81,15 +46,3 @@ Handles key input when editable ### Parameters * `key` `number` The key code that was pressed * `held` `boolean` Whether the key is being held - -## ComboBox:render() - -Renders the ComboBox - -## ComboBox:focus() - -Called when the ComboBox gains focus - -## ComboBox:blur() - -Called when the ComboBox loses focus diff --git a/docs/references/elements/DropDown.md b/docs/references/elements/DropDown.md index 4e5d180..8ba9cc8 100644 --- a/docs/references/elements/DropDown.md +++ b/docs/references/elements/DropDown.md @@ -7,7 +7,6 @@ Extends: `List` |Property|Type|Default|Description| |---|---|---|---| -|isOpen|boolean|false|Controls the expanded/collapsed state| |dropdownHeight|number|5|Maximum visible items when expanded| |selectedText|string|""|Text shown when no selection made| |dropSymbol|string|"\31"|Indicator for dropdown state| diff --git a/docs/references/elements/Input.md b/docs/references/elements/Input.md index f6b8051..657e59c 100644 --- a/docs/references/elements/Input.md +++ b/docs/references/elements/Input.md @@ -13,8 +13,6 @@ Extends: `VisualElement` |viewOffset|number|0|The horizontal scroll offset for viewing long text| |placeholder|string|...|Text to display when input is empty| |placeholderColor|color|gray|Color of the placeholder text| -|focusedBackground|color|blue|Background color when input is focused| -|focusedForeground|color|white|Foreground color when input is focused| |cursorColor|number|nil|Color of the cursor| |replaceChar|string|nil|Character to replace the input with (for password fields)| diff --git a/docs/references/elements/List.md b/docs/references/elements/List.md index 8be9e0d..4424c45 100644 --- a/docs/references/elements/List.md +++ b/docs/references/elements/List.md @@ -2,18 +2,13 @@ _This is the list class. It provides a scrollable list of selectable items with support for _ _custom item rendering, separators, and selection handling._ -Extends: `VisualElement` +Extends: `Collection` ## Properties |Property|Type|Default|Description| |---|---|---|---| -|items|table|{}|List of items to display. Items can be tables with properties including selected state| -|selectable|boolean|true|Whether items in the list can be selected| -|multiSelection|boolean|false|Whether multiple items can be selected at once| |offset|number|0|Current scroll offset for viewing long lists| -|selectedBackground|color|blue|Background color for selected items| -|selectedForeground|color|white|Text color for selected items| ## Events @@ -25,77 +20,10 @@ Extends: `VisualElement` |Method|Returns|Description| |---|---|---| -|[List:addItem](#list-additem-text)|List|Adds an item to the list| -|[List:removeItem](#list-removeitem-index)|List|Removes an item from the list| -|[List:clear](#list-clear)|List|Clears all items from the list| -|[List:getSelectedItems](#list-getselecteditems)|table|Gets the currently selected items| -|[List:getSelectedItem](#list-getselecteditem)|selected|Gets first selected item| |[List:onSelect](#list-onselect-callback)|List|Registers a callback for the select event| |[List:scrollToBottom](#list-scrolltobottom)|List|Scrolls the list to the bottom| |[List:scrollToTop](#list-scrolltotop)|List|Scrolls the list to the top| -## List:addItem(text) - -Adds an item to the list - -### Parameters -* `text` `string|table` The item to add (string or item table) - -### Returns -* `List` `self` The List instance - -### Usage -```lua -list:addItem("New Item") -list:addItem({text="Item", callback=function() end}) -``` - -## List:removeItem(index) - -Removes an item from the list - -### Parameters -* `index` `number` The index of the item to remove - -### Returns -* `List` `self` The List instance - -### Usage -```lua -list:removeItem(1) -``` - -## List:clear() - -Clears all items from the list - -### Returns -* `List` `self` The List instance - -### Usage -```lua -list:clear() -``` - -## List:getSelectedItems() - -Gets the currently selected items - -### Returns -* `table` `selected` List of selected items - -### Usage -```lua -local selected = list:getSelectedItems() -``` - -## List:getSelectedItem() - -Gets first selected item - -### Returns -* `selected` `The` first item - ## List:onSelect(callback) Registers a callback for the select event diff --git a/docs/references/elements/VisualElement.md b/docs/references/elements/VisualElement.md index 4194944..7de9810 100644 --- a/docs/references/elements/VisualElement.md +++ b/docs/references/elements/VisualElement.md @@ -15,15 +15,12 @@ Extends: `BaseElement` |height|number|1|The height of the element| |background|color|black|The background color| |foreground|color|white|The text/foreground color| -|clicked|boolean|false|Whether the element is currently clicked| -|hover|boolean|false|Whether the mouse is currently hover over the element (Craftos-PC only)| |backgroundEnabled|boolean|true|Whether to render the background| |borderTop|boolean|false|Draw top border| |borderBottom|boolean|false|Draw bottom border| |borderLeft|boolean|false|Draw left border| |borderRight|boolean|false|Draw right border| |borderColor|color|white|Border color| -|focused|boolean|false|Whether the element has input focus| |visible|boolean|true|Whether the element is visible| |ignoreOffset|boolean|false|Whether to ignore the parent's offset| @@ -37,7 +34,40 @@ Extends: `BaseElement` |Method|Returns|Description| |---|---|---| +|[VisualElement:setConstraint](#visualelement-setconstraint-property-targetelement-targetproperty-offset)|VisualElement|Sets a constraint on a property relative to another element's property| +|[VisualElement:resolveAllConstraints](#visualelement-resolveallconstraints)|VisualElement|Resolves all constraints for the element| +|[VisualElement:removeConstraint](#visualelement-removeconstraint-property)|VisualElement|Removes a constraint from the element| +|[VisualElement:updateConstraints](#visualelement-updateconstraints)|VisualElement|Updates all constraints, recalculating positions and sizes| +|[VisualElement:alignRight](#visualelement-alignright-target-offset)|VisualElement|Aligns the element's right edge to the target's right edge with optional offset| +|[VisualElement:alignLeft](#visualelement-alignleft-target-offset)|VisualElement|Aligns the element's left edge to the target's left edge with optional offset| +|[VisualElement:alignTop](#visualelement-aligntop-target-offset)|VisualElement|Aligns the element's top edge to the target's top edge with optional offset| +|[VisualElement:alignBottom](#visualelement-alignbottom-target-offset)|VisualElement|Aligns the element's bottom edge to the target's bottom edge with optional offset| +|[VisualElement:centerHorizontal](#visualelement-centerhorizontal-target-offset)|VisualElement|Centers the element horizontally relative to the target with optional offset| +|[VisualElement:centerVertical](#visualelement-centervertical-target-offset)|VisualElement|Centers the element vertically relative to the target with optional offset| +|[VisualElement:centerIn](#visualelement-centerin-target)|VisualElement|Centers the element both horizontally and vertically relative to the target| +|[VisualElement:rightOf](#visualelement-rightof-target-gap)|VisualElement|Positions the element to the right of the target with optional gap| +|[VisualElement:leftOf](#visualelement-leftof-target-gap)|VisualElement|Positions the element to the left of the target with optional gap| +|[VisualElement:below](#visualelement-below-target-gap)|VisualElement|Positions the element below the target with optional gap| +|[VisualElement:above](#visualelement-above-target-gap)|VisualElement|Positions the element above the target with optional gap| +|[VisualElement:stretchWidth](#visualelement-stretchwidth-target-margin)|VisualElement|Stretches the element to match the target's width with optional margin| +|[VisualElement:stretchHeight](#visualelement-stretchheight-target-margin)|VisualElement|Stretches the element to match the target's height with optional margin| +|[VisualElement:stretch](#visualelement-stretch-target-margin)|VisualElement|Stretches the element to match the target's width and height with optional margin| +|[VisualElement:widthPercent](#visualelement-widthpercent-target-percent)|VisualElement|Sets the element's width as a percentage of the target's width| +|[VisualElement:heightPercent](#visualelement-heightpercent-target-percent)|VisualElement|Sets the element's height as a percentage of the target's height| +|[VisualElement:matchWidth](#visualelement-matchwidth-target-offset)|VisualElement|Matches the element's width to the target's width with optional offset| +|[VisualElement:matchHeight](#visualelement-matchheight-target-offset)|VisualElement|Matches the element's height to the target's height with optional offset| +|[VisualElement:fillParent](#visualelement-fillparent-margin)|VisualElement|Stretches the element to fill its parent's width and height with optional margin| +|[VisualElement:fillWidth](#visualelement-fillwidth-margin)|VisualElement|Stretches the element to fill its parent's width with optional margin| +|[VisualElement:fillHeight](#visualelement-fillheight-margin)|VisualElement|Stretches the element to fill its parent's height with optional margin| +|[VisualElement:center](#visualelement-center)|VisualElement|Centers the element within its parent both horizontally and vertically| +|[VisualElement:toRight](#visualelement-toright-gap)|VisualElement|Aligns the element's right edge to its parent's right edge with optional gap| +|[VisualElement:toLeft](#visualelement-toleft-gap)|VisualElement|Aligns the element's left edge to its parent's left edge with optional gap| +|[VisualElement:toTop](#visualelement-totop-gap)|VisualElement|Aligns the element's top edge to its parent's top edge with optional gap| +|[VisualElement:toBottom](#visualelement-tobottom-gap)|VisualElement|Aligns the element's bottom edge to its parent's bottom edge with optional gap| |[VisualElement:isInBounds](#visualelement-isinbounds-x-y)|boolean|Checks if point is within bounds| +|[VisualElement:setFocused](#visualelement-setfocused-focused-internal)|VisualElement|Sets focus state| +|[VisualElement:isFocused](#visualelement-isfocused)|boolean|Checks if element is focused| +|[VisualElement:isFocused](#visualelement-isfocused)|boolean|Checks if element is focused| |[VisualElement:addBorder](#visualelement-addborder-colororoptions)|VisualElement|Adds or updates a drawable character border around the element using the canvas plugin. The border will automatically adapt to size/background changes because the command reads current properties each render.| @@ -47,6 +77,317 @@ reads current properties each render.| |[VisualElement:getRelativePosition](#visualelement-getrelativeposition-x-y)|number, number|Returns the relative position of the element| |[VisualElement:prioritize](#visualelement-prioritize)|VisualElement|Prioritizes the element by moving it to the top of its parent's children| +## VisualElement:setConstraint(property, targetElement, targetProperty, offset) + +Sets a constraint on a property relative to another element's property + +### Parameters +* `property` `string` The property to constrain (x, y, width, height, left, right, top, bottom, centerX, centerY) +* `targetElement` `BaseElement|string` The target element or "parent" +* `targetProperty` `string` The target property to constrain to (left, right, top, bottom, centerX, centerY, width, height) +* `offset` `number` The offset to apply (negative = inside, positive = outside, fractional = percentage) + +### Returns +* `VisualElement` `self` The element instance + +## VisualElement:resolveAllConstraints() + +Resolves all constraints for the element + +### Returns +* `VisualElement` `self` The element instance + +## VisualElement:removeConstraint(property) + +Removes a constraint from the element + +### Parameters +* `property` `string` The property of the constraint to remove + +### Returns +* `VisualElement` `self` The element instance + +## VisualElement:updateConstraints() + +Updates all constraints, recalculating positions and sizes + +### Returns +* `VisualElement` `self` The element instance + +## VisualElement:alignRight(target, offset?) + +Aligns the element's right edge to the target's right edge with optional offset + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `offset` *(optional)* `number` Offset from the edge (negative = inside, positive = outside, default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:alignLeft(target, offset?) + +Aligns the element's left edge to the target's left edge with optional offset + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `offset` *(optional)* `number` Offset from the edge (negative = inside, positive = outside, default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:alignTop(target, offset?) + +Aligns the element's top edge to the target's top edge with optional offset + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `offset` *(optional)* `number` Offset from the edge (negative = inside, positive = outside, default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:alignBottom(target, offset?) + +Aligns the element's bottom edge to the target's bottom edge with optional offset + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `offset` *(optional)* `number` Offset from the edge (negative = inside, positive = outside, default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:centerHorizontal(target, offset?) + +Centers the element horizontally relative to the target with optional offset + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `offset` *(optional)* `number` Horizontal offset from center (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:centerVertical(target, offset?) + +Centers the element vertically relative to the target with optional offset + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `offset` *(optional)* `number` Vertical offset from center (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:centerIn(target) + +Centers the element both horizontally and vertically relative to the target + +### Parameters +* `target` `BaseElement|string` The target element or "parent" + +### Returns +* `VisualElement` self + +## VisualElement:rightOf(target, gap?) + +Positions the element to the right of the target with optional gap + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `gap` *(optional)* `number` Gap between elements (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:leftOf(target, gap?) + +Positions the element to the left of the target with optional gap + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `gap` *(optional)* `number` Gap between elements (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:below(target, gap?) + +Positions the element below the target with optional gap + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `gap` *(optional)* `number` Gap between elements (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:above(target, gap?) + +Positions the element above the target with optional gap + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `gap` *(optional)* `number` Gap between elements (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:stretchWidth(target, margin?) + +Stretches the element to match the target's width with optional margin + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `margin` *(optional)* `number` Margin on each side (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:stretchHeight(target, margin?) + +Stretches the element to match the target's height with optional margin + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `margin` *(optional)* `number` Margin on top and bottom (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:stretch(target, margin?) + +Stretches the element to match the target's width and height with optional margin + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `margin` *(optional)* `number` Margin on all sides (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:widthPercent(target, percent) + +Sets the element's width as a percentage of the target's width + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `percent` `number` Percentage of target's width (0-100) + +### Returns +* `VisualElement` self + +## VisualElement:heightPercent(target, percent) + +Sets the element's height as a percentage of the target's height + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `percent` `number` Percentage of target's height (0-100) + +### Returns +* `VisualElement` self + +## VisualElement:matchWidth(target, offset?) + +Matches the element's width to the target's width with optional offset + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `offset` *(optional)* `number` Offset to add to target's width (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:matchHeight(target, offset?) + +Matches the element's height to the target's height with optional offset + +### Parameters +* `target` `BaseElement|string` The target element or "parent" +* `offset` *(optional)* `number` Offset to add to target's height (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:fillParent(margin?) + +Stretches the element to fill its parent's width and height with optional margin + +### Parameters +* `margin` *(optional)* `number` Margin on all sides (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:fillWidth(margin?) + +Stretches the element to fill its parent's width with optional margin + +### Parameters +* `margin` *(optional)* `number` Margin on left and right (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:fillHeight(margin?) + +Stretches the element to fill its parent's height with optional margin + +### Parameters +* `margin` *(optional)* `number` Margin on top and bottom (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:center() + +Centers the element within its parent both horizontally and vertically + +### Returns +* `VisualElement` self + +## VisualElement:toRight(gap?) + +Aligns the element's right edge to its parent's right edge with optional gap + +### Parameters +* `gap` *(optional)* `number` Gap from the edge (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:toLeft(gap?) + +Aligns the element's left edge to its parent's left edge with optional gap + +### Parameters +* `gap` *(optional)* `number` Gap from the edge (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:toTop(gap?) + +Aligns the element's top edge to its parent's top edge with optional gap + +### Parameters +* `gap` *(optional)* `number` Gap from the edge (default: 0) + +### Returns +* `VisualElement` self + +## VisualElement:toBottom(gap?) + +Aligns the element's bottom edge to its parent's bottom edge with optional gap + +### Parameters +* `gap` *(optional)* `number` Gap from the edge (default: 0) + +### Returns +* `VisualElement` self + ## VisualElement:isInBounds(x, y) Checks if the specified coordinates are within the bounds of the element @@ -58,6 +399,31 @@ Checks if the specified coordinates are within the bounds of the element ### Returns * `boolean` `isInBounds` Whether the coordinates are within the bounds of the element +## VisualElement:setFocused(focused, internal?) + +Sets or removes focus from this element + +### Parameters +* `focused` `boolean` Whether to focus or blur +* `internal` *(optional)* `boolean` Internal flag to prevent parent notification + +### Returns +* `VisualElement` self + +## VisualElement:isFocused() + +Gets whether this element is focused + +### Returns +* `boolean` isFocused + +## VisualElement:isFocused() + +Gets whether this element is focused + +### Returns +* `boolean` isFocused + ## VisualElement:addBorder(colorOrOptions) Adds or updates a drawable character border around the element using the canvas plugin. diff --git a/docs/references/libraries/collectionentry.md b/docs/references/libraries/collectionentry.md new file mode 100644 index 0000000..84c33e9 --- /dev/null +++ b/docs/references/libraries/collectionentry.md @@ -0,0 +1 @@ +!! EMPTY MARKDOWN GENERATED !! diff --git a/docs/references/main.md b/docs/references/main.md index f4f8f8c..088f9a6 100644 --- a/docs/references/main.md +++ b/docs/references/main.md @@ -27,6 +27,10 @@ _What this code does is it loads basalt into the project, and you can access it |[basalt.onEvent](#basalt-onevent-eventname-callback)|-|Registers an event callback| |[basalt.removeEvent](#basalt-removeevent-eventname-callback)|boolean|Removes an event callback| |[basalt.triggerEvent](#basalt-triggerevent-eventname)|-|Triggers a custom event| +|[basalt.requireElements](#basalt-requireelements-elements-autoload)|-|Requires elements for the application| +|[basalt.loadManifest](#basalt-loadmanifest-path)|table|Loads an application manifest| +|[basalt.install](#basalt-install-elementname-source)|-|Installs an element| +|[basalt.configure](#basalt-configure-config)|-|Configures element loading behavior| ## basalt.create(type, properties?) @@ -194,3 +198,58 @@ Triggers a custom event and calls all registered callbacks ```lua basalt.triggerEvent("custom_event", "data1", "data2") ``` + +## basalt.requireElements(elements, autoLoad?) + +Requires specific elements and validates they are available + +### Parameters +* `elements` `table|string` List of element names or single element name +* `autoLoad` *(optional)* `boolean` Whether to automatically load missing elements (default: false) + +### Usage +```lua +basalt.requireElements({"Button", "Label", "Slider"}) +basalt.requireElements("Button", true) +``` + +## basalt.loadManifest(path) + +Loads a manifest file that describes element requirements and configuration + +### Parameters +* `path` `string` The path to the manifest file + +### Returns +* `table` `manifest` The loaded manifest data + +### Usage +```lua +basalt.loadManifest("myapp.manifest") +``` + +## basalt.install(elementName, source?) + +Installs an element interactively or from a specified source + +### Parameters +* `elementName` `string` The name of the element to install +* `source` *(optional)* `string` Optional source URL or path + +### Usage +```lua +basalt.install("Slider") +basalt.install("Slider", "https://example.com/slider.lua") +``` + +## basalt.configure(config) + +Configures the ElementManager (shortcut to elementManager.configure) + +### Parameters +* `config` `table` Configuration options + +### Usage +```lua +basalt.configure({allowRemoteLoading = true, useGlobalCache = true}) +``` From f798a698b383279500d4e6445467a12ab7655fff Mon Sep 17 00:00:00 2001 From: NoryiE Date: Mon, 27 Oct 2025 16:47:11 +0000 Subject: [PATCH 14/17] deploy: eaad81dc1a5f016e9f28f64aeece8970ebbe4f4f --- docs/references/elements/VisualElement.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/references/elements/VisualElement.md b/docs/references/elements/VisualElement.md index 7de9810..172e795 100644 --- a/docs/references/elements/VisualElement.md +++ b/docs/references/elements/VisualElement.md @@ -68,9 +68,7 @@ Extends: `BaseElement` |[VisualElement:setFocused](#visualelement-setfocused-focused-internal)|VisualElement|Sets focus state| |[VisualElement:isFocused](#visualelement-isfocused)|boolean|Checks if element is focused| |[VisualElement:isFocused](#visualelement-isfocused)|boolean|Checks if element is focused| -|[VisualElement:addBorder](#visualelement-addborder-colororoptions)|VisualElement|Adds or updates a drawable character border around the element using the canvas plugin. -The border will automatically adapt to size/background changes because the command -reads current properties each render.| +|[VisualElement:addBorder](#visualelement-addborder-colororoptions-sideoptions)|VisualElement|Adds or updates a drawable character border around the element using the canvas plugin. The border will automatically adapt to size/background changes because the command reads current properties each render.| |[VisualElement:removeBorder](#visualelement-removeborder)|VisualElement|Removes the previously added border (if any)| |[VisualElement:calculatePosition](#visualelement-calculateposition)|number, number|Calculates the position of the element| |[VisualElement:getAbsolutePosition](#visualelement-getabsoluteposition-x-y)|number, number|Returns the absolute position of the element| @@ -424,14 +422,13 @@ Gets whether this element is focused ### Returns * `boolean` isFocused -## VisualElement:addBorder(colorOrOptions) +## VisualElement:addBorder(colorOrOptions, sideOptions?) -Adds or updates a drawable character border around the element using the canvas plugin. -The border will automatically adapt to size/background changes because the command -reads current properties each render. +Adds or updates a drawable character border around the element using the canvas plugin. The border will automatically adapt to size/background changes because the command reads current properties each render. ### Parameters * `colorOrOptions` `any` Border color or options table +* `sideOptions` *(optional)* `table` Side options table (if color is provided as first argument) ### Returns * `VisualElement` self From 9a5b46138e49d514bfe9dfde6443374cac566a2d Mon Sep 17 00:00:00 2001 From: NoryiE Date: Wed, 29 Oct 2025 08:11:09 +0000 Subject: [PATCH 15/17] deploy: 41bd5bdf041f6e73d056b3b306b6e371039b064b --- docs/references/elements/Collection.md | 29 ++++++++++++++++++++++++++ docs/references/elements/List.md | 22 +++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/docs/references/elements/Collection.md b/docs/references/elements/Collection.md index 725aae9..b320999 100644 --- a/docs/references/elements/Collection.md +++ b/docs/references/elements/Collection.md @@ -27,6 +27,9 @@ Extends: `VisualElement` |[Collection:clear](#collection-clear)|Collection|Clears all items from the Collection| |[Collection:getSelectedItems](#collection-getselecteditems)|table|Gets the currently selected items| |[Collection:getSelectedItem](#collection-getselecteditem)|selected|Gets first selected item| +|[Collection:getSelectedIndex](#collection-getselectedindex)|index|Gets the index of the first selected item| +|[Collection:selectNext](#collection-selectnext)|Collection|Selects the next item| +|[Collection:selectPrevious](#collection-selectprevious)|Collection|Selects the previous item| |[Collection:onSelect](#collection-onselect-callback)|Collection|Registers a callback for the select event| ## Collection:addItem(text) @@ -91,6 +94,32 @@ Gets first selected item ### Returns * `selected` `The` first item +## Collection:getSelectedIndex() + +Gets the index of the first selected item + +### Returns +* `index` `The` index of the first selected item, or nil if none selected + +### Usage +```lua +local index = Collection:getSelectedIndex() +``` + +## Collection:selectNext() + +Selects the next item in the collection + +### Returns +* `Collection` `self` The Collection instance + +## Collection:selectPrevious() + +Selects the previous item in the collection + +### Returns +* `Collection` `self` The Collection instance + ## Collection:onSelect(callback) Registers a callback for the select event diff --git a/docs/references/elements/List.md b/docs/references/elements/List.md index 4424c45..ab560a7 100644 --- a/docs/references/elements/List.md +++ b/docs/references/elements/List.md @@ -9,6 +9,12 @@ Extends: `Collection` |Property|Type|Default|Description| |---|---|---|---| |offset|number|0|Current scroll offset for viewing long lists| +|emptyText|string|"No|items" Text to display when the list is empty| +|showScrollBar|boolean|true|Whether to show the scrollbar when items exceed height| +|scrollBarSymbol|string|"|" Symbol used for the scrollbar handle| +|scrollBarBackground|string|"\127"|Symbol used for the scrollbar background| +|scrollBarColor|color|lightGray|Color of the scrollbar handle| +|scrollBarBackgroundColor|color|gray|Background color of the scrollbar| ## Events @@ -23,6 +29,7 @@ Extends: `Collection` |[List:onSelect](#list-onselect-callback)|List|Registers a callback for the select event| |[List:scrollToBottom](#list-scrolltobottom)|List|Scrolls the list to the bottom| |[List:scrollToTop](#list-scrolltotop)|List|Scrolls the list to the top| +|[List:scrollToItem](#list-scrolltoitem-index)|List|Scrolls to a specific item| ## List:onSelect(callback) @@ -52,3 +59,18 @@ Scrolls the list to the top ### Returns * `List` `self` The List instance + +## List:scrollToItem(index) + +Scrolls to make a specific item visible + +### Parameters +* `index` `number` The index of the item to scroll to + +### Returns +* `List` `self` The List instance + +### Usage +```lua +list:scrollToItem(5) +``` From 00a9ce56322133f9b5e8b2b522bbe4894c0a17ed Mon Sep 17 00:00:00 2001 From: NoryiE Date: Wed, 29 Oct 2025 16:56:08 +0000 Subject: [PATCH 16/17] deploy: 5a1ec672a7e821dea326faaa14b93f1ab38d96f5 --- docs/references/elementManager.md | 4 +- docs/references/elements/BarChart.md | 61 +++++++++ docs/references/elements/BigFont.md | 69 ++++++++++ docs/references/elements/Button.md | 81 +++++++++++ docs/references/elements/CheckBox.md | 49 +++++++ docs/references/elements/Collection.md | 15 ++- docs/references/elements/ComboBox.md | 73 ++++++++++ docs/references/elements/Display.md | 85 ++++++++++++ docs/references/elements/DropDown.md | 50 +++++++ docs/references/elements/FlexBox.md | 29 ++++ docs/references/elements/Graph.md | 45 +++++++ docs/references/elements/LineChart.md | 45 +++++++ docs/references/elements/List.md | 4 +- docs/references/elements/Menu.md | 22 ++- docs/references/elements/ProgressBar.md | 13 ++ docs/references/elements/ScrollFrame.md | 16 +++ docs/references/elements/Slider.md | 2 +- docs/references/elements/Table.md | 157 +++++++++++++++++----- docs/references/elements/Tree.md | 7 +- docs/references/elements/VisualElement.md | 4 +- docs/references/errorManager.md | 2 +- docs/references/log.md | 8 +- docs/references/main.md | 25 +++- docs/references/plugins/animation.md | 2 +- docs/references/plugins/benchmark.md | 4 +- docs/references/plugins/reactive.md | 17 +++ 26 files changed, 812 insertions(+), 77 deletions(-) create mode 100644 docs/references/elements/ScrollFrame.md diff --git a/docs/references/elementManager.md b/docs/references/elementManager.md index 4e0278d..daccefc 100644 --- a/docs/references/elementManager.md +++ b/docs/references/elementManager.md @@ -60,7 +60,7 @@ Loads an element by name. This will load the element and apply any plugins to it * `name` `string` The name of the element to load ### Usage -```lua +```lua run ElementManager.loadElement("Button") ``` @@ -116,7 +116,7 @@ Checks if an element is loaded Clears the global cache (_G) ### Usage -```lua +```lua run ElementManager.clearGlobalCache() ``` diff --git a/docs/references/elements/BarChart.md b/docs/references/elements/BarChart.md index 977a870..b7f5813 100644 --- a/docs/references/elements/BarChart.md +++ b/docs/references/elements/BarChart.md @@ -2,3 +2,64 @@ _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` + +## Usage +```lua run +-- Create a bar chart +``` + +```lua run +local chart = main:addBarChart() +``` + +```lua run + +``` + +```lua run +-- Add two data series with different colors +``` + +```lua run +chart:addSeries("input", " ", colors.green, colors.green, 5) +``` + +```lua run +chart:addSeries("output", " ", colors.red, colors.red, 5) +``` + +```lua run + +``` + +```lua run +-- Continuously update the chart with random data +``` + +```lua run +basalt.schedule(function() +``` + +```lua run +while true do +``` + +```lua run +chart:addPoint("input", math.random(1,100)) +``` + +```lua run +chart:addPoint("output", math.random(1,100)) +``` + +```lua run +sleep(2) +``` + +```lua run +end +``` + +```lua run +end) +``` diff --git a/docs/references/elements/BigFont.md b/docs/references/elements/BigFont.md index 24ee292..9fa380e 100644 --- a/docs/references/elements/BigFont.md +++ b/docs/references/elements/BigFont.md @@ -3,6 +3,75 @@ _A specialized text element that renders characters in larger sizes using Wojbie Extends: `VisualElement` +## Usage +```lua run +-- Create a large welcome message +``` + +```lua run +local main = basalt.getMainFrame() +``` + +```lua run +local title = main:addBigFont() +``` + +```lua run +:setPosition(3, 3) +``` + +```lua run +:setFontSize(2) -- Makes text twice as large +``` + +```lua run +:setText("Welcome!") +``` + +```lua run +:setForeground(colors.yellow) -- Make text yellow +``` + +```lua run + +``` + +```lua run +-- For animated text +``` + +```lua run +basalt.schedule(function() +``` + +```lua run +while true do +``` + +```lua run +title:setForeground(colors.yellow) +``` + +```lua run +sleep(0.5) +``` + +```lua run +title:setForeground(colors.orange) +``` + +```lua run +sleep(0.5) +``` + +```lua run +end +``` + +```lua run +end) +``` + ## Properties |Property|Type|Default|Description| diff --git a/docs/references/elements/Button.md b/docs/references/elements/Button.md index 709ef40..a9f9ae4 100644 --- a/docs/references/elements/Button.md +++ b/docs/references/elements/Button.md @@ -3,6 +3,87 @@ _A clickable interface element that triggers actions when pressed. Supports text Extends: `VisualElement` +## Usage +```lua run +-- Create a simple action button +``` + +```lua run +local button = parent:addButton() +``` + +```lua run +:setPosition(5, 5) +``` + +```lua run +:setText("Click me!") +``` + +```lua run +:setBackground(colors.blue) +``` + +```lua run +:setForeground(colors.white) +``` + +```lua run + +``` + +```lua run +-- Add click handling +``` + +```lua run +button:onClick(function(self, button, x, y) +``` + +```lua run +-- Change appearance when clicked +``` + +```lua run +self:setBackground(colors.green) +``` + +```lua run +self:setText("Success!") +``` + +```lua run + +``` + +```lua run +-- Revert after delay +``` + +```lua run +basalt.schedule(function() +``` + +```lua run +sleep(1) +``` + +```lua run +self:setBackground(colors.blue) +``` + +```lua run +self:setText("Click me!") +``` + +```lua run +end) +``` + +```lua run +end) +``` + ## Properties |Property|Type|Default|Description| diff --git a/docs/references/elements/CheckBox.md b/docs/references/elements/CheckBox.md index 747e0e0..bc8c0f3 100644 --- a/docs/references/elements/CheckBox.md +++ b/docs/references/elements/CheckBox.md @@ -3,6 +3,55 @@ _A toggleable UI element that can be checked or unchecked. Displays different te Extends: `VisualElement` +## Usage +```lua run +-- Create a checkbox for a setting +``` + +```lua run +local checkbox = parent:addCheckBox() +``` + +```lua run +:setText("Enable Feature") +``` + +```lua run +:setCheckedText("✓") +``` + +```lua run +:onChange("checked", function(self, checked) +``` + +```lua run +-- React to checkbox state changes +``` + +```lua run +if checked then +``` + +```lua run +-- Handle enabled state +``` + +```lua run +else +``` + +```lua run +-- Handle disabled state +``` + +```lua run +end +``` + +```lua run +end) +``` + ## Properties |Property|Type|Default|Description| diff --git a/docs/references/elements/Collection.md b/docs/references/elements/Collection.md index b320999..ce2a1e3 100644 --- a/docs/references/elements/Collection.md +++ b/docs/references/elements/Collection.md @@ -43,8 +43,11 @@ Adds an item to the Collection * `Collection` `self` The Collection instance ### Usage -```lua +```lua run Collection:addItem("New Item") +``` + +```lua run Collection:addItem({text="Item", callback=function() end}) ``` @@ -59,7 +62,7 @@ Removes an item from the Collection * `Collection` `self` The Collection instance ### Usage -```lua +```lua run Collection:removeItem(1) ``` @@ -71,7 +74,7 @@ Clears all items from the Collection * `Collection` `self` The Collection instance ### Usage -```lua +```lua run Collection:clear() ``` @@ -83,7 +86,7 @@ Gets the currently selected items * `table` `selected` Collection of selected items ### Usage -```lua +```lua run local selected = Collection:getSelectedItems() ``` @@ -102,7 +105,7 @@ Gets the index of the first selected item * `index` `The` index of the first selected item, or nil if none selected ### Usage -```lua +```lua run local index = Collection:getSelectedIndex() ``` @@ -131,6 +134,6 @@ Registers a callback for the select event * `Collection` `self` The Collection instance ### Usage -```lua +```lua run Collection:onSelect(function(index, item) print("Selected item:", index, item) end) ``` diff --git a/docs/references/elements/ComboBox.md b/docs/references/elements/ComboBox.md index 28d087e..51de986 100644 --- a/docs/references/elements/ComboBox.md +++ b/docs/references/elements/ComboBox.md @@ -4,6 +4,79 @@ _Supports auto-completion, custom styling, and both single and multi-selection m Extends: `DropDown` +## Usage +```lua run +-- Create a searchable country selector +``` + +```lua run +local combo = main:addComboBox() +``` + +```lua run +:setPosition(5, 5) +``` + +```lua run +:setSize(20, 1) -- Height will expand when opened +``` + +```lua run +:setItems({ +``` + +```lua run +{text = "Germany"}, +``` + +```lua run +{text = "France"}, +``` + +```lua run +{text = "Spain"}, +``` + +```lua run +{text = "Italy"} +``` + +```lua run +}) +``` + +```lua run +:setPlaceholder("Select country...") +``` + +```lua run +:setAutoComplete(true) -- Enable filtering while typing +``` + +```lua run + +``` + +```lua run +-- Handle selection changes +``` + +```lua run +combo:onChange(function(self, value) +``` + +```lua run +-- value will be the selected country +``` + +```lua run +basalt.debug("Selected:", value) +``` + +```lua run +end) +``` + ## Properties |Property|Type|Default|Description| diff --git a/docs/references/elements/Display.md b/docs/references/elements/Display.md index 8344ad6..6512603 100644 --- a/docs/references/elements/Display.md +++ b/docs/references/elements/Display.md @@ -9,6 +9,91 @@ _The Display maintains its own terminal buffer and can be manipulated using fami Extends: `VisualElement` +## Usage +```lua run +-- Create a display for a custom terminal +``` + +```lua run +local display = main:addDisplay() +``` + +```lua run +:setSize(30, 10) +``` + +```lua run +:setPosition(2, 2) +``` + +```lua run + +``` + +```lua run +-- Get the window object for CC API operations +``` + +```lua run +local win = display:getWindow() +``` + +```lua run + +``` + +```lua run +-- Use standard CC terminal operations +``` + +```lua run +win.setTextColor(colors.yellow) +``` + +```lua run +win.setBackgroundColor(colors.blue) +``` + +```lua run +win.clear() +``` + +```lua run +win.setCursorPos(1, 1) +``` + +```lua run +win.write("Hello World!") +``` + +```lua run + +``` + +```lua run +-- Or use the helper method +``` + +```lua run +display:write(1, 2, "Direct write", colors.red, colors.black) +``` + +```lua run + +``` + +```lua run +-- Useful for external APIs +``` + +```lua run +local paintutils = require("paintutils") +``` + +```lua run +paintutils.drawLine(1, 1, 10, 1, colors.red, win) +``` + ## Functions |Method|Returns|Description| diff --git a/docs/references/elements/DropDown.md b/docs/references/elements/DropDown.md index 8ba9cc8..39cabd1 100644 --- a/docs/references/elements/DropDown.md +++ b/docs/references/elements/DropDown.md @@ -3,6 +3,56 @@ _A collapsible selection menu that expands to show multiple options when clicked Extends: `List` +## Usage +```lua run +-- Create a styled dropdown menu +local dropdown = main:addDropDown() +:setPosition(5, 5) +:setSize(20, 1) -- Height expands when opened +:setSelectedText("Select an option...") + +-- Add items with different styles and callbacks +dropdown:setItems({ +{ +text = "Category A", +background = colors.blue, +foreground = colors.white +}, +{ separator = true, text = "-" }, -- Add a separator +{ +text = "Option 1", +callback = function(self) +-- Handle selection +basalt.debug("Selected Option 1") +end +}, +{ +text = "Option 2", +-- Custom colors when selected +selectedBackground = colors.green, +selectedForeground = colors.white +} +}) + +-- Listen for selections +dropdown:onChange(function(self, value) +basalt.debug("Selected:", value) +end) +``` + +## Table Types + +### ItemTable + +|Property|Type|Description| +|---|---|---| +|text|string|The display text for the item| +|callback|function|Function called when selected| +|fg|color|Normal text color| +|bg|color|Normal background color| +|selectedFg|color|Text color when selected| +|selectedBg|color|Background when selected| + ## Properties |Property|Type|Default|Description| diff --git a/docs/references/elements/FlexBox.md b/docs/references/elements/FlexBox.md index 8687208..5a8094f 100644 --- a/docs/references/elements/FlexBox.md +++ b/docs/references/elements/FlexBox.md @@ -4,6 +4,35 @@ _The flexbox element adds the following properties to its children:_ Extends: `Container` +## Usage +```lua run +local flex = main:addFlexbox({background=colors.black, width=30, height=10}) +``` + +```lua run +flex:addButton():setFlexGrow(1) +``` + +```lua run +flex:addButton():setFlexGrow(1) +``` + +```lua run +flex:addButton():setFlexGrow(1) +``` + +```lua run +flex:addButton():setFlexGrow(1) -- The flex-grow property defines the ability for a flex item to grow if necessary. +``` + +```lua run +flex:addButton():setFlexShrink(1) -- The flex-shrink property defines the ability for a flex item to shrink if necessary. +``` + +```lua run +flex:addButton():setFlexBasis(1) -- The flex-basis property defines the default size of an element before the remaining space is distributed. +``` + ## Properties |Property|Type|Default|Description| diff --git a/docs/references/elements/Graph.md b/docs/references/elements/Graph.md index b2eb608..7c3cebf 100644 --- a/docs/references/elements/Graph.md +++ b/docs/references/elements/Graph.md @@ -3,6 +3,51 @@ _This is the base class for all graph elements. It is a point based graph._ Extends: `VisualElement` +## Usage +```lua run +local graph = main:addGraph() +``` + +```lua run +:addSeries("input", " ", colors.green, colors.green, 10) +``` + +```lua run +:addSeries("output", " ", colors.red, colors.red, 10) +``` + +```lua run + +``` + +```lua run +basalt.schedule(function() +``` + +```lua run +while true do +``` + +```lua run +graph:addPoint("input", math.random(1,100)) +``` + +```lua run +graph:addPoint("output", math.random(1,100)) +``` + +```lua run +sleep(2) +``` + +```lua run +end +``` + +```lua run +end) +``` + ## Properties |Property|Type|Default|Description| diff --git a/docs/references/elements/LineChart.md b/docs/references/elements/LineChart.md index 6bf0a96..3e50bda 100644 --- a/docs/references/elements/LineChart.md +++ b/docs/references/elements/LineChart.md @@ -2,3 +2,48 @@ _The Line Chart element visualizes data series as connected line graphs. It plots points on a coordinate system and connects them with lines._ Extends: `Graph` + +## Usage +```lua run +local chart = main:addLineChart() +``` + +```lua run +:addSeries("input", " ", colors.green, colors.green, 10) +``` + +```lua run +:addSeries("output", " ", colors.red, colors.red, 10) +``` + +```lua run + +``` + +```lua run +basalt.schedule(function() +``` + +```lua run +while true do +``` + +```lua run +chart:addPoint("input", math.random(1,100)) +``` + +```lua run +chart:addPoint("output", math.random(1,100)) +``` + +```lua run +sleep(2) +``` + +```lua run +end +``` + +```lua run +end) +``` diff --git a/docs/references/elements/List.md b/docs/references/elements/List.md index ab560a7..40f83be 100644 --- a/docs/references/elements/List.md +++ b/docs/references/elements/List.md @@ -42,7 +42,7 @@ Registers a callback for the select event * `List` `self` The List instance ### Usage -```lua +```lua run list:onSelect(function(index, item) print("Selected item:", index, item) end) ``` @@ -71,6 +71,6 @@ Scrolls to make a specific item visible * `List` `self` The List instance ### Usage -```lua +```lua run list:scrollToItem(5) ``` diff --git a/docs/references/elements/Menu.md b/docs/references/elements/Menu.md index 6a3efa1..2d84cb7 100644 --- a/docs/references/elements/Menu.md +++ b/docs/references/elements/Menu.md @@ -1,6 +1,5 @@ # Menu -_This is the menu class. It provides a horizontal menu bar with selectable items._ -_Menu items are displayed in a single row and can have custom colors and callbacks._ +_This is the menu class. It provides a horizontal menu bar with selectable items. Menu items are displayed in a single row and can have custom colors and callbacks._ Extends: `List` @@ -9,24 +8,19 @@ Extends: `List` |Property|Type|Default|Description| |---|---|---|---| |separatorColor|color|gray|The color used for separator items in the menu| +|spacing|number|0|The number of spaces between menu items| +|horizontalOffset|number|0|Current horizontal scroll offset| +|maxWidth|number|nil|Maximum width before scrolling is enabled (nil = auto-size to items)| ## Functions |Method|Returns|Description| |---|---|---| -|[Menu:setItems](#menu-setitems-items)|Menu|Sets the menu items and calculates total width| +|[Menu:getTotalWidth](#menu-gettotalwidth)|number|Calculates total width of menu items| -## Menu:setItems(items) +## Menu:getTotalWidth() -Sets the menu items - -### Parameters -* `items` `table` [] List of items with {text, separator, callback, foreground, background} properties +Calculates the total width of all menu items with spacing ### Returns -* `Menu` `self` The Menu instance - -### Usage -```lua -menu:setItems({{text="File"}, {separator=true}, {text="Edit"}}) -``` +* `number` `totalWidth` The total width of all items diff --git a/docs/references/elements/ProgressBar.md b/docs/references/elements/ProgressBar.md index 30db285..ac7e1d7 100644 --- a/docs/references/elements/ProgressBar.md +++ b/docs/references/elements/ProgressBar.md @@ -4,6 +4,19 @@ _with optional percentage display and customizable colors._ Extends: `VisualElement` +## Usage +```lua run +local progressBar = main:addProgressBar() +``` + +```lua run +progressBar:setDirection("up") +``` + +```lua run +progressBar:setProgress(50) +``` + ## Properties |Property|Type|Default|Description| diff --git a/docs/references/elements/ScrollFrame.md b/docs/references/elements/ScrollFrame.md new file mode 100644 index 0000000..bf54fb4 --- /dev/null +++ b/docs/references/elements/ScrollFrame.md @@ -0,0 +1,16 @@ +# ScrollFrame +_A container that provides automatic scrolling capabilities with visual scrollbars. Displays vertical and/or horizontal scrollbars when child content exceeds the container's dimensions._ + +Extends: `Container` + +## Properties + +|Property|Type|Default|Description| +|---|---|---|---| +|showScrollBar|boolean|true|Whether to show scrollbars| +|scrollBarSymbol|string|"|" The symbol used for the scrollbar handle| +|scrollBarBackground|string|"\127"|The symbol used for the scrollbar background| +|scrollBarColor|color|lightGray|Color of the scrollbar handle| +|scrollBarBackgroundColor|color|gray|Background color of the scrollbar| +|contentWidth|number|0|The total width of the content (calculated from children)| +|contentHeight|number|0|The total height of the content (calculated from children)| diff --git a/docs/references/elements/Slider.md b/docs/references/elements/Slider.md index e3bb015..c45e5b0 100644 --- a/docs/references/elements/Slider.md +++ b/docs/references/elements/Slider.md @@ -34,6 +34,6 @@ Gets the current value of the slider * `number` `value` The current value (0 to max) ### Usage -```lua +```lua run local value = slider:getValue() ``` diff --git a/docs/references/elements/Table.md b/docs/references/elements/Table.md index 82eb14c..5a4388b 100644 --- a/docs/references/elements/Table.md +++ b/docs/references/elements/Table.md @@ -1,32 +1,120 @@ # Table -_This is the table class. It provides a sortable data grid with customizable columns,_ -_row selection, and scrolling capabilities._ +_This is the table class. It provides a sortable data grid with customizable columns, row selection, and scrolling capabilities. Built on Collection for consistent item management._ -Extends: `VisualElement` +Extends: `Collection` + +## Usage +```lua run +local people = container:addTable():setWidth(40) +``` + +```lua run +people:setColumns({{name="Name",width=12}, {name="Age",width=10}, {name="Country",width=15}}) +``` + +```lua run +people:addRow("Alice", 30, "USA"):addRow("Bob", 25, "UK") +``` ## Properties |Property|Type|Default|Description| |---|---|---|---| |columns|table|{}|List of column definitions with {name, width} properties| -|data|table|{}|The table data as array of row arrays| |headerColor|color|blue|Color of the column headers| -|selectedColor|color|lightBlue|Background color of selected row| |gridColor|color|gray|Color of grid lines| |sortDirection|string|"asc"|Sort direction ("asc" or "desc")| -|scrollOffset|number|0|Current scroll position| |customSortFunction|table|{}|Custom sort functions for columns| +|offset|number|0|Scroll offset for vertical scrolling| +|showScrollBar|boolean|true|Whether to show the scrollbar when items exceed height| +|scrollBarSymbol|string|"|" Symbol used for the scrollbar handle| +|scrollBarBackground|string|"\127"|Symbol used for the scrollbar background| +|scrollBarColor|color|lightGray|Color of the scrollbar handle| +|scrollBarBackgroundColor|color|gray|Background color of the scrollbar| + +## Events + +|Event|Parameters|Description| +|---|---|---| +|onRowSelect|`rowIndex number, row table`|Fired when a row is selected| ## Functions |Method|Returns|Description| |---|---|---| +|[Table:addRow](#table-addrow-any)|Table|Adds a new row with cell values| +|[Table:removeRow](#table-removerow-rowindex)|Table|Removes a row at the specified index| +|[Table:getRow](#table-getrow-rowindex)|row|Gets the row data at the specified index| +|[Table:updateCell](#table-updatecell-rowindex-colindex-value)|Table|Updates a cell value at row and column| +|[Table:getSelectedRow](#table-getselectedrow)|row|Gets the currently selected row data| +|[Table:clearData](#table-cleardata)|Table|Removes all rows from the table| |[Table:addColumn](#table-addcolumn-name-width)|Table|Adds a new column to the table| -|[Table:addData](#table-adddata-any)|Table|Adds a new row of data to the table| |[Table:setColumnSortFunction](#table-setcolumnsortfunction-columnindex-sortfn)|Table|Sets a custom sort function for a column| -|[Table:setFormattedData](#table-setformatteddata-displaydata-sortdata)|Table|Adds formatted data with raw sort values| |[Table:setData](#table-setdata-rawdata-formatters)|Table|Sets table data with optional column formatters| -|[Table:sortData](#table-sortdata-columnindex-fn)|Table|Sorts the table data by the specified column| +|[Table:getData](#table-getdata)|table|Gets all rows as array of cell arrays| +|[Table:sortByColumn](#table-sortbycolumn-columnindex-fn)|Table|Sorts the table data by the specified column| +|[Table:onRowSelect](#table-onrowselect-callback)|Table|Registers a callback when a row is selected| + +## Table:addRow(any) + +Adds a new row to the table + +### Parameters +* `any` `The` cell values for the new row + +### Returns +* `Table` `self` The Table instance + +### Usage +```lua run +table:addRow("Alice", 30, "USA") +``` + +## Table:removeRow(rowIndex) + +Removes a row by index + +### Parameters +* `rowIndex` `number` The index of the row to remove + +### Returns +* `Table` `self` The Table instance + +## Table:getRow(rowIndex) + +Gets a row by index + +### Parameters +* `rowIndex` `number` The index of the row + +### Returns +* `row` `The` row data or nil + +## Table:updateCell(rowIndex, colIndex, value) + +Updates a specific cell value + +### Parameters +* `rowIndex` `number` The row index +* `colIndex` `number` The column index +* `value` `any` The new value + +### Returns +* `Table` `self` The Table instance + +## Table:getSelectedRow() + +Gets the currently selected row + +### Returns +* `row` `The` selected row or nil + +## Table:clearData() + +Clears all table data + +### Returns +* `Table` `self` The Table instance ## Table:addColumn(name, width) @@ -34,17 +122,7 @@ Adds a new column to the table ### Parameters * `name` `string` The name of the column -* `width` `number` The width of the column - -### Returns -* `Table` `self` The Table instance - -## Table:addData(any) - -Adds a new row of data to the table - -### Parameters -* `any` `The` data for the new row +* `width` `number|string` The width of the column (number, "auto", or "30%") ### Returns * `Table` `self` The Table instance @@ -60,29 +138,30 @@ Sets a custom sort function for a specific column ### Returns * `Table` `self` The Table instance -## Table:setFormattedData(displayData, sortData) - -Adds data with both display and sort values - -### Parameters -* `displayData` `table` The formatted data for display -* `sortData` `table` The raw data for sorting (optional) - -### Returns -* `Table` `self` The Table instance - ## Table:setData(rawData, formatters) Set data with automatic formatting ### Parameters -* `rawData` `table` The raw data array -* `formatters` `table` Optional formatter functions for columns {[2] = function(value) return value end} +* `rawData` `table` The raw data array (array of row arrays) +* `formatters` `table` ? Optional formatter functions for columns {[2] = function(value) return value end} ### Returns * `Table` `self` The Table instance -## Table:sortData(columnIndex, fn) +### Usage +```lua run +table:setData({{...}}, {[1] = tostring, [2] = function(age) return age.."y" end}) +``` + +## Table:getData() + +Gets all table data + +### Returns +* `table` `data` Array of row cell arrays + +## Table:sortByColumn(columnIndex, fn) Sorts the table data by column @@ -92,3 +171,13 @@ Sorts the table data by column ### Returns * `Table` `self` The Table instance + +## Table:onRowSelect(callback) + +Registers callback for row selection + +### Parameters +* `callback` `function` The callback function(rowIndex, row) + +### Returns +* `Table` `self` The Table instance diff --git a/docs/references/elements/Tree.md b/docs/references/elements/Tree.md index 24dae79..bf5bcea 100644 --- a/docs/references/elements/Tree.md +++ b/docs/references/elements/Tree.md @@ -10,10 +10,15 @@ Extends: `VisualElement` |---|---|---|---| |nodes|table|{}|The tree structure containing node objects with {text, children} properties| |expandedNodes|table|{}|Table of nodes that are currently expanded| -|scrollOffset|number|0|Current vertical scroll position| +|offset|number|0|Current vertical scroll position| |horizontalOffset|number|0|Current horizontal scroll position| |selectedForegroundColor|color|white|foreground color of selected node| |selectedBackgroundColor|color|lightBlue|background color of selected node| +|showScrollBar|boolean|true|Whether to show the scrollbar when nodes exceed height| +|scrollBarSymbol|string|"|" Symbol used for the scrollbar handle| +|scrollBarBackground|string|"\127"|Symbol used for the scrollbar background| +|scrollBarColor|color|lightGray|Color of the scrollbar handle| +|scrollBarBackgroundColor|color|gray|Background color of the scrollbar| ## Functions diff --git a/docs/references/elements/VisualElement.md b/docs/references/elements/VisualElement.md index 172e795..b8e7570 100644 --- a/docs/references/elements/VisualElement.md +++ b/docs/references/elements/VisualElement.md @@ -68,7 +68,7 @@ Extends: `BaseElement` |[VisualElement:setFocused](#visualelement-setfocused-focused-internal)|VisualElement|Sets focus state| |[VisualElement:isFocused](#visualelement-isfocused)|boolean|Checks if element is focused| |[VisualElement:isFocused](#visualelement-isfocused)|boolean|Checks if element is focused| -|[VisualElement:addBorder](#visualelement-addborder-colororoptions-sideoptions)|VisualElement|Adds or updates a drawable character border around the element using the canvas plugin. The border will automatically adapt to size/background changes because the command reads current properties each render.| +|[VisualElement:addBorder](#visualelement-addborder-colororoptions-sideoptions)|VisualElement|Adds or updates a drawable character border around the element. The border will automatically adapt to size/background changes because the command reads current properties each render.| |[VisualElement:removeBorder](#visualelement-removeborder)|VisualElement|Removes the previously added border (if any)| |[VisualElement:calculatePosition](#visualelement-calculateposition)|number, number|Calculates the position of the element| |[VisualElement:getAbsolutePosition](#visualelement-getabsoluteposition-x-y)|number, number|Returns the absolute position of the element| @@ -424,7 +424,7 @@ Gets whether this element is focused ## VisualElement:addBorder(colorOrOptions, sideOptions?) -Adds or updates a drawable character border around the element using the canvas plugin. The border will automatically adapt to size/background changes because the command reads current properties each render. +Adds or updates a drawable character border around the element. The border will automatically adapt to size/background changes because the command reads current properties each render. ### Parameters * `colorOrOptions` `any` Border color or options table diff --git a/docs/references/errorManager.md b/docs/references/errorManager.md index dcf14f9..e9c7fb6 100644 --- a/docs/references/errorManager.md +++ b/docs/references/errorManager.md @@ -15,6 +15,6 @@ Handles an error * `errMsg` `string` The error message ### Usage -```lua +```lua run errorHandler.error("An error occurred") ``` diff --git a/docs/references/log.md b/docs/references/log.md index 39c325d..aabde54 100644 --- a/docs/references/log.md +++ b/docs/references/log.md @@ -25,7 +25,7 @@ Sets if the logger should log Sends a debug message to the logger. ### Usage -```lua +```lua run Log.debug("This is a debug message") ``` @@ -34,7 +34,7 @@ Log.debug("This is a debug message") Sends an info message to the logger. ### Usage -```lua +```lua run Log.info("This is an info message") ``` @@ -43,7 +43,7 @@ Log.info("This is an info message") Sends a warning message to the logger. ### Usage -```lua +```lua run Log.warn("This is a warning message") ``` @@ -52,6 +52,6 @@ Log.warn("This is a warning message") Sends an error message to the logger. ### Usage -```lua +```lua run Log.error("This is an error message") ``` diff --git a/docs/references/main.md b/docs/references/main.md index 088f9a6..7bd311b 100644 --- a/docs/references/main.md +++ b/docs/references/main.md @@ -4,6 +4,11 @@ _This is the UI Manager and the starting point for your project. The following f _Before you can access Basalt, you need to add the following code on top of your file:_ _What this code does is it loads basalt into the project, and you can access it by using the variable defined as "basalt"._ +## Usage +```lua run +local basalt = require("basalt") +``` + ## Functions |Method|Returns|Description| @@ -44,7 +49,7 @@ Creates and returns a new UI element of the specified type. * `table` `element` The created element instance ### Usage -```lua +```lua run local button = basalt.create("Button") ``` @@ -172,7 +177,7 @@ Registers a callback function for a specific event * `callback` `function` The callback function to execute when the event occurs ### Usage -```lua +```lua run basalt.onEvent("mouse_click", function(button, x, y) basalt.debug("Clicked at", x, y) end) ``` @@ -195,7 +200,7 @@ Triggers a custom event and calls all registered callbacks * `eventName` `string` The name of the event to trigger ### Usage -```lua +```lua run basalt.triggerEvent("custom_event", "data1", "data2") ``` @@ -208,8 +213,11 @@ Requires specific elements and validates they are available * `autoLoad` *(optional)* `boolean` Whether to automatically load missing elements (default: false) ### Usage -```lua +```lua run basalt.requireElements({"Button", "Label", "Slider"}) +``` + +```lua run basalt.requireElements("Button", true) ``` @@ -224,7 +232,7 @@ Loads a manifest file that describes element requirements and configuration * `table` `manifest` The loaded manifest data ### Usage -```lua +```lua run basalt.loadManifest("myapp.manifest") ``` @@ -237,8 +245,11 @@ Installs an element interactively or from a specified source * `source` *(optional)* `string` Optional source URL or path ### Usage -```lua +```lua run basalt.install("Slider") +``` + +```lua run basalt.install("Slider", "https://example.com/slider.lua") ``` @@ -250,6 +261,6 @@ Configures the ElementManager (shortcut to elementManager.configure) * `config` `table` Configuration options ### Usage -```lua +```lua run basalt.configure({allowRemoteLoading = true, useGlobalCache = true}) ``` diff --git a/docs/references/plugins/animation.md b/docs/references/plugins/animation.md index af3fc19..8b8bcd8 100644 --- a/docs/references/plugins/animation.md +++ b/docs/references/plugins/animation.md @@ -74,7 +74,7 @@ Registers a new animation type * `handlers` `table` Table containing start, update and complete handlers ### Usage -```lua +```lua run Animation.registerAnimation("fade", {start=function(anim) end, update=function(anim,progress) end}) ``` diff --git a/docs/references/plugins/benchmark.md b/docs/references/plugins/benchmark.md index 1a46c5d..2621baf 100644 --- a/docs/references/plugins/benchmark.md +++ b/docs/references/plugins/benchmark.md @@ -42,7 +42,7 @@ Enables benchmarking for a method * `BaseElement` `self` The element instance ### Usage -```lua +```lua run element:benchmark("render") ``` @@ -99,7 +99,7 @@ Enables benchmarking for a container and all its children * `Container` `self` The container instance ### Usage -```lua +```lua run container:benchmarkContainer("render") ``` diff --git a/docs/references/plugins/reactive.md b/docs/references/plugins/reactive.md index ac69a90..523e04e 100644 --- a/docs/references/plugins/reactive.md +++ b/docs/references/plugins/reactive.md @@ -1,3 +1,20 @@ # Reactive _This module provides reactive functionality for elements, it adds no new functionality for elements. _ _It is used to evaluate expressions in property values and update the element when the expression changes._ + +## Usage +```lua run +local button = main:addButton({text="Exit"}) +``` + +```lua run +button:setX("{parent.x - 12}") +``` + +```lua run +button:setBackground("{self.clicked and colors.red or colors.green}") +``` + +```lua run +button:setWidth("{#self.text + 2}") +``` From c9bdfc6a6989d697f3ef120bbd86b21843659382 Mon Sep 17 00:00:00 2001 From: NoryiE Date: Wed, 29 Oct 2025 17:18:10 +0000 Subject: [PATCH 17/17] deploy: 167fc8ef81c993ef24675810fe53f4335399e820 --- docs/references/elementManager.md | 4 +-- docs/references/elements/BarChart.md | 30 +++++++++--------- docs/references/elements/BigFont.md | 34 ++++++++++---------- docs/references/elements/Button.md | 40 +++++++++++------------ docs/references/elements/CheckBox.md | 24 +++++++------- docs/references/elements/Collection.md | 14 ++++----- docs/references/elements/ComboBox.md | 36 ++++++++++----------- docs/references/elements/Display.md | 42 ++++++++++++------------- docs/references/elements/DropDown.md | 2 +- docs/references/elements/FlexBox.md | 14 ++++----- docs/references/elements/Graph.md | 22 ++++++------- docs/references/elements/LineChart.md | 22 ++++++------- docs/references/elements/List.md | 4 +-- docs/references/elements/ProgressBar.md | 6 ++-- docs/references/elements/Slider.md | 2 +- docs/references/elements/Table.md | 10 +++--- docs/references/errorManager.md | 2 +- docs/references/log.md | 8 ++--- docs/references/main.md | 20 ++++++------ docs/references/plugins/animation.md | 2 +- docs/references/plugins/benchmark.md | 4 +-- docs/references/plugins/reactive.md | 8 ++--- 22 files changed, 175 insertions(+), 175 deletions(-) diff --git a/docs/references/elementManager.md b/docs/references/elementManager.md index daccefc..4e0278d 100644 --- a/docs/references/elementManager.md +++ b/docs/references/elementManager.md @@ -60,7 +60,7 @@ Loads an element by name. This will load the element and apply any plugins to it * `name` `string` The name of the element to load ### Usage -```lua run +```lua ElementManager.loadElement("Button") ``` @@ -116,7 +116,7 @@ Checks if an element is loaded Clears the global cache (_G) ### Usage -```lua run +```lua ElementManager.clearGlobalCache() ``` diff --git a/docs/references/elements/BarChart.md b/docs/references/elements/BarChart.md index b7f5813..5982b32 100644 --- a/docs/references/elements/BarChart.md +++ b/docs/references/elements/BarChart.md @@ -4,62 +4,62 @@ _A data visualization element that represents numeric data through vertical bars Extends: `Graph` ## Usage -```lua run +```lua -- Create a bar chart ``` -```lua run +```lua local chart = main:addBarChart() ``` -```lua run +```lua ``` -```lua run +```lua -- Add two data series with different colors ``` -```lua run +```lua chart:addSeries("input", " ", colors.green, colors.green, 5) ``` -```lua run +```lua chart:addSeries("output", " ", colors.red, colors.red, 5) ``` -```lua run +```lua ``` -```lua run +```lua -- Continuously update the chart with random data ``` -```lua run +```lua basalt.schedule(function() ``` -```lua run +```lua while true do ``` -```lua run +```lua chart:addPoint("input", math.random(1,100)) ``` -```lua run +```lua chart:addPoint("output", math.random(1,100)) ``` -```lua run +```lua sleep(2) ``` -```lua run +```lua end ``` -```lua run +```lua end) ``` diff --git a/docs/references/elements/BigFont.md b/docs/references/elements/BigFont.md index 9fa380e..cabdb84 100644 --- a/docs/references/elements/BigFont.md +++ b/docs/references/elements/BigFont.md @@ -4,71 +4,71 @@ _A specialized text element that renders characters in larger sizes using Wojbie Extends: `VisualElement` ## Usage -```lua run +```lua -- Create a large welcome message ``` -```lua run +```lua local main = basalt.getMainFrame() ``` -```lua run +```lua local title = main:addBigFont() ``` -```lua run +```lua :setPosition(3, 3) ``` -```lua run +```lua :setFontSize(2) -- Makes text twice as large ``` -```lua run +```lua :setText("Welcome!") ``` -```lua run +```lua :setForeground(colors.yellow) -- Make text yellow ``` -```lua run +```lua ``` -```lua run +```lua -- For animated text ``` -```lua run +```lua basalt.schedule(function() ``` -```lua run +```lua while true do ``` -```lua run +```lua title:setForeground(colors.yellow) ``` -```lua run +```lua sleep(0.5) ``` -```lua run +```lua title:setForeground(colors.orange) ``` -```lua run +```lua sleep(0.5) ``` -```lua run +```lua end ``` -```lua run +```lua end) ``` diff --git a/docs/references/elements/Button.md b/docs/references/elements/Button.md index a9f9ae4..cd55d48 100644 --- a/docs/references/elements/Button.md +++ b/docs/references/elements/Button.md @@ -4,83 +4,83 @@ _A clickable interface element that triggers actions when pressed. Supports text Extends: `VisualElement` ## Usage -```lua run +```lua -- Create a simple action button ``` -```lua run +```lua local button = parent:addButton() ``` -```lua run +```lua :setPosition(5, 5) ``` -```lua run +```lua :setText("Click me!") ``` -```lua run +```lua :setBackground(colors.blue) ``` -```lua run +```lua :setForeground(colors.white) ``` -```lua run +```lua ``` -```lua run +```lua -- Add click handling ``` -```lua run +```lua button:onClick(function(self, button, x, y) ``` -```lua run +```lua -- Change appearance when clicked ``` -```lua run +```lua self:setBackground(colors.green) ``` -```lua run +```lua self:setText("Success!") ``` -```lua run +```lua ``` -```lua run +```lua -- Revert after delay ``` -```lua run +```lua basalt.schedule(function() ``` -```lua run +```lua sleep(1) ``` -```lua run +```lua self:setBackground(colors.blue) ``` -```lua run +```lua self:setText("Click me!") ``` -```lua run +```lua end) ``` -```lua run +```lua end) ``` diff --git a/docs/references/elements/CheckBox.md b/docs/references/elements/CheckBox.md index bc8c0f3..d5f8d68 100644 --- a/docs/references/elements/CheckBox.md +++ b/docs/references/elements/CheckBox.md @@ -4,51 +4,51 @@ _A toggleable UI element that can be checked or unchecked. Displays different te Extends: `VisualElement` ## Usage -```lua run +```lua -- Create a checkbox for a setting ``` -```lua run +```lua local checkbox = parent:addCheckBox() ``` -```lua run +```lua :setText("Enable Feature") ``` -```lua run +```lua :setCheckedText("✓") ``` -```lua run +```lua :onChange("checked", function(self, checked) ``` -```lua run +```lua -- React to checkbox state changes ``` -```lua run +```lua if checked then ``` -```lua run +```lua -- Handle enabled state ``` -```lua run +```lua else ``` -```lua run +```lua -- Handle disabled state ``` -```lua run +```lua end ``` -```lua run +```lua end) ``` diff --git a/docs/references/elements/Collection.md b/docs/references/elements/Collection.md index ce2a1e3..8294bb2 100644 --- a/docs/references/elements/Collection.md +++ b/docs/references/elements/Collection.md @@ -43,11 +43,11 @@ Adds an item to the Collection * `Collection` `self` The Collection instance ### Usage -```lua run +```lua Collection:addItem("New Item") ``` -```lua run +```lua Collection:addItem({text="Item", callback=function() end}) ``` @@ -62,7 +62,7 @@ Removes an item from the Collection * `Collection` `self` The Collection instance ### Usage -```lua run +```lua Collection:removeItem(1) ``` @@ -74,7 +74,7 @@ Clears all items from the Collection * `Collection` `self` The Collection instance ### Usage -```lua run +```lua Collection:clear() ``` @@ -86,7 +86,7 @@ Gets the currently selected items * `table` `selected` Collection of selected items ### Usage -```lua run +```lua local selected = Collection:getSelectedItems() ``` @@ -105,7 +105,7 @@ Gets the index of the first selected item * `index` `The` index of the first selected item, or nil if none selected ### Usage -```lua run +```lua local index = Collection:getSelectedIndex() ``` @@ -134,6 +134,6 @@ Registers a callback for the select event * `Collection` `self` The Collection instance ### Usage -```lua run +```lua Collection:onSelect(function(index, item) print("Selected item:", index, item) end) ``` diff --git a/docs/references/elements/ComboBox.md b/docs/references/elements/ComboBox.md index 51de986..0e3082e 100644 --- a/docs/references/elements/ComboBox.md +++ b/docs/references/elements/ComboBox.md @@ -5,75 +5,75 @@ _Supports auto-completion, custom styling, and both single and multi-selection m Extends: `DropDown` ## Usage -```lua run +```lua -- Create a searchable country selector ``` -```lua run +```lua local combo = main:addComboBox() ``` -```lua run +```lua :setPosition(5, 5) ``` -```lua run +```lua :setSize(20, 1) -- Height will expand when opened ``` -```lua run +```lua :setItems({ ``` -```lua run +```lua {text = "Germany"}, ``` -```lua run +```lua {text = "France"}, ``` -```lua run +```lua {text = "Spain"}, ``` -```lua run +```lua {text = "Italy"} ``` -```lua run +```lua }) ``` -```lua run +```lua :setPlaceholder("Select country...") ``` -```lua run +```lua :setAutoComplete(true) -- Enable filtering while typing ``` -```lua run +```lua ``` -```lua run +```lua -- Handle selection changes ``` -```lua run +```lua combo:onChange(function(self, value) ``` -```lua run +```lua -- value will be the selected country ``` -```lua run +```lua basalt.debug("Selected:", value) ``` -```lua run +```lua end) ``` diff --git a/docs/references/elements/Display.md b/docs/references/elements/Display.md index 6512603..703e702 100644 --- a/docs/references/elements/Display.md +++ b/docs/references/elements/Display.md @@ -10,87 +10,87 @@ _The Display maintains its own terminal buffer and can be manipulated using fami Extends: `VisualElement` ## Usage -```lua run +```lua -- Create a display for a custom terminal ``` -```lua run +```lua local display = main:addDisplay() ``` -```lua run +```lua :setSize(30, 10) ``` -```lua run +```lua :setPosition(2, 2) ``` -```lua run +```lua ``` -```lua run +```lua -- Get the window object for CC API operations ``` -```lua run +```lua local win = display:getWindow() ``` -```lua run +```lua ``` -```lua run +```lua -- Use standard CC terminal operations ``` -```lua run +```lua win.setTextColor(colors.yellow) ``` -```lua run +```lua win.setBackgroundColor(colors.blue) ``` -```lua run +```lua win.clear() ``` -```lua run +```lua win.setCursorPos(1, 1) ``` -```lua run +```lua win.write("Hello World!") ``` -```lua run +```lua ``` -```lua run +```lua -- Or use the helper method ``` -```lua run +```lua display:write(1, 2, "Direct write", colors.red, colors.black) ``` -```lua run +```lua ``` -```lua run +```lua -- Useful for external APIs ``` -```lua run +```lua local paintutils = require("paintutils") ``` -```lua run +```lua paintutils.drawLine(1, 1, 10, 1, colors.red, win) ``` diff --git a/docs/references/elements/DropDown.md b/docs/references/elements/DropDown.md index 39cabd1..3904ec7 100644 --- a/docs/references/elements/DropDown.md +++ b/docs/references/elements/DropDown.md @@ -3,7 +3,7 @@ _A collapsible selection menu that expands to show multiple options when clicked Extends: `List` -## Usage +## Examples (Executable) ```lua run -- Create a styled dropdown menu local dropdown = main:addDropDown() diff --git a/docs/references/elements/FlexBox.md b/docs/references/elements/FlexBox.md index 5a8094f..6336518 100644 --- a/docs/references/elements/FlexBox.md +++ b/docs/references/elements/FlexBox.md @@ -5,31 +5,31 @@ _The flexbox element adds the following properties to its children:_ Extends: `Container` ## Usage -```lua run +```lua local flex = main:addFlexbox({background=colors.black, width=30, height=10}) ``` -```lua run +```lua flex:addButton():setFlexGrow(1) ``` -```lua run +```lua flex:addButton():setFlexGrow(1) ``` -```lua run +```lua flex:addButton():setFlexGrow(1) ``` -```lua run +```lua flex:addButton():setFlexGrow(1) -- The flex-grow property defines the ability for a flex item to grow if necessary. ``` -```lua run +```lua flex:addButton():setFlexShrink(1) -- The flex-shrink property defines the ability for a flex item to shrink if necessary. ``` -```lua run +```lua flex:addButton():setFlexBasis(1) -- The flex-basis property defines the default size of an element before the remaining space is distributed. ``` diff --git a/docs/references/elements/Graph.md b/docs/references/elements/Graph.md index 7c3cebf..8c0bbdd 100644 --- a/docs/references/elements/Graph.md +++ b/docs/references/elements/Graph.md @@ -4,47 +4,47 @@ _This is the base class for all graph elements. It is a point based graph._ Extends: `VisualElement` ## Usage -```lua run +```lua local graph = main:addGraph() ``` -```lua run +```lua :addSeries("input", " ", colors.green, colors.green, 10) ``` -```lua run +```lua :addSeries("output", " ", colors.red, colors.red, 10) ``` -```lua run +```lua ``` -```lua run +```lua basalt.schedule(function() ``` -```lua run +```lua while true do ``` -```lua run +```lua graph:addPoint("input", math.random(1,100)) ``` -```lua run +```lua graph:addPoint("output", math.random(1,100)) ``` -```lua run +```lua sleep(2) ``` -```lua run +```lua end ``` -```lua run +```lua end) ``` diff --git a/docs/references/elements/LineChart.md b/docs/references/elements/LineChart.md index 3e50bda..42096f4 100644 --- a/docs/references/elements/LineChart.md +++ b/docs/references/elements/LineChart.md @@ -4,46 +4,46 @@ _The Line Chart element visualizes data series as connected line graphs. It plot Extends: `Graph` ## Usage -```lua run +```lua local chart = main:addLineChart() ``` -```lua run +```lua :addSeries("input", " ", colors.green, colors.green, 10) ``` -```lua run +```lua :addSeries("output", " ", colors.red, colors.red, 10) ``` -```lua run +```lua ``` -```lua run +```lua basalt.schedule(function() ``` -```lua run +```lua while true do ``` -```lua run +```lua chart:addPoint("input", math.random(1,100)) ``` -```lua run +```lua chart:addPoint("output", math.random(1,100)) ``` -```lua run +```lua sleep(2) ``` -```lua run +```lua end ``` -```lua run +```lua end) ``` diff --git a/docs/references/elements/List.md b/docs/references/elements/List.md index 40f83be..ab560a7 100644 --- a/docs/references/elements/List.md +++ b/docs/references/elements/List.md @@ -42,7 +42,7 @@ Registers a callback for the select event * `List` `self` The List instance ### Usage -```lua run +```lua list:onSelect(function(index, item) print("Selected item:", index, item) end) ``` @@ -71,6 +71,6 @@ Scrolls to make a specific item visible * `List` `self` The List instance ### Usage -```lua run +```lua list:scrollToItem(5) ``` diff --git a/docs/references/elements/ProgressBar.md b/docs/references/elements/ProgressBar.md index ac7e1d7..9983f1f 100644 --- a/docs/references/elements/ProgressBar.md +++ b/docs/references/elements/ProgressBar.md @@ -5,15 +5,15 @@ _with optional percentage display and customizable colors._ Extends: `VisualElement` ## Usage -```lua run +```lua local progressBar = main:addProgressBar() ``` -```lua run +```lua progressBar:setDirection("up") ``` -```lua run +```lua progressBar:setProgress(50) ``` diff --git a/docs/references/elements/Slider.md b/docs/references/elements/Slider.md index c45e5b0..e3bb015 100644 --- a/docs/references/elements/Slider.md +++ b/docs/references/elements/Slider.md @@ -34,6 +34,6 @@ Gets the current value of the slider * `number` `value` The current value (0 to max) ### Usage -```lua run +```lua local value = slider:getValue() ``` diff --git a/docs/references/elements/Table.md b/docs/references/elements/Table.md index 5a4388b..297970f 100644 --- a/docs/references/elements/Table.md +++ b/docs/references/elements/Table.md @@ -4,15 +4,15 @@ _This is the table class. It provides a sortable data grid with customizable col Extends: `Collection` ## Usage -```lua run +```lua local people = container:addTable():setWidth(40) ``` -```lua run +```lua people:setColumns({{name="Name",width=12}, {name="Age",width=10}, {name="Country",width=15}}) ``` -```lua run +```lua people:addRow("Alice", 30, "USA"):addRow("Bob", 25, "UK") ``` @@ -66,7 +66,7 @@ Adds a new row to the table * `Table` `self` The Table instance ### Usage -```lua run +```lua table:addRow("Alice", 30, "USA") ``` @@ -150,7 +150,7 @@ Set data with automatic formatting * `Table` `self` The Table instance ### Usage -```lua run +```lua table:setData({{...}}, {[1] = tostring, [2] = function(age) return age.."y" end}) ``` diff --git a/docs/references/errorManager.md b/docs/references/errorManager.md index e9c7fb6..dcf14f9 100644 --- a/docs/references/errorManager.md +++ b/docs/references/errorManager.md @@ -15,6 +15,6 @@ Handles an error * `errMsg` `string` The error message ### Usage -```lua run +```lua errorHandler.error("An error occurred") ``` diff --git a/docs/references/log.md b/docs/references/log.md index aabde54..39c325d 100644 --- a/docs/references/log.md +++ b/docs/references/log.md @@ -25,7 +25,7 @@ Sets if the logger should log Sends a debug message to the logger. ### Usage -```lua run +```lua Log.debug("This is a debug message") ``` @@ -34,7 +34,7 @@ Log.debug("This is a debug message") Sends an info message to the logger. ### Usage -```lua run +```lua Log.info("This is an info message") ``` @@ -43,7 +43,7 @@ Log.info("This is an info message") Sends a warning message to the logger. ### Usage -```lua run +```lua Log.warn("This is a warning message") ``` @@ -52,6 +52,6 @@ Log.warn("This is a warning message") Sends an error message to the logger. ### Usage -```lua run +```lua Log.error("This is an error message") ``` diff --git a/docs/references/main.md b/docs/references/main.md index 7bd311b..e2f7ef5 100644 --- a/docs/references/main.md +++ b/docs/references/main.md @@ -5,7 +5,7 @@ _Before you can access Basalt, you need to add the following code on top of your _What this code does is it loads basalt into the project, and you can access it by using the variable defined as "basalt"._ ## Usage -```lua run +```lua local basalt = require("basalt") ``` @@ -49,7 +49,7 @@ Creates and returns a new UI element of the specified type. * `table` `element` The created element instance ### Usage -```lua run +```lua local button = basalt.create("Button") ``` @@ -177,7 +177,7 @@ Registers a callback function for a specific event * `callback` `function` The callback function to execute when the event occurs ### Usage -```lua run +```lua basalt.onEvent("mouse_click", function(button, x, y) basalt.debug("Clicked at", x, y) end) ``` @@ -200,7 +200,7 @@ Triggers a custom event and calls all registered callbacks * `eventName` `string` The name of the event to trigger ### Usage -```lua run +```lua basalt.triggerEvent("custom_event", "data1", "data2") ``` @@ -213,11 +213,11 @@ Requires specific elements and validates they are available * `autoLoad` *(optional)* `boolean` Whether to automatically load missing elements (default: false) ### Usage -```lua run +```lua basalt.requireElements({"Button", "Label", "Slider"}) ``` -```lua run +```lua basalt.requireElements("Button", true) ``` @@ -232,7 +232,7 @@ Loads a manifest file that describes element requirements and configuration * `table` `manifest` The loaded manifest data ### Usage -```lua run +```lua basalt.loadManifest("myapp.manifest") ``` @@ -245,11 +245,11 @@ Installs an element interactively or from a specified source * `source` *(optional)* `string` Optional source URL or path ### Usage -```lua run +```lua basalt.install("Slider") ``` -```lua run +```lua basalt.install("Slider", "https://example.com/slider.lua") ``` @@ -261,6 +261,6 @@ Configures the ElementManager (shortcut to elementManager.configure) * `config` `table` Configuration options ### Usage -```lua run +```lua basalt.configure({allowRemoteLoading = true, useGlobalCache = true}) ``` diff --git a/docs/references/plugins/animation.md b/docs/references/plugins/animation.md index 8b8bcd8..af3fc19 100644 --- a/docs/references/plugins/animation.md +++ b/docs/references/plugins/animation.md @@ -74,7 +74,7 @@ Registers a new animation type * `handlers` `table` Table containing start, update and complete handlers ### Usage -```lua run +```lua Animation.registerAnimation("fade", {start=function(anim) end, update=function(anim,progress) end}) ``` diff --git a/docs/references/plugins/benchmark.md b/docs/references/plugins/benchmark.md index 2621baf..1a46c5d 100644 --- a/docs/references/plugins/benchmark.md +++ b/docs/references/plugins/benchmark.md @@ -42,7 +42,7 @@ Enables benchmarking for a method * `BaseElement` `self` The element instance ### Usage -```lua run +```lua element:benchmark("render") ``` @@ -99,7 +99,7 @@ Enables benchmarking for a container and all its children * `Container` `self` The container instance ### Usage -```lua run +```lua container:benchmarkContainer("render") ``` diff --git a/docs/references/plugins/reactive.md b/docs/references/plugins/reactive.md index 523e04e..3116657 100644 --- a/docs/references/plugins/reactive.md +++ b/docs/references/plugins/reactive.md @@ -3,18 +3,18 @@ _This module provides reactive functionality for elements, it adds no new functi _It is used to evaluate expressions in property values and update the element when the expression changes._ ## Usage -```lua run +```lua local button = main:addButton({text="Exit"}) ``` -```lua run +```lua button:setX("{parent.x - 12}") ``` -```lua run +```lua button:setBackground("{self.clicked and colors.red or colors.green}") ``` -```lua run +```lua button:setWidth("{#self.text + 2}") ```