GitHub/Basalt
1
0
Fork 0
Code Issues 28 Pull Requests 3 Actions Packages Projects Releases 9 Wiki Activity

Docs 1.6

Browse Source 
Accidentally uploaded outdated 1.6 docs
This commit is contained in:
Robert Jelic
2023-05-01 16:28:46 +02:00
parent 92b93a3862
commit d4c72514ef
265 changed files with 25608 additions and 3867 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/docs1_6/tips/buttonColoring.md Normal file
View File

@@ -0,0 +1,80 @@
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

41
docs/docs1_6/tips/buttons.md
View File

@@ -1,41 +0,0 @@
Here I want to explain to you how you would create a button with the default color gray, and as long as the user is clicking on the button it will change its color to black (the default frame-background is lightGray).
To make this possible the button needs 1 onClick event, 1 onClickUp event and 1 onLoseFocus event.
Very interesting sidetip: events can hold multiple functions!<br>
**Example snippet:**
```lua
local function buttonColoring()
-- here you can add some coloring for your button
end
local function buttonLogic()
-- here you can add some logic for your button
end
local button = mainFrame:addButton("ExampleButton"):show()
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 your own unique function for that and add it to your button.
With this knowledge we create now a function where we pass a button-object as parameter and this will setup the coloring of our button:
**Example snippet:**
```lua
local basalt = dofile("basalt.lua")
local mainFrame = basalt.createFrame("mainFrame"):show()
local button = mainFrame:addButton("firstButton"):setPosition(3,3):setSize(12,3):setText("Click me"):setBackground(colors.gray):setForeground(colors.black):show()
local button2 = mainFrame:addButton("secondButton"):setPosition(25,3):setSize(16,3):setText("Another Btn"):setBackground(colors.gray):setForeground(colors.black):show()
local function setupButtonColoring(btn)
btn:onClick(function() btn:setBackground(colors.black) btn:setForeground(colors.lightGray) end)
btn:onClickUp(function() btn:setBackground(colors.gray) btn:setForeground(colors.black) end)
btn:onLoseFocus(function() btn:setBackground(colors.gray) btn:setForeground(colors.black) end)
end
setupButtonColoring(button)
setupButtonColoring(button2)
basalt.autoUpdate()
```
Now you've got a function which sets your buttons up.

172
docs/docs1_6/tips/design.md
View File

@@ -1,82 +1,112 @@
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 complex designs
To understand this page, it is recommended to familiarize yourself with [Animations](../objects/Animation.md) as animations are important for creating cool looking designs
Let us begin with simple things:
## Recolor objects
Let's create a Button:
## Animation-move
Here i will show you how you can move objects by using the animation object.
```lua
local basalt = require("Basalt")
local mainFrame = basalt.createFrame():setBackground(colors.black):show()
local aButton = mainFrame:addButton():setSize(10, 3):setText("Beautiful"):setBackground(colors.gray):show()
```
local basalt = require("basalt")
Here lets make use of the event system:<br>
```lua
local function changeButtonColor(self,event,typ,x,y)
if(event=="mouse_click")then
self:setBackground(colors.lightGray)
end
if(event=="mouse_up")then
self:setBackground(colors.gray)
end
end
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 function buttonLogic()
-- here you can do some logic when button gets the mouse_up event
end
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)
aButton:onClick(changeButtonColor) -- button color change on click
aButton:onClickUp(changeButtonColor) -- button color change on click up
aButton:onClickUp(buttonLogic) -- button logic on click up
aButton:onLoseFocus(function(self) self:setBackground(colors.gray) end) -- if user is clicking on the button and dragging out of button size this event will change the bg color back to gray
```
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()
## Fade In/Out Objects
instead of recoloring we are also able to slowly reposition the button, something like fade in:<br>
```lua
local buttonAnimation = mainFrame:addAnimation()
local function fadeButtonIn(btn)
if(btn.x < 5)then
btn:setPosition(1,0,"r")
else
buttonAnimation:cancel() -- here you cancel the loop
end
end
buttonAnimation:wait(0.1):add(function() fadeButtonIn(aButton) end):play(true) -- with play(true) you will create a infinite loop
```
This is also possible with entire frames and its children objects. So keep that in mind if you want to create something like a bigger panel to the right or a menu bar
## How To use XML
Here is a example on how to create a cool looking frame by using xml:
```xml
<frame width="parent.w/2" bg="gray" scrollable="true" importantScroll="true">
<button x="2" y="2" width="parent.w-2" bg="black" fg="lightGray" text="Example Button 1!"/>
<button x="2" y="6" width="parent.w-2" bg="black" fg="lightGray" text="Example Button 2!"/>
<button x="2" y="10" width="parent.w-2" bg="black" fg="lightGray" text="Example Button 3!"/>
<button x="2" y="14" width="parent.w-2" bg="black" fg="lightGray" text="Example Button 4!"/>
<button x="2" y="18" width="parent.w-2" bg="black" fg="lightGray" text="Example Button 5!"/>
<button x="2" y="22" width="parent.w-2" bg="black" fg="lightGray" text="Example Button 6!"/>
<button x="2" y="26" width="parent.w-2" bg="black" fg="lightGray" text="Example Button 7!"/>
</frame>
<frame x="parent.w/2+1" width="parent.w/2+1" bg="black">
<textfield bg="gray" x="2" y="2" width="parent.w-2">
<lines>
<line>This is line 1.</line>
<line>And this is line 2.</line>
</lines>
</textfield>
<label anchor="bottomLeft" x="2" y="0" text="I love labels!" fg="lightGray"/>
</frame>
```
in your lua code you just have to add this layout to your frame:
```lua
local basalt = require("Basalt")
basalt.createFrame():addLayout("example.xml")
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()
```

54
docs/docs1_6/tips/dynamicvalues.md Normal file
View File

@@ -0,0 +1,54 @@
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()
```

34
docs/docs1_6/tips/events.md
View File

@@ -1,34 +0,0 @@
## Short way of adding functions to events
Not everyone knows that a function (or in other words a method) does not need to have a name. Instead of a function name you are also able to add the function itself as a argument.
Both do the exact same thing:
```lua
local function clickButton()
basalt.debug("I got clicked!")
end
button:onClick(clickButton)
```
```lua
button:onClick(function()
basalt.debug("I got clicked!")
end)
```
## Using isKeyDown for shortcuts
there is also a function with which you can check if the user is holding a key down, it is called `basalt.isKeyDown()`. It's especially useful for click events.
Let us say you want a button to execute something, but if you are holding ctrl down, something in the execution should get changed. This is how you would
achieve that:
```lua
button:onClick(function()
if(basalt.isKeyDown(keys.leftCtrl)then
basalt.debug("Ctrl is down!")
else
basalt.debug("Ctrl is up!")
end
end)
```
Make sure to always use the available `keys` table: https://computercraft.info/wiki/Keys_(API)

87
docs/docs1_6/tips/logic.md
View File

@@ -1,56 +1,95 @@
You question yourself how you can execute your own logic while basalt is also active? There are multiple ways of doing that:
## Method 1:
Using parallel.waitForAll
## Parallel
Using parallel.waitForAll or parallel.waitForAny
```lua
local basalt = dofile("basalt.lua")
local basalt = require("basalt")
local mainFrame = basalt.createFrame("mainFrame"):show()-- lets create a frame and a button without functionality
mainFrame:addButton("aButton"):onClick(function() end):show()
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 os.pullEvent() aswell
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 basalts handlers at the time
parallel.waitForAll(basalt.autoUpdate, yourCustomHandler) -- here it will handle your function (yourCustomHandler) and basalt's handlers at the same time using parallel's API
```
You can read [here (tweaked.cc)](https://tweaked.cc/module/parallel.html) what exactly parallel.waitForAll() does
## Method 2:
Using threads
[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 = dofile("basalt.lua")
local basalt = require("basalt")
local mainFrame = basalt.createFrame("mainFrame"):show()-- lets create a frame, a button without functionality and a thread
mainFrame:addButton("aButton"):onClick(function() end):show()
local thread = mainFrame:addThread("customHandlerExecutingThread")
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 os.pullEvent() aswell
os.sleep(1) -- you need something which calls coroutine.yield(), yes os.sleep() does that and os.pullEvent() too
end
end
thread:start(yourCustomHandler) -- this will create a coroutine and starts the coroutine, os.sleep does the rest, so you just have to call start once.
thread:start(yourCustomHandler) -- here we start the thread and pass the function which you want to run.
```
## Method 3:
Using timers
## 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 = dofile("basalt.lua")
local basalt = require("basalt")
local mainFrame = basalt.createFrame("mainFrame"):show()-- lets create a frame, a button without functionality and a timer
mainFrame:addButton("aButton"):onClick(function() end):show()
local timer = mainFrame:addTimer("customHandlerExecutingTimer")
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
```
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
```

79
docs/docs1_6/tips/xml.md Normal file
View File

@@ -0,0 +1,79 @@
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