This commit is contained in:
NoryiE
2025-10-29 16:56:08 +00:00
parent 9a5b46138e
commit 00a9ce5632
26 changed files with 812 additions and 77 deletions

View File

@@ -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)
```

View File

@@ -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|

View File

@@ -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|

View File

@@ -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|

View File

@@ -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)
```

View File

@@ -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|

View File

@@ -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|

View File

@@ -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|

View File

@@ -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|

View File

@@ -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|

View File

@@ -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)
```

View File

@@ -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)
```

View File

@@ -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

View File

@@ -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|

View File

@@ -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)|

View File

@@ -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()
```

View File

@@ -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

View File

@@ -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

View File

@@ -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