import{_ as o,C as t,o as p,c as r,k as a,a as s,H as e,Q as l}from"./chunks/framework.4313453f.js";const js=JSON.parse('{"title":"VisualElement","description":"","frontmatter":{},"headers":[],"relativePath":"references/visualelement.md","filePath":"references/visualelement.md","lastUpdated":null}'),c={name:"references/visualelement.md"},i=l('
The VisualElement class is derived from the Element class and serves as the foundation for all visual components in Basalt. VisualElements include elements like frames, buttons, label's or input fields. The VisualElement class provides methods for managing the appearance, position, size, and other general visual properties of these elements.
VisualElement inherit from BasicElement
| Property | Type | Description |
|---|---|---|
| background | color | Background color of the element. |
| foreground | color | Foreground color or text color. |
| x | number | Horizontal position of the element. |
| y | number | Vertical position of the element. |
| width | number | Width of the element. |
| height | number | Height of the element. |
| visible | bool | Whether the element is visible or hidden. |
| transparent | bool | Whether the element's background is transparent. |
| ignoreOffset | bool | Ignores parent's offset when positioning. |
| focused | bool | Whether the element currently has focus. |
| preRenderData | table | A table with custom pre-render information. |
| postRenderData | table | A table with custom post-render information. |
Events are actions or occurrences that happen during the execution of your program. In Basalt, elements can respond to various events, such as user interactions or incoming redstone/rednet events.
| Name | Description |
|---|---|
| onClick | Fires when the element is clicked. |
| onClickUp | Fires when the mouse button is released on the element. |
| onRelease | Fires when the mouse button is released. |
| onScroll | Fires when scrolling with the mouse wheel. |
| onDrag | Fires when the element is being dragged. |
| onHover | CraftOS-PC - fires when the mouse hovers over an element. |
| onLeave | CraftOS-PC - fires when the mouse leaves an element. |
| onKey | Fires when the element is focused and a keyboard key is pressed. |
| onKeyUp | Fires when the element is focused and a keyboard key is released. |
| onChar | Fires when the element is focused and a character key is pressed. |
| onGetFocus | Fires when the element gains focus. |
| onLoseFocus | Fires when the element loses focus. |
| onEvent | Fires on any other (uncategorized) event. |
| onResize | Fires when the size of the element is changed. |
| onReposition | Fires when the position of the element is changed (moved to a new location). |
| Methods | Returns | Description |
|---|---|---|
| preRender | self | This method is beeing called before the actual element render happens. |
| render | self | This will render the element. |
| postRender | self | This method is beeing called after the actual element render happens. |
| preText | self | This method allows the user to draw custom text for the element before rendering. |
| preBg | self | This method allows the user to draw a custom background for the element before rendering. |
| preFg | self | This method allows the user to draw a custom foreground (e.g., text color) for the element before rendering. |
| preBlit | self | This method allows the user to draw text, bg and fg onto the element before rendering. |
| preTextBox | self | This method allows the user to draw a custom text box within the element before rendering. |
| preBackgroundBox | self | This method allows the user to draw a custom background box before rendering. |
| preForegroundBox | self | This method allows the user to draw a custom foreground box before rendering. |
| postText | self | This method allows the user to draw custom text for the element after rendering. |
| postBg | self | This method allows the user to draw a custom background for the element after rendering. |
| postFg | self | This method allows the user to draw a custom foreground (e.g., text color) for the element after rendering. |
| postBlit | self | This method allows the user to draw text, bg and fg onto the element after rendering. |
| postTextBox | self | This method allows the user to draw a custom text box within the element after rendering. |
| postBackgroundBox | self | This method allows the user to draw a custom background box after rendering. |
| postForegroundBox | self | This method allows the user to draw a custom foreground box after rendering. |
| clearPreRender | self | Clears any custom pre-render data that has been set for the element. |
| clearPostRender | self | Clears any custom post-render data that has been set for the element. |
| getRelativePosition | number | Returns the relative position of the element within its parent container. |
| getAbsolutePosition | number | Returns the absolute position of the element relative to the screen or window. |
| isInside | boolean | Checks whether a given point (coordinates) is inside the boundaries of the element. Returns a boolean value indicating whether the point is inside the element or not. |
Registers a new event listener for mouse_click events.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local button = main:addButton()
local function mouseClick(self, button, x, y)
basalt.debug("Button got clicked!")
end
button:onClick(mouseClick)local main = basalt.getMainFrame()
local button = main:addButton()
local function mouseClick(self, button, x, y)
basalt.debug("Button got clicked!")
end
button:onClick(mouseClick)Registers a new event listener for mouse_up events.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local button = main:addButton()
local function mouseRelease(self, button, x, y)
basalt.debug("Mouse button released!")
end
button:onClickUp(mouseRelease)local main = basalt.getMainFrame()
local button = main:addButton()
local function mouseRelease(self, button, x, y)
basalt.debug("Mouse button released!")
end
button:onClickUp(mouseRelease)Registers a new event listener for mouse_up events, even when it doesn't happen inside the element.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local button = main:addButton()
local function releaseHandler(self)
basalt.debug("Mouse button released!")
end
button:onRelease(releaseHandler)local main = basalt.getMainFrame()
local button = main:addButton()
local function releaseHandler(self)
basalt.debug("Mouse button released!")
end
button:onRelease(releaseHandler)Registers a new event listener for mouse_scroll events
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local list = main:addList()
local function scrollHandler(self, direction, x, y)
basalt.debug("Mouse scrolled: " .. direction)
end
list:onScroll(scrollHandler)local main = basalt.getMainFrame()
local list = main:addList()
local function scrollHandler(self, direction, x, y)
basalt.debug("Mouse scrolled: " .. direction)
end
list:onScroll(scrollHandler)Registers a new event listener for mouse_drag events
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local movableFrame = main:addMovableFrame()
local function dragHandler(self, button, x, y)
basalt.debug("Element dragged!")
end
movableFrame:onDrag(dragHandler)local main = basalt.getMainFrame()
local movableFrame = main:addMovableFrame()
local function dragHandler(self, button, x, y)
basalt.debug("Element dragged!")
end
movableFrame:onDrag(dragHandler)Registers a new event listener for mouse_move events.
WARNING
This is only available for CraftOS-PC. CC:Tweaked has no mouse_move events implemented.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local button = main:addButton()
local function hoverHandler(self, x, y)
basalt.debug("Mouse hovered over the button!")
end
button:onHover(hoverHandler)local main = basalt.getMainFrame()
local button = main:addButton()
local function hoverHandler(self, x, y)
basalt.debug("Mouse hovered over the button!")
end
button:onHover(hoverHandler)Registers a new event listener for mouse_move events.
WARNING
This is only available for CraftOS-PC. CC:Tweaked has no mouse_move events implemented.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local button = main:addButton()
local function leaveHandler(self)
basalt.debug("Mouse left the button!")
end
button:onLeave(leaveHandler)local main = basalt.getMainFrame()
local button = main:addButton()
local function leaveHandler(self)
basalt.debug("Mouse left the button!")
end
button:onLeave(leaveHandler)Registers a new event listener for key events.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local input = main:addInput()
local function keyPressHandler(self, key)
basalt.debug("Key pressed: " .. keys[key])
end
input:onKey(keyPressHandler)local main = basalt.getMainFrame()
local input = main:addInput()
local function keyPressHandler(self, key)
basalt.debug("Key pressed: " .. keys[key])
end
input:onKey(keyPressHandler)Registers a new event listener for key_up events.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local input = main:addInput()
local function keyReleaseHandler(self, key)
basalt.debug("Key released: " .. keys[key])
end
input:onKeyUp(keyReleaseHandler)local main = basalt.getMainFrame()
local input = main:addInput()
local function keyReleaseHandler(self, key)
basalt.debug("Key released: " .. keys[key])
end
input:onKeyUp(keyReleaseHandler)Registers a new event listener char events.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local input = main:addInput()
local function charPressHandler(self, char)
basalt.debug("Character pressed: " .. char)
end
input:onChar(charPressHandler)local main = basalt.getMainFrame()
local input = main:addInput()
local function charPressHandler(self, char)
basalt.debug("Character pressed: " .. char)
end
input:onChar(charPressHandler)Registers a new custom event listener for when the element gains focus.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local textfield = main:addTextfield()
local function focusHandler(self)
basalt.debug("Element gained focus!")
end
textfield:onGetFocus(focusHandler)local main = basalt.getMainFrame()
local textfield = main:addTextfield()
local function focusHandler(self)
basalt.debug("Element gained focus!")
end
textfield:onGetFocus(focusHandler)Registers a new custom event listener for when the element loses focus.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local textfield = main:addTextfield()
local function blurHandler(self)
basalt.debug("Element lost focus!")
end
textfield:onLoseFocus(blurHandler)local main = basalt.getMainFrame()
local textfield = main:addTextfield()
local function blurHandler(self)
basalt.debug("Element lost focus!")
end
textfield:onLoseFocus(blurHandler)Registers a new event listener for any other (uncategorized) event that may occur.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local textfield = main:addTextfield()
local function pasteHandler(self, event, text)
if event == "paste" then
basalt.debug("Text got pasted: "..text)
end
end
textfield:onLoseFocus(pasteHandler)local main = basalt.getMainFrame()
local textfield = main:addTextfield()
local function pasteHandler(self, event, text)
if event == "paste" then
basalt.debug("Text got pasted: "..text)
end
end
textfield:onLoseFocus(pasteHandler)Registers a new custom event listener for when the size of the element is changed.
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local function resizeHandler(self, width, height)
basalt.debug("Element resized to " .. width .. "x" .. height)
end
main:onResize(resizeHandler)local main = basalt.getMainFrame()
local function resizeHandler(self, width, height)
basalt.debug("Element resized to " .. width .. "x" .. height)
end
main:onResize(resizeHandler)Registers a new event listener for when the position of the element is changed (moved to a new location).
function The function to call when the event triggersselflocal main = basalt.getMainFrame()
local function repositionHandler(self, x, y)
basalt.debug("Element repositioned to (" .. x .. ", " .. y .. ")")
end
main:onReposition(repositionHandler)local main = basalt.getMainFrame()
local function repositionHandler(self, x, y)
basalt.debug("Element repositioned to (" .. x .. ", " .. y .. ")")
end
main:onReposition(repositionHandler)This method is called before the actual element rendering happens. It can be overridden to perform specific preprocessing before the element is rendered.
WARNING
This method is not supposed to be called outside of basalt's render system!
-- No example avaialble yet-- No example avaialble yetThis method renders the element. It can be overridden to customize the default rendering behavior of the element and modify it significantly. In case render gets overridden, the default visuals for the elements won't appear anymore.
WARNING
This method is not supposed to be called outside of basalt's render system!
-- No example avaialble yet-- No example avaialble yetThis method is called after the actual element rendering happens. It can be overridden to perform additional processing after the element has been rendered.
WARNING
This method is not supposed to be called outside of basalt's render system!
-- No example avaialble yet-- No example avaialble yetThis method allows the user to draw custom text for the element before or after rendering.
number x - The x-coordinate.number y - The y-coordinate.string The text content to be drawnselflocal main = basalt.getMainFrame()
main:postText(3, 3, "Hello World!")local main = basalt.getMainFrame()
main:postText(3, 3, "Hello World!")These methods allow the user to draw a custom background for the element before or after rendering.
number x - The x-coordinate.number y - The y-coordinate.string The background color to be drawn e.g. "ffffff"selflocal main = basalt.getMainFrame()
main:postBg(3, 3, "5555555")local main = basalt.getMainFrame()
main:postBg(3, 3, "5555555")These methods allow the user to draw a custom foreground for the element before or after rendering.
number x - The x-coordinate.number y - The y-coordinate.string The foreground color to be drawn e.g. "ffffff"selflocal main = basalt.getMainFrame()
main:postFg(3, 2, "22222222")local main = basalt.getMainFrame()
main:postFg(3, 2, "22222222")These methods allow the user to draw text, background, and foreground elements onto the element before or after rendering.
TIP
Note that text, fg, and bg must be the same string size!
number x - The x-coordinate.number y - The y-coordinate.string The text content to be drawnstring The foreground color to be drawnstring The background color to be drawnselflocal main = basalt.getMainFrame()
main:postBlit(2, 2, "Hello World!", "111111111111", "dddddddddddd")local main = basalt.getMainFrame()
main:postBlit(2, 2, "Hello World!", "111111111111", "dddddddddddd")These methods allow the user to draw a custom text box with a single char before or after rendering.
number x - The x-coordinate.number y - The y-coordinate.number width - The width of the box.number height - The height of the box.string the symbol you want to be drawnselflocal main = basalt.getMainFrame()
main:postTextBox(2, 2, 10, 10, "\\2\\4")local main = basalt.getMainFrame()
main:postTextBox(2, 2, 10, 10, "\\2\\4")These methods allow the user to draw a custom background box for the element before or after rendering.
number x - The x-coordinate.number y - The y-coordinate.number width - The width of the box.number height - The height of the box.string|color The background color as string or a colorselflocal main = basalt.getMainFrame()
main:postBackgroundBox(2, 2, 10, 10, "241d") -- or colors.red e.glocal main = basalt.getMainFrame()
main:postBackgroundBox(2, 2, 10, 10, "241d") -- or colors.red e.gThese methods allow the user to draw a custom foreground box for the element before or after rendering.
number x - The x-coordinate.number y - The y-coordinate.number width - The width of the box.number height - The height of the box.string|color The foreground color as string or a colorselflocal main = basalt.getMainFrame()
main:postForegroundBox(2, 2, 10, 10, "1213") -- or colors.blue e.g
main:postTextBox(2, 2, 10, 10, "Hello")local main = basalt.getMainFrame()
main:postForegroundBox(2, 2, 10, 10, "1213") -- or colors.blue e.g
main:postTextBox(2, 2, 10, 10, "Hello")These methods clear any custom pre-render or post-render data that has been set for the element, respectively.
selflocal main = basalt.getMainFrame()
main:postForegroundBox(2, 2, 10, 10, "1213")
main:postTextBox(2, 2, 10, 10, "Hello")
main:addButton():setPosition(15, 2):onClick(function()
main:clearPostRender()
end)local main = basalt.getMainFrame()
main:postForegroundBox(2, 2, 10, 10, "1213")
main:postTextBox(2, 2, 10, 10, "Hello")
main:addButton():setPosition(15, 2):onClick(function()
main:clearPostRender()
end)This method returns the relative position of the element within its parent container.
number? The X-Coordinatenumber? The Y-Coordinatenumber X-Cooridnatenumber y-Cooridnatelocal main = basalt.getMainFrame()
main:addButton():setPosition(2, 2):onClick(function(self)
basalt.debug(self:getRelativePosition())
end)local main = basalt.getMainFrame()
main:addButton():setPosition(2, 2):onClick(function(self)
basalt.debug(self:getRelativePosition())
end)This method returns the absolute position of the element relative to the screen or window.
number? The X-Coordinatenumber? The Y-Coordinatenumber X-Cooridnatenumber y-Cooridnatelocal main = basalt.getMainFrame()
main:addButton():setPosition(2, 2):onClick(function(self)
basalt.debug(self:getAbsolutePosition())
end)local main = basalt.getMainFrame()
main:addButton():setPosition(2, 2):onClick(function(self)
basalt.debug(self:getAbsolutePosition())
end)This method checks whether a given point (coordinates) is inside the boundaries of the element. It returns a boolean value indicating whether the point is inside the element or not.
number? The X-Coordinatenumber? The Y-Coordinateboolean true if the given coordinate is inside the element, otherwise falselocal main = basalt.getMainFrame()
main:addButton():setPosition(2, 2):onClick(function(self)
basalt.debug(self:isInside(5, 5)) -- checks if x5, y5 is inside the button
end)local main = basalt.getMainFrame()
main:addButton():setPosition(2, 2):onClick(function(self)
basalt.debug(self:isInside(5, 5)) -- checks if x5, y5 is inside the button
end)