Merge remote-tracking branch 'origin/master'

# Conflicts:
#	docs/home/gettingStarted.md
#	docs/home/installer.md
#	docs/tips/logic.md
This commit is contained in:
Samuel Pizette
2022-06-09 11:08:46 -04:00
37 changed files with 675 additions and 430 deletions

View File

@@ -1,24 +1,24 @@
# Welcome to The Basalt Wiki!<br>
# Welcome to The Basalt Wiki!
_Note: The Basalt Wiki is a work in progress. Please treat Wiki errors the same as bugs and report them accordingly._
*Note: The Basalt Wiki is a work in progress. Please treat Wiki errors the same as bugs and report them accordingly.*
Here you can find information about how to use Basalt as well as examples of functional Basalt code. The aim of Basalt is to improve user interaction through visual display.
## About Basalt
Basalt is intended to be an easy-to-understand UI Framework designed for CC:Tweaked (AKA Computer Craft: Tweaked) - a popular minecraft mod. For more information about CC:Tweaked, checkout the project's <a href="https://tweaked.cc/">home page</a>.
<br><br>
Basalt is intended to be an easy-to-understand UI Framework designed for CC:Tweaked (Also know as "ComputerCraft: Tweaked") - a popular minecraft mod. For more information about CC:Tweaked, checkout the project's [wiki](https://tweaked.cc/) or [download](https://www.curseforge.com/minecraft/mc-mods/cc-tweaked).
## Quick Demo
![Preview](https://media0.giphy.com/media/fvmNPshXKeU7FFA9iA/giphy.gif)
<br><br>
## Questions & Bugs
Obviously I've implemented some easter eggs, _some people_ call them "bugs". If you happen to discover one of these just make a new <a href="https://github.com/NoryiE/Basalt/issues">issue</a>.
Obviously NyoriE has implemented some easter eggs, *some people* call them "bugs". If you happen to discover one of these just make a new <a href="https://github.com/Pyroxenium/Basalt/issues">issue</a>.
Additionally, if you have questions about Basalt or how to make use of it, feel free to create a new discussion on <a href="https://github.com/NoryiE/Basalt/discussions">Basalt's Discussion Board</a>.
Additionally, if you have questions about Basalt or how to make use of it, feel free to create a new discussion on <a href="https://github.com/Pyroxenium/Basalt/discussions">Basalt's Discussion Board</a>, or ask in our [discord](https://discord.gg/yNNnmBVBpE).
You may also message me on Discord: NyoriE#8206
---
Feel free to join our [discord](https://discord.gg/yNNnmBVBpE)!
<br><br>

BIN
docs/_media/installer.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.6 KiB

View File

@@ -3,7 +3,7 @@
- [Quick Start](home/Quick-Start.md)
- [Installer](home/installer)
- Objects
- [Animation](objects/Animation.md)
- [Object](objects/Object)
- [Basalt](objects/Basalt)
- [Button](objects/Button)
- [Checkbox](objects/Checkbox)
@@ -14,16 +14,18 @@
- [Label](objects/Label)
- [List](objects/List)
- [Menubar](objects/Menubar)
- [Object](objects/Object)
- [Pane](objects/Pane)
- [Program](objects/Program)
- [Radio](objects/Radio)
- [Scrollbar](objects/Scrollbar)
- [Slider](objects/Slider)
- [Text Field](objects/Textfield)
- [Animation](objects/Animation.md)
- [Thread](objects/Thread)
- [Timer](objects/Timer)
- Events
- [Mouse Events](events/mouseEvents.md)
- Tips & Tricks
- [Component Logic](tips/logic)
- [Changing Button Color](tips/buttons)
- [Changing Button Color](tips/buttons)
- [Advanced usage of Events](tips/events.md)

View File

@@ -0,0 +1,63 @@
Here we will talk about mouse events and how you can manipulate them. There are 2 possible mouse events you can add to almost every visual object.
# onClick
`onClick(self, button, x, y)`<br>
The computercraft event which triggers this method is `mouse_click` and `monitor_touch`.
Any visual object can register onClick events.
Here is a example on how to add a onClick event to your button:
```lua
local basalt = dofile("basalt.lua")
local mainFrame = basalt.createFrame("myMainFrame"):show()
local button = mainFrame:addButton("myButton"):setPosition(3,3):setSize(12,3):setText("Click"):show()
function buttonOnClick()
basalt.debug("Button got clicked!")
end
button:onClick(buttonOnClick())
```
# onClickUp
`onClickUp(self, button, x, y)`<br>
The computercraft event which triggers this method is `mouse_up`.
Any visual object can register onClickUp events.
Here is a example on how to add a onClickUp event to your button:
```lua
local basalt = dofile("basalt.lua")
local mainFrame = basalt.createFrame("myMainFrame"):show()
local button = mainFrame:addButton("myButton"):setPosition(3,3):setSize(12,3):setText("Click"):show()
function buttonOnClick()
basalt.debug("Button got clicked!")
end
button:onClick(buttonOnClick)
function buttonOnRelease()
basalt.debug("Button got released!")
end
button:onClickUp(buttonOnRelease)
```
# onScroll
`onScroll(self, direction, x, y)`<br>
The computercraft event which triggers this method is `mouse_scroll`.
Any visual object can register a onScroll events.
Here is a example on how to add a onScroll event to your button:
```lua
local basalt = dofile("basalt.lua")
local mainFrame = basalt.createFrame("myMainFrame"):show()
local button = mainFrame:addButton("myButton"):setPosition(3,3):setSize(12,3):setText("Click"):show()
function buttonOnScroll()
basalt.debug("Someone scrolls on me!")
end
button:onScroll(buttonOnScroll)
```

BIN
docs/favicon-16x16.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.0 KiB

BIN
docs/favicon-32x32.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.2 KiB

BIN
docs/favicon.ico Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

View File

@@ -1,71 +0,0 @@
# Getting Started!
Basalt aims to be a relatively small, easy to use framework.
Accordingly, we have provided an installation script.
Just use the following command in any CC:Tweaked shell:
`wget https://github.com/Pyroxenium/Basalt/raw/master/basalt.lua basalt.lua`
This will download `basalt.lua` to your local directory.
To load the framework, make use of the following snippet:
```lua
--> For those who are unfamiliar with lua, dofile executes the code in the referenced file
local basalt = dofile("basalt.lua")
```
Here is a fully functioning example of Basalt code:
```lua
local basalt = dofile("basalt.lua") --> Load the Basalt framework
--> Create the first frame. Please note that Basalt needs at least one active "non-parent" frame to properly supply events
--> When Basalt#createFrame makes use of unique identifiers (commonly referred to as UIDs), meaning that the supplied value must be UNIQUE
--> If the supplied UID is ambiguous, Basalt#createFrame returns a nil value
local mainFrame = basalt.createFrame("mainFrame")
--> Show the frame to the user
mainFrame:show()
local button = mainFrame:addButton("clickableButton") --> Add a button to the mainFrame (With a unique identifier)
--> Set the position of the button, Button#setPosition follows an x, y pattern.
--> The x value is how far right the object should be from its anchor (negative values from an anchor will travel left)
--> The y value is how far down the object should be from its anchor (negative values from an anchor will travel up)
button:setPosition(4, 4)
button:setText("Click me!") --> Set the text of our button
local function buttonClick() --> This function serves as our click logic
basalt.debug("I got clicked!")
end
--> Remember! You cannot supply buttonClick(), that will only supply the result of the function
--> Make sure the button knows which function to call when it's clicked
button:onClick(buttonClick)
button:show() --> Make the button visible, so the user can click it
basalt.autoUpdate() --> Basalt#autoUpdate starts the event listener to detect user input
```
If you're like us and strive for succinct and beautiful code, here is a cleaner implementation of the code above:
```lua
local basalt = dofile("basalt.lua")
local mainFrame = basalt.createFrame("mainFrame"):show()
local button = mainFrame --> Basalt returns an instance of the object on most methods, to make use of "call-chaining"
:addButton("clickableButton") --> This is an example of call chaining
:setPosition(4,4)
:setText("Click me!")
:onClick(
function()
basalt.debug("I got clicked!")
end)
:show()
basalt.autoUpdate()
```

View File

@@ -1,10 +1,21 @@
# Installer
This is just a script which helps you to install basalt.lua, if it's not already on the computer. Means, you create your program (which requires basalt) and add this on the top of your program. Now, everytime you execute your program it checks if basalt.lua exists or not.
This is just a script which helps you to setup your program to automatically install the Basalt UI Framework, if it doesn't exists. Means, you create your program (which requires basalt) and add this on the top of your program. Now, everytime you execute your program it checks if basalt.lua (or your custom filepath) exists or not, if not it installs it, or if you are using the advanced installer, it asks the user if the program is allowed to install basalt for you.
## Visual Installer
## Basic Installer
Here is a very basic one which just installs basalt.lua if don't exist:
```lua
--Basalt configurated installer
local filePath = "basalt.lua" --here you can change the file path default: basalt.lua
if not(fs.exists(filePath))then
shell.run("pastebin run ESs1mg7P "..filePath) -- this is an alternative to the wget command
end
local basalt = dofile(filePath) -- here you can change the variablename in any variablename you want default: basalt
```
## Advanced Installer
This is a visual version, it asks the user if he wants to install basalt.lua (if not found)<br>
![](https://i.imgur.com/b4Ys7FB.png)
![](https://raw.githubusercontent.com/Pyroxenium/Basalt/master/docs/_media/installer.png)
```lua
--Basalt configurated installer
local filePath = "basalt.lua" --here you can change the file path default: basalt.lua
@@ -40,12 +51,12 @@ if not(fs.exists(filePath))then
local event, p1,p2,p3,p4 = os.pullEvent()
if(event=="mouse_click")then
if(p3==math.floor(h/2+2))and(p2>=w/2-8)and(p2<=w/2-2)then
shell.run("pastebin run ESs1mg7P") -- this is an alternative to the wget command
shell.run("pastebin run ESs1mg7P "..filePath)
_installerWindow.setVisible(false)
term.clear()
break
end
if(p3==h/2+2)and(p2<=w/2+9)and(p2>=w/2+4)then
if(p3==math.floor(h/2+2))and(p2<=w/2+9)and(p2>=w/2+4)then
_installerWindow.clear()
_installerWindow.setVisible(false)
term.setCursorPos(1,1)
@@ -59,16 +70,5 @@ if not(fs.exists(filePath))then
end
local basalt = dofile(filePath) -- here you can change the variablename in any variablename you want default: basalt
------------------------------
```
## Basic Installer
Here is a very basic one which just installs basalt.lua if don't exist:
```lua
--Basalt configurated installer
local filePath = "basalt.lua" --here you can change the file path default: basalt.lua
if not(fs.exists(filePath))then
shell.run("wget https://github.com/Pyroxenium/Basalt/raw/master/basalt.lua basalt.lua")
end
local basalt = dofile(filePath) -- here you can change the variablename in any variablename you want default: basalt
```

View File

@@ -8,6 +8,8 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
<!-- <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">-->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<style>
:root {
--theme-color: #16CC27;
@@ -43,7 +45,7 @@
auto2top: true
}
</script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-lua.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.28.0/components/prism-lua.min.js"></script>
<!-- Docsify v4 -->
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/js/docsify-themeable.min.js"></script>

View File

@@ -68,8 +68,10 @@ Sets the frame's bar-text alignment
#### Parameters:
1. `string` Can be supplied with "left", "center", or "right"
#### Returns:
1. `frame` The frame being used
#### Usage:
* Set the title of myFrame to "My first frame!", and align it to the right.
```lua
@@ -78,10 +80,13 @@ local mainFrame = myFrame:setBar("My first Frame!"):setBarTextAlign("right")
## showBar
Toggles the frame's upper bar
#### Parameters:
1. `boolean | nil` Whether the frame's bar is visible or if supplied `nil`, is automatically visible
#### Returns:
1. `frame` The frame being used
#### Usage:
* Sets myFrame to have a bar titled "Hello World!" and subsequently displays it.
```lua
@@ -90,10 +95,13 @@ local mainFrame = myFrame:setBar("Hello World!"):showBar()
## addMonitor
adds a monitor to the active main frame.
#### Parameters:
1. `string` The monitor name ("right", "left",... "monitor_1", "monitor_2",...)
#### Returns:
1. `frame` returns a frame which you can use like normal frames
#### Usage:
* Adds a monitor to the mainFrame. Only as long as this frame is also the active Frame, the monitor will be shown.
```lua
@@ -105,10 +113,13 @@ monitor1:setBar("Monitor 1"):showBar()
## setMonitorScale
changes the monitor scale (almost the same as setTextScale())
#### Parameters:
1. `number` Possible values are: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 (1 is the same as 0.5 by setTextScale, and 10 is the same as 5)
#### Returns:
1. `monitor` The monitor being used
#### Usage:
* Changes the monitor scale to 2
```lua
@@ -124,8 +135,10 @@ Returns true if the user is currently holding the respective key down
#### Parameters:
1. `number | string` - Any os.queueEvent("key") key, or you can use the following strings: "shift", "ctrl", "alt"
#### Returns:
1. `boolean` - Whether the user is holding the key down
#### Usage:
* Checks if the "shift" modifier is active on the myFrame frame
```lua
@@ -150,8 +163,10 @@ Returns a child object of the frame
#### Parameters:
1. `string` The name of the child object
#### Returns:
1. `object | nil` The object with the supplied name, or `nil` if there is no object present with the given name
#### Usage:
* Adds a button with id "myFirstButton", then retrieves it again through the frame object
```lua
@@ -161,10 +176,13 @@ local aButton = myFrame:getObject("myFirstButton")
## removeObject
Removes a child object from the frame
#### Parameters:
1. `string` The name of the child object
#### Returns:
1. `boolean` Whether the object with the given name was properly removed
#### Usage:
* Adds a button with the id "myFirstButton", then removes it with the aforementioned id
```lua
@@ -177,8 +195,10 @@ Sets the currently focused object
#### Parameters:
1. `object` The child object to focus on
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates button with id "myFirstButton", sets the focused object to the previously mentioned button
```lua
@@ -187,10 +207,13 @@ myFrame:setFocusedObject(aButton)
```
## removeFocusedObject
Removes the focus of the supplied object
#### Parameters:
1. `object` The child object to remove focus from
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a button with id "myFirstButton", then removes the focus from that button
```lua
@@ -200,9 +223,9 @@ myFrame:removeFocusedObject(aButton)
## getFocusedObject
Gets the currently focused object
#### Parameters:
#### Returns:
1. `object` The currently focused object
#### Usage:
* Gets the currently focused object from the frame, storing it in a variable
```lua
@@ -213,8 +236,10 @@ local focusedObject = myFrame:getFocusedObject()
Sets whether the frame can be moved. _In order to move the frame click and drag the upper bar of the frame_
#### Parameters:
1. `boolean` Whether the object is movable
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a frame with id "myFirstFrame" and makes it movable
```lua
@@ -227,8 +252,10 @@ local myFrame = basalt.createFrame("myFirstFrame"):setMovable(true)
Sets whether the frame can be moved. _In order to move the frame use the upper bar of the frame_
#### Parameters:
1. `boolean` Whether the object is movable
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a frame with id "myFirstFrame" and makes it movable
```lua
@@ -244,8 +271,10 @@ The function can be supplied negative offsets
#### Parameters:
1. `number` The x direction offset (+/-)
2. `number` The y direction offset (+/-)
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates "myFirstFrame" with an x offset of 5 and a y offset of 3
```lua

34
docs/tips/events.md Normal file
View File

@@ -0,0 +1,34 @@
## 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)

View File

@@ -3,7 +3,7 @@ You question yourself how you can execute your own logic while basalt is also ac
## Method 1:
Using parallel.waitForAll
```lua
````lua
local basalt = dofile("basalt.lua")
local mainFrame = basalt.createFrame("mainFrame"):show()-- lets create a frame and a button without functionality
@@ -17,13 +17,13 @@ local function yourCustomHandler()
end
parallel.waitForAll(basalt.autoUpdate, yourCustomHandler) -- here it will handle your function (yourCustomHandler) and basalts handlers at the time
```
You can read [here](http://www.computercraft.info/wiki/Parallel_(API)) what exactly parallel.waitForAll() does
````
You can read [here (tweaked.cc)](https://tweaked.cc/module/parallel.html) what exactly parallel.waitForAll() does
## Method 2:
Using threads
```lua
````lua
local basalt = dofile("basalt.lua")
local mainFrame = basalt.createFrame("mainFrame"):show()-- lets create a frame, a button without functionality and a thread
@@ -37,12 +37,12 @@ local function yourCustomHandler()
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.
```
````
## Method 3:
Using timers
```lua
````lua
local basalt = dofile("basalt.lua")
local mainFrame = basalt.createFrame("mainFrame"):show()-- lets create a frame, a button without functionality and a timer
@@ -53,4 +53,4 @@ 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
```
````