docs

2022-07-18 16:45:59 +02:00
parent 8157c025ea
commit 9d10e95fae
10 changed files with 468 additions and 178 deletions
--- a/docs/objects/Animation.md
+++ b/docs/objects/Animation.md
@@ -18,8 +18,8 @@ Adds a new function to an animation
 #### 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():show()
-local testButton = mainFrame:addButton():show()
+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()
 ```
@@ -34,8 +34,8 @@ Sets a wait timer for the next function after the previous function got executed

 #### Usage:
 ```lua
-local mainFrame = basalt.createFrame():show()
-local testButton = mainFrame:addButton():show()
+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()
@@ -51,8 +51,8 @@ Plays the animation

 #### Usage:
 ```lua
-local mainFrame = basalt.createFrame():show()
-local testButton = mainFrame:addButton():show()
+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 
@@ -67,8 +67,8 @@ Cancels the animation
 #### Usage:

 ```lua
-local mainFrame = basalt.createFrame():show()
-local testButton = mainFrame:addButton():show()
+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()
@@ -87,30 +87,17 @@ Sets the object which the animation should reposition/resize
 #### Usage:

 ```lua
-local mainFrame = basalt.createFrame():show()
-local testButton = mainFrame:addButton():show()
+local mainFrame = basalt.createFrame()
+local testButton = mainFrame:addButton()
 local aAnimation = mainFrame:addAnimation():setObject(testButton)
 ```

-## move
-Moves the object which got defined by setObject
-
-#### Parameters: 
-1. `number` x coordinate
-2. `number` y coordinate
-1. `number` time in seconds
-1. `number` frames (how fluid it should look like)
-1. `table` object - optional, you could also define the object here
-
-#### Returns: 
-1. `animation` Animation in use
-
-#### Usage:
-
 ```lua
-local mainFrame = basalt.createFrame():show()
-local testButton = mainFrame:addButton():show()
-local aAnimation = mainFrame:addAnimation():setObject(testButton):move(15,3,1,5):play()
+local mainFrame = basalt.createFrame()
+local testButton = mainFrame:addButton("buttonToAnimate")
+```
+```xml
+<animation object="buttonToAnimate" />
 ```

 ## move
@@ -119,19 +106,24 @@ Moves the object which got defined by setObject
 #### Parameters: 
 1. `number` x coordinate
 2. `number` y coordinate
-1. `number` time in seconds
-1. `number` frames (how fluid it should look like)
-1. `table` object - optional, you could also define the object here
+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():show()
-local testButton = mainFrame:addButton():show()
-local aAnimation = mainFrame:addAnimation():setObject(testButton):move(15,3,1,5):play()
+local mainFrame = basalt.createFrame()
+local testButton = mainFrame:addButton("buttonToAnimate")
+local aAnimation = mainFrame:addAnimation():setObject(testButton):move(15,3,2):play()
+```
+```xml
+<animation object="buttonToAnimate" play="true">
+<move><x>15</x><y>6</y><duration>2</duration></move>
+</animation>
 ```

 ## offset
@@ -140,9 +132,9 @@ Changes the offset on the object which got defined by setObject
 #### Parameters: 
 1. `number` x offset
 2. `number` y offset
-1. `number` time in seconds
-1. `number` frames (how fluid it should look like)
-1. `table` object - optional, you could also define the object here
+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
@@ -150,9 +142,14 @@ Changes the offset on the object which got defined by setObject
 #### Usage:

 ```lua
-local mainFrame = basalt.createFrame():show()
-local subFrame = mainFrame:addFrame():show()
-local aAnimation = mainFrame:addAnimation():setObject(subFrame):offset(1,12,1,5):play()
+local mainFrame = basalt.createFrame()
+local subFrame = mainFrame:addFrame("frameToAnimate")
+local aAnimation = mainFrame:addAnimation():setObject(subFrame):offset(1,12,1):play()
+```
+```xml
+<animation object="frameToAnimate" play="true">
+<offset><x>1</x><y>12</y><duration>1</duration></offset>
+</animation>
 ```

 ## size
@@ -161,26 +158,32 @@ Changes the size on the object which got defined by setObject
 #### Parameters: 
 1. `number` width
 2. `number` height
-1. `number` time in seconds
-1. `number` frames (how fluid it should look like)
-1. `table` object - optional, you could also define the object here
+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():show()
-local testButton = mainFrame:addButton():show()
-local aAnimation = mainFrame:addAnimation():setObject(testButton):size(15,3,1,5):play()
+local mainFrame = basalt.createFrame()
+local testButton = mainFrame:addButton("buttonToAnimate")
+local aAnimation = mainFrame:addAnimation():setObject(testButton):size(15,3,1):play()
+```
+```xml
+<animation object="buttonToAnimate" play="true">
+<offset><w>15</w><h>3</h><duration>1</duration></offset>
+</animation>
 ```

-## textColoring
-Changes the text colors of an object
+## changeText
+Changes the text while animation is running

 #### Parameters: 
-1. `color|number` multiple colors
+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
@@ -188,7 +191,113 @@ Changes the text colors of an object
 #### Usage:

 ```lua
-local mainFrame = basalt.createFrame():show()
-local testButton = mainFrame:addButton():show()
-local aAnimation = mainFrame:addAnimation():setObject(testButton):textColoring(colors.black, colors.gray, colors.lightGray):play()
+local mainFrame = basalt.createFrame()
+local testButton = mainFrame:addButton("buttonToAnimate")
+local aAnimation = mainFrame:addAnimation():setObject(testButton):changeText({"i", "am", "groot"}, 2):play()
 ```
+```xml
+<animation object="buttonToAnimate" play="true">
+    <text>
+        <text>i</text>
+        <text>am</text>
+        <text>groot</text>
+        <duration>2</duration>
+    </text>
+</animation>
+```
+
+## 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
+<animation object="buttonToAnimate" play="true">
+    <textColor>
+        <color>red</color>
+        <color>yellow</color>
+        <color>green</color>
+        <duration>2</duration>
+    </textColor>
+</animation>
+```
+
+## 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
+<animation object="buttonToAnimate" play="true">
+    <background>
+        <color>red</color>
+        <color>yellow</color>
+        <color>green</color>
+        <duration>2</duration>
+    </background>
+</animation>
+```
+
+# Events
+
+## onDone
+`onDone(self)`<br>
+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
+<animation id="anim2" object="buttonToAnimate">
+    <textColor>
+        <color>red</color>
+        <color>yellow</color>
+        <color>green</color>
+        <duration>2</duration>
+    </textColor>
+</animation>
+<animation onDone="#anim2" object="buttonToAnimate" play="true">
+    <background>
+        <color>red</color>
+        <color>yellow</color>
+        <color>green</color>
+        <duration>2</duration>
+    </background>
+</animation>
+```