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

Updated docs

Browse Source 
There is still stuff to do
This commit is contained in:
Robert Jelic
2022-08-28 18:18:26 +02:00
parent 53d7b9f70c
commit 4d614372a1
207 changed files with 3868 additions and 3785 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/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/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/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()
```

34
docs/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)

60
docs/tips/logic.md
View File

@@ -1,56 +1,70 @@
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
[Here (tweaked.cc)](https://tweaked.cc/module/parallel.html) you can find out more about the parallel API.
## Method 2:
Using threads
## 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
```