Basalt2/docs/references/main.md

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: What this code does is it loads basalt into the project, and you can access it by using the variable defined as "basalt".

Usage

local basalt = require("basalt")

Functions

Method	Returns	Description
basalt.create	table	Creates a new UI element
basalt.createFrame	BaseFrame	Creates a new BaseFrame
basalt.getElementManager	table	Returns the element manager
basalt.getErrorManager	table	Returns the error manager
basalt.getMainFrame	BaseFrame	Gets or creates the main frame
basalt.setActiveFrame	-	Sets the active frame
basalt.getActiveFrame	BaseFrame	Returns the active frame
basalt.setFocus	-	Sets a frame as focused
basalt.getFocus	BaseFrame	Returns the focused frame
basalt.schedule	thread	Schedules a function to run in a coroutine
basalt.removeSchedule	boolean	Removes a scheduled update
basalt.update	-	Runs basalt once
basalt.stop	-	Stops the Basalt runtime
basalt.run	-	Starts the Basalt runtime
basalt.getElementClass	table	Returns an element class
basalt.getAPI	table	Returns a Plugin API
basalt.onEvent	-	Registers an event callback
basalt.removeEvent	boolean	Removes an event callback
basalt.triggerEvent	-	Triggers a custom event
basalt.requireElements	-	Requires elements for the application
basalt.loadManifest	table	Loads an application manifest
basalt.install	-	Installs an element
basalt.configure	-	Configures element loading behavior

basalt.create(type, properties?)

Creates and returns a new UI element of the specified type.

Parameters

• type string The type of element to create (e.g. "Button", "Label", "BaseFrame")
• properties (optional) string|table Optional name for the element or a table with properties to initialize the element with

Returns

• table element The created element instance

Usage

local button = basalt.create("Button")

basalt.createFrame()

Creates and returns a new BaseFrame

Returns

• BaseFrame BaseFrame The created frame instance

basalt.getElementManager()

Returns the element manager instance

Returns

• table ElementManager The element manager

basalt.getErrorManager()

Returns the error manager instance

Returns

• table ErrorManager The error manager

basalt.getMainFrame()

Gets or creates the main frame

Returns

• BaseFrame BaseFrame The main frame instance

basalt.setActiveFrame(frame, setActive?)

Sets the active frame

Parameters

• frame BaseFrame The frame to set as active
• setActive (optional) boolean Whether to set the frame as active (default: true)

basalt.getActiveFrame(t?)

Returns the active frame

Parameters

• t (optional) term The term to get the active frame for (default: current term)

Returns

• BaseFrame The frame to set as active

basalt.setFocus(frame)

Sets a frame as focused

Parameters

• frame BaseFrame The frame to set as focused

basalt.getFocus()

Returns the focused frame

Returns

• BaseFrame The focused frame

basalt.schedule(func)

Schedules a function to run in a coroutine

Parameters

• func function The function to schedule

Returns

• thread func The scheduled function

basalt.removeSchedule(func)

Removes a scheduled update

Parameters

• func thread The scheduled function to remove

Returns

• boolean success Whether the scheduled function was removed

basalt.update()

Runs basalt once, can be used to update the UI manually, but you have to feed it the events

basalt.stop()

Stops the Basalt runtime

basalt.run(isActive?)

Starts the Basalt runtime

Parameters

• isActive (optional) boolean Whether to start active (default: true)

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.getAPI(name)

Returns a Plugin API

Parameters

• name string The name of the plugin

Returns

• table Plugin The plugin API

basalt.onEvent(eventName, callback)

Registers a callback function for a specific event

Parameters

• eventName string The name of the event to listen for (e.g. "mouse_click", "key", "timer")
• callback function The callback function to execute when the event occurs

Usage

basalt.onEvent("mouse_click", function(button, x, y) basalt.debug("Clicked at", x, y) end)

basalt.removeEvent(eventName, callback)

Removes a callback function for a specific event

Parameters

• eventName string The name of the event
• callback function The callback function to remove

Returns

• boolean success Whether the callback was found and removed

basalt.triggerEvent(eventName)

Triggers a custom event and calls all registered callbacks

Parameters

• eventName string The name of the event to trigger

Usage

basalt.triggerEvent("custom_event", "data1", "data2")

basalt.requireElements(elements, autoLoad?)

Requires specific elements and validates they are available

Parameters

• elements table|string List of element names or single element name
• autoLoad (optional) boolean Whether to automatically load missing elements (default: false)

Usage

basalt.requireElements({"Button", "Label", "Slider"})

basalt.requireElements("Button", true)

basalt.loadManifest(path)

Loads a manifest file that describes element requirements and configuration

Parameters

• path string The path to the manifest file

Returns

• table manifest The loaded manifest data

Usage

basalt.loadManifest("myapp.manifest")

basalt.install(elementName, source?)

Installs an element interactively or from a specified source

Parameters

• elementName string The name of the element to install
• source (optional) string Optional source URL or path

Usage

basalt.install("Slider")

basalt.install("Slider", "https://example.com/slider.lua")

basalt.configure(config)

Configures the ElementManager (shortcut to elementManager.configure)

Parameters

• config table Configuration options

Usage

basalt.configure({allowRemoteLoading = true, useGlobalCache = true})