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

deploy: a967cde115

Browse Source
This commit is contained in:
NoryiE
2025-10-30 13:13:21 +00:00
parent 31d6051568
commit f89c639383
5 changed files with 556 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
docs/references/elements/Accordion.md Normal file
View File

@@ -0,0 +1,185 @@
# Accordion
_The Accordion is a container that provides collapsible panel functionality_
Extends: `Container`
## Examples (Executable)
```lua run
local basalt = require("basalt")
local main = basalt.getMainFrame()
-- Create an Accordion
local accordion = main:addAccordion({
x = 2,
y = 2,
width = 30,
height = 15,
allowMultiple = true, -- Only one panel open at a time
headerBackground = colors.gray,
headerTextColor = colors.white,
expandedHeaderBackground = colors.lightBlue,
expandedHeaderTextColor = colors.white,
})
-- Panel 1: Info
local infoPanel = accordion:newPanel("Information", true) -- starts expanded
infoPanel:addLabel({
x = 2,
y = 1,
text = "This is an accordion",
foreground = colors.yellow
})
infoPanel:addLabel({
x = 2,
y = 2,
text = "with collapsible panels.",
foreground = colors.white
})
-- Panel 2: Settings
local settingsPanel = accordion:newPanel("Settings", false)
settingsPanel:addLabel({
x = 2,
y = 1,
text = "Volume:",
foreground = colors.white
})
local volumeSlider = settingsPanel:addSlider({
x = 10,
y = 1,
width = 15,
value = 50
})
settingsPanel:addLabel({
x = 2,
y = 3,
text = "Auto-save:",
foreground = colors.white
})
settingsPanel:addSwitch({
x = 13,
y = 3,
})
-- Panel 3: Actions
local actionsPanel = accordion:newPanel("Actions", false)
local statusLabel = actionsPanel:addLabel({
x = 2,
y = 4,
text = "Ready",
foreground = colors.lime
})
actionsPanel:addButton({
x = 2,
y = 1,
width = 10,
height = 1,
text = "Save",
background = colors.green,
foreground = colors.white,
})
actionsPanel:addButton({
x = 14,
y = 1,
width = 10,
height = 1,
text = "Cancel",
background = colors.red,
foreground = colors.white,
})
-- Panel 4: About
local aboutPanel = accordion:newPanel("About", false)
aboutPanel:addLabel({
x = 2,
y = 1,
text = "Basalt Accordion v1.0",
foreground = colors.white
})
aboutPanel:addLabel({
x = 2,
y = 2,
text = "A collapsible panel",
foreground = colors.gray
})
aboutPanel:addLabel({
x = 2,
y = 3,
text = "component for UI.",
foreground = colors.gray
})
-- Instructions
main:addLabel({
x = 2,
y = 18,
text = "Click panel headers to expand/collapse",
foreground = colors.lightGray
})
basalt.run()
```
## Properties
|Property|Type|Default|Description|
|---|---|---|---|
|panels|table|{}|List of panel definitions|
|panelHeaderHeight|number|1|Height of each panel header|
|allowMultiple|boolean|false|Allow multiple panels to be open at once|
|headerBackground|color|gray|Background color for panel headers|
|headerTextColor|color|white|Text color for panel headers|
|expandedHeaderBackground|color|lightGray|Background color for expanded panel headers|
|expandedHeaderTextColor|color|black|Text color for expanded panel headers|
## Functions
|Method|Returns|Description|
|---|---|---|
|[Accordion:newPanel](#accordion-newpanel-title-expanded)|table|Creates a new accordion panel|
|[Accordion:togglePanel](#accordion-togglepanel-panelid)|Accordion|Toggles a panel's expanded state|
|[Accordion:expandPanel](#accordion-expandpanel-panelid)|Accordion|Expands a specific panel|
|[Accordion:collapsePanel](#accordion-collapsepanel-panelid)|Accordion|Collapses a specific panel|
|[Accordion:getPanel](#accordion-getpanel-panelid)|container|Gets a panel container by ID|
## Accordion:newPanel(title, expanded)
Creates a new panel and returns the panel's container
### Parameters
* `title` `string` The title of the panel
* `expanded` `boolean` Whether the panel starts expanded (default: false)
### Returns
* `table` `panelContainer` The container for this panel
## Accordion:togglePanel(panelId)
### Parameters
* `panelId` `number` The ID of the panel to toggle
### Returns
* `Accordion` `self` For method chaining
## Accordion:expandPanel(panelId)
### Parameters
* `panelId` `number` The ID of the panel to expand
### Returns
* `Accordion` `self` For method chaining
## Accordion:collapsePanel(panelId)
### Parameters
* `panelId` `number` The ID of the panel to collapse
### Returns
* `Accordion` `self` For method chaining
## Accordion:getPanel(panelId)
### Parameters
* `panelId` `number` The ID of the panel
### Returns
* `container` `The` panel's container or nil

53
docs/references/elements/Breadcrumb.md Normal file
View File

@@ -0,0 +1,53 @@
# Breadcrumb
Extends: `VisualElement`
## Properties
|Property|Type|Default|Description|
|---|---|---|---|
|path|table|{}|Array of strings representing the breadcrumb segments|
|clickable|true|boolean|Whether the segments are clickable|
|autoSize|false|boolean|Whether to resize the element width automatically based on text|
## Functions
|Method|Returns|Description|
|---|---|---|
|[Breadcrumb.new](#breadcrumb-new)|table|Creates a new Breadcrumb instance|
|[Breadcrumb:init](#breadcrumb-init-props-basalt)|-|Initializes the Breadcrumb instance|
|[Breadcrumb:mouse_click](#breadcrumb-mouse-click-button-x-y)|boolean|Handles mouse click events|
|[Breadcrumb:onSelect](#breadcrumb-onselect-callback)|Breadcrumb|Registers a callback for the select event|
## Breadcrumb.new()
### Returns
* `table` self
## Breadcrumb:init(props, basalt)
### Parameters
* `props` `table`
* `basalt` `table`
## Breadcrumb:mouse_click(button, x, y)
### Parameters
* `button` `number`
* `x` `number`
* `y` `number`
### Returns
* `boolean` handled
## Breadcrumb:onSelect(callback)
Registers a callback for the select event
### Parameters
* `callback` `function` The callback function to register
### Returns
* `Breadcrumb` `self` The Breadcrumb instance
### Usage
```lua
breadcrumb:onSelect(function(segmentIndex, path) print("Navigated to segment:", segmentIndex, path) end)
```

148
docs/references/elements/ContextMenu.md Normal file
View File

@@ -0,0 +1,148 @@
# ContextMenu
_The ContextMenu displays a list of clickable items with optional submenus_
Extends: `Container`
## Examples (Executable)
```lua run
local basalt = require("basalt")
local main = basalt.getMainFrame()
-- Create a label that shows the selected action
local statusLabel = main:addLabel({
x = 2,
y = 2,
text = "Right-click anywhere!",
foreground = colors.yellow
})
-- Create a ContextMenu
local contextMenu = main:addContextMenu({
x = 10,
y = 5,
background = colors.black,
foreground = colors.white,
})
contextMenu:setItems({
{
label = "Copy",
onClick = function()
statusLabel:setText("Action: Copy")
end
},
{
label = "Paste",
onClick = function()
statusLabel:setText("Action: Paste")
end
},
{
label = "Delete",
background = colors.red,
foreground = colors.white,
onClick = function()
statusLabel:setText("Action: Delete")
end
},
{label = "---", disabled = true},
{
label = "More Options",
submenu = {
{
label = "Option 1",
onClick = function()
statusLabel:setText("Action: Option 1")
end
},
{
label = "Option 2",
onClick = function()
statusLabel:setText("Action: Option 2")
end
},
{label = "---", disabled = true},
{
label = "Nested",
submenu = {
{
label = "Deep 1",
onClick = function()
statusLabel:setText("Action: Deep 1")
end
}
}
}
}
},
{label = "---", disabled = true},
{
label = "Exit",
onClick = function()
statusLabel:setText("Action: Exit")
end
}
})
-- Open menu on right-click anywhere
main:onClick(function(self, button, x, y)
if button == 2 then
contextMenu.set("x", x)
contextMenu.set("y", y)
contextMenu:open()
basalt.LOGGER.info("Context menu opened at (" .. x .. ", " .. y .. ")")
end
end)
basalt.run()
```
## Properties
|Property|Type|Default|Description|
|---|---|---|---|
|items|table|{}|List of menu items|
|isOpen|boolean|false|Whether the menu is currently open|
|openSubmenu|table|nil|Currently open submenu data|
|itemHeight|number|1|Height of each menu item|
## Functions
|Method|Returns|Description|
|---|---|---|
|[ContextMenu:setItems](#contextmenu-setitems-items)|ContextMenu|Sets the menu items from a table|
|[ContextMenu:open](#contextmenu-open)|ContextMenu|Opens the context menu|
|[ContextMenu:close](#contextmenu-close)|ContextMenu|Closes the context menu|
|[ContextMenu:closeAll](#contextmenu-closeall)|ContextMenu|Closes the root menu and all child menus|
## ContextMenu:setItems(items)
Sets the menu items
### Parameters
* `items` `table` Array of item definitions
### Returns
* `ContextMenu` `self` For method chaining
## ContextMenu:open()
Opens the menu
### Returns
* `ContextMenu` `self` For method chaining
## ContextMenu:close()
Closes the menu and any submenus
### Returns
* `ContextMenu` `self` For method chaining
## ContextMenu:closeAll()
Closes the entire menu chain (parent and all submenus)
### Returns
* `ContextMenu` `self` For method chaining

75
docs/references/elements/Dialog.md Normal file
View File

@@ -0,0 +1,75 @@
# Dialog
_A dialog overlay system that provides common dialog types such as alert, confirm, and prompt._
Extends: `Frame`
## Properties
|Property|Type|Default|Description|
|---|---|---|---|
|title|string|""|The dialog title|
|primaryColor|color|lime|Primary button color (OK, confirm actions)|
|secondaryColor|color|lightGray|Secondary button color (Cancel, dismiss actions)|
|buttonForeground|color|black|Foreground color for buttons|
|modal|boolean|true|If true, blocks all events outside the dialog|
## Functions
|Method|Returns|Description|
|---|---|---|
|[Dialog:show](#dialog-show)|Dialog|Shows the dialog|
|[Dialog:close](#dialog-close)|Dialog|Closes the dialog|
|[Dialog:alert](#dialog-alert-title-message-callback)|Dialog|Creates a simple alert dialog|
|[Dialog:confirm](#dialog-confirm-title-message-callback)|Dialog|Creates a confirm dialog|
|[Dialog:prompt](#dialog-prompt-title-message-default-callback)|Dialog|Creates a prompt dialog with input|
## Dialog:show()
Shows the dialog
### Returns
* `Dialog` `self` The Dialog instance
## Dialog:close()
Closes the dialog
### Returns
* `Dialog` `self` The Dialog instance
## Dialog:alert(title, message, callback?)
Creates a simple alert dialog
### Parameters
* `title` `string` The alert title
* `message` `string` The alert message
* `callback` *(optional)* `function` Callback when OK is clicked
### Returns
* `Dialog` `self` The Dialog instance
## Dialog:confirm(title, message, callback)
Creates a confirm dialog
### Parameters
* `title` `string` The dialog title
* `message` `string` The confirmation message
* `callback` `function` Callback (receives boolean result)
### Returns
* `Dialog` `self` The Dialog instance
## Dialog:prompt(title, message, default?, callback?)
Creates a prompt dialog with input
### Parameters
* `title` `string` The dialog title
* `message` `string` The prompt message
* `default` *(optional)* `string` Default input value
* `callback` *(optional)* `function` Callback (receives input text or nil if cancelled)
### Returns
* `Dialog` `self` The Dialog instance

95
docs/references/elements/Toast.md Normal file
View File

@@ -0,0 +1,95 @@
# Toast
_A toast notification element that displays temporary messages with optional icons and auto-hide functionality._
_The element is always visible but only renders content when a message is shown._
Extends: `VisualElement`
## Properties
|Property|Type|Default|Description|
|---|---|---|---|
|title|string|""|The title text of the toast|
|message|string|""|The message text of the toast|
|duration|number|3|Duration in seconds before the toast auto-hides|
|toastType|string|"default"|Type of toast: default, success, error, warning, info|
|autoHide|boolean|true|Whether the toast should automatically hide after duration|
|active|boolean|false|Whether the toast is currently showing a message|
|colorMap|table|Map|of toast types to their colors|
## Functions
|Method|Returns|Description|
|---|---|---|
|[Toast:show](#toast-show-titleormessage-messageorduration-duration)|Toast|Shows a toast message|
|[Toast:hide](#toast-hide)|Toast|Hides the toast|
|[Toast:success](#toast-success-titleormessage-messageorduration-duration)|Toast|Shows a success toast|
|[Toast:error](#toast-error-titleormessage-messageorduration-duration)|Toast|Shows an error toast|
|[Toast:warning](#toast-warning-titleormessage-messageorduration-duration)|Toast|Shows a warning toast|
|[Toast:info](#toast-info-titleormessage-messageorduration-duration)|Toast|Shows an info toast|
## Toast:show(titleOrMessage, messageOrDuration?, duration?)
Shows a toast message
### Parameters
* `titleOrMessage` `string` The title (if message provided) or the message (if no message)
* `messageOrDuration` *(optional)* `string|number` The message (if string) or duration (if number)
* `duration` *(optional)* `number` Duration in seconds
### Returns
* `Toast` `self` The Toast instance
## Toast:hide()
Hides the toast
### Returns
* `Toast` `self` The Toast instance
## Toast:success(titleOrMessage, messageOrDuration?, duration?)
Shows a success toast
### Parameters
* `titleOrMessage` `string` The title or message
* `messageOrDuration` *(optional)* `string|number` The message or duration
* `duration` *(optional)* `number` Duration in seconds
### Returns
* `Toast` `self` The Toast instance
## Toast:error(titleOrMessage, messageOrDuration?, duration?)
Shows an error toast
### Parameters
* `titleOrMessage` `string` The title or message
* `messageOrDuration` *(optional)* `string|number` The message or duration
* `duration` *(optional)* `number` Duration in seconds
### Returns
* `Toast` `self` The Toast instance
## Toast:warning(titleOrMessage, messageOrDuration?, duration?)
Shows a warning toast
### Parameters
* `titleOrMessage` `string` The title or message
* `messageOrDuration` *(optional)* `string|number` The message or duration
* `duration` *(optional)* `number` Duration in seconds
### Returns
* `Toast` `self` The Toast instance
## Toast:info(titleOrMessage, messageOrDuration?, duration?)
Shows an info toast
### Parameters
* `titleOrMessage` `string` The title or message
* `messageOrDuration` *(optional)* `string|number` The message or duration
* `duration` *(optional)* `number` Duration in seconds
### Returns
* `Toast` `self` The Toast instance