Small Docs Update
This commit is contained in:
Robert Jelic
@@ -4,6 +4,7 @@
|
||||
|
||||
Basalt is a user-friendly UI framework for CC:Tweaked (also known as "ComputerCraft: Tweaked") - a popular Minecraft mod. It was developed to enhance user interaction through visual displays. In this wiki, you'll find information on how to use Basalt as well as examples of functional Basalt code.
|
||||
|
||||
This Website is made with the help of ChatGPT.
|
||||
|
||||
## About Basalt
|
||||
|
||||
|
||||
@@ -1 +1,3 @@
|
||||
Thanks for checking out our wiki, join our discord for more help: [discord.gg/yM7kndJdJJ](discord.gg/yM7kndJdJJ)
|
||||
---
|
||||
|
||||
Thanks for checking out our wiki, join our discord for more help: [discord.gg/yM7kndJdJJ](discord.gg/yNNnmBVBpE)
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
[1.6 Docs](https://basalt.madefor.cc/docs1_6)
|
||||
|
||||
- About
|
||||
- [Home](home)
|
||||
- [Home](/)
|
||||
- [How To](home/How-To)
|
||||
- [Download](home/download)
|
||||
- [1.6 Docs](docs1_6)
|
||||
- Objects
|
||||
- [Basalt](objects/Basalt.md)
|
||||
- [Object](objects/Object.md)
|
||||
@@ -33,9 +34,5 @@
|
||||
- [Thread](objects/Thread.md)
|
||||
- [Treeview](objects/Treeview.md)
|
||||
- [Timer](objects/Timer.md)
|
||||
- Tutorials
|
||||
- [Your Logic](tips/logic.md)
|
||||
- [Button coloring](tips/buttonColoring.md)
|
||||
- [Designing/Animating](tips/design.md)
|
||||
- [Dynamic Values](tips/dynamicvalues.md)
|
||||
- [XML](tips/xml.md)
|
||||
- Guides
|
||||
- [Introduction to Basalt](guides/introduction.md)
|
||||
|
||||
42
docs/guides/introduction.md
Normal file
42
docs/guides/introduction.md
Normal file
@@ -0,0 +1,42 @@
|
||||
Basalt is a powerful and flexible user interface (UI) framework designed to make it easy for developers to create visually appealing and interactive applications. This guide will provide an overview of Basalt, its main components, and the basic concepts and terminology used in the framework.
|
||||
|
||||
## What is Basalt?
|
||||
|
||||
Basalt is a UI framework that simplifies the process of creating, designing, and managing user interfaces for various applications. It provides a wide range of UI elements and components, such as frames, buttons, labels, text fields, and more, making it easier for developers to create custom and responsive layouts without having to worry about the low-level details of UI rendering and event handling.
|
||||
|
||||
## Main Components of Basalt
|
||||
|
||||
Basalt consists of several key components that work together to create a seamless user interface experience. Some of the main components include:
|
||||
|
||||
1. Objects: Basalt objects represent the various UI elements that make up an application's interface. Examples of objects include frames, buttons, text fields, and more. Each object comes with a set of properties and methods that allow you to customize its appearance and behavior.
|
||||
|
||||
2. Frames: Frames are the primary containers for organizing and laying out UI objects in Basalt. They can be nested, allowing for complex and hierarchical layouts. Basalt provides different types of frames, such as basic frames, movable frames, scrollable frames, and flexboxes, each with their own unique properties and use cases.
|
||||
|
||||
3. Events: Events are triggered by user interactions, such as clicks, keypresses, and other inputs. Basalt provides an event handling system that allows you to easily respond to these events and update your application's interface or behavior accordingly.
|
||||
|
||||
4. Threading: Basalt supports the use of threads in applications, enabling concurrent actions and background processes to run without blocking the main program.
|
||||
|
||||
This introduction should give you a basic understanding of Basalt and its main components. As you continue to explore the framework and its features, you'll gain a deeper understanding of how to create and customize your own applications using Basalt.
|
||||
|
||||
## Layout Management
|
||||
|
||||
Understanding how to manage and organize the layout of UI objects is important when working with Basalt. You can use different types of frames, such as Flexbox or ScrollableFrame, to create responsive and adaptive layouts for your applications.
|
||||
|
||||
```lua
|
||||
local main = basalt.createFrame() -- The main frame/most important frame in your project
|
||||
|
||||
local column1 = main:addFrame():setSize("parent.w/2", "parent.h")
|
||||
local column2 = main:addFrame():setSize("parent.w/2", "parent.h"):setPosition("parent.w/2+1", 1)
|
||||
```
|
||||
|
||||
## Input Handling
|
||||
|
||||
Handling user input, such as text input or slider adjustments, is essential for creating interactive applications. Basalt provides various UI elements for capturing user input and events for processing the input.
|
||||
|
||||
```lua
|
||||
local mainFrame = basalt.createFrame()
|
||||
local aInput = mainFrame:addInput()
|
||||
aInput:onChange(function(text)
|
||||
basalt.debug("User entered: " .. text)
|
||||
end)
|
||||
```
|
||||
@@ -41,11 +41,11 @@
|
||||
loadSidebar: true,
|
||||
loadFooter: '_footer.md',
|
||||
autoHeader: true,
|
||||
subMaxLevel: 3,
|
||||
homepage: 'Home.md',
|
||||
name: 'Basalt',
|
||||
repo: 'https://github.com/Pyroxenium/Basalt',
|
||||
auto2top: true,
|
||||
noCompileLinks: ['/docs1_6'],
|
||||
search: {
|
||||
maxAge: 86400000, // Expiration time, the default one day
|
||||
paths: 'auto',
|
||||
|
||||
@@ -1,80 +0,0 @@
|
||||
Here i will explain to you how you can add some coloring to your buttons in certain events. This is not only for buttons possible but also for all the other visual objects
|
||||
|
||||
But first, i want to explain to you that you can also add the same event-type multiple times:
|
||||
```lua
|
||||
local function buttonColoring(self, event, button, x, y)
|
||||
-- here you can add some coloring for your button - for example:
|
||||
self:setBackground(colors.black)
|
||||
end
|
||||
local function buttonLogic(self, event, button, x, y)
|
||||
-- here you can add some logic for your button
|
||||
basalt.debug("Some logic")
|
||||
end
|
||||
local button = main:addButton()
|
||||
button:onClick(buttonColoring):onClick(buttonLogic) -- yes this would work, if not its a bug!
|
||||
```
|
||||
This means you can create a function wich handles only the coloring side of your button, and if your button also needs some logic you just create another function for that and add it to your button.
|
||||
|
||||
|
||||
Now let's create a function where we pass a button object as an argument on which we set up the coloring
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
local main = basalt.createFrame()
|
||||
local button = main:addButton()
|
||||
:setPosition(3,3)
|
||||
:setSize(12,3)
|
||||
:setText("Click me")
|
||||
:setBackground(colors.gray)
|
||||
:setForeground(colors.black)
|
||||
|
||||
local button2 = main:addButton()
|
||||
:setPosition(25,3)
|
||||
:setSize(16,3)
|
||||
:setText("Another Btn")
|
||||
:setBackground(colors.gray)
|
||||
:setForeground(colors.black)
|
||||
|
||||
local function setupButtonColoring(self, event, button, x, y)
|
||||
self:onClick(function()
|
||||
self:setBackground(colors.black)
|
||||
self:setForeground(colors.lightGray)
|
||||
end)
|
||||
self:onClickUp(function()
|
||||
self:setBackground(colors.gray)
|
||||
self:setForeground(colors.black)
|
||||
end)
|
||||
self:onLoseFocus(function()
|
||||
self:setBackground(colors.gray)
|
||||
self:setForeground(colors.black)
|
||||
end)
|
||||
end
|
||||
|
||||
setupButtonColoring(button)
|
||||
setupButtonColoring(button2)
|
||||
|
||||
basalt.autoUpdate()
|
||||
```
|
||||
|
||||
Now you got a button which changes the color when you click on it.
|
||||
|
||||
|
||||
There is also another way of doing it, but this is time based, which means it does not check if the user is holding the mousebutton down.
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.createFrame()
|
||||
local button = main:addButton()
|
||||
:setPosition(3,3)
|
||||
:setSize(12,3)
|
||||
:setText("Click me")
|
||||
:setBackground(colors.gray)
|
||||
:setForeground(colors.black)
|
||||
|
||||
button:onClick(basalt.schedule(function()
|
||||
button:setBackground(colors.black)
|
||||
sleep(0.5)
|
||||
button:setBackground(colors.gray)
|
||||
end))
|
||||
```
|
||||
|
||||
Here you are using basalt.schedule, which will start the function in a coroutine
|
||||
@@ -1,112 +0,0 @@
|
||||
Hello! This page contains some tips on how to create cool designs with Basalt
|
||||
|
||||
To understand this page, it is recommended to familiarize yourself with [Animations](../objects/Animation.md) as animations are important for creating cool looking designs
|
||||
|
||||
## Animation-move
|
||||
Here i will show you how you can move objects by using the animation object.
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.createFrame()
|
||||
local sub = main:addFrame():setSize("parent.w - 2",12):setPosition("-parent.w",4)
|
||||
sub:addLabel()
|
||||
:setText("Cool Title")
|
||||
:setBackground(colors.black)
|
||||
:setForeground(colors.lightGray)
|
||||
:setSize("parent.w", 1)
|
||||
|
||||
local button = sub:addButton()
|
||||
:setBackground(colors.black)
|
||||
:setForeground(colors.lightGray)
|
||||
:setPosition(-12,9)
|
||||
local button2 = sub:addButton()
|
||||
:setBackground(colors.black)
|
||||
:setForeground(colors.lightGray)
|
||||
:setPosition("parent.w + 12",9)
|
||||
|
||||
local anim = main:addAnimation()
|
||||
:setObject(sub)
|
||||
:move(2,4,1.5)
|
||||
:setObject(button)
|
||||
:move(2,9,1,1.5)
|
||||
:setObject(button2)
|
||||
:move(sub:getWidth()-12,9,1,1.5)
|
||||
:play()
|
||||
|
||||
basalt.autoUpdate()
|
||||
```
|
||||
|
||||
As you can see, you only need 1 animation but you can still move 3 objects.
|
||||
|
||||
## Animation-offset
|
||||
Here is a example which changes the offset on your base frame. It shows you, how you could create multiple pages and switch between them in a cool looking way:
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.createFrame()
|
||||
local mainAnim = main:addAnimation()
|
||||
|
||||
local frames = {
|
||||
main:addFrame():setPosition(1,2):setSize("parent.w", "parent.h-1"):setBackground(colors.lightGray),
|
||||
main:addFrame():setPosition("parent.w+1",2):setSize("parent.w", "parent.h-1"):setBackground(colors.lightGray),
|
||||
main:addFrame():setPosition("parent.w*2+1",2):setSize("parent.w", "parent.h-1"):setBackground(colors.lightGray),
|
||||
main:addFrame():setPosition("parent.w*3+1",2):setSize("parent.w", "parent.h-1"):setBackground(colors.lightGray),
|
||||
}
|
||||
|
||||
frames[1]:addLabel():setText("This is frame 1")
|
||||
frames[2]:addLabel():setText("This is frame 2")
|
||||
frames[3]:addLabel():setText("This is frame 3")
|
||||
frames[4]:addLabel():setText("This is frame 4")
|
||||
|
||||
local menubar = main:addMenubar():ignoreOffset()
|
||||
:addItem("Page 1",nil,nil,1)
|
||||
:addItem("Page 2",nil,nil,2)
|
||||
:addItem("Page 3",nil,nil,3)
|
||||
:addItem("Page 4",nil,nil,4)
|
||||
:setSpace(3)
|
||||
:setSize("parent.w",1)
|
||||
:onChange(function(self, value)
|
||||
mainAnim:clear()
|
||||
:cancel()
|
||||
:setObject(main)
|
||||
:offset(value.args[1] * main:getWidth() - main:getWidth(), 0, 2)
|
||||
:play()
|
||||
end)
|
||||
|
||||
|
||||
basalt.autoUpdate()
|
||||
```
|
||||
|
||||
## Visually showing
|
||||
Here I'll show you how to visually show the user when something isn't working. this is just one example that you can apply to other topics as well.
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local password = "12345"
|
||||
|
||||
local main = basalt.createFrame()
|
||||
|
||||
main:addLabel():setText("Password:"):setPosition(2,2)
|
||||
local input = main:addInput():setInputType("password"):setPosition(2,3):setSize(24,1)
|
||||
local submit = main:addButton():setPosition(2,5):setText("Submit")
|
||||
submit:onClick(basalt.schedule(function()
|
||||
if(password==input:getValue())then
|
||||
basalt.debug("Password correct!")
|
||||
else
|
||||
basalt.debug("Wrong password!")
|
||||
submit:setBackground(colors.red)
|
||||
sleep(0.05)
|
||||
submit:setPosition(3,5)
|
||||
sleep(0.05)
|
||||
submit:setPosition(2,5)
|
||||
sleep(0.05)
|
||||
submit:setPosition(1,5)
|
||||
sleep(0.05)
|
||||
submit:setPosition(2,5)
|
||||
submit:setBackground(colors.gray)
|
||||
end
|
||||
end))
|
||||
|
||||
basalt.autoUpdate()
|
||||
```
|
||||
@@ -1,54 +0,0 @@
|
||||
Dynamic Values is a way to position or size your object based on the position/size of other objects. This makes it pretty easy to create programs where the terminal size
|
||||
doesn't matter.
|
||||
|
||||
A dynamic value is always a string, and you can add anything you want in there. Here are some examples:<br>
|
||||
"5 + 2"<br>
|
||||
"(5 + 2) * 3"<br>
|
||||
"math.floor(5+2.2)"<br>
|
||||
"objectid.x + objectid.y + objectid.w + objectid+h"<br>
|
||||
"parent.w"<br>
|
||||
"self.w"<br>
|
||||
|
||||
Parent always refers to it's parent object, self always refers to itself.
|
||||
|
||||
## Positioning
|
||||
Here i will show you a example on how to position a button next to another button, doesn't matter which size it has.
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.createFrame()
|
||||
|
||||
local button = main:addButton("firstBtn")
|
||||
:setBackground(colors.black)
|
||||
:setForeground(colors.lightGray)
|
||||
:setPosition(2, 2)
|
||||
local button2 = main:addButton()
|
||||
:setBackground(colors.black)
|
||||
:setForeground(colors.lightGray)
|
||||
:setPosition("firstBtn.w + firstBtn.x + 2", "firstBtn.y")
|
||||
|
||||
basalt.autoUpdate()
|
||||
```
|
||||
Now, you can move the first button and the second button would also move. Doesn't matter how.
|
||||
|
||||
## Sizing
|
||||
This is a example on how you can create buttons where the size is always based on it's parent frame
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.createFrame()
|
||||
|
||||
local button = main:addButton("firstBtn")
|
||||
:setBackground(colors.black)
|
||||
:setForeground(colors.lightGray)
|
||||
:setPosition(2, 2)
|
||||
:setSize("parent.w - 2", 3)
|
||||
local button2 = main:addButton()
|
||||
:setBackground(colors.black)
|
||||
:setForeground(colors.lightGray)
|
||||
:setPosition(2, "firstBtn.y + firstBtn.h + 1")
|
||||
:setSize("parent.w - 2", 3)
|
||||
|
||||
basalt.autoUpdate()
|
||||
```
|
||||
@@ -1,95 +0,0 @@
|
||||
You question yourself how you can execute your own logic while basalt is also active? There are multiple ways of doing that:
|
||||
|
||||
## Parallel
|
||||
|
||||
Using parallel.waitForAll or parallel.waitForAny
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.createFrame() -- we need a base frame
|
||||
main:addButton() -- just a button
|
||||
:onClick(function()
|
||||
basalt.debug("Button got clicked")
|
||||
end)
|
||||
|
||||
local function yourCustomHandler()
|
||||
while true do
|
||||
-- add your logic here
|
||||
os.sleep(1) -- you need something which calls coroutine.yield(), yes os.sleep() does that and os.pullEvent() too
|
||||
end
|
||||
end
|
||||
|
||||
parallel.waitForAll(basalt.autoUpdate, yourCustomHandler) -- here it will handle your function (yourCustomHandler) and basalt's handlers at the same time using parallel's API
|
||||
```
|
||||
|
||||
[Here (tweaked.cc)](https://tweaked.cc/module/parallel.html) you can find out more about the parallel API.
|
||||
|
||||
## Threads
|
||||
|
||||
Using basalt's thread implementation.
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.createFrame() -- we need a base frame
|
||||
main:addButton() -- just a button
|
||||
:onClick(function()
|
||||
basalt.debug("Button got clicked")
|
||||
end)
|
||||
|
||||
local thread = mainFrame:addThread() -- here we create a thread
|
||||
|
||||
local function yourCustomHandler()
|
||||
while true do
|
||||
-- add your logic here
|
||||
os.sleep(1) -- you need something which calls coroutine.yield(), yes os.sleep() does that and os.pullEvent() too
|
||||
end
|
||||
end
|
||||
thread:start(yourCustomHandler) -- here we start the thread and pass the function which you want to run.
|
||||
```
|
||||
|
||||
## Timers
|
||||
|
||||
Using basalt's implementation of timers.
|
||||
Remember, timers don't run asynchronly which means if you're using sleep somewhere this will freeze basalt's event system too.
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.createFrame() -- we need a base frame
|
||||
main:addButton() -- just a button
|
||||
:onClick(function()
|
||||
basalt.debug("Button got clicked")
|
||||
end)
|
||||
|
||||
local timer = mainFrame:addTimer() -- here we will create the timer object
|
||||
|
||||
local function yourCustomHandler()
|
||||
-- add your logic here
|
||||
end
|
||||
timer:onCall(yourCustomHandler)
|
||||
:setTime(1, -1)
|
||||
:start() -- this will call your function every second until you :cancel() the timer
|
||||
```
|
||||
|
||||
## Schedule
|
||||
|
||||
Using basalt's schedule implementation.
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
local main = basalt.createFrame() -- we need a base frame
|
||||
main:addButton() -- just a button
|
||||
:onClick(function()
|
||||
basalt.debug("Button got clicked")
|
||||
end)
|
||||
|
||||
local yourCustomHandler = basalt.schedule(function() -- create a new schedule task
|
||||
-- add your logic here
|
||||
end)
|
||||
|
||||
yourCustomHandler() -- execute the schedule task
|
||||
|
||||
```
|
||||
@@ -1,79 +0,0 @@
|
||||
This is a basic guide on how to create a UI with XML.
|
||||
|
||||
In XML you are not able to create logic, but you could refer to logic - i will show you how.
|
||||
But first i will show you how you are able to create some basic XML design.
|
||||
|
||||
First we will need a .lua file - we need to process the XML stuff, and this is only possible in lua.
|
||||
So let's create a lua file:
|
||||
|
||||
```lua
|
||||
local basalt = require("basalt") -- as always we will need basalt
|
||||
|
||||
local main = basalt.createFrame() -- and atleast 1 base frame is needed
|
||||
|
||||
basalt.autoUpdate() -- starting the event and draw handler is also needed
|
||||
```
|
||||
|
||||
The code above you are just not able to do in XML, you are not able to create base frames and you are also not able to start the event/draw handlers.
|
||||
This can only be done in Lua.
|
||||
|
||||
In Basalt XML Code will always be loaded into frames. Which means all the objects created in XML are always childrens of that particular frame. Here is a example to show what i mean:
|
||||
|
||||
Lua:
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
local main = basalt.createFrame():addLayout("example.xml")
|
||||
basalt.autoUpdate()
|
||||
```
|
||||
|
||||
XML:
|
||||
```xml
|
||||
<button x="5" y="3" text="Hello" />
|
||||
```
|
||||
|
||||
This would be exactly the same like if you would use the following lua code:
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
local main = basalt.createFrame()
|
||||
main:addButton():setPosition(5, 3):setText("Hello")
|
||||
basalt.autoUpdate()
|
||||
```
|
||||
|
||||
You can also add a layout multiple times, or create multiple frames and always use the same layout. For example a design layout for more frames and then you could also use
|
||||
a unique layout for each frame. I wont show you a example, you just have to use :addLayout multiple times on different frames.
|
||||
|
||||
Another thing is, you could add/load XML files IN XML:
|
||||
example.xml:
|
||||
```xml
|
||||
<frame layout="anotherExample.xml" />
|
||||
```
|
||||
|
||||
anotherExample.xml:
|
||||
```xml
|
||||
<button x="2" y="3" width="parent.w - 2" text="Greetings" />
|
||||
```
|
||||
|
||||
# Events
|
||||
|
||||
Using events in XML is also pretty simple. For that basalt has a function called basalt.setVariable. This is to store functions or other things which you can access via
|
||||
XML. Obviously the logic you want to add has to be done in lua, here:
|
||||
|
||||
Lua:
|
||||
```lua
|
||||
local basalt = require("basalt")
|
||||
|
||||
basalt.setVariable("buttonClick", function()
|
||||
basalt.debug("i got clicked!")
|
||||
end)
|
||||
|
||||
local main = basalt.createFrame():addLayout("example.xml")
|
||||
basalt.autoUpdate()
|
||||
```
|
||||
|
||||
And then you just have to link your function in your XML file:
|
||||
```xml
|
||||
<button x="2" y="3" width="parent.w - 2" text="Greetings" onClick="buttonClick" />
|
||||
```
|
||||
|
||||
This is pretty simple! BUT there is one thing you shouldn't forget: In Lua you always have to create the function's before you want to access it, which means
|
||||
always use basalt.setVariable before you use frame:addLayout() - otherwise basalt is not able to find the function
|
||||
Reference in New Issue
Block a user