diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml deleted file mode 100644 index f800bad..0000000 --- a/.github/workflows/deploy.yml +++ /dev/null @@ -1,55 +0,0 @@ -name: Automatic Deploy VitePress site to Pages - -on: - push: - branches: [gh-pages] - paths: - - 'docs/**' - - workflow_dispatch: - -permissions: - contents: read - pages: write - id-token: write - -concurrency: - group: pages - cancel-in-progress: false - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Checkout gh-pages - uses: actions/checkout@v4 - with: - ref: gh-pages - fetch-depth: 0 - - name: Setup Node - uses: actions/setup-node@v4 - with: - node-version: 20 - cache: npm - - name: Setup Pages - uses: actions/configure-pages@v4 - - name: Install dependencies - run: npm ci - - name: Build with VitePress - run: npm run docs:build - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: docs/.vitepress/dist - - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - needs: build - runs-on: ubuntu-latest - name: Deploy - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/docs/references/elements/BarChart.md b/docs/references/elements/BarChart.md new file mode 100644 index 0000000..275e0a8 --- /dev/null +++ b/docs/references/elements/BarChart.md @@ -0,0 +1,17 @@ +# BarChart : Graph +This is the bar chart class. It is based on the graph element. It draws bar based points. + +## Functions + +|Method|Returns|Description| +|---|---|---| + + +## Protected Functions + +|Method|Returns|Description| +|---|---|---| +|[BarChart:init](#BarChart:init)|BarChart|Initializes the BarChart instance +|[BarChart:render](#BarChart:render)|-|Renders the BarChart + + diff --git a/docs/references/elements/BaseElement.md b/docs/references/elements/BaseElement.md index 6d0cd1a..068a618 100644 --- a/docs/references/elements/BaseElement.md +++ b/docs/references/elements/BaseElement.md @@ -14,6 +14,8 @@ The base class for all UI elements in Basalt. This class provides basic properti |Method|Returns|Description| |---|---|---| +|[BaseElement.defineEvent](#BaseElement.defineEvent)|-| +|[BaseElement.registerEventCallback](#BaseElement.registerEventCallback)|-| |[BaseElement:destroy](#BaseElement:destroy)|-|Destroys the element and cleans up all references |[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 @@ -33,6 +35,12 @@ The base class for all UI elements in Basalt. This class provides basic properti |[BaseElement:init](#BaseElement:init)|table|Initializes the BaseElement instance |[BaseElement:postInit](#BaseElement:postInit)|table|Post initialization +## BaseElement.defineEvent() +Registers a new event listener for the element (on class level) + +## BaseElement.registerEventCallback() +Registers a new event callback for the element (on class level) + ## BaseElement:destroy() Destroys the element and cleans up all references diff --git a/docs/references/elements/Container.md b/docs/references/elements/Container.md index 1a6aaf6..5215367 100644 --- a/docs/references/elements/Container.md +++ b/docs/references/elements/Container.md @@ -17,6 +17,12 @@ like Frames, BaseFrames, and more. |offsetX|number|0|Horizontal content offset |offsetY|number|0|Vertical content offset +## Combined Properties + +|Name|Properties|Description| +|---|---|---| +|offset|`offsetX number, offsetY number`|Combined property for offsetX and offsetY| + ## Functions |Method|Returns|Description| diff --git a/docs/references/elements/Display.md b/docs/references/elements/Display.md new file mode 100644 index 0000000..3a06066 --- /dev/null +++ b/docs/references/elements/Display.md @@ -0,0 +1,24 @@ +# Display : VisualElement +The Display is a special element where you can use the window (term) API to draw on a element, useful when you need to use external APIs. + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[Display:getWindow](#Display:getWindow)|table|Returns the current window object + + +## Protected Functions + +|Method|Returns|Description| +|---|---|---| +|[Display:init](#Display:init)|-|Initializes the Display instance +|[Display:render](#Display:render)|-|Renders the Display + +## Display:getWindow() +Returns the current window object + +### Returns +* `table` `window` The current window object + + diff --git a/docs/references/elements/Graph.md b/docs/references/elements/Graph.md new file mode 100644 index 0000000..a2dbd70 --- /dev/null +++ b/docs/references/elements/Graph.md @@ -0,0 +1,92 @@ +# Graph : VisualElement +This is the base class for all graph elements. It is a point based graph. + +## Properties + +|Property|Type|Default|Description| +|---|---|---|---| +|minValue|number|0|The minimum value of the graph +|maxValue|number|100|The maximum value of the graph +|series|table|{}|The series of the graph + +## Functions + +|Method|Returns|Description| +|---|---|---| +|[Graph:addPoint](#Graph:addPoint)|Graph|Adds a point to a series +|[Graph:addSeries](#Graph:addSeries)|-|Adds a series to the graph +|[Graph:changeSeriesVisibility](#Graph:changeSeriesVisibility)|Graph|Changes the visibility of a series +|[Graph:focusSeries](#Graph:focusSeries)|Graph|Focuses a series +|[Graph:getSeries](#Graph:getSeries)|table?|Gets a series from the graph +|[Graph:removeSeries](#Graph:removeSeries)|Graph|Removes a series from the graph +|[Graph:setSeriesPointCount](#Graph:setSeriesPointCount)|Graph|Sets the point count of a series + + +## Protected Functions + +|Method|Returns|Description| +|---|---|---| +|[Graph:init](#Graph:init)|Graph|Initializes the Graph instance +|[Graph:render](#Graph:render)|-|Renders the graph + +## Graph:addPoint(name, value) + +### Parameters +* `name` `string` The name of the series +* `value` `number` The value of the point + +### Returns +* `Graph` `self` The graph instance + +## Graph:addSeries(name, symbol, bgCol, fgCol, pointCount) + +### Parameters +* `name` `string` The name of the series +* `symbol` `string` The symbol of the series +* `bgCol` `number` The background color of the series +* `fgCol` `number` The foreground color of the series +* `pointCount` `number` The number of points in the series + +## Graph:changeSeriesVisibility(name, visible) + +### Parameters +* `name` `string` The name of the series +* `visible` `boolean` Whether the series should be visible + +### Returns +* `Graph` `self` The graph instance + +## Graph:focusSeries(name) + +### Parameters +* `name` `string` The name of the series + +### Returns +* `Graph` `self` The graph instance + +## Graph:getSeries(name) + +### Parameters +* `name` `string` The name of the series + +### Returns +* `table?` `series` The series + +## Graph:removeSeries(name) + +### Parameters +* `name` `string` The name of the series + +### Returns +* `Graph` `self` The graph instance + +## Graph:setSeriesPointCount(name, count) + +### Parameters +* `name` `string` The name of the series +* `count` `number` The number of points in the series + +### Returns +* `Graph` `self` The graph instance + + diff --git a/docs/references/elements/Image.md b/docs/references/elements/Image.md index 4d6160e..ae7b431 100644 --- a/docs/references/elements/Image.md +++ b/docs/references/elements/Image.md @@ -1,6 +1,6 @@ # Image : VisualElement -This is the Image element class which can be used to display bimg format images. -The bimg format is a universal ComputerCraft image format. +This is the Image element class which can be used to display bimg formatted images. +Bimg is a universal ComputerCraft image format. See: https://github.com/SkyTheCodeMaster/bimg ## Properties @@ -9,7 +9,6 @@ See: https://github.com/SkyTheCodeMaster/bimg |---|---|---|---| |bimg|table|{}|The bimg image data |currentFrame|number|1|Current animation frame -|metadata|table|{}|Image metadata (version, palette, etc) |autoResize|boolean|false|Whether to automatically resize the image when content exceeds bounds |offsetX|number|0|Horizontal offset for viewing larger images |offsetY|number|0|Vertical offset for viewing larger images @@ -25,15 +24,21 @@ See: https://github.com/SkyTheCodeMaster/bimg |Method|Returns|Description| |---|---|---| |[Image:addFrame](#Image:addFrame)|Image|Adds a new frame to the image +|[Image:getBg](#Image:getBg)|string|Gets the background color at the specified position +|[Image:getFg](#Image:getFg)|string|Gets the foreground color at the specified position +|[Image:getFrame](#Image:getFrame)|table|Gets the specified frame |[Image:getImageSize](#Image:getImageSize)|number|Gets the size of the image +|[Image:getMetadata](#Image:getMetadata)|table|Gets the metadata of the image |[Image:getPixelData](#Image:getPixelData)|number?|Gets pixel information at position -|[Image:loadBimg](#Image:loadBimg)|Image|Loads a bimg format image +|[Image:getText](#Image:getText)|string|Gets the text at the specified position |[Image:nextFrame](#Image:nextFrame)|Image|Advances to the next frame in the animation |[Image:resizeImage](#Image:resizeImage)|Image|Resizes the image to the specified width and height |[Image:setBg](#Image:setBg)|Image|Sets the background color at the specified position |[Image:setFg](#Image:setFg)|Image|Sets the foreground color at the specified position +|[Image:setMetadata](#Image:setMetadata)|Image|Sets the metadata of the image |[Image:setPixel](#Image:setPixel)|Image|Sets the pixel at the specified position |[Image:setText](#Image:setText)|Image|Sets the text at the specified position +|[Image:updateFrame](#Image:updateFrame)|Image|Updates the specified frame with the provided data ## Protected Functions @@ -49,6 +54,37 @@ Adds a new frame to the image ### Returns * `Image` `self` The Image instance +## Image:getBg(x, y, length) +Gets the background color at the specified position + +### Parameters +* `x` `number` The x position +* `y` `number` The y position +* `length` `number` The length of the background color pattern to get + +### Returns +* `string` `bg` The background color pattern + +## Image:getFg(x, y, length) +Gets the foreground color at the specified position + +### Parameters +* `x` `number` The x position +* `y` `number` The y position +* `length` `number` The length of the foreground color pattern to get + +### Returns +* `string` `fg` The foreground color pattern + +## Image:getFrame(frameIndex) +Gets the specified frame + +### Parameters +* `frameIndex` `number` The index of the frame to get + +### Returns +* `table` `frame` The frame data + ## Image:getImageSize() Gets the size of the image @@ -56,6 +92,12 @@ Gets the size of the image * `number` `width` The width of the image * `number` `height` The height of the image +## Image:getMetadata() +Gets the metadata of the image + +### Returns +* `table` `metadata` The metadata of the image + ## Image:getPixelData(x, y) Gets pixel information at position @@ -68,14 +110,16 @@ Gets pixel information at position * `number?` `bg` Background color * `string?` `char` Character at position -## Image:loadBimg(bimgData) -Loads a bimg format image +## Image:getText(x, y, length) +Gets the text at the specified position ### Parameters -* `bimgData` `table` The bimg image data +* `x` `number` The x position +* `y` `number` The y position +* `length` `number` The length of the text to get ### Returns -* `Image` `self` The Image instance +* `string` `text` The text at the specified position ## Image:nextFrame() Advances to the next frame in the animation @@ -115,6 +159,16 @@ Sets the foreground color at the specified position ### Returns * `Image` `self` The Image instance +## Image:setMetadata(key, value) +Sets the metadata of the image + +### Parameters +* `key` `string` The key of the metadata to set +* `value` `string` The value of the metadata to set + +### Returns +* `Image` `self` The Image instance + ## Image:setPixel(x, y, char, fg, bg) Sets the pixel at the specified position @@ -139,4 +193,14 @@ Sets the text at the specified position ### Returns * `Image` `self` The Image instance +## Image:updateFrame(frameIndex, frame) +Updates the specified frame with the provided data + +### Parameters +* `frameIndex` `number` The index of the frame to update +* `frame` `table` The new frame data + +### Returns +* `Image` `self` The Image instance + diff --git a/docs/references/elements/Input.md b/docs/references/elements/Input.md index 8c149d7..bdffedf 100644 --- a/docs/references/elements/Input.md +++ b/docs/references/elements/Input.md @@ -12,7 +12,8 @@ cursor movement, text manipulation, placeholder text, and input validation. |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 +|focusedBackground|color|blue|Background color when input is focused +|focusedForeground|color|white|Foreground color when input is focused |pattern|string?|nil|Regular expression pattern for input validation |cursorColor|number|nil|Color of the cursor @@ -20,6 +21,8 @@ cursor movement, text manipulation, placeholder text, and input validation. |Method|Returns|Description| |---|---|---| +|[Input:blur](#Input:blur)|-| +|[Input:focus](#Input:focus)|-| |[Input:setCursor](#Input:setCursor)|-| |[Input:updateViewport](#Input:updateViewport)|Input|Updates the input's viewport @@ -34,6 +37,10 @@ cursor movement, text manipulation, placeholder text, and input validation. |[Input:mouse_click](#Input:mouse_click)|boolean|Handles mouse click events |[Input:render](#Input:render)|-|Renders the input element +## Input:blur() + +## Input:focus() + ## Input:setCursor() ## Input:updateViewport() diff --git a/docs/references/elements/LineChart.md b/docs/references/elements/LineChart.md new file mode 100644 index 0000000..86e5bfe --- /dev/null +++ b/docs/references/elements/LineChart.md @@ -0,0 +1,17 @@ +# LineChart : Graph +This is the line chart class. It is based on the graph element. It draws lines between points. + +## Functions + +|Method|Returns|Description| +|---|---|---| + + +## Protected Functions + +|Method|Returns|Description| +|---|---|---| +|[LineChart:init](#LineChart:init)|LineChart|Initializes the LineChart instance +|[LineChart:render](#LineChart:render)|-|Renders the LineChart + + diff --git a/docs/references/elements/List.md b/docs/references/elements/List.md index 82e18e5..30d615a 100644 --- a/docs/references/elements/List.md +++ b/docs/references/elements/List.md @@ -17,7 +17,7 @@ custom item rendering, separators, and selection handling. |Event|Parameters|Description| |---|---|---| -|onSelect|`index number, item any`|Fired when an item is selected| +|onSelect|`index number, item table`|Fired when an item is selected| ## Functions @@ -25,6 +25,7 @@ custom item rendering, separators, and selection handling. |---|---|---| |[List:addItem](#List:addItem)|List|Adds an item to the list |[List:clear](#List:clear)|List|Clears all items from the list +|[List:getSelectedItem](#List:getSelectedItem)|table?|Gets first selected item |[List:getSelectedItems](#List:getSelectedItems)|table|Gets the currently selected items |[List:onSelect](#List:onSelect)|List|Registers a callback for the select event |[List:removeItem](#List:removeItem)|List|Removes an item from the list @@ -67,6 +68,12 @@ Clears all items from the list list:clear() ``` +## List:getSelectedItem() +Gets first selected item + +### Returns +* `table?` `selected` The first item + ## List:getSelectedItems() Gets the currently selected items diff --git a/docs/references/elements/VisualElement.md b/docs/references/elements/VisualElement.md index cb3989a..d29ae90 100644 --- a/docs/references/elements/VisualElement.md +++ b/docs/references/elements/VisualElement.md @@ -24,15 +24,15 @@ and provides core functionality for positioning, sizing, colors, and rendering. |Name|Properties|Description| |---|---|---| -|position|`x y`|Combined x, y position| -|size|`width height`|Combined width, height| -|color|`foreground background`|Combined foreground, background colors| +|position|`x number, y number`|Combined x, y position| +|size|`width number, height number`|Combined width, height| +|color|`foreground number, background number`|Combined foreground, background colors| ## Events |Event|Parameters|Description| |---|---|---| -|onClick|`button, x, y`|Fired on mouse click| +|onClick|`button string, x number, y number`|Fired on mouse click| |onMouseUp|`button, x, y`|Fired on mouse button release| |onRelease|`button, x, y`|Fired when mouse leaves while clicked| |onDrag|`button, x, y`|Fired when mouse moves while clicked| @@ -119,8 +119,7 @@ Checks if the specified coordinates are within the bounds of the element * `boolean` `isInBounds` Whether the coordinates are within the bounds of the element ## VisualElement:prioritize() -This function is used to prioritize the element by moving it to the top of its parent's children. -It removes the element from its parent and adds it back, effectively changing its order. +This function is used to prioritize the element by moving it to the top of its parent's children. It removes the element from its parent and adds it back, effectively changing its order. ### Returns * `VisualElement` `self` The VisualElement instance diff --git a/docs/references/main.md b/docs/references/main.md index 159baa0..c98f181 100644 --- a/docs/references/main.md +++ b/docs/references/main.md @@ -1,4 +1,4 @@ -# Basalt +# 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: @@ -18,6 +18,7 @@ What this code does is it loads basalt into the project, and you can access it b |_events|`table`|A table of events and their callbacks| |_schedule|`function[]`|A table of scheduled functions| |_plugins|`table`|A table of plugins| +|isRunning|`boolean`|Whether the Basalt runtime is active| |LOGGER|`Log`|The logger instance| |path|`string`|The path to the Basalt library| @@ -26,8 +27,10 @@ What this code does is it loads basalt into the project, and you can access it b |Method|Returns|Description| |---|---|---| |[basalt.create](#basalt.create)|table|Creates a new UI element -|[basalt.createFrame](#basalt.createFrame)|table|Creates a new BaseFrame +|[basalt.createFrame](#basalt.createFrame)|BaseFrame|Creates a new BaseFrame |[basalt.getAPI](#basalt.getAPI)|table|Returns a Plugin API +|[basalt.getActiveFrame](#basalt.getActiveFrame)|BaseFrame?|Returns the active frame +|[basalt.getElementClass](#basalt.getElementClass)|table|Returns an element class |[basalt.getElementManager](#basalt.getElementManager)|table|Returns the element manager |[basalt.getMainFrame](#basalt.getMainFrame)|BaseFrame|Gets or creates the main frame |[basalt.removeSchedule](#basalt.removeSchedule)|boolean|Removes a scheduled update @@ -57,7 +60,7 @@ local button = basalt.create("Button") Creates and returns a new BaseFrame ### Returns -* `table` `BaseFrame` The created frame instance +* `BaseFrame` `BaseFrame` The created frame instance ### Usage ```lua @@ -73,6 +76,26 @@ Returns a Plugin API ### Returns * `table` `Plugin` The plugin API +## basalt.getActiveFrame() +Returns the active frame + +### Returns +* `BaseFrame?` `BaseFrame` The frame to set as active + +### Usage + ```lua +local frame = basalt.getActiveFrame() +``` + +## basalt.getElementClass(name) +Returns an element's class without creating a instance + +### Parameters +* `name` `string` The name of the element + +### Returns +* `table` `Element` The element class + ## basalt.getElementManager() Returns the element manager instance @@ -88,7 +111,7 @@ local manager = basalt.getElementManager() Gets or creates the main frame ### Returns -* `BaseFrame` `table` The main frame instance +* `BaseFrame` `BaseFrame` The main frame instance ### Usage ```lua @@ -139,7 +162,7 @@ local id = basalt.scheduleUpdate(myFunction) Sets the active frame ### Parameters -* `frame` `table` The frame to set as active +* `frame` `BaseFrame` The frame to set as active ### Usage ```lua @@ -155,7 +178,7 @@ basalt.stop() ``` ## basalt.update(...) -Runs basalt once +Runs basalt once, can be used to update the UI manually, but you have to feed it the events ### Parameters * `...` *(vararg)* `any` The event to run with diff --git a/docs/references/plugins/theme.md b/docs/references/plugins/theme.md index 79d8357..c6bdb16 100644 --- a/docs/references/plugins/theme.md +++ b/docs/references/plugins/theme.md @@ -39,24 +39,24 @@ The Theme API provides methods for managing themes globally |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](#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() +## ThemeAPI.getTheme() Gets the current theme configuration ### Returns * `table` `theme` The current theme configuration -## themeAPI.loadTheme(path) +## ThemeAPI.loadTheme(path) Loads a theme from a JSON file ### Parameters * `path` `string` Path to the theme JSON file -## themeAPI.setTheme(newTheme) +## ThemeAPI.setTheme(newTheme) Sets the current theme ### Parameters diff --git a/docs/references/plugins/xml.md b/docs/references/plugins/xml.md index a61b550..b63d542 100644 --- a/docs/references/plugins/xml.md +++ b/docs/references/plugins/xml.md @@ -1,27 +1,3 @@ -# 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 diff --git a/docs/references/propertySystem.md b/docs/references/propertySystem.md index 03364e3..b147c17 100644 --- a/docs/references/propertySystem.md +++ b/docs/references/propertySystem.md @@ -27,7 +27,7 @@ It also allows for properties to have custom getters and setters. This is the ba |[PropertySystem:instanceProperty](#PropertySystem:instanceProperty)|table|Adds a property to the PropertySystem on instance level |[PropertySystem:observe](#PropertySystem:observe)|table|Observers a property |[PropertySystem:removeAllObservers](#PropertySystem:removeAllObservers)|table|Removes all observers from a property -|[PropertySystem:removeObserver](#PropertySystem:removeObserver)|table| +|[PropertySystem:removeObserver](#PropertySystem:removeObserver)|table|Removes an observer from a property |[PropertySystem:removeProperty](#PropertySystem:removeProperty)|table|Removes a property from the PropertySystem @@ -128,7 +128,6 @@ Removes all observers from a property ## PropertySystem:removeObserver(name, callback) Removes an observer from a property -@NshortDescription Removes an observer from a property ### Parameters * `name` `string` The name of the property diff --git a/docs/references/render.md b/docs/references/render.md index 6876da9..58293f0 100644 --- a/docs/references/render.md +++ b/docs/references/render.md @@ -31,7 +31,7 @@ functionality. It also has a buffer system to reduce the number of calls |[Render:rectOverlaps](#Render:rectOverlaps)|boolean| |[Render:render](#Render:render)|Render| |[Render:setCursor](#Render:setCursor)|Render| -|[Render:setSize](#Render:setSize)|-| +|[Render:setSize](#Render:setSize)|Render| |[Render:text](#Render:text)|Render| |[Render:textBg](#Render:textBg)|Render| |[Render:textFg](#Render:textFg)|Render| @@ -173,7 +173,15 @@ Sets the cursor position ### Returns * `nil` `nil` nil -## Render:setSize() +## Render:setSize(width, height) +Sets the size of the render + +### Parameters +* `width` `number` The width of the render +* `height` `number` The height of the render + +### Returns +* `nil` `nil` nil ## Render:text(x, y, text) Blits text to the screen