deploy: ebd4cc0010
This commit is contained in:
NoryiE
@@ -1,142 +1,205 @@
|
||||
# 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.
|
||||
local elementManager = require("elementManager")
|
||||
local errorManager = require("errorManager")
|
||||
local propertySystem = require("propertySystem")
|
||||
|
||||
Before you can access Basalt, you need to add the following code on top of your file:
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
local basalt = require("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:
|
||||
--- @usage local basalt = require("basalt")
|
||||
--- What this code does is it loads basalt into the project, and you can access it by using the variable defined as "basalt".
|
||||
-- @module Basalt
|
||||
local basalt = {}
|
||||
basalt.traceback = true
|
||||
basalt._events = {}
|
||||
basalt._schedule = {}
|
||||
basalt._plugins = {}
|
||||
basalt.LOGGER = require("log")
|
||||
basalt.path = fs.getDir(select(2, ...))
|
||||
|
||||
What this code does is it loads basalt into the project, and you can access it by using the variable defined as "basalt".
|
||||
local mainFrame = nil
|
||||
local updaterActive = false
|
||||
local _type = type
|
||||
|
||||
## Functions
|
||||
local lazyElements = {}
|
||||
local lazyElementCount = 10
|
||||
local lazyElementsTimer = 0
|
||||
local isLazyElementsTimerActive = false
|
||||
|
||||
|Method|Returns|Description|
|
||||
|---|---|---|
|
||||
|[basalt.create](#basalt.create)|table|Creates a new UI element
|
||||
|[basalt.createFrame](#basalt.createFrame)|table|
|
||||
|[basalt.getAPI](#basalt.getAPI)|-|
|
||||
|[basalt.getElementManager](#basalt.getElementManager)|table|
|
||||
|[basalt.getMainFrame](#basalt.getMainFrame)|BaseFrame|
|
||||
|[basalt.removeSchedule](#basalt.removeSchedule)|-|
|
||||
|[basalt.run](#basalt.run)|-|
|
||||
|[basalt.scheduleUpdate](#basalt.scheduleUpdate)|number|
|
||||
|[basalt.setActiveFrame](#basalt.setActiveFrame)|-|
|
||||
|[basalt.stop](#basalt.stop)|-|
|
||||
|[basalt.update](#basalt.update)|-|
|
||||
|
||||
## basalt.create(type, properties?)
|
||||
Creates and returns a new UI element of the specified type.
|
||||
local function queueLazyElements()
|
||||
if(isLazyElementsTimerActive)then return end
|
||||
lazyElementsTimer = os.startTimer(0.2)
|
||||
isLazyElementsTimerActive = true
|
||||
end
|
||||
|
||||
### 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
|
||||
local function loadLazyElements(count)
|
||||
for _=1,count do
|
||||
local blueprint = lazyElements[1]
|
||||
if(blueprint)then
|
||||
blueprint:create()
|
||||
end
|
||||
table.remove(lazyElements, 1)
|
||||
end
|
||||
end
|
||||
|
||||
### Returns
|
||||
* `table` `element` The created element instance
|
||||
local function lazyElementsEventHandler(event, timerId)
|
||||
if(event=="timer")then
|
||||
if(timerId==lazyElementsTimer)then
|
||||
loadLazyElements(lazyElementCount)
|
||||
isLazyElementsTimerActive = false
|
||||
lazyElementsTimer = 0
|
||||
if(#lazyElements>0)then
|
||||
queueLazyElements()
|
||||
end
|
||||
return true
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
local button = basalt.create("Button")
|
||||
```
|
||||
--- Creates and returns a new UI element of the specified type.
|
||||
--- @shortDescription Creates a new UI element
|
||||
--- @param type string The type of element to create (e.g. "Button", "Label", "BaseFrame")
|
||||
--- @param properties? string|table Optional name for the element or a table with properties to initialize the element with
|
||||
--- @return table element The created element instance
|
||||
--- @usage local button = basalt.create("Button")
|
||||
function basalt.create(type, properties, lazyLoading, parent)
|
||||
if(_type(properties)=="string")then properties = {name=properties} end
|
||||
if(properties == nil)then properties = {name = type} end
|
||||
local elementClass = elementManager.getElement(type)
|
||||
if(lazyLoading)then
|
||||
local blueprint = propertySystem.blueprint(elementClass, properties, basalt, parent)
|
||||
table.insert(lazyElements, blueprint)
|
||||
queueLazyElements()
|
||||
return blueprint
|
||||
else
|
||||
local element = elementClass.new()
|
||||
element:init(properties, basalt)
|
||||
return element
|
||||
end
|
||||
end
|
||||
|
||||
## basalt.createFrame()
|
||||
Creates and returns a new frame
|
||||
--- Creates and returns a new frame
|
||||
--- @return table BaseFrame The created frame instance
|
||||
--- @usage local mainFrame = basalt.createFrame()
|
||||
function basalt.createFrame()
|
||||
local frame = basalt.create("BaseFrame")
|
||||
frame:postInit()
|
||||
mainFrame = frame
|
||||
return frame
|
||||
end
|
||||
|
||||
### Returns
|
||||
* `table` `BaseFrame` The created frame instance
|
||||
--- Returns the element manager instance
|
||||
--- @return table ElementManager The element manager
|
||||
--- @usage local manager = basalt.getElementManager()
|
||||
function basalt.getElementManager()
|
||||
return elementManager
|
||||
end
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
local mainFrame = basalt.createFrame()
|
||||
```
|
||||
--- Gets or creates the main frame
|
||||
--- @return BaseFrame table The main frame instance
|
||||
--- @usage local frame = basalt.getMainFrame()
|
||||
function basalt.getMainFrame()
|
||||
if(mainFrame == nil)then
|
||||
mainFrame = basalt.createFrame()
|
||||
end
|
||||
return mainFrame
|
||||
end
|
||||
|
||||
## basalt.getAPI()
|
||||
--- Sets the active frame
|
||||
--- @param frame table The frame to set as active
|
||||
--- @usage basalt.setActiveFrame(myFrame)
|
||||
function basalt.setActiveFrame(frame)
|
||||
mainFrame = frame
|
||||
end
|
||||
|
||||
## basalt.getElementManager()
|
||||
Returns the element manager instance
|
||||
--- Schedules a function to be updated
|
||||
--- @function scheduleUpdate
|
||||
--- @param func function The function to schedule
|
||||
--- @return number Id The schedule ID
|
||||
--- @usage local id = basalt.scheduleUpdate(myFunction)
|
||||
function basalt.scheduleUpdate(func)
|
||||
table.insert(basalt._schedule, func)
|
||||
return #basalt._schedule
|
||||
end
|
||||
|
||||
### Returns
|
||||
* `table` `ElementManager` The element manager
|
||||
--- Removes a scheduled update
|
||||
--- @function removeSchedule
|
||||
--- @param id number The schedule ID to remove
|
||||
--- @usage basalt.removeSchedule(scheduleId)
|
||||
function basalt.removeSchedule(id)
|
||||
basalt._schedule[id] = nil
|
||||
end
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
local manager = basalt.getElementManager()
|
||||
```
|
||||
--- @local Internal event handler
|
||||
local function updateEvent(event, ...)
|
||||
if(event=="terminate")then basalt.stop() end
|
||||
if lazyElementsEventHandler(event, ...) then return end
|
||||
|
||||
## basalt.getMainFrame()
|
||||
Gets or creates the main frame
|
||||
if(mainFrame)then
|
||||
if(mainFrame:dispatchEvent(event, ...))then
|
||||
return
|
||||
end
|
||||
end
|
||||
|
||||
### Returns
|
||||
* `BaseFrame` `table` The main frame instance
|
||||
if basalt._events[event] then
|
||||
for _, callback in ipairs(basalt._events[event]) do
|
||||
callback(...)
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
local frame = basalt.getMainFrame()
|
||||
```
|
||||
--- @local Internal render function
|
||||
local function renderFrames()
|
||||
if(mainFrame)then
|
||||
mainFrame:render()
|
||||
end
|
||||
end
|
||||
|
||||
## basalt.removeSchedule(id)
|
||||
Removes a scheduled update
|
||||
--- Updates all scheduled functions
|
||||
--- @usage basalt.update()
|
||||
function basalt.update()
|
||||
for k,v in pairs(basalt._schedule) do
|
||||
if type(v)=="function" then
|
||||
v()
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
### Parameters
|
||||
* `id` `number` The schedule ID to remove
|
||||
--- Stops the Basalt runtime
|
||||
--- @usage basalt.stop()
|
||||
function basalt.stop()
|
||||
term.clear()
|
||||
term.setCursorPos(1,1)
|
||||
updaterActive = false
|
||||
end
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
basalt.removeSchedule(scheduleId)
|
||||
```
|
||||
--- Starts the Basalt runtime
|
||||
--- @param isActive? boolean Whether to start active (default: true)
|
||||
--- @usage basalt.run()
|
||||
--- @usage basalt.run(false)
|
||||
function basalt.run(isActive)
|
||||
updaterActive = isActive
|
||||
if(isActive==nil)then updaterActive = true end
|
||||
local function f()
|
||||
renderFrames()
|
||||
while updaterActive do
|
||||
updateEvent(os.pullEventRaw())
|
||||
renderFrames()
|
||||
end
|
||||
end
|
||||
while updaterActive do
|
||||
local ok, err = pcall(f)
|
||||
if not(ok)then
|
||||
errorManager.header = "Basalt Runtime Error"
|
||||
errorManager.error(err)
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
## basalt.run(isActive?)
|
||||
Starts the Basalt runtime
|
||||
function basalt.getAPI(name)
|
||||
return elementManager.getAPI(name)
|
||||
end
|
||||
|
||||
### Parameters
|
||||
* `isActive` *(optional)* `boolean` Whether to start active (default: true)
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
basalt.run()
|
||||
basalt.run(false)
|
||||
```
|
||||
|
||||
## basalt.scheduleUpdate(func)
|
||||
Schedules a function to be updated
|
||||
|
||||
### Parameters
|
||||
* `func` `function` The function to schedule
|
||||
|
||||
### Returns
|
||||
* `number` `Id` The schedule ID
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
local id = basalt.scheduleUpdate(myFunction)
|
||||
```
|
||||
|
||||
## basalt.setActiveFrame(frame)
|
||||
Sets the active frame
|
||||
|
||||
### Parameters
|
||||
* `frame` `table` The frame to set as active
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
basalt.setActiveFrame(myFrame)
|
||||
```
|
||||
|
||||
## basalt.stop()
|
||||
Stops the Basalt runtime
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
basalt.stop()
|
||||
```
|
||||
|
||||
## basalt.update()
|
||||
Updates all scheduled functions
|
||||
|
||||
### Usage
|
||||
```lua
|
||||
basalt.update()
|
||||
```
|
||||
|
||||
return basalt
|
||||
Reference in New Issue
Block a user