updated Getting-Started.md

Getting-Started.md

@@ -1,45 +1,66 @@
-You want to know how to use basalt for your projects? Easy! Just use the following command in your computercraft computer/turtle/pocket comp. shell:
+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:
 
 `pastebin run ESs1mg7P`
 
-After this is done, edit your program and add the following line on top of your program:
+This will download `basalt.lua` to your local directory
 
+To make use of 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")
 ````
 
-now you are able to access everything you need from basalt.
-
-but how do you actually start?
-Here is a simple example of how you would create a simple button on the screen:
 ````lua
---Here you load the basalt framework into your file:
+local basalt = dofile("basalt.lua") --> Load the Basalt framework
-local basalt = dofile("basalt.lua")
 
---Here you create a non-parent frame. The basalt.update/autoUpdate events will always give their events to a non-parent frame! Which means you always need atleast one active non-parent frame!
+--> Create the first frame. Please note that Basalt needs at least one active "non-parent" frame to properly supply events
---As variable you have to use a unique name - otherwise you wont get a frame object back. :show() immediatly shows the object on the screen
+--> When Basalt#createFrame makes use of unique identifiers (commonly referred to as UIDs), meaning that the supplied value must be UNIQUE
-local main = basalt.createFrame("mainFrame")
+--> If the supplied UID is ambiguous, Basalt#createFrame returns a nil value
-main:show() -- now we make the main frame visible
+local mainFrame = basalt.createFrame("mainFrame")
 
-local button = main:addButton("clickableButton") -- here we add a button to the main frame (with a unique name)
+--> Show the frame to the user
-button:setPosition(4,4) -- here we just change the position of that button (default position would be 1, 1)
+mainFrame:show()
-button:setText("Click me!") -- we set the text of that button 
+
-local function buttonClick() -- we create a function which the button should call if we click on that button
+local button = mainFrame:addButton("clickableButton") --> Add a button to the mainFrame (With a unique identifier)
-basalt.debug("I got clicked!") 
+
+--> 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
-button:onClick(buttonClick) -- here we add a onClick event and add the created function to the list
-button:show() -- ofc it also has to be visible
 
---Here you start the event listener.
+--> Remember! You cannot supply buttonClick(), that will only supply the result of the function
-basalt.autoUpdate()
+--> 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
 ````
-You dont like the amount of lines you need for that? No problem, this does 1-1 the same thing as above:
+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 main = basalt.createFrame("mainFrame"):show()
+local mainFrame = basalt.createFrame("mainFrame"):show()
-local button = main:addButton("clickableButton"):setPosition(4,4):setText("Click me!"):onClick(function() basalt.debug("I got clicked!") end):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()
 ````