VisualElement

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

Properties

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

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

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.

onClick

Registers a new event listener for mouse_click events.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local button = main:addButton()

local function mouseClick(self, button, x, y)
    basalt.debug("Button got clicked!")
end

button:onClick(mouseClick)

onClickUp

Registers a new event listener for mouse_up events.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local button = main:addButton()

local function mouseRelease(self, button, x, y)
    basalt.debug("Mouse button released!")
end

button:onClickUp(mouseRelease)

onRelease

Registers a new event listener for mouse_up events, even when it doesn't happen inside the element.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local button = main:addButton()

local function releaseHandler(self)
    basalt.debug("Mouse button released!")
end

button:onRelease(releaseHandler)

onScroll

Registers a new event listener for mouse_scroll events

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local list = main:addList()

local function scrollHandler(self, direction, x, y)
    basalt.debug("Mouse scrolled: " .. direction)
end

list:onScroll(scrollHandler)

onDrag

Registers a new event listener for mouse_drag events

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local movableFrame = main:addMovableFrame()

local function dragHandler(self, button, x, y)
    basalt.debug("Element dragged!")
end

movableFrame:onDrag(dragHandler)

onHover

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.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

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)

onLeave

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.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local button = main:addButton()

local function leaveHandler(self)
    basalt.debug("Mouse left the button!")
end

button:onLeave(leaveHandler)

onKey

Registers a new event listener for key events.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local input = main:addInput()

local function keyPressHandler(self, key)
    basalt.debug("Key pressed: " .. keys[key])
end

input:onKey(keyPressHandler)

onKeyUp

Registers a new event listener for key_up events.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local input = main:addInput()

local function keyReleaseHandler(self, key)
    basalt.debug("Key released: " .. keys[key])
end

input:onKeyUp(keyReleaseHandler)

onChar

Registers a new event listener char events.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local input = main:addInput()

local function charPressHandler(self, char)
    basalt.debug("Character pressed: " .. char)
end

input:onChar(charPressHandler)

onGetFocus

Registers a new custom event listener for when the element gains focus.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local textfield = main:addTextfield()

local function focusHandler(self)
    basalt.debug("Element gained focus!")
end

textfield:onGetFocus(focusHandler)

onLoseFocus

Registers a new custom event listener for when the element loses focus.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
local textfield = main:addTextfield()

local function blurHandler(self)
    basalt.debug("Element lost focus!")
end

textfield:onLoseFocus(blurHandler)

onEvent

Registers a new event listener for any other (uncategorized) event that may occur.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

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)

onResize

Registers a new custom event listener for when the size of the element is changed.

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()

local function resizeHandler(self, width, height)
    basalt.debug("Element resized to " .. width .. "x" .. height)
end

main:onResize(resizeHandler)

onReposition

Registers a new event listener for when the position of the element is changed (moved to a new location).

Parameters

1. function The function to call when the event triggers

Returns

1. self

Click to see example

local main = basalt.getMainFrame()

local function repositionHandler(self, x, y)
    basalt.debug("Element repositioned to (" .. x .. ", " .. y .. ")")
end

main:onReposition(repositionHandler)

preRender

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!

Click to see example

-- No example avaialble yet

render

This 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!

Click to see example

-- No example avaialble yet

postRender

This 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!

Click to see example

-- No example avaialble yet

pre-/postText

This method allows the user to draw custom text for the element before or after rendering.

Parameters

1. number x - The x-coordinate.
2. number y - The y-coordinate.
3. string The text content to be drawn

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
main:postText(3, 3, "Hello World!")

pre-/postBg

These methods allow the user to draw a custom background for the element before or after rendering.

Parameters

1. number x - The x-coordinate.
2. number y - The y-coordinate.
3. string The background color to be drawn e.g. "ffffff"

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
main:postBg(3, 3, "5555555")

pre-/postFg

These methods allow the user to draw a custom foreground for the element before or after rendering.

Parameters

1. number x - The x-coordinate.
2. number y - The y-coordinate.
3. string The foreground color to be drawn e.g. "ffffff"

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
main:postFg(3, 2, "22222222")

pre-/postBlit

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!

Parameters

1. number x - The x-coordinate.
2. number y - The y-coordinate.
3. string The text content to be drawn
4. string The foreground color to be drawn
5. string The background color to be drawn

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
main:postBlit(2, 2, "Hello World!", "111111111111", "dddddddddddd")

pre-/postTextBox

These methods allow the user to draw a custom text box with a single char before or after rendering.

Parameters

1. number x - The x-coordinate.
2. number y - The y-coordinate.
3. number width - The width of the box.
4. number height - The height of the box.
5. string the symbol you want to be drawn

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
main:postTextBox(2, 2, 10, 10, "\2\4")

pre-/postBackgroundBox

These methods allow the user to draw a custom background box for the element before or after rendering.

Parameters

1. number x - The x-coordinate.
2. number y - The y-coordinate.
3. number width - The width of the box.
4. number height - The height of the box.
5. string|color The background color as string or a color

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
main:postBackgroundBox(2, 2, 10, 10, "241d") -- or colors.red e.g

pre-/postForegroundBox

These methods allow the user to draw a custom foreground box for the element before or after rendering.

Parameters

1. number x - The x-coordinate.
2. number y - The y-coordinate.
3. number width - The width of the box.
4. number height - The height of the box.
5. string|color The foreground color as string or a color

Returns

1. self

Click to see example

local main = basalt.getMainFrame()
main:postForegroundBox(2, 2, 10, 10, "1213") -- or colors.blue e.g
main:postTextBox(2, 2, 10, 10, "Hello")

clearPreRender / clearPostRender

These methods clear any custom pre-render or post-render data that has been set for the element, respectively.

Returns

1. self

Click to see example

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)

getRelativePosition

This method returns the relative position of the element within its parent container.

Parameters

1. number? The X-Coordinate
2. number? The Y-Coordinate

Returns

1. number X-Cooridnate
2. number y-Cooridnate

Click to see example

local main = basalt.getMainFrame()
main:addButton():setPosition(2, 2):onClick(function(self)
    basalt.debug(self:getRelativePosition())
end)

getAbsolutePosition

This method returns the absolute position of the element relative to the screen or window.

Parameters

1. number? The X-Coordinate
2. number? The Y-Coordinate

Returns

1. number X-Cooridnate
2. number y-Cooridnate

Click to see example

local main = basalt.getMainFrame()
main:addButton():setPosition(2, 2):onClick(function(self)
    basalt.debug(self:getAbsolutePosition())
end)

isInside

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.

Parameters

1. number? The X-Coordinate
2. number? The Y-Coordinate

Returns

1. boolean true if the given coordinate is inside the element, otherwise false

Click to see example

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)