diff --git a/docs/references/elementManager.md b/docs/references/elementManager.md index 2df46b6..9f02420 100644 --- a/docs/references/elementManager.md +++ b/docs/references/elementManager.md @@ -1,8 +1,49 @@ -## ElementManager.getAPI() +# ElementManager +This class manages elements and plugins. It loads elements and plugins from the elements and plugins directories +and then applies the plugins to the elements. It also provides a way to get elements and APIs. -## ElementManager.getElement() +## Functions + +|Method|Returns|Description| +|---|---|---| +|[ElementManager.getAPI](#ElementManager.getAPI)|table| +|[ElementManager.getElement](#ElementManager.getElement)|table| +|[ElementManager.getElementList](#ElementManager.getElementList)|table| +|[ElementManager.loadElement](#ElementManager.loadElement)|-| + +## ElementManager.getAPI(name) +Gets an Plugin API by name + +### Parameters +* `name` `string` The name of the API to get + +### Returns +* `table` `API` The API + +## ElementManager.getElement(name) +Gets an element by name. If the element is not loaded, it will try to load it first. + +### Parameters +* `name` `string` The name of the element to get + +### Returns +* `table` `Element` The element class ## ElementManager.getElementList() +Gets a list of all elements + +### Returns +* `table` `ElementList` A list of all elements + +## ElementManager.loadElement(name) +Loads an element by name. This will load the element and apply any plugins to it. + +### Parameters +* `name` `string` The name of the element to load + +### Usage + ```lua +ElementManager.loadElement("Button") +``` -## ElementManager.loadElement() diff --git a/docs/references/elements/BaseElement.md b/docs/references/elements/BaseElement.md index fea0b07..cc1119b 100644 --- a/docs/references/elements/BaseElement.md +++ b/docs/references/elements/BaseElement.md @@ -14,19 +14,19 @@ The base class for all UI elements in Basalt |Method|Returns|Description| |---|---|---| -|[BaseElement.listenTo](#BaseElement.listenTo)|-| -|[BaseElement.new](#BaseElement.new)|table| -|[BaseElement:destroy](#BaseElement:destroy)|-| -|[BaseElement:dispatchEvent](#BaseElement:dispatchEvent)|boolean?| -|[BaseElement:fireEvent](#BaseElement:fireEvent)|table| -|[BaseElement:getBaseFrame](#BaseElement:getBaseFrame)|table| -|[BaseElement:handleEvent](#BaseElement:handleEvent)|boolean?| -|[BaseElement:init](#BaseElement:init)|table| -|[BaseElement:isType](#BaseElement:isType)|boolean| -|[BaseElement:listenEvent](#BaseElement:listenEvent)|table| -|[BaseElement:postInit](#BaseElement:postInit)|table| -|[BaseElement:registerCallback](#BaseElement:registerCallback)|table| -|[BaseElement:updateRender](#BaseElement:updateRender)|-| +|[BaseElement.listenTo](#BaseElement.listenTo)|-|Registers an event that this class can listen to +|[BaseElement.new](#BaseElement.new)|table|Creates a new BaseElement instance +|[BaseElement:destroy](#BaseElement:destroy)|-|Destroys the element and cleans up all references +|[BaseElement:dispatchEvent](#BaseElement:dispatchEvent)|boolean?|Handles all events +|[BaseElement:fireEvent](#BaseElement:fireEvent)|table|Triggers an event and calls all registered callbacks +|[BaseElement:getBaseFrame](#BaseElement:getBaseFrame)|table|Returns the base frame of the element +|[BaseElement:handleEvent](#BaseElement:handleEvent)|boolean?|The default event handler for all events +|[BaseElement:init](#BaseElement:init)|table|Initializes the BaseElement instance +|[BaseElement:isType](#BaseElement:isType)|boolean|Checks if the element is a specific type +|[BaseElement:listenEvent](#BaseElement:listenEvent)|table|Enables or disables event listening for a specific event +|[BaseElement:postInit](#BaseElement:postInit)|table|Post initialization +|[BaseElement:registerCallback](#BaseElement:registerCallback)|table|Registers a callback function +|[BaseElement:updateRender](#BaseElement:updateRender)|-|Requests a render update for this element ## BaseElement.listenTo(class, eventName) Registers an event that this class can listen to @@ -52,7 +52,7 @@ Creates a new BaseElement instance ### Usage ```lua -local element = BaseElement.new("myId", basalt) +local element = BaseElement.new() ``` ## BaseElement:destroy() @@ -167,3 +167,4 @@ Requests a render update for this element element:updateRender() ``` + diff --git a/docs/references/elements/BaseFrame.md b/docs/references/elements/BaseFrame.md index 77b932a..4fcbda5 100644 --- a/docs/references/elements/BaseFrame.md +++ b/docs/references/elements/BaseFrame.md @@ -1,37 +1,102 @@ # BaseFrame : Container +This is the base frame class. It is the root element of all elements and the only element without a parent. + +## Fields + +|Field|Type|Description| +|---|---|---| +|_render|`Render`|The render object| +|_renderUpdate|`boolean`|Whether the render object needs to be updated| ## Properties |Property|Type|Default|Description| |---|---|---|---| -|text|term|term|nil text +|text|term|nil|The terminal object to render to ## Functions |Method|Returns|Description| |---|---|---| -|[BaseFrame.new](#BaseFrame.new)|-| -|[BaseFrame:blit](#BaseFrame:blit)|-| -|[BaseFrame:init](#BaseFrame:init)|-| -|[BaseFrame:multiBlit](#BaseFrame:multiBlit)|-| -|[BaseFrame:render](#BaseFrame:render)|-| -|[BaseFrame:setCursor](#BaseFrame:setCursor)|-| -|[BaseFrame:textBg](#BaseFrame:textBg)|-| -|[BaseFrame:textFg](#BaseFrame:textFg)|-| +|[BaseFrame.new](#BaseFrame.new)|BaseFrame|Creates a new Frame instance +|[BaseFrame:blit](#BaseFrame:blit)|-|Renders a text with a foreground and background color to the render Object +|[BaseFrame:init](#BaseFrame:init)|table|Initializes the Frame instance +|[BaseFrame:multiBlit](#BaseFrame:multiBlit)|-|Renders a multiBlit to the render Object +|[BaseFrame:render](#BaseFrame:render)|-|Renders the Frame +|[BaseFrame:setCursor](#BaseFrame:setCursor)|-|Sets the cursor position +|[BaseFrame:textBg](#BaseFrame:textBg)|-|Renders a text with a background color to the render Object +|[BaseFrame:textFg](#BaseFrame:textFg)|-|Renders a text with a foreground color to the render Object ## BaseFrame.new() +Creates a new Frame instance -## BaseFrame:blit() +### Returns +* `BaseFrame` `object` The newly created Frame instance -## BaseFrame:init() +### Usage + ```lua +local element = BaseFrame.new() +``` -## BaseFrame:multiBlit() +## BaseFrame:blit(x, y, text, fg, bg) +Renders a text with a foreground and background color to the render Object + +### Parameters +* `x` `number` The x position to render to +* `y` `number` The y position to render to +* `text` `string` The text to render +* `fg` `string` The foreground color +* `bg` `string` The background color + +## BaseFrame:init(props, basalt) +Initializes the Frame instance + +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + +### Returns +* `table` `self` The initialized instance + +## BaseFrame:multiBlit(x, y, width, height, text, fg, bg) +Renders a multiBlit to the render Object + +### Parameters +* `x` `number` The x position to render to +* `y` `number` The y position to render to +* `width` `number` The width of the text +* `height` `number` The height of the text +* `text` `string` The text to render +* `fg` `string` The foreground color +* `bg` `string` The background color ## BaseFrame:render() +Renders the Frame -## BaseFrame:setCursor() +## BaseFrame:setCursor(x, y, blink) +Sets the cursor position -## BaseFrame:textBg() +### Parameters +* `x` `number` The x position to set the cursor to +* `y` `number` The y position to set the cursor to +* `blink` `boolean` Whether the cursor should blink + +## BaseFrame:textBg(x, y, text, bg) +Renders a text with a background color to the render Object + +### Parameters +* `x` `number` The x position to render to +* `y` `number` The y position to render to +* `text` `string` The text to render +* `bg` `colors` The background color + +## BaseFrame:textFg(x, y, text, fg) +Renders a text with a foreground color to the render Object + +### Parameters +* `x` `number` The x position to render to +* `y` `number` The y position to render to +* `text` `string` The text to render +* `fg` `colors` The foreground color -## BaseFrame:textFg() diff --git a/docs/references/elements/Button.md b/docs/references/elements/Button.md index 77621d1..206816c 100644 --- a/docs/references/elements/Button.md +++ b/docs/references/elements/Button.md @@ -1,4 +1,5 @@ # Button : VisualElement +This is the button class. It is a visual element that can be clicked. ## Properties @@ -15,9 +16,9 @@ |Method|Returns|Description| |---|---|---| -|[Button.new](#Button.new)|table| -|[Button:init](#Button:init)|-| -|[Button:render](#Button:render)|-| +|[Button.new](#Button.new)|table|Creates a new Button instance +|[Button:init](#Button:init)|-|Initializes the Button instance +|[Button:render](#Button:render)|-|Renders the Button ## Button.new() Creates a new Button instance @@ -35,3 +36,4 @@ Initializes the Button instance ## Button:render() Renders the Button + diff --git a/docs/references/elements/Checkbox.md b/docs/references/elements/Checkbox.md index 65cffd9..b8b57c2 100644 --- a/docs/references/elements/Checkbox.md +++ b/docs/references/elements/Checkbox.md @@ -1,4 +1,5 @@ # Checkbox : VisualElement +This is the checkbox class. It is a visual element that can be checked. ## Properties @@ -12,10 +13,10 @@ |Method|Returns|Description| |---|---|---| -|[Checkbox.new](#Checkbox.new)|Checkbox| -|[Checkbox:init](#Checkbox:init)|-| -|[Checkbox:mouse_click](#Checkbox:mouse_click)|boolean| -|[Checkbox:render](#Checkbox:render)|-| +|[Checkbox.new](#Checkbox.new)|Checkbox|Creates a new Checkbox instance +|[Checkbox:init](#Checkbox:init)|-|Initializes the Checkbox instance +|[Checkbox:mouse_click](#Checkbox:mouse_click)|boolean|Handles mouse click events +|[Checkbox:render](#Checkbox:render)|-|Renders the Checkbox ## Checkbox.new() Creates a new Checkbox instance @@ -39,8 +40,9 @@ Handles mouse click events * `y` `number` The y position of the click ### Returns -* `boolean` `Whether` the event was handled +* `boolean` `Clicked` Whether the event was handled ## Checkbox:render() Renders the Checkbox + diff --git a/docs/references/elements/Container.md b/docs/references/elements/Container.md index 9409675..2bf50de 100644 --- a/docs/references/elements/Container.md +++ b/docs/references/elements/Container.md @@ -1,4 +1,6 @@ # Container : VisualElement +The container class. It is a visual element that can contain other elements. It is the base class for all containers, +like Frames, BaseFrames, and more. ## Properties @@ -17,30 +19,30 @@ |Method|Returns|Description| |---|---|---| -|[Container.new](#Container.new)|Container| -|[Container:addChild](#Container:addChild)|Container| -|[Container:blit](#Container:blit)|Container| -|[Container:char](#Container:char)|boolean| -|[Container:clear](#Container:clear)|Container| -|[Container:destroy](#Container:destroy)|-| -|[Container:getChild](#Container:getChild)|Container?| -|[Container:handleEvent](#Container:handleEvent)|boolean| -|[Container:init](#Container:init)|-| -|[Container:isChildVisible](#Container:isChildVisible)|boolean| -|[Container:key](#Container:key)|boolean| -|[Container:key_up](#Container:key_up)|boolean| -|[Container:mouse_click](#Container:mouse_click)|boolean| -|[Container:mouse_up](#Container:mouse_up)|boolean| -|[Container:multiBlit](#Container:multiBlit)|Container| -|[Container:registerChildEvent](#Container:registerChildEvent)|Container| -|[Container:registerChildrenEvents](#Container:registerChildrenEvents)|Container| -|[Container:removeChild](#Container:removeChild)|Container| -|[Container:removeChildrenEvents](#Container:removeChildrenEvents)|Container| -|[Container:render](#Container:render)|-| -|[Container:sortChildren](#Container:sortChildren)|Container| -|[Container:sortChildrenEvents](#Container:sortChildrenEvents)|Container| -|[Container:textFg](#Container:textFg)|Container| -|[Container:unregisterChildEvent](#Container:unregisterChildEvent)|Container| +|[Container.new](#Container.new)|Container|Creates a new Container instance +|[Container:addChild](#Container:addChild)|Container|Adds a child to the container +|[Container:blit](#Container:blit)|Container|Draws a line of text and fg and bg as colors +|[Container:char](#Container:char)|boolean|Handles char events +|[Container:clear](#Container:clear)|Container|Clears the container +|[Container:destroy](#Container:destroy)|Container|Destroys the container and its children +|[Container:getChild](#Container:getChild)|Container?|Removes a child from the container +|[Container:handleEvent](#Container:handleEvent)|boolean|Default handler for events +|[Container:init](#Container:init)|-|Initializes the Container instance +|[Container:isChildVisible](#Container:isChildVisible)|boolean|Returns whether a child is visible +|[Container:key](#Container:key)|boolean|Handles key events +|[Container:key_up](#Container:key_up)|boolean|Handles key up events +|[Container:mouse_click](#Container:mouse_click)|boolean|Handles mouse click events +|[Container:mouse_up](#Container:mouse_up)|boolean|Handles mouse up events +|[Container:multiBlit](#Container:multiBlit)|Container|Draws multiple lines of text, fg and bg strings +|[Container:registerChildEvent](#Container:registerChildEvent)|Container|Registers the children events of the container +|[Container:registerChildrenEvents](#Container:registerChildrenEvents)|Container|Registers the children events of the container +|[Container:removeChild](#Container:removeChild)|Container|Removes a child from the container +|[Container:removeChildrenEvents](#Container:removeChildrenEvents)|Container|Unregisters the children events of the container +|[Container:render](#Container:render)|-|Renders the container +|[Container:sortChildren](#Container:sortChildren)|Container|Sorts the children of the container +|[Container:sortChildrenEvents](#Container:sortChildrenEvents)|Container|Sorts the children events of the container +|[Container:textFg](#Container:textFg)|Container|Draws a line of text and fg as color +|[Container:unregisterChildEvent](#Container:unregisterChildEvent)|Container|Unregisters the children events of the container ## Container.new() Creates a new Container instance @@ -77,7 +79,7 @@ Handles char events * `char` `string` The character that was pressed ### Returns -* `boolean` `Whether` the event was handled +* `boolean` `handled` Whether the event was handled ## Container:clear() Clears the container @@ -86,6 +88,10 @@ Clears the container * `Container` `self` The container instance ## Container:destroy() +Destroys the container and its children + +### Returns +* `Container` `self` The container instance ## Container:getChild(path) Removes a child from the container @@ -104,7 +110,7 @@ Default handler for events * `...` *(vararg)* `any` The event arguments ### Returns -* `boolean` `Whether` the event was handled +* `boolean` `handled` Whether the event was handled ## Container:init(props, basalt) Initializes the Container instance @@ -129,7 +135,7 @@ Handles key events * `key` `number` The key that was pressed ### Returns -* `boolean` `Whether` the event was handled +* `boolean` `handled` Whether the event was handled ## Container:key_up(key) Handles key up events @@ -138,7 +144,7 @@ Handles key up events * `key` `number` The key that was released ### Returns -* `boolean` `Whether` the event was handled +* `boolean` `handled` Whether the event was handled ## Container:mouse_click(button, x, y) Handles mouse click events @@ -149,7 +155,7 @@ Handles mouse click events * `y` `number` The y position of the click ### Returns -* `boolean` `Whether` the event was handled +* `boolean` `handled` Whether the event was handled ## Container:mouse_up(button, x, y) Handles mouse up events @@ -160,7 +166,7 @@ Handles mouse up events * `y` `number` The y position of the click ### Returns -* `boolean` `Whether` the event was handled +* `boolean` `handled` Whether the event was handled ## Container:multiBlit(x, y, width, height, text, fg, bg) Draws multiple lines of text, fg and bg strings, it is usually used in the render loop @@ -254,3 +260,4 @@ Unregisters the children events of the container ### Returns * `Container` `self` The container instance + diff --git a/docs/references/elements/Dropdown.md b/docs/references/elements/Dropdown.md index d47b3b0..e5ef42c 100644 --- a/docs/references/elements/Dropdown.md +++ b/docs/references/elements/Dropdown.md @@ -1,19 +1,57 @@ # Dropdown : List +This is the dropdown class. It is a visual element that can show a list of selectable items in a dropdown menu. + +## Properties + +|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 ## Functions |Method|Returns|Description| |---|---|---| -|[Dropdown.new](#Dropdown.new)|-| -|[Dropdown:init](#Dropdown:init)|-| -|[Dropdown:mouse_click](#Dropdown:mouse_click)|-| -|[Dropdown:render](#Dropdown:render)|-| +|[Dropdown.new](#Dropdown.new)|Dropdown|Creates a new Dropdown instance +|[Dropdown:init](#Dropdown:init)|Dropdown|Initializes the Dropdown instance +|[Dropdown:mouse_click](#Dropdown:mouse_click)|boolean|Handles mouse click events +|[Dropdown:render](#Dropdown:render)|-|Renders the Dropdown ## Dropdown.new() +Creates a new Dropdown instance -## Dropdown:init() +### Returns +* `Dropdown` `self` The newly created Dropdown instance -## Dropdown:mouse_click() +### Usage + ```lua +local dropdown = Dropdown.new() +``` + +## Dropdown:init(props, basalt) +Initializes the Dropdown instance + +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + +### Returns +* `Dropdown` `self` The initialized instance + +## Dropdown:mouse_click(button, x, y) +Handles mouse click events + +### Parameters +* `button` `number` The button that was clicked +* `x` `number` The x position of the click +* `y` `number` The y position of the click + +### Returns +* `boolean` `handled` Whether the event was handled ## Dropdown:render() +Renders the Dropdown + diff --git a/docs/references/elements/Flexbox.md b/docs/references/elements/Flexbox.md index 57681b9..0e7be8a 100644 --- a/docs/references/elements/Flexbox.md +++ b/docs/references/elements/Flexbox.md @@ -39,3 +39,4 @@ Adds a new line break to the flexbox. ## Flexbox:render() + diff --git a/docs/references/elements/Frame.md b/docs/references/elements/Frame.md index a16627f..6b3387f 100644 --- a/docs/references/elements/Frame.md +++ b/docs/references/elements/Frame.md @@ -1,23 +1,38 @@ # Frame : Container +This is the frame class. It serves as a grouping container for other elements. + +## Events + +|Event|Parameters|Description| +|---|---|---| +|onResize|`width number, height number`|Fired when the frame is resized| ## Functions |Method|Returns|Description| |---|---|---| -|[Frame.new](#Frame.new)|Frame| -|[Frame:init](#Frame:init)|-| +|[Frame.new](#Frame.new)|Frame|Creates a new Frame instance +|[Frame:init](#Frame:init)|Frame|Initializes the Frame instance ## Frame.new() Creates a new Frame instance ### Returns -* `Frame` `object` The newly created Frame instance +* `Frame` `self` The newly created Frame instance ### Usage ```lua -local element = Frame.new("myId", basalt) +local frame = Frame.new() ``` -## Frame:init() +## Frame:init(props, basalt) Initializes the Frame instance +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + +### Returns +* `Frame` `self` The initialized instance + + diff --git a/docs/references/elements/Input.md b/docs/references/elements/Input.md index 09adb2e..d3c2fa6 100644 --- a/docs/references/elements/Input.md +++ b/docs/references/elements/Input.md @@ -1,28 +1,34 @@ # Input : VisualElement +This is the input class. It provides a text input field that can handle user input with various features like +cursor movement, text manipulation, placeholder text, and input validation. ## Properties |Property|Type|Default|Description| |---|---|---|---| -|text|string|Input|- text to be displayed -|cursorPos|number|Input|- current cursor position -|viewOffset|number|Input|- offset of view +|text|string|-|The current text content of the input +|cursorPos|number|1|The current cursor position in the text +|viewOffset|number|0|The horizontal scroll offset for viewing long text +|maxLength|number?|nil|Maximum length of input text (optional) +|placeholder|string|...|Text to display when input is empty +|placeholderColor|color|gray|Color of the placeholder text +|focusedColor|color|blue|Background color when input is focused +|pattern|string?|nil|Regular expression pattern for input validation ## Functions |Method|Returns|Description| |---|---|---| -|[Input.new](#Input.new)|Input| -|[Input:blur](#Input:blur)|-| -|[Input:char](#Input:char)|-| -|[Input:focus](#Input:focus)|-| -|[Input:init](#Input:init)|-| -|[Input:key](#Input:key)|-| -|[Input:mouse_click](#Input:mouse_click)|-| -|[Input:render](#Input:render)|-| -|[Input:updateViewport](#Input:updateViewport)|-| +|[Input.new](#Input.new)|Input|Creates a new Input instance +|[Input:blur](#Input:blur)|-|Handles blur events +|[Input:char](#Input:char)|boolean|Handles char events +|[Input:focus](#Input:focus)|-|Handles focus events +|[Input:init](#Input:init)|Input|Initializes the Input instance +|[Input:key](#Input:key)|boolean|Handles key events +|[Input:mouse_click](#Input:mouse_click)|boolean|Handles mouse click events +|[Input:render](#Input:render)|-|Renders the input element +|[Input:updateViewport](#Input:updateViewport)|-|Updates the input's viewport -Neue Properties ## Input.new() Creates a new Input instance @@ -35,18 +41,54 @@ local element = Input.new("myId", basalt) ``` ## Input:blur() +Handles blur events -## Input:char() +## Input:char(char) +Handles char events + +### Parameters +* `char` `string` The character that was typed + +### Returns +* `boolean` `handled` Whether the event was handled ## Input:focus() +Handles focus events -## Input:init() +## Input:init(props, basalt) +Initializes the Input instance -## Input:key() +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance -## Input:mouse_click() +### Returns +* `Input` `self` The initialized instance + +## Input:key(key) +Handles key events + +### Parameters +* `key` `number` The key that was pressed + +### Returns +* `boolean` `handled` Whether the event was handled + +## Input:mouse_click(button, x, y) +Handles mouse click events + +### Parameters +* `button` `number` The button that was clicked +* `x` `number` The x position of the click +* `y` `number` The y position of the click + +### Returns +* `boolean` `handled` Whether the event was handled ## Input:render() +Renders the input element ## Input:updateViewport() +Updates the input's viewport + diff --git a/docs/references/elements/Label.md b/docs/references/elements/Label.md index 73346f1..5fdb788 100644 --- a/docs/references/elements/Label.md +++ b/docs/references/elements/Label.md @@ -1,31 +1,43 @@ # Label : VisualElement +This is the label class. It provides a simple text display element that automatically +resizes its width based on the text content. ## Properties |Property|Type|Default|Description| |---|---|---|---| -|text|string|Label|Label text to be displayed +|text|string|Label|The text content to display. Can be a string or a function that returns a string ## Functions |Method|Returns|Description| |---|---|---| -|[Label.new](#Label.new)|Label| -|[Label:init](#Label:init)|-| -|[Label:render](#Label:render)|-| +|[Label.new](#Label.new)|Label|Creates a new Label instance +|[Label:init](#Label:init)|Label|Initializes the Label instance +|[Label:render](#Label:render)|-|Renders the Label by drawing its text content ## Label.new() Creates a new Label instance ### Returns -* `Label` `object` The newly created Label instance +* `Label` `self` The newly created Label instance ### Usage ```lua -local element = Label.new("myId", basalt) +local label = Label.new() ``` -## Label:init() +## Label:init(props, basalt) +Initializes the Label instance + +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + +### Returns +* `Label` `self` The initialized instance ## Label:render() +Renders the Label + diff --git a/docs/references/elements/List.md b/docs/references/elements/List.md index c7ece50..dd26506 100644 --- a/docs/references/elements/List.md +++ b/docs/references/elements/List.md @@ -1,44 +1,135 @@ # List : VisualElement +This is the list class. It provides a scrollable list of selectable items with support for +custom item rendering, separators, and selection handling. ## Properties |Property|Type|Default|Description| |---|---|---|---| -|items|table|List|of items to display -|selectedIndex|number|Currently|selected item index -|selectable|boolean|Whether|items can be selected -|offset|number|Scrolling|offset -|selectedColor|color|Color|for selected item +|items|table|{}|List of items to display. Items can be strings or tables with properties +|selectedIndex|number|0|Index of the currently selected item (0 means no selection) +|selectable|boolean|true|Whether items in the list can be selected +|offset|number|0|Current scroll offset for viewing long lists +|selectedColor|color|blue|Background color for the selected item + +## Events + +|Event|Parameters|Description| +|---|---|---| +|onSelect|`index number, item any`|Fired when an item is selected| ## Functions |Method|Returns|Description| |---|---|---| -|[List.new](#List.new)|-| -|[List:addItem](#List:addItem)|-| -|[List:clear](#List:clear)|-| -|[List:init](#List:init)|-| -|[List:mouse_click](#List:mouse_click)|-| -|[List:mouse_scroll](#List:mouse_scroll)|-| -|[List:onSelect](#List:onSelect)|-| -|[List:removeItem](#List:removeItem)|-| -|[List:render](#List:render)|-| +|[List.new](#List.new)|List|Creates a new List instance +|[List:addItem](#List:addItem)|List|Adds an item to the list +|[List:clear](#List:clear)|List|Clears all items from the list +|[List:init](#List:init)|List|Initializes the List instance +|[List:mouse_click](#List:mouse_click)|boolean|Handles mouse click events +|[List:mouse_scroll](#List:mouse_scroll)|boolean|Handles mouse scroll events +|[List:onSelect](#List:onSelect)|List|Registers a callback for the select event +|[List:removeItem](#List:removeItem)|List|Removes an item from the list +|[List:render](#List:render)|-|Renders the list ## List.new() +Creates a new List instance -## List:addItem() +### Returns +* `List` `self` The newly created List instance + +### Usage + ```lua +local list = List.new() +``` + +## 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:clear() +Clears all items from the list -## List:init() +### Returns +* `List` `self` The List instance -## List:mouse_click() +### Usage + ```lua +list:clear() +``` -## List:mouse_scroll() +## List:init(props, basalt) +Initializes the List instance -## List:onSelect() +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance -## List:removeItem() +### Returns +* `List` `self` The initialized instance + +## List:mouse_click(button, x, y) +Handles mouse click events + +### Parameters +* `button` `number` The mouse button that was clicked +* `x` `number` The x-coordinate of the click +* `y` `number` The y-coordinate of the click + +### Returns +* `boolean` `Whether` the event was handled + +## List:mouse_scroll(direction, x, y) +Handles mouse scroll events + +### Parameters +* `direction` `number` The direction of the scroll (1 for down, -1 for up) +* `x` `number` The x-coordinate of the scroll +* `y` `number` The y-coordinate of the scroll + +### Returns +* `boolean` `Whether` the event was handled + +## List:onSelect(callback) +Registers a callback for the select event + +### Parameters +* `callback` `function` The callback function to register + +### Returns +* `List` `self` The List instance + +### Usage + ```lua +list:onSelect(function(index, item) print("Selected item:", index, item) 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:render() +Renders the list + diff --git a/docs/references/elements/Menu.md b/docs/references/elements/Menu.md index 528ca19..8f2249d 100644 --- a/docs/references/elements/Menu.md +++ b/docs/references/elements/Menu.md @@ -1,22 +1,70 @@ # Menu : List +This is the menu class. It provides a horizontal menu bar with selectable items and separators. +Menu items are displayed in a single row and can have custom colors and callbacks. + +## Properties + +|Property|Type|Default|Description| +|---|---|---|---| +|separatorColor|color|gray|The color used for separator items in the menu ## Functions |Method|Returns|Description| |---|---|---| -|[Menu.new](#Menu.new)|-| -|[Menu:init](#Menu:init)|-| -|[Menu:mouse_click](#Menu:mouse_click)|-| -|[Menu:render](#Menu:render)|-| -|[Menu:setItems](#Menu:setItems)|-| +|[Menu.new](#Menu.new)|Menu|Creates a new Menu instance +|[Menu:init](#Menu:init)|Menu|Initializes the Menu instance +|[Menu:mouse_click](#Menu:mouse_click)|boolean|Handles mouse click events and item selection +|[Menu:render](#Menu:render)|-|Renders the menu horizontally with proper spacing and colors +|[Menu:setItems](#Menu:setItems)|Menu|Sets the menu items and calculates total width ## Menu.new() +Creates a new Menu instance -## Menu:init() +### Returns +* `Menu` `self` The newly created Menu instance -## Menu:mouse_click() +### Usage + ```lua +local menu = Menu.new() +``` + +## Menu:init(props, basalt) +Initializes the Menu instance + +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + +### Returns +* `Menu` `self` The initialized instance + +## Menu:mouse_click(button, x, y) +Handles mouse click events + +### Parameters +* `button` `number` The button that was clicked +* `x` `number` The x position of the click +* `y` `number` The y position of the click + +### Returns +* `boolean` `Whether` the event was handled ## Menu:render() +Renders the menu + +## Menu:setItems(items) +Sets the menu items + +### Parameters +* `items` `table[]` List of items with {text, separator, callback, foreground, background} properties + +### Returns +* `Menu` `self` The Menu instance + +### Usage + ```lua +menu:setItems({{text="File"}, {separator=true}, {text="Edit"}}) +``` -## Menu:setItems() diff --git a/docs/references/elements/Program.md b/docs/references/elements/Program.md index 0940d63..ab6fae7 100644 --- a/docs/references/elements/Program.md +++ b/docs/references/elements/Program.md @@ -1,6 +1,3 @@ -Rendering optimization (only render when screen changed) -Eventsystem improvement -Cursor is sometimes not visible on time # Program : VisualElement ## Functions @@ -50,3 +47,4 @@ local element = Program.new("myId", basalt) ## Program:render() + diff --git a/docs/references/elements/ProgressBar.md b/docs/references/elements/ProgressBar.md index 5446403..f28a618 100644 --- a/docs/references/elements/ProgressBar.md +++ b/docs/references/elements/ProgressBar.md @@ -1,24 +1,45 @@ # ProgressBar : VisualElement +This is the progress bar class. It provides a visual representation of progress +with optional percentage display and customizable colors. ## Properties |Property|Type|Default|Description| |---|---|---|---| -|progress|number|Current|progress (0-100) -|showPercentage|boolean|Show|percentage text -|progressColor|color|Progress|bar color +|progress|number|0|Current progress value (0-100) +|showPercentage|boolean|false|Whether to show the percentage text in the center +|progressColor|color|lime|The color used for the filled portion of the progress bar ## Functions |Method|Returns|Description| |---|---|---| -|[ProgressBar.new](#ProgressBar.new)|-| -|[ProgressBar:init](#ProgressBar:init)|-| -|[ProgressBar:render](#ProgressBar:render)|-| +|[ProgressBar.new](#ProgressBar.new)|ProgressBar|Creates a new ProgressBar instance +|[ProgressBar:init](#ProgressBar:init)|ProgressBar|Initializes the ProgressBar instance +|[ProgressBar:render](#ProgressBar:render)|-|Renders the progress bar with filled portion and optional percentage text ## ProgressBar.new() +Creates a new ProgressBar instance -## ProgressBar:init() +### Returns +* `ProgressBar` `self` The newly created ProgressBar instance + +### Usage + ```lua +local progressBar = ProgressBar.new() +``` + +## ProgressBar:init(props, basalt) +Initializes the ProgressBar instance + +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + +### Returns +* `ProgressBar` `self` The initialized instance ## ProgressBar:render() +Renders the ProgressBar + diff --git a/docs/references/elements/Slider.md b/docs/references/elements/Slider.md index 0670eda..c1560fd 100644 --- a/docs/references/elements/Slider.md +++ b/docs/references/elements/Slider.md @@ -1,35 +1,80 @@ # Slider : VisualElement +This is the slider class. It provides a draggable slider control that can be either horizontal or vertical, +with customizable colors and value ranges. ## Properties |Property|Type|Default|Description| |---|---|---|---| -|step|number|1|Current step position (1 to width/height) -|max|number|100|Maximum value for value conversion -|horizontal|boolean|true|Whether the slider is horizontal -|barColor|color|color|Colors for the slider bar -|sliderColor|color|The|color of the slider handle +|step|number|1|Current position of the slider handle (1 to width/height) +|max|number|100|Maximum value for value conversion (maps slider position to this range) +|horizontal|boolean|true|Whether the slider is horizontal (false for vertical) +|barColor|color|gray|Color of the slider track +|sliderColor|color|blue|Color of the slider handle + +## Events + +|Event|Parameters|Description| +|---|---|---| +|onChange|`value number`|Fired when the slider value changes| ## Functions |Method|Returns|Description| |---|---|---| -|[Slider.new](#Slider.new)|-| -|[Slider:getValue](#Slider:getValue)|-| -|[Slider:init](#Slider:init)|-| -|[Slider:mouse_click](#Slider:mouse_click)|-| +|[Slider.new](#Slider.new)|Slider|Creates a new Slider instance +|[Slider:getValue](#Slider:getValue)|number|Gets the current value mapped to the max range +|[Slider:init](#Slider:init)|Slider|Initializes the Slider instance +|[Slider:mouse_click](#Slider:mouse_click)|boolean|Updates slider position on mouse click |[Slider:mouse_scroll](#Slider:mouse_scroll)|-| -|[Slider:render](#Slider:render)|-| +|[Slider:render](#Slider:render)|-|Renders the slider with track and handle ## Slider.new() +Creates a new Slider instance + +### Returns +* `Slider` `self` The newly created Slider instance + +### Usage + ```lua +local slider = Slider.new() +``` ## Slider:getValue() +Gets the current value of the slider -## Slider:init() +### Returns +* `number` `value` The current value (0 to max) -## Slider:mouse_click() +### Usage + ```lua +local value = slider:getValue() +``` + +## Slider:init(props, basalt) +Initializes the Slider instance + +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + +### Returns +* `Slider` `self` The initialized instance + +## Slider:mouse_click(button, x, y) +Handles mouse click events + +### Parameters +* `button` `number` The mouse button that was clicked +* `x` `number` The x position of the click +* `y` `number` The y position of the click + +### Returns +* `boolean` `handled` Whether the event was handled ## Slider:mouse_scroll() ## Slider:render() +Renders the slider + diff --git a/docs/references/elements/Table.md b/docs/references/elements/Table.md index 2525be0..5284222 100644 --- a/docs/references/elements/Table.md +++ b/docs/references/elements/Table.md @@ -1,31 +1,115 @@ # Table : VisualElement +This is the table class. It provides a sortable data grid with customizable columns, +row selection, and scrolling capabilities. + +## 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 +|selectedRow|number?|nil|Currently selected row index +|headerColor|color|blue|Color of the column headers +|selectedColor|color|lightBlue|Background color of selected row +|gridColor|color|gray|Color of grid lines +|sortColumn|number?|nil|Currently sorted column index +|sortDirection|string|"asc"|Sort direction ("asc" or "desc") +|scrollOffset|number|0|Current scroll position ## Functions |Method|Returns|Description| |---|---|---| -|[Table.new](#Table.new)|-| -|[Table:init](#Table:init)|-| -|[Table:mouse_click](#Table:mouse_click)|-| -|[Table:mouse_scroll](#Table:mouse_scroll)|-| -|[Table:render](#Table:render)|-| -|[Table:setColumns](#Table:setColumns)|-| -|[Table:setData](#Table:setData)|-| -|[Table:sortData](#Table:sortData)|-| +|[Table.new](#Table.new)|Table|Creates a new Table instance +|[Table:init](#Table:init)|Table|Initializes the Table instance +|[Table:mouse_click](#Table:mouse_click)|boolean|Handles header clicks for sorting and row selection +|[Table:mouse_scroll](#Table:mouse_scroll)|boolean|Handles scrolling through the table data +|[Table:render](#Table:render)|-|Renders the table with headers, data and scrollbar +|[Table:setColumns](#Table:setColumns)|Table|Sets the table columns configuration +|[Table:setData](#Table:setData)|Table|Sets the table data +|[Table:sortData](#Table:sortData)|Table|Sorts the table data by the specified column ## Table.new() +Creates a new Table instance -## Table:init() +### Returns +* `Table` `self` The newly created Table instance -## Table:mouse_click() +### Usage + ```lua +local table = Table.new() +``` -## Table:mouse_scroll() +## Table:init(props, basalt) +Initializes the Table instance + +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + +### Returns +* `Table` `self` The initialized instance + +## Table:mouse_click(button, x, y) +Handles mouse click events + +### Parameters +* `button` `number` The button that was clicked +* `x` `number` The x position of the click +* `y` `number` The y position of the click + +### Returns +* `boolean` `handled` Whether the event was handled + +## Table:mouse_scroll(direction, x, y) +Handles mouse scroll events + +### Parameters +* `direction` `number` The scroll direction (-1 up, 1 down) +* `x` `number` The x position of the scroll +* `y` `number` The y position of the scroll + +### Returns +* `boolean` `handled` Whether the event was handled ## Table:render() +Renders the table -## Table:setColumns() +## Table:setColumns(columns) +Sets the table columns -## Table:setData() +### Parameters +* `columns` `table[]` Array of column definitions {name="Name", width=10} + +### Returns +* `Table` `self` The Table instance + +### Usage + ```lua +table:setColumns({{name="ID", width=4}, {name="Name", width=10}}) +``` + +## Table:setData(data) +Sets the table data + +### Parameters +* `data` `table[]` Array of row data arrays + +### Returns +* `Table` `self` The Table instance + +### Usage + ```lua +table:setData({{"1", "Item One"}, {"2", "Item Two"}}) +``` + +## Table:sortData(columnIndex) +Sorts the table data by column + +### Parameters +* `columnIndex` `number` The index of the column to sort by + +### Returns +* `Table` `self` The Table instance -## Table:sortData() diff --git a/docs/references/elements/TextBox.md b/docs/references/elements/TextBox.md new file mode 100644 index 0000000..75e94a3 --- /dev/null +++ b/docs/references/elements/TextBox.md @@ -0,0 +1,59 @@ +# TextBox : VisualElement +A multi-line text editor component with cursor support and text manipulation features + +## Properties + +|Property|Type|Default|Description| +|---|---|---|---| +|lines|table|{}|Array of text lines +|cursorX|number|1|Cursor X position +|cursorY|number|1|Cursor Y position (line number) +|scrollX|number|0|Horizontal scroll offset +|scrollY|number|0|Vertical scroll offset +|editable|boolean|true|Whether text can be edited +|syntaxPatterns|table|{}|Syntax highlighting patterns + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[TextBox.new](#TextBox.new)|-| +|[TextBox:addSyntaxPattern](#TextBox:addSyntaxPattern)|-| +|[TextBox:char](#TextBox:char)|-| +|[TextBox:getText](#TextBox:getText)|-| +|[TextBox:init](#TextBox:init)|-| +|[TextBox:key](#TextBox:key)|-| +|[TextBox:mouse_click](#TextBox:mouse_click)|-| +|[TextBox:mouse_scroll](#TextBox:mouse_scroll)|-| +|[TextBox:render](#TextBox:render)|-| +|[TextBox:setText](#TextBox:setText)|-| +|[TextBox:updateViewport](#TextBox:updateViewport)|-| + +## TextBox.new() + +## TextBox:addSyntaxPattern(pattern, color) +Adds a new syntax highlighting pattern + +### Parameters +* `pattern` `string` The regex pattern to match +* `color` `color` The color to apply + +## TextBox:char() + +## TextBox:getText() + +## TextBox:init() + +## TextBox:key() + +## TextBox:mouse_click() + +## TextBox:mouse_scroll() + +## TextBox:render() + +## TextBox:setText() + +## TextBox:updateViewport() + + diff --git a/docs/references/elements/Tree.md b/docs/references/elements/Tree.md index 48fee24..9b8be77 100644 --- a/docs/references/elements/Tree.md +++ b/docs/references/elements/Tree.md @@ -1,27 +1,71 @@ # Tree : VisualElement +This is the tree class. It provides a hierarchical view of nodes that can be expanded and collapsed, +with support for selection and scrolling. + +## Properties + +|Property|Type|Default|Description| +|---|---|---|---| +|nodes|table|{}|The tree structure containing node objects with {text, children} properties +|selectedNode|table?|nil|Currently selected node +|expandedNodes|table|{}|Table of nodes that are currently expanded +|scrollOffset|number|0|Current scroll position +|nodeColor|color|white|Color of unselected nodes +|selectedColor|color|lightBlue|Background color of selected node ## Functions |Method|Returns|Description| |---|---|---| -|[Tree.new](#Tree.new)|-| -|[Tree:collapseNode](#Tree:collapseNode)|-| -|[Tree:expandNode](#Tree:expandNode)|-| -|[Tree:init](#Tree:init)|-| +|[Tree.new](#Tree.new)|Tree|Creates a new Tree instance +|[Tree:collapseNode](#Tree:collapseNode)|Tree|Collapses a node to hide its children +|[Tree:expandNode](#Tree:expandNode)|Tree|Expands a node to show its children +|[Tree:init](#Tree:init)|Tree|Initializes the Tree instance |[Tree:mouse_click](#Tree:mouse_click)|-| |[Tree:mouse_scroll](#Tree:mouse_scroll)|-| |[Tree:onSelect](#Tree:onSelect)|-| |[Tree:render](#Tree:render)|-| -|[Tree:setNodes](#Tree:setNodes)|-| -|[Tree:toggleNode](#Tree:toggleNode)|-| +|[Tree:setNodes](#Tree:setNodes)|Tree|Sets the tree nodes and expands the root node +|[Tree:toggleNode](#Tree:toggleNode)|Tree|Toggles between expanded and collapsed state ## Tree.new() +Creates a new Tree instance -## Tree:collapseNode() +### Returns +* `Tree` `self` The newly created Tree instance -## Tree:expandNode() +### Usage + ```lua +local tree = Tree.new() +``` -## Tree:init() +## Tree:collapseNode(node) +Collapses a node + +### Parameters +* `node` `table` The node to collapse + +### Returns +* `Tree` `self` The Tree instance + +## Tree:expandNode(node) +Expands a node + +### Parameters +* `node` `table` The node to expand + +### Returns +* `Tree` `self` The Tree instance + +## Tree:init(props, basalt) +Initializes the Tree instance + +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + +### Returns +* `Tree` `self` The initialized instance ## Tree:mouse_click() @@ -31,7 +75,27 @@ ## Tree:render() -## Tree:setNodes() +## Tree:setNodes(nodes) +Sets the tree nodes + +### Parameters +* `nodes` `table[]` Array of node objects + +### Returns +* `Tree` `self` The Tree instance + +### Usage + ```lua +tree:setNodes({{text="Root", children={{text="Child"}}}}) +``` + +## Tree:toggleNode(node) +Toggles a node's expanded state + +### Parameters +* `node` `table` The node to toggle + +### Returns +* `Tree` `self` The Tree instance -## Tree:toggleNode() diff --git a/docs/references/elements/VisualElement.md b/docs/references/elements/VisualElement.md index 00fa098..7c7b0df 100644 --- a/docs/references/elements/VisualElement.md +++ b/docs/references/elements/VisualElement.md @@ -1,62 +1,64 @@ # VisualElement : BaseElement +This is the visual element class. It serves as the base class for all visual UI elements +and provides core functionality for positioning, sizing, colors, and rendering. ## Properties |Property|Type|Default|Description| |---|---|---|---| -|x|number|1|x position of the element -|y|number|1|y position of the element -|z|number|1|z position of the element -|width|number|1|width of the element -|height|number|1|height of the element -|background|color|black|background color of the element -|foreground|color|white|foreground color of the element -|clicked|boolean|an|false element is currently clicked -|backgroundEnabled|boolean|true|whether the background is enabled -|focused|boolean|false|whether the element is focused -|visible|boolean|true|whether the element is visible +|x|number|1|The horizontal position relative to parent +|y|number|1|The vertical position relative to parent +|z|number|1|The z-index for layering elements +|width|number|1|The width of the element +|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 +|backgroundEnabled|boolean|true|Whether to render the background +|focused|boolean|false|Whether the element has input focus +|visible|boolean|true|Whether the element is visible ## Combined Properties |Name|Properties|Description| |---|---|---| -|position|{x|y}|Position of the element -|size|{width|height}|Size of the element -|color|{foreground|background}|Color of the element +|position|`x y`|Combined x, y position| +|size|`width height`|Combined width, height| +|color|`foreground background`|Combined foreground, background colors| ## Events |Event|Parameters|Description| |---|---|---| -|onMouseClick|`button number, x number, y number`|Fired when the element is clicked| -|onMouseUp|`button number, x number, y number`|Fired when the mouse is released| -|onMouseRelease|`button number, x number, y number`|Fired when the mouse is released| -|onMouseDrag|`button number, x number, y number`|Fired when the mouse is dragged| -|onFocus|`-`|Fired when the element is focused| -|onBlur|`-`|Fired when the element is blurred| -|onKey|`key number, code number, isRepeat boolean`|Fired when a key is pressed| -|onKeyUp|`key number, code number`|Fired when a key is released| -|onChar|`char string`|Fired when a key is pressed| +|onMouseClick|`button number, x number, y number`|Fired on mouse click| +|onMouseUp|`button number, x number, y number`|Fired on mouse button release| +|onMouseRelease|`button number, x number, y number`|Fired when mouse leaves while clicked| +|onMouseDrag|`button number, x number, y number`|Fired when mouse moves while clicked| +|onFocus|`-`|Fired when element receives focus| +|onBlur|`-`|Fired when element loses focus| +|onKey|`key number, code number, isRepeat boolean`|Fired on key press| +|onKeyUp|`key number, code number`|Fired on key release| +|onChar|`char string`|Fired on character input| ## Functions |Method|Returns|Description| |---|---|---| -|[VisualElement.new](#VisualElement.new)|VisualElement| -|[VisualElement:blit](#VisualElement:blit)|-| -|[VisualElement:blur](#VisualElement:blur)|-| -|[VisualElement:focus](#VisualElement:focus)|-| -|[VisualElement:getAbsolutePosition](#VisualElement:getAbsolutePosition)|-| -|[VisualElement:getRelativePosition](#VisualElement:getRelativePosition)|number,| -|[VisualElement:init](#VisualElement:init)|-| -|[VisualElement:isInBounds](#VisualElement:isInBounds)|boolean| -|[VisualElement:mouse_click](#VisualElement:mouse_click)|boolean| -|[VisualElement:mouse_release](#VisualElement:mouse_release)|boolean| -|[VisualElement:mouse_up](#VisualElement:mouse_up)|boolean| -|[VisualElement:render](#VisualElement:render)|-| -|[VisualElement:setCursor](#VisualElement:setCursor)|-| -|[VisualElement:textBg](#VisualElement:textBg)|-| -|[VisualElement:textFg](#VisualElement:textFg)|-| +|[VisualElement.new](#VisualElement.new)|VisualElement|Creates a new visual element +|[VisualElement:blit](#VisualElement:blit)|-|Draws text with both colors +|[VisualElement:blur](#VisualElement:blur)|-|Handles a blur event +|[VisualElement:focus](#VisualElement:focus)|-|Handles a focus event +|[VisualElement:getAbsolutePosition](#VisualElement:getAbsolutePosition)|-|Returns the absolute position of the element +|[VisualElement:getRelativePosition](#VisualElement:getRelativePosition)|number,|Returns the relative position of the element +|[VisualElement:init](#VisualElement:init)|-|Initializes a new visual element with properties +|[VisualElement:isInBounds](#VisualElement:isInBounds)|boolean|Checks if point is within bounds +|[VisualElement:mouse_click](#VisualElement:mouse_click)|boolean|Handles a mouse click event +|[VisualElement:mouse_release](#VisualElement:mouse_release)|boolean|Handles a mouse release event +|[VisualElement:mouse_up](#VisualElement:mouse_up)|boolean|Handles a mouse up event +|[VisualElement:render](#VisualElement:render)|-|Renders the element +|[VisualElement:setCursor](#VisualElement:setCursor)|-|Sets the cursor position +|[VisualElement:textBg](#VisualElement:textBg)|-|Draws text with background color +|[VisualElement:textFg](#VisualElement:textFg)|-|Draws text with foreground color ## VisualElement.new(props, basalt) Creates a new VisualElement instance @@ -74,7 +76,7 @@ local element = VisualElement.new("myId", basalt) ``` ## VisualElement:blit(x, y, text, fg, bg) -Draws a text character with a foreground and background at the specified position, used in the rendering system +Draws text with both foreground and background colors ### Parameters * `x` `number` The x position to draw @@ -106,9 +108,13 @@ Returns the relative position of the element or the given coordinates. ### Returns * `nil` `nil` nil -## VisualElement:init() +## VisualElement:init(props, basalt) Initializes the VisualElement instance +### Parameters +* `props` `table` The properties to initialize the element with +* `basalt` `table` The basalt instance + ## VisualElement:isInBounds(x, y) Checks if the specified coordinates are within the bounds of the element @@ -164,7 +170,7 @@ Sets the cursor position * `blink` `boolean` Whether the cursor should blink ## VisualElement:textBg(x, y, text, bg) -Draws a text character with a background at the specified position, used in the rendering system +Draws text with background color ### Parameters * `x` `number` The x position to draw @@ -173,7 +179,7 @@ Draws a text character with a background at the specified position, used in the * `bg` `color` The background color ## VisualElement:textFg(x, y, text, fg) -Draws a text character at the specified position, used in the rendering system +Draws text with foreground color ### Parameters * `x` `number` The x position to draw @@ -181,3 +187,4 @@ Draws a text character at the specified position, used in the rendering system * `text` `string` The text char to draw * `fg` `color` The foreground color + diff --git a/docs/references/errorManager.md b/docs/references/errorManager.md index 255da8e..0a72f7d 100644 --- a/docs/references/errorManager.md +++ b/docs/references/errorManager.md @@ -1,2 +1,28 @@ -## errorHandler.error() +# ErrorHandler +This is Basalt's error handler. All the errors are handled by this module. + +## Fields + +|Field|Type|Description| +|---|---|---| +|tracebackEnabled|`boolean`|If the error handler should print a stack trace| +|header|`string`|The header of the error message| + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[errorHandler.error](#errorHandler.error)|-| + +## errorHandler.error(errMsg) +Handles an error + +### Parameters +* `errMsg` `string` The error message + +### Usage + ```lua +errorHandler.error("An error occurred") +``` + diff --git a/docs/references/log.md b/docs/references/log.md index d7ce417..c78d88d 100644 --- a/docs/references/log.md +++ b/docs/references/log.md @@ -1,4 +1,5 @@ # Log +Logger module for Basalt. Logs messages to the console and optionally to a file. ## Fields @@ -21,9 +22,12 @@ |[Log.setLogToFile](#Log.setLogToFile)|-|Sets if the logger should log to a file |[Log.warn](#Log.warn)|-|Sends a warning message -## Log.debug() +## Log.debug(...) Sends a debug message to the logger. +### Parameters +* `...` *(vararg)* `string` The message to log + ### Usage ```lua Log.debug("This is a debug message") @@ -68,3 +72,4 @@ Sends a warning message to the logger. Log.warn("This is a warning message") ``` + diff --git a/docs/references/main.md b/docs/references/main.md index 1347c46..8e595b0 100644 --- a/docs/references/main.md +++ b/docs/references/main.md @@ -1,8 +1,14 @@ +# Basalt This is the UI Manager and the starting point for your project. The following functions allow you to influence the default behavior of Basalt. Before you can access Basalt, you need to add the following code on top of your file: + +### Usage + ```lua +local basalt = require("basalt") +``` + What this code does is it loads basalt into the project, and you can access it by using the variable defined as "basalt". -# Basalt ## Fields @@ -152,3 +158,4 @@ Updates all scheduled functions basalt.update() ``` + diff --git a/docs/references/plugins/animation.md b/docs/references/plugins/animation.md index a39a254..0714771 100644 --- a/docs/references/plugins/animation.md +++ b/docs/references/plugins/animation.md @@ -1,34 +1,100 @@ -## Animation.new() +# Animation +This is the animation plugin. It provides a animation system for visual elements +with support for sequences, easing functions, and multiple animation types. -## Animation.registerAnimation() +## Functions -## Animation.registerEasing() +|Method|Returns|Description| +|---|---|---| +|[Animation.new](#Animation.new)|Animation|Creates a new animation +|[Animation.registerAnimation](#Animation.registerAnimation)|-|Registers a custom animation type +|[Animation.registerEasing](#Animation.registerEasing)|-|Adds a custom easing function +|[Animation:addAnimation](#Animation:addAnimation)|-|Adds a new animation to the sequence +|[Animation:event](#Animation:event)|-|The event handler for the animation +|[Animation:onComplete](#Animation:onComplete)|Animation|Registers a callback for the complete event +|[Animation:onStart](#Animation:onStart)|-|Registers a callback for the start event +|[Animation:onUpdate](#Animation:onUpdate)|Animation|Registers a callback for the update event +|[Animation:sequence](#Animation:sequence)|Animation|Creates a new sequence +|[Animation:start](#Animation:start)|Animation|Starts the animation -## Animation:addAnimation() +## Animation.new(element) +Creates a new Animation -## Animation:event() +### Parameters +* `element` `VisualElement` The element to animate -## Animation:onComplete() +### Returns +* `Animation` `The` new animation -## Animation:onStart() +## Animation.registerAnimation(name, handlers) +Registers a new animation type -## Animation:onUpdate() +### Parameters +* `name` `string` The name of the animation +* `handlers` `table` Table containing start, update and complete handlers + +### Usage + ```lua +Animation.registerAnimation("fade", {start=function(anim) end, update=function(anim,progress) end}) +``` + +## Animation.registerEasing(name, func) +Registers a new easing function + +### Parameters +* `name` `string` The name of the easing function +* `func` `function` The easing function (takes progress 0-1, returns modified progress) + +## Animation:addAnimation(type, args, duration, easing) +Adds a new animation to the sequence + +### Parameters +* `type` `string` The type of animation +* `args` `table` The animation arguments +* `duration` `number` The duration in seconds +* `easing` `string` The easing function name + +## Animation:event(event, timerId) +The event handler for the animation (listens to timer events) + +### Parameters +* `event` `string` The event type +* `timerId` `number` The timer ID + +## Animation:onComplete(callback) +Registers a callback for the complete event + +### Parameters +* `callback` `function` The callback function to register + +### Returns +* `Animation` `self` The animation instance + +## Animation:onStart(callback) +Registers a callback for the start event + +### Parameters +* `callback` `function` The callback function to register + +## Animation:onUpdate(callback) +Registers a callback for the update event + +### Parameters +* `callback` `function` The callback function to register + +### Returns +* `Animation` `self` The animation instance ## Animation:sequence() +Creates a new sequence + +### Returns +* `Animation` `self` The animation instance ## Animation:start() +Starts the animation -## AnimationInstance.new() +### Returns +* `Animation` `self` The animation instance -## AnimationInstance:complete() - -## AnimationInstance:start() - -## AnimationInstance:update() - -## VisualElement.hooks.dispatchEvent() - -## VisualElement.setup() - -## VisualElement:animate() diff --git a/docs/references/plugins/animation_AnimationInstance.md b/docs/references/plugins/animation_AnimationInstance.md new file mode 100644 index 0000000..df00ed7 --- /dev/null +++ b/docs/references/plugins/animation_AnimationInstance.md @@ -0,0 +1,57 @@ +# AnimationInstance +This is the AnimationInstance class. It represents a single animation instance + +## Fields + +|Field|Type|Description| +|---|---|---| +|element|`VisualElement`|The element being animated| +|type|`string`|The type of animation| +|args|`table`|The animation arguments| +|duration|`number`|The duration in seconds| +|startTime|`number`|The animation start time| +|isPaused|`boolean`|Whether the animation is paused| +|handlers|`table`|The animation handlers| +|easing|`string`|The easing function name| + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[AnimationInstance.new](#AnimationInstance.new)|AnimationInstance|Creates a new animation instance +|[AnimationInstance:complete](#AnimationInstance:complete)|-|Called when the animation is completed +|[AnimationInstance:start](#AnimationInstance:start)|AnimationInstance|Starts the animation +|[AnimationInstance:update](#AnimationInstance:update)|boolean|Updates the animation + +## AnimationInstance.new(element, animType, args, duration, easing) +Creates a new AnimationInstance + +### Parameters +* `element` `VisualElement` The element to animate +* `animType` `string` The type of animation +* `args` `table` The animation arguments +* `duration` `number` Duration in seconds +* `easing` `string` The easing function name + +### Returns +* `AnimationInstance` `The` new animation instance + +## AnimationInstance:complete() +Gets called when the animation is completed + +## AnimationInstance:start() +Starts the animation + +### Returns +* `AnimationInstance` `self` The animation instance + +## AnimationInstance:update(elapsed) +Updates the animation + +### Parameters +* `elapsed` `number` The elapsed time in seconds + +### Returns +* `boolean` `Whether` the animation is finished + + diff --git a/docs/references/plugins/animation_VisualElement.md b/docs/references/plugins/animation_VisualElement.md new file mode 100644 index 0000000..4d2ae2c --- /dev/null +++ b/docs/references/plugins/animation_VisualElement.md @@ -0,0 +1,16 @@ +# VisualElement +Adds additional methods for VisualElement when adding animation plugin + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[VisualElement:animate](#VisualElement:animate)|Animation|Creates a new animation + +## VisualElement:animate() +Creates a new Animation Object + +### Returns +* `Animation` `animation` The new animation + + diff --git a/docs/references/plugins/benchmark.md b/docs/references/plugins/benchmark.md index 41def59..dabd471 100644 --- a/docs/references/plugins/benchmark.md +++ b/docs/references/plugins/benchmark.md @@ -1,18 +1,45 @@ -## BaseElement:benchmark() +# BenchmarkAPI +Benchmark API methods -## BaseElement:endProfile() +## Functions -## BaseElement:getBenchmarkStats() +|Method|Returns|Description| +|---|---|---| +|[API.clear](#API.clear)|-|Removes a benchmark's data +|[API.clearAll](#API.clearAll)|-|Removes all custom benchmark data +|[API.getStats](#API.getStats)|table?|Retrieves benchmark statistics +|[API.start](#API.start)|-|Starts timing a custom operation +|[API.stop](#API.stop)|-|Stops timing and logs results -## BaseElement:logBenchmark() +## API.clear(name) +Clears a specific benchmark -## BaseElement:startProfile() +### Parameters +* `name` `string` The name of the benchmark to clear -## BaseElement:stopBenchmark() +## API.clearAll() +Clears all custom benchmarks -## Container:benchmarkContainer() +## API.getStats(name) +Gets statistics for a benchmark -## Container:logContainerBenchmarks() +### Parameters +* `name` `string` The name of the benchmark + +### Returns +* `table?` `stats` The benchmark statistics or nil + +## API.start(name, options?) +Starts a custom benchmark + +### Parameters +* `name` `string` The name of the benchmark +* `options` *(optional)* `table` Optional configuration + +## API.stop(name) +Stops a custom benchmark + +### Parameters +* `name` `string` The name of the benchmark to stop -## Container:stopContainerBenchmark() diff --git a/docs/references/plugins/benchmark_BaseElement.md b/docs/references/plugins/benchmark_BaseElement.md new file mode 100644 index 0000000..31e8c0b --- /dev/null +++ b/docs/references/plugins/benchmark_BaseElement.md @@ -0,0 +1,76 @@ +# BaseElement +This is the benchmark plugin. It provides performance measurement tools for elements and methods, +with support for hierarchical profiling and detailed statistics. +The following methods are available for BaseElement + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[BaseElement:benchmark](#BaseElement:benchmark)|BaseElement|Enables performance measurement for a method +|[BaseElement:endProfile](#BaseElement:endProfile)|BaseElement|Ends timing a method call and records statistics +|[BaseElement:getBenchmarkStats](#BaseElement:getBenchmarkStats)|table?|Retrieves benchmark statistics for a method +|[BaseElement:logBenchmark](#BaseElement:logBenchmark)|BaseElement|Logs benchmark statistics for a method +|[BaseElement:startProfile](#BaseElement:startProfile)|BaseElement|Starts timing a method call +|[BaseElement:stopBenchmark](#BaseElement:stopBenchmark)|BaseElement|Disables performance measurement for a method + +## BaseElement:benchmark(methodName) +Enables benchmarking for a method + +### Parameters +* `methodName` `string` The name of the method to benchmark + +### Returns +* `BaseElement` `self` The element instance + +### Usage + ```lua +element:benchmark("render") +``` + +## BaseElement:endProfile(methodName) +Ends profiling a method + +### Parameters +* `methodName` `string` The name of the method to stop profiling + +### Returns +* `BaseElement` `self` The element instance + +## BaseElement:getBenchmarkStats(methodName) +Gets benchmark statistics for a method + +### Parameters +* `methodName` `string` The name of the method to get statistics for + +### Returns +* `table?` `stats` The benchmark statistics or nil + +## BaseElement:logBenchmark(methodName) +Logs benchmark statistics for a method + +### Parameters +* `methodName` `string` The name of the method to log + +### Returns +* `BaseElement` `self` The element instance + +## BaseElement:startProfile(methodName) +Starts profiling a method + +### Parameters +* `methodName` `string` The name of the method to profile + +### Returns +* `BaseElement` `self` The element instance + +## BaseElement:stopBenchmark(methodName) +Stops benchmarking for a method + +### Parameters +* `methodName` `string` The name of the method to stop benchmarking + +### Returns +* `BaseElement` `self` The element instance + + diff --git a/docs/references/plugins/benchmark_Container.md b/docs/references/plugins/benchmark_Container.md new file mode 100644 index 0000000..2f91981 --- /dev/null +++ b/docs/references/plugins/benchmark_Container.md @@ -0,0 +1,44 @@ +# Container +Container benchmarking methods + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[Container:benchmarkContainer](#Container:benchmarkContainer)|Container|Recursively enables benchmarking +|[Container:logContainerBenchmarks](#Container:logContainerBenchmarks)|Container|Recursively logs benchmark statistics +|[Container:stopContainerBenchmark](#Container:stopContainerBenchmark)|Container|Recursively stops benchmarking + +## Container:benchmarkContainer(methodName) +Enables benchmarking for a container and all its children + +### Parameters +* `methodName` `string` The method to benchmark + +### Returns +* `Container` `self` The container instance + +### Usage + ```lua +container:benchmarkContainer("render") +``` + +## Container:logContainerBenchmarks(methodName) +Logs benchmark statistics for a container and all its children + +### Parameters +* `methodName` `string` The method to log + +### Returns +* `Container` `self` The container instance + +## Container:stopContainerBenchmark(methodName) +Stops benchmarking for a container and all its children + +### Parameters +* `methodName` `string` The method to stop benchmarking + +### Returns +* `Container` `self` The container instance + + diff --git a/docs/references/plugins/debug.md b/docs/references/plugins/debug.md index e69de29..729cae6 100644 --- a/docs/references/plugins/debug.md +++ b/docs/references/plugins/debug.md @@ -0,0 +1,75 @@ +# BaseElement +No Description + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[BaseElement.debug](#BaseElement.debug)|-|Enables debugging for this element +|[BaseElement.dumpDebug](#BaseElement.dumpDebug)|-|Dumps debug information + +## BaseElement.debug(self, level) +Enables debugging for this element + +### Parameters +* `self` `BaseElement` The element to debug +* `level` `number` The debug level + +## BaseElement.dumpDebug(self) +Dumps debug information for this element + +### Parameters +* `self` `BaseElement` The element to dump debug info for + + +--- +
+ +# BaseFrame + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[BaseFrame.hideDebugLog](#BaseFrame.hideDebugLog)|-|Hides the debug log frame +|[BaseFrame.showDebugLog](#BaseFrame.showDebugLog)|-|Shows the debug log frame +|[BaseFrame.toggleDebugLog](#BaseFrame.toggleDebugLog)|-|Toggles the debug log frame + +## BaseFrame.hideDebugLog(self) +Hides the debug log frame + +### Parameters +* `self` `BaseFrame` The frame to hide debug log for + +## BaseFrame.showDebugLog(self) +Shows the debug log frame + +### Parameters +* `self` `BaseFrame` The frame to show debug log in + +## BaseFrame.toggleDebugLog(self) +Toggles the debug log frame + +### Parameters +* `self` `BaseFrame` The frame to toggle debug log for + + +--- +
+ +# Container + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[Container.debugChildren](#Container.debugChildren)|-|Debug container and children + +## Container.debugChildren(self, level) +Enables debugging for this container and all its children + +### Parameters +* `self` `Container` The container to debug +* `level` `number` The debug level + + diff --git a/docs/references/plugins/state.md b/docs/references/plugins/state.md index d14c4ab..433a26f 100644 --- a/docs/references/plugins/state.md +++ b/docs/references/plugins/state.md @@ -1,14 +1,84 @@ -## BaseElement.setup() +# BaseElement +This is the state plugin. It provides a state management system for UI elements with support for +persistent states, computed states, and state sharing between elements. -## BaseElement:computed() +## Functions -## BaseElement:getState() +|Method|Returns|Description| +|---|---|---| +|[BaseElement:computed](#BaseElement:computed)|BaseElement|Creates a computed state +|[BaseElement:getState](#BaseElement:getState)|any|Gets a state value +|[BaseElement:initializeState](#BaseElement:initializeState)|BaseElement|Initializes a new state +|[BaseElement:onStateChange](#BaseElement:onStateChange)|BaseElement|Watches for state changes +|[BaseElement:setState](#BaseElement:setState)|BaseElement|Sets a state value +|[BaseElement:shareState](#BaseElement:shareState)|BaseElement|Shares state between elements -## BaseElement:initializeState() +## BaseElement:computed(self, key, computeFn) +Creates a computed state that derives its value from other states -## BaseElement:onStateChange() +### Parameters +* `self` `BaseElement` The element to create computed state for +* `key` `string` The name of the computed state +* `computeFn` `function` Function that computes the state value -## BaseElement:setState() +### Returns +* `BaseElement` `self` The element instance + +## BaseElement:getState(self, name) +Gets the value of a state + +### Parameters +* `self` `BaseElement` The element to get state from +* `name` `string` The name of the state + +### Returns +* `any` `value` The current state value + +## BaseElement:initializeState(self, name, default, canTriggerRender?, persist?, path?) +Initializes a new state for this element + +### Parameters +* `self` `BaseElement` The element to initialize state for +* `name` `string` The name of the state +* `default` `any` The default value of the state +* `canTriggerRender` *(optional)* `boolean` Whether state changes trigger a render +* `persist` *(optional)* `boolean` Whether to persist the state to disk +* `path` *(optional)* `string` Custom file path for persistence + +### Returns +* `BaseElement` `self` The element instance + +## BaseElement:onStateChange(self, stateName, callback) +Registers a callback for state changes + +### Parameters +* `self` `BaseElement` The element to watch +* `stateName` `string` The state to watch +* `callback` `function` Called with (element, newValue, oldValue) + +### Returns +* `BaseElement` `self` The element instance + +## BaseElement:setState(self, name, value) +Sets the value of a state + +### Parameters +* `self` `BaseElement` The element to set state for +* `name` `string` The name of the state +* `value` `any` The new value for the state + +### Returns +* `BaseElement` `self` The element instance + +## BaseElement:shareState(self, stateKey...) +Shares a state with other elements, keeping them in sync + +### Parameters +* `self` `BaseElement` The source element +* `stateKey` `string` The state to share +* `...` *(vararg)* `BaseElement` The target elements to share with + +### Returns +* `BaseElement` `self` The source element -## BaseElement:shareState() diff --git a/docs/references/plugins/theme.md b/docs/references/plugins/theme.md index 270c1f8..676a867 100644 --- a/docs/references/plugins/theme.md +++ b/docs/references/plugins/theme.md @@ -1,4 +1,63 @@ -## BaseElement.____getElementPath() +# BaseElement +This is the theme plugin. It provides a theming system that allows for consistent styling across elements +with support for inheritance, named styles, and dynamic theme switching. + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[BaseElement:applyTheme](#BaseElement:applyTheme)|BaseElement|Applies theme styles to the element +|[BaseElement:getTheme](#BaseElement:getTheme)|table|Gets theme properties for the element + +## BaseElement:applyTheme(self) +Applies the current theme to this element + +### Parameters +* `self` `BaseElement` The element to apply theme to + +### Returns +* `BaseElement` `self` The element instance + +## BaseElement:getTheme(self) +Gets the theme properties for this element + +### Parameters +* `self` `BaseElement` The element to get theme for + +### Returns +* `table` `styles` The theme properties + + +--- +
+ +# ThemeAPI +The Theme API provides methods for managing themes globally + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[themeAPI.getTheme](#themeAPI.getTheme)|table|Gets the current theme +|[themeAPI.loadTheme](#themeAPI.loadTheme)|-|Loads theme from JSON file +|[themeAPI.setTheme](#themeAPI.setTheme)|-|Sets a new theme + +## themeAPI.getTheme() +Gets the current theme configuration + +### Returns +* `table` `theme` The current theme configuration + +## themeAPI.loadTheme(path) +Loads a theme from a JSON file + +### Parameters +* `path` `string` Path to the theme JSON file + +## themeAPI.setTheme(newTheme) +Sets the current theme + +### Parameters +* `newTheme` `table` The theme configuration to set -## BaseElement:getTheme() diff --git a/docs/references/plugins/xml.md b/docs/references/plugins/xml.md index 34c729f..40e036f 100644 --- a/docs/references/plugins/xml.md +++ b/docs/references/plugins/xml.md @@ -1,4 +1,54 @@ -## BaseElement:fromXML() +# BaseElement +The XML plugin provides XML parsing and UI creation from XML markup + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[BaseElement:fromXML](#BaseElement:fromXML)|BaseElement|Creates element from XML node + +## BaseElement:fromXML(self, node) +Creates an element from an XML node + +### Parameters +* `self` `BaseElement` The element instance +* `node` `table` The XML node to create from + +### Returns +* `BaseElement` `self` The element instance + + +--- +
+ +# Container + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[Container:loadXML](#Container:loadXML)|Container|Loads UI from XML string + +## Container:loadXML(self, content, scope?) +Loads and creates UI elements from XML content +local xml = [[ + +