diff --git a/Basalt/objects/Animation.lua b/Basalt/objects/Animation.lua index fc7dabb..48d9d97 100644 --- a/Basalt/objects/Animation.lua +++ b/Basalt/objects/Animation.lua @@ -143,7 +143,9 @@ return function(name) if(typ~=nil)then if(activeAnimations[typ]==nil)then activeAnimations[typ] = {} end if(activeAnimations[typ][name]~=nil)then - activeAnimations[typ][name]:cancel() + if(activeAnimations[typ][name]~=self)then + activeAnimations[typ][name]:cancel() + end end activeAnimations[typ][name] = self end diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 17667c6..488f803 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -3,33 +3,28 @@ - [Quick Start](home/Quick-Start.md) - [Installer](home/installer) - Objects - - [Basalt](objects/Basalt) - - [Object](objects/Object) - - [Button](objects/Button) - - [Checkbox](objects/Checkbox) - - [Dropdown](objects/Dropdown) - - [Frame](objects/Frame) - - [Image](objects/Image) - - [Input](objects/Input) - - [Label](objects/Label) - - [List](objects/List) - - [Menubar](objects/Menubar) - - [Pane](objects/Pane) - - [Program](objects/Program) - - [Progressbar](objects/Progressbar) - - [Radio](objects/Radio) - - [Scrollbar](objects/Scrollbar) - - [Slider](objects/Slider) - - [Textfield](objects/Textfield) + - [Basalt](objects/Basalt.md) + - [Object](objects/Object.md) + - [Button](objects/Button.md) + - [Checkbox](objects/Checkbox.md) + - [Dropdown](objects/Dropdown.md) + - [Frame](objects/Frame.md) + - [Image](objects/Image.md) + - [Input](objects/Input.md) + - [Label](objects/Label.md) + - [List](objects/List.md) + - [Menubar](objects/Menubar.md) + - [Pane](objects/Pane.md) + - [Program](objects/Program.md) + - [Progressbar](objects/Progressbar.md) + - [Radio](objects/Radio.md) + - [Scrollbar](objects/Scrollbar.md) + - [Slider](objects/Slider.md) + - [Textfield](objects/Textfield.md) - [Animation](objects/Animation.md) - - [Thread](objects/Thread) - - [Timer](objects/Timer) -- Events - - [Mouse Events](events/mouseEvents.md) - - [Keyboard Events](events/keyEvents.md) - - [Other Events](events/otherEvents.md) + - [Thread](objects/Thread.md) + - [Timer](objects/Timer.md) - Tips & Tricks - - [Component Logic](tips/logic) - - [Changing Button Color](tips/buttons) - - [Advanced usage of Events](tips/events.md) - - [Example Designs](tips/design.md) + - [Your Logic](tips/logic.md) + - [Button coloring](tips/buttonColoring.md) + - [Designing/Animating](tips/design.md) diff --git a/docs/events/keyEvents.md b/docs/events/keyEvents.md deleted file mode 100644 index 079fa99..0000000 --- a/docs/events/keyEvents.md +++ /dev/null @@ -1,39 +0,0 @@ -Here we will talk about keyboard events and how you can manipulate them. There are 2 possible key events you can add to almost every visual object. - -# onKey -`onKey(self, event, key)`
-The computercraft event which triggers this method is `key`. -Any visual object can register onKey events. - -Here is a example on how to add a onKey event to your frame: - -```lua -local basalt = require("Basalt") - -local mainFrame = basalt.createFrame("myMainFrame"):show() -local subFrame = mainFrame:addFrame("subFrame"):setPosition(3,3):setSize(18,6):setBar("Sub Frame",colors.black):showBar():show() - -function openSubFrame() - subFrame:show() -end -mainFrame:onKey(openSubFrame) -``` - -# onKeyUp -`onKeyUp(self, event, key)`
-The computercraft event which triggers this method is `key_up`. -Any visual object can register onKeyUp events. - -Here is a example on how to add a onKeyUp event to your frame: - -```lua -local basalt = require("Basalt") - -local mainFrame = basalt.createFrame("myMainFrame"):show() -local subFrame = mainFrame:addFrame("subFrame"):setPosition(3,3):setSize(18,6):setBar("Sub Frame",colors.black):showBar():show() - -function openSubFrame() - subFrame:show() -end -mainFrame:onKeyUp(openSubFrame) -``` diff --git a/docs/events/mouseEvents.md b/docs/events/mouseEvents.md deleted file mode 100644 index 88fae51..0000000 --- a/docs/events/mouseEvents.md +++ /dev/null @@ -1,82 +0,0 @@ -Here we will talk about mouse events and how you can use them. You can register custom mouse events to all visual objects - -# onClick -`onClick(self, event, button, x, y)`
-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 = require("Basalt") - -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, event, button, x, y)`
-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 = require("Basalt") - -local mainFrame = basalt.createFrame("myMainFrame"):show() -local button = mainFrame:addButton("myButton"):setPosition(3,3):setSize(12,3):setText("Click"):show() - -function buttonOnClick(self, button, x, y) - basalt.debug("Button got clicked!") -end -button:onClick(buttonOnClick) - -function buttonOnRelease(self, button, x, y) - basalt.debug("Button got released!") -end -button:onClickUp(buttonOnRelease) -``` - -# onScroll -`onScroll(self, event, direction, x, y)`
-The computercraft event which triggers this method is `mouse_scroll`. -Any visual object can register onScroll events. - -Here is a example on how to add a onScroll event to your button: - -```lua -local basalt = require("Basalt") - -local mainFrame = basalt.createFrame("myMainFrame"):show() -local button = mainFrame:addButton("myButton"):setPosition(3,3):setSize(12,3):setText("Click"):show() - -function buttonOnScroll(self, direction, x, y) - basalt.debug("Someone scrolls on me!") -end -button:onScroll(buttonOnScroll) -``` - -# onDrag -`onDrag(self, event, button, x, y)`
-The computercraft event which triggers this method is `mouse_drag`. -Any visual object can register onDrag events. - -Here is a example on how to add a onDrag event to your button: - -```lua -local basalt = require("Basalt") - -local mainFrame = basalt.createFrame("myMainFrame"):show() -local button = mainFrame:addButton("myButton"):setPosition(3,3):setSize(12,3):setText("Click"):show() - -function buttonOnDrag(self, button, x, y) - basalt.debug("Someone drags me (i know i wont reposition myself)!") -end -button:onDrag(buttonOnDrag) -``` diff --git a/docs/events/otherEvents.md b/docs/events/otherEvents.md deleted file mode 100644 index 8ed8f3e..0000000 --- a/docs/events/otherEvents.md +++ /dev/null @@ -1,79 +0,0 @@ -There are also other useful events you can listen to: - -# onChange -`onChange(self)`
-This is a custom event which gets triggered as soon as the function :setValue() is called. This function is also called by basalt, for example if you change the input, textfield or checkbox (or all the different types of lists) objects. - -Here is a example on how to add a onChange event to your input, and also another example for your checkbox: - -```lua -local basalt = require("Basalt") - -local mainFrame = basalt.createFrame("myMainFrame"):show() -local aInput = mainFrame:addInput("specialInput"):setPosition(3,3):show() -local aCheckbox = mainFrame:addCheckbox("specialCheckbox"):setPosition(3,5):show() - -local function checkInput(input) - if(string.lower(input:getValue())=="hello")then - basalt.debug("Hello back!") - end -end - -local function checkCheckbox(checkbox) - if(checkbox:getValue()==true)then -- or if(checkbox:getValue())then - basalt.debug("Checkbox is active, let us do something!") - end -end - -aInput:onChange(checkInput) -aCheckbox:onChange(checkCheckbox) -``` - -# onResize -`onResize(self)`
-This is a custom event which gets triggered as soon as the parent frame gets resized. - -Here is a example on how to add a onResize event to your button: - -```lua -local basalt = require("Basalt") - -local mainFrame = basalt.createFrame("myMainFrame"):show() -local aButton = mainFrame:addButton("myButton"):setPosition(3,3):show() - -local function onButtonResize(button) - local width = mainFrame:getWidth() - button:setSize() -end - -aButton:onResize(onButtonResize) -``` -# onLoseFocus -`onLoseFocus(self)`
-This event gets triggered as soon as the object loses its focus. - -```lua -local basalt = require("Basalt") - -local mainFrame = basalt.createFrame("myFirstFrame"):show() -local aButton = mainFrame:addButton("exampleButton"):setPosition(3,3):onLoseFocus( - function(self) - basalt.debug("Please come back... :(") - end -):show() -``` - -# onGetFocus -`onGetFocus(self)`
-This event gets triggered as soon as the object is the currently focused object. - -```lua -local basalt = require("Basalt") - -local mainFrame = basalt.createFrame("myFirstFrame"):show() -local aButton = mainFrame:addButton("exampleButton"):setPosition(3,3):onGetFocus( - function(self) - basalt.debug("Welcome back!") - end -):show() -``` diff --git a/docs/home/Quick-Start.md b/docs/home/Quick-Start.md index c7d48f5..5002627 100644 --- a/docs/home/Quick-Start.md +++ b/docs/home/Quick-Start.md @@ -45,11 +45,14 @@ Here is a fully functioning example of Basalt code ```lua local basalt = require("basalt") --> Load the Basalt framework ---> Create a base frame. Please note that Basalt needs at least one active base frame to properly supply events -local mainFrame = basalt.createFrame() +--> 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 +local mainFrame = basalt.createFrame("mainFrame") +--> Show the frame to the user +mainFrame:show() -local button = mainFrame:addButton() --> Add a button to the mainFrame +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) @@ -66,21 +69,24 @@ end --> 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 = require("basalt") -local mainFrame = basalt.createFrame() +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() --> This is an example 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() ``` diff --git a/docs/objects/Animation.md b/docs/objects/Animation.md index 77b8725..ef789f0 100644 --- a/docs/objects/Animation.md +++ b/docs/objects/Animation.md @@ -1,303 +1,21 @@ -With animations, you can create a beautiful experience for users while interacting with objects.
-For now the animation class is very basic, it will be expanded in the future, but we have to say you can already do almost everything you can imagine! +With animations, you can create a beautiful experience for users while interacting with your program.
-Right now animation is a class which makes use of the timer event.
-You can find more information below: - -`The animation object is still a WIP and the way you use it right now could change in the future!` - -## add -Adds a new function to an animation -#### Parameters: -1. `function` The function containing animation logic - -#### Returns: -1. `animation` Animation in use - - -#### Usage: -* This will set the button position to 3,3, waits 1 second, then sets position to 4,4, waits 2 seconds, and then sets the position to 5,5 -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton() -local aAnimation = mainFrame:addAnimation():add(function() testButton:setPosition(3,3) end):wait(1):add(function() testButton:setPosition(1,1,"r") end):wait(2):add(function() testButton:setPosition(1,1,"r") end) -aAnimation:play() -``` - -## wait -Sets a wait timer for the next function after the previous function got executed, no wait timer calls the next function immediately -#### Parameters: -1. `number` The length of delay between the functions _(in seconds)_ - -#### Returns: -1. `animation` Animation in use - -#### Usage: -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton() -local aAnimation = mainFrame:addAnimation():add(function() testButton:setPosition(3,3) end):wait(1):add(function() testButton:setPosition(1,1,"r") end):wait(2):add(function() testButton:setPosition(1,1,"r") end) - -aAnimation:play() -``` - -## play -Plays the animation -#### Parameters: -1. `boolean` Whether it will loop forever, will most likely be replaced with a count in the future - -#### Returns: -1. `animation` Animation in use - -#### Usage: -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton() -local aAnimation = mainFrame:addAnimation():add(function() testButton:setBackground(colors.black) end):wait(1):add(function() testButton:setBackground(colors.gray) end):wait(1):add(function() testButton:setBackground(colors.lightGray) end) - -aAnimation:play() -- changes the background color of that button from black to gray and then to lightGray -``` - -## cancel -Cancels the animation - -#### Returns: -1. `animation` Animation in use - -#### Usage: - -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton() -local aAnimation = mainFrame:addAnimation():add(function() testButton:setBackground(colors.black) end):wait(1):add(function() aAnimation:cancel() end):wait(1):add(function() testButton:setBackground(colors.lightGray) end) - -aAnimation:play() -``` - - -## setObject -Sets the object which the animation should reposition/resize - -#### Parameters: -1. `table` object - -#### Returns: -1. `animation` Animation in use - -#### Usage: - -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton() -local aAnimation = mainFrame:addAnimation():setObject(testButton) -``` - -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton("buttonToAnimate") -``` -```xml - -``` - -## move -Moves the object which got defined by setObject - -#### Parameters: -1. `number` x coordinate -2. `number` y coordinate -3. `number` duration in seconds -4. `number` time - time when this part should begin (offset to when the animation starts - default 0) -5. `table` object - optional, you could also define the object here - -#### Returns: -1. `animation` Animation in use - -#### Usage: -* Takes 2 seconds to move the object from its current position to x15 y3 -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton("buttonToAnimate") -local aAnimation = mainFrame:addAnimation():setObject(testButton):move(15,3,2):play() -``` -```xml - -1562 - -``` - -## offset -Changes the offset on the object which got defined by setObject - -#### Parameters: -1. `number` x offset -2. `number` y offset -3. `number` duration in seconds -4. `number` time - time when this part should begin (offset to when the animation starts - default 0) -5. `table` object - optional, you could also define the object here - -#### Returns: -1. `animation` Animation in use - -#### Usage: - -```lua -local mainFrame = basalt.createFrame() -local subFrame = mainFrame:addFrame("frameToAnimate") -local aAnimation = mainFrame:addAnimation():setObject(subFrame):offset(1,12,1):play() -``` -```xml - -1121 - -``` - -## size -Changes the size on the object which got defined by setObject - -#### Parameters: -1. `number` width -2. `number` height -3. `number` duration in seconds -4. `number` time - time when this part should begin (offset to when the animation starts - default 0) -5. `table` object - optional, you could also define the object here - -#### Returns: -1. `animation` Animation in use - -#### Usage: -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton("buttonToAnimate") -local aAnimation = mainFrame:addAnimation():setObject(testButton):size(15,3,1):play() -``` -```xml - -1531 - -``` - -## changeText -Changes the text while animation is running - -#### Parameters: -1. `table` multiple text strings - example: {"i", "am", "groot"} -2. `number` duration in seconds -3. `number` time - time when this part should begin (offset to when the animation starts - default 0) - -#### Returns: -1. `animation` Animation in use - -#### Usage: - -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton("buttonToAnimate") -local aAnimation = mainFrame:addAnimation():setObject(testButton):changeText({"i", "am", "groot"}, 2):play() -``` -```xml - - - i - am - groot - 2 - - -``` - -## changeTextColor -Changes the text color while the animation is running - -#### Parameters: -1. `table` multiple color numbers - example: {colors.red, colors.yellow, colors.green} -2. `number` duration in seconds -3. `number` time - time when this part should begin (offset to when the animation starts - default 0) - -#### Returns: -1. `animation` Animation in use - -#### Usage: - -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton("buttonToAnimate") -local aAnimation = mainFrame:addAnimation():setObject(testButton):changeTextColor({colors.red, colors.yellow, colors.green}, 2):play() -``` -```xml - - - red - yellow - green - 2 - - -``` - -## changeBackground -Changes the background color while the animation is running - -#### Parameters: -1. `table` multiple color numbers - example: {colors.red, colors.yellow, colors.green} -2. `number` duration in seconds -3. `number` time - time when this part should begin (offset to when the animation starts - default 0) - -#### Returns: -1. `animation` Animation in use - -#### Usage: - -```lua -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton("buttonToAnimate") -local aAnimation = mainFrame:addAnimation():setObject(testButton):changeTextColor({colors.red, colors.yellow, colors.green}, 2):play() -``` -```xml - - - red - yellow - green - 2 - - -``` +| | | +|---|---| +|[add](objects/Animation/add.md)|Adds a new custom function to call at the current time +|[wait](objects/Animation/wait.md)|Adds a amount to the animation time +|[play](objects/Animation/play.md)|Plays the animation +|[cancel](objects/Animation/cancel.md)|Cancels the animation +|[setObject](objects/Animation/setObject.md)|Sets an object on which predefined animations should work on +|[move](objects/Animation/move.md)|Predefined animation: moves the object to a new position +|[offset](objects/Animation/offset.md)|Predefined animation: Changes the offset of that object +|[size](objects/Animation/size.md)|Predefined animation: Changes the size on a object +|[changeText](objects/Animation/changeText.md)|Predefined animation: Changes the text (object needs a setText method) +|[changeTextColor](objects/Animation/changeTextColor.md)|Predefined animation: changes the foreground/textcolor on a object +|[changeBackground](objects/Animation/changeBackground.md)|Predefined animation: changes the background on a object # Events -## onDone -`onDone(self)`
-This is a event which gets fired as soon as the animation has finished. - -```lua -local basalt = require("Basalt") - -local mainFrame = basalt.createFrame() -local testButton = mainFrame:addButton("buttonToAnimate") -local aAnimation = mainFrame:addAnimation():setObject(testButton):changeTextColor({colors.red, colors.yellow, colors.green}, 2):play() -aAnimation:onDone(function() - basalt.debug("The animation is done") -end) -``` - -In XML you are also able to queue multiple animations, like this: - -```xml - - - red - yellow - green - 2 - - - - - red - yellow - green - 2 - - -``` \ No newline at end of file +| | | +|---|---| +|[onDone](objects/Animation/onDone.md)|Gets called as soon as the animation has finished diff --git a/docs/objects/Animation/add.md b/docs/objects/Animation/add.md new file mode 100644 index 0000000..8587646 --- /dev/null +++ b/docs/objects/Animation/add.md @@ -0,0 +1,17 @@ +## add +Adds a new function to an animation +#### Parameters: +1. `function` The function containing animation logic + +#### Returns: +1. `animation` Animation in use + + +#### Usage: +* This will set the button position to 3,3, waits 1 second, then sets position to 4,4, waits 2 seconds, and then sets the position to 5,5 +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton() +local aAnimation = mainFrame:addAnimation():add(function() testButton:setPosition(3,3) end):wait(1):add(function() testButton:setPosition(1,1,"r") end):wait(2):add(function() testButton:setPosition(1,1,"r") end) +aAnimation:play() +``` \ No newline at end of file diff --git a/docs/objects/Animation/cancel.md b/docs/objects/Animation/cancel.md new file mode 100644 index 0000000..b96c96a --- /dev/null +++ b/docs/objects/Animation/cancel.md @@ -0,0 +1,15 @@ +## cancel +Cancels the animation + +#### Returns: +1. `animation` Animation in use + +#### Usage: + +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton() +local aAnimation = mainFrame:addAnimation():add(function() testButton:setBackground(colors.black) end):wait(1):add(function() aAnimation:cancel() end):wait(1):add(function() testButton:setBackground(colors.lightGray) end) + +aAnimation:play() +``` \ No newline at end of file diff --git a/docs/objects/Animation/changeBackground.md b/docs/objects/Animation/changeBackground.md new file mode 100644 index 0000000..903031e --- /dev/null +++ b/docs/objects/Animation/changeBackground.md @@ -0,0 +1,28 @@ +## changeBackground +Changes the background color while the animation is running + +#### Parameters: +1. `table` multiple color numbers - example: {colors.red, colors.yellow, colors.green} +2. `number` duration in seconds +3. `number` time - time when this part should begin (offset to when the animation starts - default 0) + +#### Returns: +1. `animation` Animation in use + +#### Usage: + +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton("buttonToAnimate") +local aAnimation = mainFrame:addAnimation():setObject(testButton):changeTextColor({colors.red, colors.yellow, colors.green}, 2):play() +``` +```xml + + + red + yellow + green + 2 + + +``` \ No newline at end of file diff --git a/docs/objects/Animation/changeText.md b/docs/objects/Animation/changeText.md new file mode 100644 index 0000000..e5a6019 --- /dev/null +++ b/docs/objects/Animation/changeText.md @@ -0,0 +1,28 @@ +## changeText +Changes the text while animation is running + +#### Parameters: +1. `table` multiple text strings - example: {"i", "am", "groot"} +2. `number` duration in seconds +3. `number` time - time when this part should begin (offset to when the animation starts - default 0) + +#### Returns: +1. `animation` Animation in use + +#### Usage: + +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton("buttonToAnimate") +local aAnimation = mainFrame:addAnimation():setObject(testButton):changeText({"i", "am", "groot"}, 2):play() +``` +```xml + + + i + am + groot + 2 + + +``` \ No newline at end of file diff --git a/docs/objects/Animation/changeTextColor.md b/docs/objects/Animation/changeTextColor.md new file mode 100644 index 0000000..26b9153 --- /dev/null +++ b/docs/objects/Animation/changeTextColor.md @@ -0,0 +1,28 @@ +## changeTextColor +Changes the text color while the animation is running + +#### Parameters: +1. `table` multiple color numbers - example: {colors.red, colors.yellow, colors.green} +2. `number` duration in seconds +3. `number` time - time when this part should begin (offset to when the animation starts - default 0) + +#### Returns: +1. `animation` Animation in use + +#### Usage: + +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton("buttonToAnimate") +local aAnimation = mainFrame:addAnimation():setObject(testButton):changeTextColor({colors.red, colors.yellow, colors.green}, 2):play() +``` +```xml + + + red + yellow + green + 2 + + +``` \ No newline at end of file diff --git a/docs/objects/Animation/move.md b/docs/objects/Animation/move.md new file mode 100644 index 0000000..094a8b3 --- /dev/null +++ b/docs/objects/Animation/move.md @@ -0,0 +1,25 @@ +## move +Moves the object which got defined by setObject + +#### Parameters: +1. `number` x coordinate +2. `number` y coordinate +3. `number` duration in seconds +4. `number` time - time when this part should begin (offset to when the animation starts - default 0) +5. `table` object - optional, you could also define the object here + +#### Returns: +1. `animation` Animation in use + +#### Usage: +* Takes 2 seconds to move the object from its current position to x15 y3 +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton("buttonToAnimate") +local aAnimation = mainFrame:addAnimation():setObject(testButton):move(15,3,2):play() +``` +```xml + +1562 + +``` \ No newline at end of file diff --git a/docs/objects/Animation/offset.md b/docs/objects/Animation/offset.md new file mode 100644 index 0000000..7f99a4d --- /dev/null +++ b/docs/objects/Animation/offset.md @@ -0,0 +1,25 @@ +## offset +Changes the offset on the object which got defined by setObject + +#### Parameters: +1. `number` x offset +2. `number` y offset +3. `number` duration in seconds +4. `number` time - time when this part should begin (offset to when the animation starts - default 0) +5. `table` object - optional, you could also define the object here + +#### Returns: +1. `animation` Animation in use + +#### Usage: + +```lua +local mainFrame = basalt.createFrame() +local subFrame = mainFrame:addFrame("frameToAnimate") +local aAnimation = mainFrame:addAnimation():setObject(subFrame):offset(1,12,1):play() +``` +```xml + +1121 + +``` \ No newline at end of file diff --git a/docs/objects/Animation/onDone.md b/docs/objects/Animation/onDone.md new file mode 100644 index 0000000..0ecc8ae --- /dev/null +++ b/docs/objects/Animation/onDone.md @@ -0,0 +1,35 @@ +## onDone +`onDone(self)`
+This is a event which gets fired as soon as the animation has finished. + +```lua +local basalt = require("Basalt") + +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton("buttonToAnimate") +local aAnimation = mainFrame:addAnimation():setObject(testButton):changeTextColor({colors.red, colors.yellow, colors.green}, 2):play() +aAnimation:onDone(function() + basalt.debug("The animation is done") +end) +``` + +In XML you are also able to queue multiple animations, like this: + +```xml + + + red + yellow + green + 2 + + + + + red + yellow + green + 2 + + +``` \ No newline at end of file diff --git a/docs/objects/Animation/play.md b/docs/objects/Animation/play.md new file mode 100644 index 0000000..ff550d5 --- /dev/null +++ b/docs/objects/Animation/play.md @@ -0,0 +1,16 @@ +## play +Plays the animation +#### Parameters: +1. `boolean` Whether it will loop forever, will most likely be replaced with a count in the future + +#### Returns: +1. `animation` Animation in use + +#### Usage: +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton() +local aAnimation = mainFrame:addAnimation():add(function() testButton:setBackground(colors.black) end):wait(1):add(function() testButton:setBackground(colors.gray) end):wait(1):add(function() testButton:setBackground(colors.lightGray) end) + +aAnimation:play() -- changes the background color of that button from black to gray and then to lightGray +``` \ No newline at end of file diff --git a/docs/objects/Animation/setObject.md b/docs/objects/Animation/setObject.md new file mode 100644 index 0000000..71070a4 --- /dev/null +++ b/docs/objects/Animation/setObject.md @@ -0,0 +1,24 @@ +## setObject +Sets the object which the animation should reposition/resize + +#### Parameters: +1. `table` object + +#### Returns: +1. `animation` Animation in use + +#### Usage: + +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton() +local aAnimation = mainFrame:addAnimation():setObject(testButton) +``` + +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton("buttonToAnimate") +``` +```xml + +``` \ No newline at end of file diff --git a/docs/objects/Animation/size.md b/docs/objects/Animation/size.md new file mode 100644 index 0000000..36887be --- /dev/null +++ b/docs/objects/Animation/size.md @@ -0,0 +1,24 @@ +## size +Changes the size on the object which got defined by setObject + +#### Parameters: +1. `number` width +2. `number` height +3. `number` duration in seconds +4. `number` time - time when this part should begin (offset to when the animation starts - default 0) +5. `table` object - optional, you could also define the object here + +#### Returns: +1. `animation` Animation in use + +#### Usage: +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton("buttonToAnimate") +local aAnimation = mainFrame:addAnimation():setObject(testButton):size(15,3,1):play() +``` +```xml + +1531 + +``` \ No newline at end of file diff --git a/docs/objects/Animation/wait.md b/docs/objects/Animation/wait.md new file mode 100644 index 0000000..f270479 --- /dev/null +++ b/docs/objects/Animation/wait.md @@ -0,0 +1,16 @@ +## wait +Sets a wait timer for the next function after the previous function got executed, no wait timer calls the next function immediately +#### Parameters: +1. `number` The length of delay between the functions _(in seconds)_ + +#### Returns: +1. `animation` Animation in use + +#### Usage: +```lua +local mainFrame = basalt.createFrame() +local testButton = mainFrame:addButton() +local aAnimation = mainFrame:addAnimation():add(function() testButton:setPosition(3,3) end):wait(1):add(function() testButton:setPosition(1,1,"r") end):wait(2):add(function() testButton:setPosition(1,1,"r") end) + +aAnimation:play() +``` \ No newline at end of file diff --git a/docs/objects/Basalt.md b/docs/objects/Basalt.md index 844f211..ac6393d 100644 --- a/docs/objects/Basalt.md +++ b/docs/objects/Basalt.md @@ -1,201 +1,37 @@ +This is the UI Manager and the first thing you want to access. Before you can access Basalt, you need to add the following code on top of your file: -`local basalt = require("Basalt")` +`local basalt = require("basalt")` -Now you are able to access the following methods: +require loads the UI Framework into your project. -## basalt.createFrame -Create a base-frame (main frame) -#### Parameters: -1. `string` name +Now you are able to access the following list of methods: -#### Returns: -1. `frame` object +| | | +|---|---| +|[createFrame](objects/Basalt/createFrame.md)|Creates a new base frame +|[removeFrame](objects/Basalt/removeFrame.md)|Removes a previously created base frame +|[getFrame](objects/Basalt/getFrame.md)|Returns a frame object by it's id +|[getActiveFrame](objects/Basalt/getActiveFrame.md)|Returns the currently active base frame +|[autoUpdate](objects/Basalt/autoUpdate.md)|Starts the event and draw listener +|[update](objects/Basalt/update.md)|Starts the event and draw listener once +|[stopUpdate](objects/Basalt/stopUpdate.md)|Stops the currently active event and draw listener +|[isKeyDown](objects/Basalt/isKeyDown.md)|Returns if the key is held down +|[debug](objects/Basalt/debug.md)|Writes something into the debug console +|[log](objects/Basalt/log.md)|Writes something into the log file +|[setTheme](objects/Basalt/setTheme.md)|Changes the base theme of basalt +|[setVariable](objects/Basalt/setVariable.md)|Sets a variable which you can access via XML +|[schedule](objects/Basalt/schedule.md)|Schedules a new task -#### Usage: -* Create and show a frame with id "myFirstFrame" +# Examples + +Here is a lua example on how to create a empty base frame and start basalt's listener. ```lua -local mainFrame = basalt.createFrame("myFirstFrame") -``` +local basalt = require("basalt") -- we load the UI Framework into our project -## basalt.removeFrame -Removes a base frame +local main = basalt.createFrame() -- we create a base frame - on that frame we are able to add object's -#### Parameters: -1. `string` name +-- here we would add additional object's -#### Usage: -* Removes the previously created frame with id "myFirstFrame" -```lua -local mainFrame = basalt.createFrame("myFirstFrame") -basalt.removeFrame("myFirstFrame") -``` - -## basalt.getFrame -Returns a base frame with the given name -#### Parameters: -1. `string` name - -#### Returns: -1. `frame` object - -#### Usage: -* Creates, fetches and shows the "myFirstFrame" object -```lua -basalt.createFrame("myFirstFrame"):hide() -basalt.getFrame("myFirstFrame"):show() -``` - -## basalt.getActiveFrame -Returns the currently active base frame - -#### Returns: -1. `frame` The current frame - -#### Usage: -* Displays the active frame name in the debug console -```lua -basalt.createFrame() -basalt.debug(basalt.getActiveFrame():getName()) -- returns the uuid -``` - -## basalt.autoUpdate -Starts the draw and event handler until basalt.stopUpdate() is called - -#### Usage: -* Enable the basalt updates, otherwise the screen will not continue to update -```lua -local mainFrame = basalt.createFrame() -basalt.autoUpdate() -``` - -## basalt.update -Calls the draw and event handler once - this gives more flexibility about which events basalt should process. For example you could filter the terminate event. - -#### Parameters: -1. `string` The event to be received -2. `...` Additional event variables to capture - -#### Usage: -* Creates and starts a custom update cycle -```lua -local mainFrame = basalt.createFrame() -local aButton = mainFrame:addButton():setPosition(2,2) -while true do - basalt.update(os.pullEventRaw()) -end -``` - -## basalt.stopUpdate -Stops the automatic draw and event handler which got started by basalt.autoUpdate() - -#### Usage: -* When the quit button is clicked, the button stops basalt auto updates -```lua -local mainFrame = basalt.createFrame() -local aButton = mainFrame:addButton():setPosition(2,2):setText("Stop Basalt!") -aButton:onClick(function() -basalt.stopUpdate() -end) -basalt.autoUpdate() -``` - -## basalt.isKeyDown -Checks if the user is currently holding a key - -#### Parameters: -1. `number` key code (use the keys table for that) - -#### Returns: -1. `boolean` true or false - -#### Usage: -* Shows a debug message with true or false if the left ctrl key is down, as soon as you click on the button. -```lua -local mainFrame = basalt.createFrame() -local aButton = mainFrame:addButton():setPosition(2,2):setText("Check Ctrl") -aButton:onClick(function() - basalt.debug(basalt.isKeyDown(keys.leftCtrl)) -end) -basalt.autoUpdate() -``` - -## basalt.debug -creates a label with some information on the main frame on the bottom left, if you click on that label it will open a log view for you. See it as the new print for debugging - -You can also edit the default debug Label (change position, change color or whatever you want) by accessing the variable basalt.debugLabel -which returns the debug Label. - -Also basalt.debugFrame and basalt.debugList are available. - -#### Parameters: -1. `...` (multiple parameters are possible, like print does) - -#### Usage: -* Prints "Hello! ^-^" to the debug console -```lua -basalt.debug("Hello! ", "^-^") -``` - -## basalt.setTheme -Sets the base theme of the project! Make sure to cover all existing objects, otherwise it will result in errors. A good example is [theme](https://github.com/Pyroxenium/Basalt/blob/master/Basalt/theme.lua) - -#### Parameters: -1. `table` theme layout look into [theme](https://github.com/Pyroxenium/Basalt/blob/master/Basalt/theme.lua) for a example - -#### Usage: -* Sets the default theme of basalt. -```lua -basalt.setTheme({ - ButtonBG = colors.yellow, - ButtonText = colors.red, - ..., -}) -``` - -## basalt.setVariable -This stores a variable which you're able to access via xml. You are also able to add a function, which then gets called by object events created in XML. - -#### Parameters: -1. `string` a key name -1. `any` any variable - -#### Usage: -* Adds a function to basalt. -```lua -basalt.setVariable("clickMe", function() - basalt.debug("I got clicked") -end) -``` -```xml -