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

Basalt 1.7 Update

Browse Source 
- New Objects (Flexbox, Graph, Treeview)
- Pluginsystem to add/remove functionality
- Reworked the entire Object system, instead of one big Object Class we have multiple classes: Object, VisualObject, ChangeableObject
- Instead of one big Frame Class we have multiple Frame Classes: BaseFrame, Frame, MovableFrame, ScrollableFrame, MonitorFrame, Flexbox
- Removed the Animation Object, and added a animation plugin instead
- Removed the Graphic Object and merged it's functionality with the image object
- Updated currently existing objects
This commit is contained in:
Robert Jelic
2023-04-30 17:05:34 +02:00
parent e086c1abb2
commit bb1b1beb79
341 changed files with 15541 additions and 3862 deletions
Download Patch File Download Diff File Expand all files Collapse all files

303
docs/docs1_6/objects/Animation.md Normal file
View File

@@ -0,0 +1,303 @@
With animations, you can create a beautiful experience for users while interacting with objects.<br>
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!
Right now animation is a class which makes use of the timer event.<br>
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
<animation object="buttonToAnimate" />
```
## 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
<animation object="buttonToAnimate" play="true">
<move><x>15</x><y>6</y><duration>2</duration></move>
</animation>
```
## 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
<animation object="frameToAnimate" play="true">
<offset><x>1</x><y>12</y><duration>1</duration></offset>
</animation>
```
## 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
<animation object="buttonToAnimate" play="true">
<offset><w>15</w><h>3</h><duration>1</duration></offset>
</animation>
```
## 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
<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>
```

201
docs/docs1_6/objects/Basalt.md Normal file
View File

@@ -0,0 +1,201 @@
Before you can access Basalt, you need to add the following code on top of your file:
`local basalt = require("Basalt")`
Now you are able to access the following methods:
## basalt.createFrame
Create a base-frame (main frame)
#### Parameters:
1. `string` name
#### Returns:
1. `frame` object
#### Usage:
* Create and show a frame with id "myFirstFrame"
```lua
local mainFrame = basalt.createFrame("myFirstFrame")
```
## basalt.removeFrame
Removes a base frame
#### Parameters:
1. `string` name
#### 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
<button onClick="clickMe" text="Click me" />
```
## basalt.schedule
Schedules a function which gets called in a coroutine. After the coroutine is finished it will get destroyed immediatly. It's something like threads, but with some limits.
#### Parameters:
1. `function` a function which should get executed
#### Returns:
1. `function` it returns the function which you have to execute in order to start the coroutine
#### Usage:
* Creates a schedule which switches the color between red and gray
```lua
local mainFrame = basalt.createFrame()
local aButton = mainFrame:addButton():setText("Click me")
aButton:onClick(basalt.schedule(function(self)
self:setBackground(colors.red)
os.sleep(0.1)
self:setBackground(colors.gray)
os.sleep(0.1)
self:setBackground(colors.red)
os.sleep(0.1)
self:setBackground(colors.gray)
os.sleep(0.1)
self:setBackground(colors.red)
os.sleep(0.1)
self:setBackground(colors.gray)
end))
```

91
docs/docs1_6/objects/Button.md Normal file
View File

@@ -0,0 +1,91 @@
Buttons are objects, which execute something by clicking on them.<br>
Remember button also inherits from [Object](objects/Object.md)
## setText
Sets the displayed button text
#### Parameters:
1. `string` the text the button should show
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a button with "Click me!" as text.
```lua
local mainFrame = basalt.createFrame()
local button = mainFrame:addButton():setText("Click me!")
```
```xml
<button text="Click me!" />
```
## setHorizontalAlign
Sets the horizontal align of the button text
#### Parameters:
1. `string` the position as string ("left", "center", "right") - default is center.
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the button's horizontal text align to right.
```lua
local mainFrame = basalt.createFrame()
local button = mainFrame:addButton()
:setText("Click me!")
:setHorizontalAlign("right")
```
```xml
<button text="Click me!" horizontalAlign="right" />
```
## setVerticalAlign
Sets the vertical align of the button text
#### Parameters:
1. `string` the position as string ("top", "center", "bottom") - default is center.
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the button's horizontal text align to right and the vertical text align to bottom.
```lua
local mainFrame = basalt.createFrame()
local button = mainFrame:addButton()
:setText("Click me!")
:setHorizontalAlign("right")
:setVerticalAlign("bottom")
```
```xml
<button text="Click me!" horizontalAlign="right" verticalAlign="bottom" />
```
# Example
This is a example on how you would create a fully working button:
```lua
local mainFrame = basalt.createFrame()
local aButton = mainFrame:addButton():setText("Click")
aButton:onClick(function(self,event,button,x,y)
if(event=="mouse_click")and(button==1)then
basalt.debug("Left mousebutton got clicked!")
end
end)
```
and this would be the xml way to do it:
```lua
local mainFrame = basalt.createFrame():addLayout("example.xml")
basalt.setVariable("buttonClick", function(self,event,button,x,y)
if(event=="mouse_click")and(button==1)then
basalt.debug("Left mousebutton got clicked!")
end
end)
```
```xml
<button onClick="buttonClick" text="Click" />
```

33
docs/docs1_6/objects/Checkbox.md Normal file
View File

@@ -0,0 +1,33 @@
With checkbox objects the user can set a bool to true or false
Remember checkbox also inherits from [Object](objects/Object.md)
A checkbox does not have any custom methods. All required methods are provided by the base [object](objects/Object.md) class.
# Example
This is how you would create a event which gets fired as soon as the value gets changed:
```lua
local mainFrame = basalt.createFrame()
local aCheckbox = mainFrame:addCheckbox()
local function checkboxChange(self)
local checked = self:getValue()
basalt.debug("The value got changed into ", checked)
end
aCheckbox:onChange(checkboxChange)
```
also possible via xml:
```lua
local mainFrame = basalt.createFrame():addLayout("example.xml")
basalt.setVariable("checkboxChange", function(self)
local checked = self:getValue()
basalt.debug("The value got changed into ", checked)
end)
```
```xml
<checkbox onChange="checkboxChange" />
```

307
docs/docs1_6/objects/Dropdown.md Normal file
View File

@@ -0,0 +1,307 @@
Dropdowns are objects where the user can click on a button, this will open a list where the user can choose from.
If you want to access values inside items this is how the table for single items is made (just a example):
```lua
item = {
text="1. Entry",
bgCol=colors.black,
fgCol=colors.white
args = {}
}
```
Remember Dropdown also inherits from [Object](objects/Object.md)
## addItem
Adds a item into the dropdown
#### Parameters:
1. `string` The entry name
2. `number|color` unique default background color - optional
3. `number|color` unique default text color - optional
4. `any` any value - you could access this later in a :onChange() event (you need to use :getValue()) - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default dropdown with 3 entries
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
```
```xml
<dropdown>
<item><text>1. Entry</text></item>
<item><text>2. Entry</text><bg>yellow</bg></item>
<item><text>3. Entry</text><bg>yellow</bg><fg>green</fg></item>
</dropdown>
```
## removeItem
Removes a item from the dropdown
#### Parameters:
1. `number` The index which should get removed
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default dropdown with 3 entries and removes the second one.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
aDropdown:removeItem(2)
```
## editItem
Edits a item from the dropdown
#### Parameters:
1. `number` The index which should be edited
2. `string` The new item name
3. `number` the new item background color - optional
4. `number` The new item text color - optional
5. `any` New additional information - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default dropdown with 3 entries and edits the second one.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
aDropdown:editItem(2, "Still 2. Entry", colors.red)
```
## getItem
Returns a item by index
#### Parameters:
1. `number` The index which should be returned
#### Returns:
1. `table` The item table example: {text="1. Entry", bgCol=colors.black, fgCol=colors.white}
#### Usage:
* Creates a default dropdown with 3 entries and edits the second one.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
basalt.debug(aDropdown:getItem(2).text)
```
## getItemCount
Returns the current item count
#### Returns:
1. `number` The item list count
#### Usage:
* Creates a default dropdown with 3 entries and prints the current item count.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
basalt.debug(aDropdown:getItemCount())
```
## getAll
Returns all items as table
#### Returns:
1. `table` All items
#### Usage:
* Creates a default menubar with 3 entries and prints a table.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
basalt.debug(aDropdown:getAll())
```
## selectItem
selects a item in the dropdown (same as a player would click on a item)
#### Parameters:
1. `number` The index which should get selected
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default dropdown with 3 entries and selects the second entry.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
aDropdown:selectItem(2)
```
## clear
Removes all items.
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default dropdown with 3 entries and removes them immediatley. Which makes no sense.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
aDropdown:clear()
```
## getItemIndex
returns the item index of the currently selected item
#### Returns:
1. `number` The current index
#### Usage:
* Creates a default dropdown with 3 entries selects the second entry and prints the currently selected index.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
aDropdown:selectItem(2)
basalt.debug(aDropdown:getItemIndex())
```
## setSelectedItem
Sets the background and the foreground of the item which is currently selected
#### Parameters:
1. `number|color` The background color which should be used
2. `number|color` The text color which should be used
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default dropdown with 4 entries and sets the selection background color to green.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry",colors.yellow)
aDropdown:addItem("3. Entry",colors.yellow,colors.green)
aDropdown:addItem("4. Entry")
aDropdown:setSelectedItem(colors.green, colors.red)
```
```xml
<dropdown selectionBG="green" selectionFG="red">
<item><text>1. Entry</text></item>
<item><text>2. Entry</text><bg>yellow</bg></item>
<item><text>2. Entry</text><bg>yellow</bg><fg>green</fg></item>
</dropdown>
```
## setOffset
Sets the offset of the dropdown (the same as you would scroll) - default is 0
#### Parameters:
1. `number` The offset value
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default dropdown with 6 entries and sets the offset to 3.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
:addItem("1. Entry")
:addItem("2. Entry")
:addItem("3. Entry")
:addItem("4. Entry")
:addItem("5. Entry")
:addItem("6. Entry")
:setOffset(3)
```
```xml
<dropdown offset="3">
<item><text>1. Entry</text></item>
<item><text>2. Entry</text></item>
<item><text>3. Entry</text></item>
<item><text>4. Entry</text></item>
<item><text>5. Entry</text></item>
<item><text>6. Entry</text></item>
</dropdown>
```
## getOffset
Returns the current index offset
#### Returns:
1. `number` offset value
#### Usage:
* Creates a default dropdown with 6 entries and sets the offset to 3, also prints the current offset.
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown()
:addItem("1. Entry")
:addItem("2. Entry")
:addItem("3. Entry")
:addItem("4. Entry")
:addItem("5. Entry")
:addItem("6. Entry")
:setOffset(3)
basalt.debug(aDropdown:getOffset())
```
## setDropdownSize
Sets the size of the opened dropdown
#### Parameters:
1. `number` The width value
2. `number` The height value
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default dropdown, adds 3 entries and sets the dropdown size to 15w, 8h
```lua
local mainFrame = basalt.createFrame()
local aDropdown = mainFrame:addDropdown():setDropdownSize(15,8)
aDropdown:addItem("1. Entry")
aDropdown:addItem("2. Entry")
aDropdown:addItem("3. Entry")
```
```xml
<dropdown dropdownWidth="15" dropdownHeight="8">
<item><text>1. Entry</text></item>
<item><text>2. Entry</text></item>
<item><text>3. Entry</text></item>
</dropdown>
```

409
docs/docs1_6/objects/Frame.md Normal file
View File

@@ -0,0 +1,409 @@
<a href="https://i.imgur.com/aikc0K1.png"><img src="https://i.imgur.com/aikc0K1.png" height="500" /></a>
Frames are like containers, but are also normal objects.
In other words, you can add other objects _(even frames)_ to a frame; if the frame itself is visible
all sub-objects _(if they are set as visible)_ are also visible. A better description will follow.
## basalt.createFrame
Creates a new non-parent frame - in most cases it is the first thing you'll need.
#### Parameters:
1. `string` name (should be unique)
#### Returns:
1. `frame | nil` The frame created by createFrame, or `nil` if there is already a frame with the given name.
#### Usage:
* Create a frame with an id "myFirstFrame", stored in a variable named frame
```lua
local myFrame = basalt.createFrame("myFirstFrame")
```
## addFrame
Creates a child frame on the frame, the same as [basalt.createFrame](https://github.com/Pyroxenium/Basalt/wiki/Frame#basaltcreateframe) except the frames are given a parent-child relationship automatically
#### Parameters:
1. `string` name (should be unique)
#### Returns:
1. `frame | nil` The frame created by addFrame, or `nil` if there is already a child frame with the given name.<br>
#### Usage:
* Create a new main frame and adds a child frame to it
```lua
local mainFrame = basalt.createFrame()
local myFrame = mainFrame:addFrame()
```
```xml
<frame></frame>
```
## setBar
Sets the text, background, and foreground of the upper bar of the frame, accordingly.
#### Parameters:
1. `string` The title text to set the bar to
2. `number` The background color
2. `number` The foreground color
#### Returns:
1. `frame` The frame being used
#### Usage:
* Set the title to "My first frame!", with a background of black and a foreground of light gray.
```lua
frame:setBar("My first Frame!", colors.black, colors.lightGray)
```
* Store the frame, use the named frame variable after assigning.
```lua
local mainFrame = basalt.createFrame()
local myFrame = MainFrame:addFrame()
myFrame:setBar("My first Frame!")
```
* This abuses the call-chaining that Basalt uses.
```lua
local mainFrame = basalt.createFrame()
local myFrame = mainFrame:addFrame():setBar("My first Frame!")
```
```xml
<frame barText="My first Frame!" barBG="black" barFG="lightGray"></frame>
```
## setBarTextAlign
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
myFrame:setBar("My first Frame!"):setBarTextAlign("right")
```
```xml
<frame barAlign="right"></frame>
```
## 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
myFrame:setBar("Hello World!"):showBar()
```
```xml
<frame bar="true"></frame>
```
## setMonitor
Sets this frame as a monitor frame
#### Parameters:
1. `string` The monitor name ("right", "left",... "monitor_1", "monitor_2",...)
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new monitor frame, you can use to show objects on a monitor.
```lua
local mainFrame = basalt.createFrame()
local monitorFrame = basalt.createFrame():setMonitor("right")
monitorFrame:setBar("Monitor 1"):showBar()
```
```xml
<frame monitor="right"></frame>
```
## setMirror
mirrors this frame to another peripheral monitor object.
#### Parameters:
1. `string` The monitor name ("right", "left",... "monitor_1", "monitor_2",...)
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates mirror of your main frame to a monitor on the left side.
```lua
local mainFrame = basalt.createFrame():setMirror("left")
```
```xml
<frame mirror="left"></frame>
```
## getObject
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
myFrame:addButton("myFirstButton")
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
myFrame:addButton("myFirstButton")
myFrame:removeObject("myFirstButton")
```
## setFocusedObject
Sets the currently focused object
#### Parameters:
1. `object` The child object to focus on
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new button, sets the focused object to the previously mentioned button
```lua
local aButton = myFrame:addButton()
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 new button then removes the focus from that button when clicking on it
```lua
local aButton = myFrame:addButton():setFocus():onClick(function()
myFrame:removeFocusedObject(aButton)
end)
```
## getFocusedObject
Gets the currently focused object
#### Returns:
1. `object` The currently focused object
#### Usage:
* Gets the currently focused object from the frame, storing it in a variable
```lua
local focusedObject = myFrame:getFocusedObject()
```
## setMovable
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
local myFrame = basalt.createFrame():setMovable(true)
```
```xml
<frame moveable="true"></frame>
```
## setOffset
Sets the frame's coordinate offset. The frame's child objects will receive the frame's coordinate offset. For example, when using a scrollbar, if you use its value to add an offset to a frame, you will get a scrollable frame.
Objects are also able to ignore the offset by using :ignoreOffset() (For example, you may want to ignore the offset on the scrollbar itself)
The function can also be supplied with negative values
#### Parameters:
1. `number` The x direction offset (+/-)
2. `number` The y direction offset (+/-)
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new base frame with x offset of 5 and a y offset of 3
```lua
local myFrame = basalt.createFrame():setOffset(5, 3)
```
* Creates with x offset of 5 and a y offset of -5 (Meaning if you added a button with y position 5, it would be at y position 0)
```lua
local myFrame = basalt.createFrame():setOffset(5, -5)
```
```xml
<frame xOffset="5" yOffset="-5"></frame>
```
## addLayout
Adds a new XML Layout into your frame.
#### Parameters:
1. `string` Path to your layout
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new base frame and adds the mainframe.xml layout
```lua
local myFrame = basalt.createFrame():addLayout("mainframe.xml")
```
```xml
<frame layout="mainframe.xml"></frame>
```
## addLayoutFromString
Adds a new XML Layout as string into your frame.
#### Parameters:
1. `string` xml
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new base frame and adds the mainframe.xml layout
```lua
local myFrame = basalt.createFrame():addLayoutFromString("<button x='12' y='5' bg='black' />")
```
## getLastLayout
returns a table of all objects this frame has created via xml (useful if you'd like to access all of them for some reason)
#### Returns:
1. `table` table with objects
## setTheme
Sets the default theme of that frame children objects always try to get the theme of its parent frame, if it does not exist it goes to its parent parent frame, and so on until it reaches the basalt managers theme - which is sotred in theme.lua (Please checkout [theme](https://github.com/Pyroxenium/Basalt/blob/master/Basalt/theme.lua) for how it could look like.
#### Parameters:
1. `table` theme layout look into [theme](https://github.com/Pyroxenium/Basalt/blob/master/Basalt/theme.lua) for a example
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new base frame and adds a new theme which only changes the default color of buttons.
```lua
local myFrame = basalt.createFrame():setTheme({
ButtonBG = colors.yellow,
ButtonText = colors.red,
})
```
## setScrollable
Makes the frame scrollable with mousewheel.
#### Parameters:
1. `bool` scrollable or not
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new base frame and makes it scrollable
```lua
local myFrame = basalt.createFrame():setScrollable()
```
```xml
<frame scrollable="true"></frame>
```
## setMinScroll
Sets the minimum offset it is allowed to scroll (default 0)
#### Parameters:
1. `number` minimum y offset
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new base frame and makes it scrollable and sets the minimum amount to -5
```lua
local myFrame = basalt.createFrame():setScrollable():setMinScroll(-5)
```
```xml
<frame minScroll="-5"></frame>
```
## setMaxScroll
Sets the maximum offset it is allowed to scroll (default 10)
#### Parameters:
1. `number` maximum y offset
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new base frame and makes it scrollable and sets the maximum amount to 25
```lua
local myFrame = basalt.createFrame():setScrollable():setMaxScroll(25)
```
```xml
<frame maxScroll="25"></frame>
```
## setImportantScroll
By default if you hovering your mouse over children objects, you wont scroll the frame, if you set this to true the frame scrolling becomes more important
#### Parameters:
1. `bool` important or not
#### Returns:
1. `frame` The frame being used
#### Usage:
* Creates a new base frame and makes it scrollable and defines it as important
```lua
local myFrame = basalt.createFrame():setScrollable():setImportantScroll(true)
```
```xml
<frame importantScroll="true"></frame>
```
# XML Example
*This is how you would implement frames via xml:
```xml
<frame>
<frame width="parent.w * 0.5" bg="red">
<button x="2" y="2" width="17" text="Example Button!"/>
</frame>
<frame x="parent.w * 0.5 + 1" width="parent.w * 0.5 +1" bg="black">
<textfield bg="green" x="2" width="parent.w-2" />
</frame>
</frame>
```

41
docs/docs1_6/objects/Image.md Normal file
View File

@@ -0,0 +1,41 @@
The image object is for adding more advanced backgrounds.
It also provides a :shrink() function, where you can shrink the images to smaller ones. This functionallity is fully provided by the blittle library created by Bomb Bloke. I did not ask for permission to add it into the framework. If the creator wants me to remove the blittle part, just text me on discord!
The image object is still not done. in the future i will provide more image formats.
Remember image inherits from [Object](objects/Object.md)
## loadImage
loads a default .nfp file into the object.
#### Parameters:
1. `string` the absolute file path
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default image and loads a test.nfp file
```lua
local mainFrame = basalt.createFrame():show()
local aImage = mainFrame:addImage():loadImage("test.nfp")
```
```xml
<image path="test.nfp" />
```
## shrink
Shrinks the current image into a blittle image.
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default image and loads a test.nfp file
```lua
local mainFrame = basalt.createFrame()
local aImage = mainFrame:addImage():loadImage("test.nfp"):shrink()
```
```xml
<image path="test.nfp" shrink="true" />
```

91
docs/docs1_6/objects/Input.md Normal file
View File

@@ -0,0 +1,91 @@
With input's you are able to create a object where the user can type something in.<br>
Here are all possible functions available for inputs:<br>
Remember Input inherits from [Object](objects/Object.md)
## setInputType
Changes the input type. default: text
#### Parameters:
1. `string` input type ("text", "password", "number")
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default input and sets it to numbers only.
```lua
local mainFrame = basalt.createFrame()
local aInput = mainFrame:addInput():setInputType("number")
```
```xml
<input type="number" />
```
## getInputType
Gets the current input type
#### Returns:
1. `string` input type
#### Usage:
* Creates a default input and sets it to numbers only. Also prints the current input type to log.
```lua
local mainFrame = basalt.createFrame()
local aInput = mainFrame:addInput():setInputType("number")
basalt.debug(aInput:getInputType())
```
## setDefaultText
Sets the default text. This will only be displayed if there is no input set by the user.
#### Parameters:
1. `string` input type ("text", "password", "number")
2. `number|color` default background color - optional
3. `number|color` default text color - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default input and sets the default text to "...".
```lua
local mainFrame = basalt.createFrame()
local aInput = mainFrame:addInput():setDefaultText("...")
```
```xml
<input default="..." />
```
## setInputLimit
Sets a character limit to the input.
#### Parameters:
1. `number` character limit
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default input and sets the character limit to 8.
```lua
local mainFrame = basalt.createFrame()
local aInput = mainFrame:addInput():setInputLimit(8)
```
```xml
<input limit="8" />
```
## getInputLimit
Returns the input limit.
#### Returns:
1. `number` character limit
#### Usage:
* Creates a default input and sets the character limit to 8. Prints the current limit.
```lua
local mainFrame = basalt.createFrame()
local aInput = mainFrame:addInput():setInputLimit(8)
basalt.debug(aInput:getInputLimit())
```

77
docs/docs1_6/objects/Label.md Normal file
View File

@@ -0,0 +1,77 @@
A label is for adding simple text.
By default label's width is auto sizing based on the length of the text. If you change the size with setSize it will automatically stop autosizing the width.
The fontsize feature is calculated by bigfonts, a library made by Wojbie (http://www.computercraft.info/forums2/index.php?/topic/25367-bigfont-api-write-bigger-letters-v10/)
Here are all possible functions available for labels.<br>
Remember Label inherits from [Object](objects/Object.md)
## setText
Sets the text which gets displayed.
#### Parameters:
1. `string` The text which should be displayed
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default label with text "Some random text".
```lua
local mainFrame = basalt.createFrame()
local aLabel = mainFrame:addLabel():setText("Some random text")
```
```xml
<label text="Some random text" />
```
## setFontSize
Sets the font size, calculated by bigfonts. Default size is 1.
#### Parameters:
1. `number` The size (1, 2, 3, 4)
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default label, sets the text to "Basalt!" and its font size to 2.
```lua
local mainFrame = basalt.createFrame()
local aLabel = mainFrame:addLabel():setText("Basalt!"):setFontSize(2)
```
```xml
<label font="2" />
```
## getFontSize
Returns the current font size
#### Returns:
1. `number` font size
#### Usage:
* Creates a default label, sets the text to "Basalt!" and its font size to 2. Also prints the current fontsize.
```lua
local mainFrame = basalt.createFrame()
local aLabel = mainFrame:addLabel():setText("Basalt!"):setFontSize(2)
basalt.debug(aLabel:getFontSize())
```
## setTextAlign
Changes the text align
#### Returns:
1. `string` horizontal ("left", "center", "right")
1. `string` vertical ("top", "center", "bottom")
#### Usage:
* Creates a default label, sets the text to "Basalt!" changes the horizontal align to right
```lua
local mainFrame = basalt.createFrame()
local aLabel = mainFrame:addLabel():setText("Basalt!"):setTextAlign("right")
```
```xml
<label horizontalAlign="right" verticalAlign="center" />
```

279
docs/docs1_6/objects/List.md Normal file
View File

@@ -0,0 +1,279 @@
Lists are objects where you can create endless entries, and the user is able to select one of them
If you want to access values inside items this is how the table for single items is made (just a example):
```lua
item = {
text="1. Entry",
bgCol=colors.black,
fgCol=colors.white
args = {}
}
```
Remember Lists also inherits from [Object](objects/Object.md)
## addItem
Adds a item into the list
#### Parameters:
1. `string` The entry name
2. `number|color` unique default background color - optional
3. `number|color` unique default text color - optional
4. `any` any value - you could access this later in a :onChange() event (you need to use :getValue()) - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default list with 3 entries
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
```
```xml
<list>
<item><text>1. Entry</text></item>
<item><text>2. Entry</text><bg>yellow</bg></item>
<item><text>3. Entry</text><bg>yellow</bg><fg>green</fg></item>
</list>
```
## removeItem
Removes a item from the list
#### Parameters:
1. `number` The index which should get removed
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default list with 3 entries and removes the second one.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
aList:removeItem(2)
```
## editItem
Edits a item from the list
#### Parameters:
1. `number` The index which should be edited
2. `string` The new item name
3. `number` the new item background color - optional
4. `number` The new item text color - optional
5. `any` New additional information - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default list with 3 entries and changes the second one.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
aList:editItem(2, "Still 2. Entry", colors.red)
```
## getItem
Returns a item by index
#### Parameters:
1. `number` The index which should be returned
#### Returns:
1. `table` The item table example: {text="1. Entry", bgCol=colors.black, fgCol=colors.white}
#### Usage:
* Creates a default list with 3 entries and edits the second one.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
basalt.debug(aList:getItem(2).text)
```
## getItemCount
Returns the current item count
#### Returns:
1. `number` The item list count
#### Usage:
* Creates a default list with 3 entries and prints the current item count.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
basalt.debug(aList:getItemCount())
```
## getAll
Returns all items as table
#### Returns:
1. `table` All items
#### Usage:
* Creates a default menubar with 3 entries and prints a table.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
basalt.debug(aList:getAll())
```
## selectItem
selects a item in the list (same as a player would click on a item)
#### Parameters:
1. `number` The index which should get selected
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default list with 3 entries and selects the second entry.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
aList:selectItem(2)
```
## clear
Removes all items.
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default list with 3 entries and removes them immediatley. Which makes no sense.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
aList:clear()
```
## getItemIndex
returns the item index of the currently selected item
#### Returns:
1. `number` The current index
#### Usage:
* Creates a default list with 3 entries selects the second entry and prints the currently selected index.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
aList:selectItem(2)
basalt.debug(aList:getItemIndex())
```
## setSelectedItem
Sets the background and the foreground of the item which is currently selected
#### Parameters:
1. `number|color` The background color which should be used
2. `number|color` The text color which should be used
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default list with 4 entries and sets the selection background color to green.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
aList:addItem("1. Entry")
aList:addItem("2. Entry",colors.yellow)
aList:addItem("3. Entry",colors.yellow,colors.green)
aList:addItem("4. Entry")
aList:setSelectedItem(colors.green, colors.red)
```
```xml
<list selectionBG="green" selectionFG="red">
<item><text>1. Entry</text></item>
<item><text>2. Entry</text><bg>yellow</bg></item>
<item><text>2. Entry</text><bg>yellow</bg><fg>green</fg></item>
</list>
```
## setOffset
Sets the offset of the list (the same as you would scroll) - default is 0
#### Parameters:
1. `number` The offset value
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default list with 6 entries and sets the offset to 3.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
:addItem("1. Entry")
:addItem("2. Entry")
:addItem("3. Entry")
:addItem("4. Entry")
:addItem("5. Entry")
:addItem("6. Entry")
:setOffset(3)
```
```xml
<list offset="3">
<item><text>1. Entry</text></item>
<item><text>2. Entry</text></item>
<item><text>3. Entry</text></item>
<item><text>4. Entry</text></item>
<item><text>5. Entry</text></item>
<item><text>6. Entry</text></item>
</list>
```
## getOffset
Returns the current index offset
#### Returns:
1. `number` offset value
#### Usage:
* Creates a default list with 6 entries and sets the offset to 3, also prints the current offset.
```lua
local mainFrame = basalt.createFrame()
local aList = mainFrame:addList()
:addItem("1. Entry")
:addItem("2. Entry")
:addItem("3. Entry")
:addItem("4. Entry")
:addItem("5. Entry")
:addItem("6. Entry")
:setOffset(3)
basalt.debug(aList:getOffset())
```

337
docs/docs1_6/objects/Menubar.md Normal file
View File

@@ -0,0 +1,337 @@
Menubars are like lists but instead of being vertical, they are horizontal. Imagine you are creating a Operating System and you would like to add a taskbar, menubars would be exactly what you need, because they are also scrollable, which means they have endless entry possibility.
If you want to access values inside items this is how the table for single items is made (just a example):
```lua
item = {
text="1. Entry",
bgCol=colors.black,
fgCol=colors.white
args = {}
}
```
Remember menubar inherits from [Object](objects/Object.md)
## addItem
Adds a item into the menubar
#### Parameters:
1. `string` The entry name
2. `number|color` unique default background color - optional
3. `number|color` unique default text color - optional
4. `any` any value - you could access this later in a :onChange() event (you need to use :getValue()) - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default menubar with 3 entries
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
```
```xml
<menubar>
<item><text>1. Entry</text></item>
<item><text>2. Entry</text><bg>yellow</bg></item>
<item><text>3. Entry</text><bg>yellow</bg><fg>green</fg></item>
</menubar>
```
## removeItem
Removes a item from the menubar
#### Parameters:
1. `number` The index which should get removed
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default menubar with 3 entries and removes the second one.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
aMenubar:removeItem(2)
```
## editItem
Edits a item from the menubar
#### Parameters:
1. `number` The index which should be edited
2. `string` The new item name
3. `number` the new item background color - optional
4. `number` The new item text color - optional
5. `any` New additional information - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default menubar with 3 entries and edits the second one.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
aMenubar:editItem(2, "Still 2. Entry", colors.red)
```
## getItem
Returns a item by index
#### Parameters:
1. `number` The index which should be returned
#### Returns:
1. `table` The item table example: {text="1. Entry", bgCol=colors.black, fgCol=colors.white}
#### Usage:
* Creates a default menubar with 3 entries and edits the second one.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
basalt.debug(aMenubar:getItem(2).text)
```
## getItemCount
Returns the current item count
#### Returns:
1. `number` The item list count
#### Usage:
* Creates a default menubar with 3 entries and prints the current item count.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
basalt.debug(aMenubar:getItemCount())
```
## getAll
Returns all items as table
#### Returns:
1. `table` All items
#### Usage:
* Creates a default menubar with 3 entries and prints a table.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
basalt.debug(aMenubar:getAll())
```
## setSpace
Sets the space between entries
#### Parameters:
1. `number` The space between each entry
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default menubar with 3 entries and changes the space to 3.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
aMenubar:setSpace(3)
```
```xml
<menubar space="3">
<item><text>1. Entry</text></item>
<item><text>2. Entry</text><bg>yellow</bg></item>
<item><text>3. Entry</text><bg>yellow</bg><fg>green</fg></item>
</menubar>
```
## setScrollable
Makes the menubar scrollable. The menubar will be scrollable as soon as the menubar is to small for all the entries.
#### Parameters:
1. `boolean` if this menubar should be scrollable or not
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default menubar with 3 entries and makes it scrollable.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
aMenubar:setScrollable(true)
```
```xml
<menubar scrollable="true">
<item><text>1. Entry</text></item>
<item><text>2. Entry</text><bg>yellow</bg></item>
<item><text>3. Entry</text><bg>yellow</bg><fg>green</fg></item>
</menubar>
```
## selectItem
selects a item in the list (same as a player would click on a item)
#### Parameters:
1. `number` The index which should get selected
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default menubar with 3 entries and selects the second entry.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
aMenubar:selectItem(2)
```
## clear
Removes all items.
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default menubar with 3 entries and removes them immediatley. Which makes no sense.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
aMenubar:clear()
```
## getItemIndex
returns the item index of the currently selected item
#### Returns:
1. `number` The current index
#### Usage:
* Creates a default menubar with 3 entries selects the second entry and prints the currently selected index.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry",colors.yellow)
aMenubar:addItem("3. Entry",colors.yellow,colors.green)
aMenubar:selectItem(2)
basalt.debug(aMenubar:getItemIndex())
```
## setSelectedItem
Sets the background and the foreground of the item which is currently selected
#### Parameters:
1. `number|color` The background color which should be used
2. `number|color` The text color which should be used
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default menubar with 4 entries and sets the selection background color to green.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry")
aMenubar:addItem("3. Entry")
aMenubar:addItem("4. Entry")
aMenubar:setSelectedItem(colors.green, colors.yellow)
```
```xml
<menubar selectionBG="green" selectionFG="yellow">
<item><text>1. Entry</text></item>
<item><text>2. Entry</text></item>
<item><text>3. Entry</text></item>
<item><text>4. Entry</text></item>
</menubar>
```
## setOffset
Sets the offset of the menubar (the same as you would scroll) - default is 0
#### Parameters:
1. `number` The offset value
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default menubar with 6 entries and sets the offset to 3.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry")
aMenubar:addItem("3. Entry")
aMenubar:addItem("4. Entry")
aMenubar:addItem("5. Entry")
aMenubar:addItem("6. Entry")
aMenubar:setOffset(3)
```
```xml
<menubar offset="3">
<item><text>1. Entry</text></item>
<item><text>2. Entry</text></item>
<item><text>3. Entry</text></item>
<item><text>4. Entry</text></item>
<item><text>5. Entry</text></item>
<item><text>6. Entry</text></item>
</menubar>
```
## getOffset
returns the current offset
#### Returns:
1. `number` Current offset
#### Usage:
* Creates a default menubar with 6 entries and sets the offset to 3, prints the current offset.
```lua
local mainFrame = basalt.createFrame()
local aMenubar = mainFrame:addMenubar()
aMenubar:addItem("1. Entry")
aMenubar:addItem("2. Entry")
aMenubar:addItem("3. Entry")
aMenubar:addItem("4. Entry")
aMenubar:addItem("5. Entry")
aMenubar:addItem("6. Entry")
aMenubar:getOffset(3)
basalt.debug(aMenubar:getOffset())
```

395
docs/docs1_6/objects/Object.md Normal file
View File

@@ -0,0 +1,395 @@
This is the base class for all visual objects. Which means, if you create a button, label, frame or something else (no timers, threads or animations) the following methods apply:
## show
Shows the object (only if the parent frame is already visible)
#### Returns:
1. `object` The object in use
#### Usage:
* Shows a frame
```lua
local mainFrame = basalt.createFrame()
local button = mainFrame:addButton()
button:show()
```
```xml
<button visible="true" />
```
## hide
Hides the object
#### Returns:
1. `object` The object in use
#### Usage:
* Hides a frame
```lua
local mainFrame = basalt.createFrame()
local button = mainFrame:addButton():setText("Close"):onClick(function() mainFrame:hide() end)
```
```xml
<button visible="false" />
```
## setPosition
Changes the position relative to its parent frame
#### Parameters:
1. `number` x coordinate
2. `number` y coordinate
3. `boolean` Whether it will add/remove to the current coordinates instead of setting them
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the Buttons position to an x coordinate of 2 with a y coordinate of 3
```lua
local mainFrame = basalt.createFrame()
mainFrame:addButton():setPosition(2,3)
```
```xml
<button x="2" y="3" />
```
## setBackground
Changes the object background color, if you set the value to false the background wont be visible. For example you could see trough a frame.
#### Parameters:
1. `number|color` Background color
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a frame, and sets its background color to `colors.gray`
```lua
local mainFrame = basalt.createFrame():setBackground(colors.gray)
```
```xml
<button bg="gray" />
```
## setForeground
Changes the object text color
#### Parameters:
1. `number|color` Foreground color
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a frame, and sets its foreground color to `colors.green`
```lua
local mainFrame = basalt.createFrame():setForeground(colors.green)
```
```xml
<button fg="green" />
```
## setSize
Changes the object size
#### Parameters:
1. `number` width
2. `number` height
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the frame to have a width of 15 and a height of 12
```lua
local mainFrame = basalt.createFrame()
local subFrame = mainFrame:addFrame():setSize(15,12)
```
```xml
<frame width="15" height="12" />
```
## setFocus
Sets the object to be the focused object.
If you click on an object, it's normally automatically the focused object. For example, if you call :show() on a frame, and you want this particular frame to be in
the foreground, you should also use :setFocus()
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the button to the focused object
```lua
local mainFrame = basalt.createFrame()
local aButton = mainFrame:addButton():setFocus()
```
## setZIndex
Sets the z-index. Higher value means higher draw/event priority. You can also add multiple objects to the same z-index, if so the last added object will have the highest priority.
#### Parameters:
1. `number` z-index
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the buttons z-index to `1` and the labels z-index to `2`
```lua
local mainFrame = basalt.createFrame()
local aButton = mainFrame:addButton():setZIndex(1):setPosition(2,2)
local aLabel = mainFrame:addButton():setZIndex(2):setPosition(2,2):setText("I am a label!")
```
```xml
<button x="2" y="2" zIndex="1" />
<label x="2" y="2" text="I am a label!" zIndex="2" />
```
## setParent
Sets the parent frame of the object
#### Parameters:
1. `frame` The to-be parent frame
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the parent frame of the random frame, adding it to the main frame when the button is clicked"
```lua
local mainFrame = basalt.createFrame()
local aRandomFrame = basalt.createFrame()
local aButton = mainFrame:addButton():onClick(
function()
aRandomFrame:setParent(mainFrame)
end
)
```
## isFocused
Returns if the object is currently the focused object of the parent frame
#### Returns:
1. `boolean` Whether the object is focused
#### Usage:
* Prints whether the button is focused to the debug console
```lua
local mainFrame = basalt.createFrame()
local aButton = mainFrame:addButton()
basalt.debug(aButton:isFocused()) -- shows true or false as a debug message
```
## getAnchorPosition
Converts the x and y coordinates into the anchor coordinates of the object
#### Parameters:
1. `number|nil` x
2. `number|nil` y, if nothing it uses the object's x, y
#### Returns:
1. `number` x
2. `number` y
#### Usage:
* Prints the anchor position to the debug console
```lua
local mainFrame = basalt.createFrame():setSize(15,15)
local aButton = mainFrame:addButton()
:setAnchor("bottomRight")
:setSize(8,1)
:setPosition(1,1)
basalt.debug(aButton:getAnchorPosition()) -- returns 7,14 (framesize - own size) instead of 1,1
```
## setAnchor
Sets the anchor of the object
#### Parameters:
1. `string` Anchor sides `("topLeft" "top", "topRight", "right", "bottomRight", "bottom", "bottomLeft", "left", "center")`
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the button to have an anchor of `bottomRight`
```lua
local mainFrame = basalt.createFrame():show()
local aButton = mainFrame:addButton()
:setAnchor("bottomRight")
:setSize(8,1)
:setPosition(-8,1)
```
```xml
<button anchor="bottomRight" />
```
## getAbsolutePosition
Converts the relative coordinates into absolute coordinates
#### Parameters:
1. `number|nil` x
2. `number|nil` y
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a frame and a button and prints the button's absolute position to the debug console
```lua
local mainFrame = basalt.createFrame():setPosition(3,3)
local aButton = mainFrame:addButton():setSize(8,1):setPosition(4,2)
basalt.debug(aButton:getAbsolutePosition()) -- returns 7,5 (frame coords + own coords) instead of 4,2
```
## setValue
Sets the value of that object (input, label, checkbox, textfield, scrollbar,...)
#### Parameters:
1. `any` Value to set the object to
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a checkbox and ticks it
```lua
local mainFrame = basalt.createFrame()
local aCheckbox = mainFrame:addCheckbox():setValue(true)
```
```xml
<checkbox value="true" />
```
## getValue
Returns the currently saved value
#### Returns:
1. `any` Object's value
#### Usage:
* Prints the value of the checkbox to the debug console
```lua
local mainFrame = basalt.createFrame()
local aCheckbox = mainFrame:addCheckbox():setValue(true)
basalt.debug(aCheckbox:getValue()) -- returns true
```
## getHeight/getWidth
Returns the respective height/width of the object
#### Returns:
1. `number` height/width
#### Usage:
* Prints the height of the object to the debug console
```lua
local mainFrame = basalt.createFrame()
local aButton = mainFrame:addButton():setSize(5,8)
basalt.debug(aButton:getHeight()) -- returns 8
```
## isVisible
Returns if the object is currently visible
#### Returns:
1. `boolean`
#### Usage:
* Prints boolean visibility of object to debug console
```lua
local mainFrame = basalt.createFrame()
local aButton = mainFrame:addButton():setSize(5,8)
basalt.debug(aButton:isVisible()) -- returns true
```
## getName
Returns the given name of the object
#### Returns:
1. `string` name
#### Usage:
* Prints name of object to debug window
```lua
local mainFrame = basalt.createFrame()
basalt.debug(mainFrame:getName()) -- returns myFirstFrame
```
## setShadow
Sets the shadow color - default: colors.black
#### Parameters:
1. `number|color` Shadow color
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the shadow to green and shows it:
```lua
local mainFrame = basalt.createFrame()
local subFrame = mainFrame:addFrame()
:setMoveable()
:setSize(18,6)
:setShadow(colors.green)
:showShadow(true)
```
```xml
<frame width="18" height="6" shadow="true" shadowColor="green" moveable="true" />
```
## showShadow
Shows or hides the shadow
#### Parameters:
1. `boolean` Whether it should show or hide the shadow
#### Returns:
1. `object` The object in use
#### Usage:
* Shows the shadow:
```lua
local mainFrame = basalt.createFrame()
local subFrame = mainFrame:addFrame()
:setMoveable()
:setSize(18,6)
:showShadow(true)
```
```xml
<frame width="18" height="6" shadow="true" moveable="true" />
```
## setBorder
Sets the border color - default: colors.black
#### Parameters:
1. `number|color` Border color
#### Returns:
1. `object` The object in use
#### Usage:
* Sets the border to green and shows it:
```lua
local mainFrame = basalt.createFrame()
local subFrame = mainFrame:addFrame()
:setMoveable()
:setSize(18,6)
:setBorder(colors.green)
:showBorder("left", "top", "right", "bottom")
```
```xml
<frame width="18" height="6" border="true" borderColor="green" moveable="true" />
```
## showBorder
Shows or hides the border
#### Parameters:
1. `strings` Whether it should show or hide the border on the specific sides ("left", "top", "right", "bottom")
#### Returns:
1. `object` The object in use
#### Usage:
* Shows the border:
```lua
local mainFrame = basalt.createFrame()
local subFrame = mainFrame:addFrame()
:setMoveable()
:setSize(18,6)
:showBorder("left", "top", "bottom")
```
```xml
<frame width="18" height="6" border="true" borderColor="green" borderRight="false" moveable="true" />
```

19
docs/docs1_6/objects/Pane.md Normal file
View File

@@ -0,0 +1,19 @@
Panes are very simple sizeable background objects.
The following list is only available to panes: <br>
Remember Pane also inherits from [Object](objects/Object.md)
Pane doesn't have any custom functionallity. If you want to change the color/position or size, just check out the [object](https://github.com/NoryiE/basalt/wiki/Object) wikipage.
## Example:
```lua
local mainFrame = basalt.createFrame()
local aPane = mainFrame:addPane()
aPane:setSize(30, 10)
aPane:setBackground(colors.yellow)
aPane:show()
```
```xml
<pane width="30" height="10" bg="yellow" />
```

167
docs/docs1_6/objects/Program.md Normal file
View File

@@ -0,0 +1,167 @@
Program objects are here for opening other executable programs in your main program. You can execute worms, shell or any custom program you've made.
<br>
Remember Program inherits from [Object](objects/Object.md)
## getStatus
returns the current process status
#### Returns:
1. `string` current status ("running", "normal, "suspended", or "dead")
#### Usage:
* Prints current status
```lua
local mainFrame = basalt.createFrame()
local aProgram = mainFrame:addProgram()
basalt.debug(aProgram:getStatus())
```
## execute
Executes the given path or program
#### Parameters:
1. `string|function` the path to your file as string, or function which should be called
#### Returns:
1. `object` The object in use
#### Usage:
* Executes worm
```lua
local mainFrame = basalt.createFrame()
local aProgram = mainFrame:addProgram()
aProgram:execute("rom/programs/fun/worm.lua") -- executes worm
```
```xml
<program path="rom/programs/fun/worm.lua" execute="true" />
```
## stop
Stops a currently running program
#### Returns:
1. `object` The object in use
#### Usage:
* Stops worm by clicking a button
```lua
local mainFrame = basalt.createFrame()
local aProgram = mainFrame:addProgram()
aProgram:execute("rom/programs/fun/worm.lua") -- executes worm
mainFrame:addButton():setText("Pause"):onClick(function() aProgram:stop() end):show()
```
## pause
pauses the current program (prevents the program from receiving events)
#### Parameters:
1. `boolean` true, false or nothing
#### Returns:
1. `object` The object in use
#### Usage:
* Pauses worm by clicking a button
```lua
local mainFrame = basalt.createFrame():show()
local aProgram = mainFrame:addProgram():execute("rom/programs/shell.lua"):show()
mainFrame:addButton():setText("Pause"):onClick(function() aProgram:pause(true) end):show()
```
## isPaused
returns if the program is paused
#### Returns:
1. `boolean` pause status
#### Usage:
* Prints the pause status of the program
```lua
local mainFrame = basalt.createFrame():show()
local aProgram = mainFrame:addProgram():execute("rom/programs/shell.lua"):show()
basalt.debug(aProgram:isPaused())
```
## injectEvent
injects a event into the program manually. For example you could inject w a s and d for worm, by clicking buttons.
#### Parameters:
1. `string` event
2. `any` parameter
3. `any` parameter
4. `any` parameter
5. `any` parameter
6. `boolean` if this is true, the injected event will be executed even if the program is paused
#### Returns:
1. `object` The object in use
#### Usage:
* injects a event by clicking a button
```lua
local mainFrame = basalt.createFrame():show()
local aProgram = mainFrame:addProgram():execute("rom/programs/shell.lua"):show()
mainFrame:addButton():setText("inject"):onClick(function() aProgram:injectEvent("char", "w") end):show()
```
## injectEvents
Injects multiple events
#### Parameters:
1. `table` a table, items should be {event="event", args={para1, para2, para3, para4}}
#### Returns:
1. `object` The object in use
#### Usage:
* injects a multiple char events by clicking a button
```lua
local mainFrame = basalt.createFrame():show()
local aProgram = mainFrame:addProgram():execute("rom/programs/shell.lua"):show()
local events = {
{event="char", args={"h"}},
{event="char", args={"e"}},
{event="char", args={"y"}}
}
mainFrame:addButton():setText("inject"):onClick(function() aProgram:injectEvents(events) end):show()
```
## getQueuedEvents
If the program is paused, incomming events will be inserted into a queued events table. As soon as the program is unpaused, the queued events table will be empty
#### Returns:
1. `table` a table - {event="event", args={"a", "b",...}}
#### Usage:
* prints the queued events table
```lua
local mainFrame = basalt.createFrame():show()
local aProgram = mainFrame:addProgram():execute("rom/programs/shell.lua"):show()
mainFrame:addButton():setText("inject"):onClick(function() basalt.debug(aProgram:getQueuedEvents()) end):show()
```
## updateQueuedEvents
Here you can manipulate the queued events table
#### Parameters:
1. `table` a table, items should be {event="event", args={para1, para2, para3, para4}}
#### Returns:
1. `object` The object in use
```lua
local mainFrame = basalt.createFrame():show()
local aProgram = mainFrame:addProgram():execute("rom/programs/shell.lua"):show()
mainFrame:addButton():setText("inject"):onClick(function()
local events = aProgram:getQueuedEvents()
table.insert(events,1,{event="char", args={"w"}}
aProgram:updateQueuedEvents(events)
end):show()
```

134
docs/docs1_6/objects/Progressbar.md Normal file
View File

@@ -0,0 +1,134 @@
Progressbars are objects to visually display the current state of your progression. They always go from 0 to 100 (%) - no matter how big they are. which means if you
want to add some energy progress you have to do simple maths: currentValue / maxValue * 100
Here are all possible functions available for progessbars. Remember progressbar inherits from [Object](objects/Object.md)
## setDirection
Sets the direction in which the bar should be expanding.
#### Parameters:
1. `number` x direction (0 = left to right, 1 = top to bottom, 2 = right to left and 3 = bottom to top)
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a progressbar and sets the direction from bottom to top
```lua
local mainFrame = basalt.createFrame()
local aProgressbar = mainFrame:addProgressbar()
aProgressbar:setDirection(3)
```
```xml
<frame direction="3"></frame>
```
## setProgress
This is the function you need to call if you want the progression to change.
#### Parameters:
1. `number` a number from 0 to 100
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a progressbar and sets the current progress to 50
```lua
local mainFrame = basalt.createFrame()
local aProgressbar = mainFrame:addProgressbar()
aProgressbar:setProgress(50)
```
## getProgress
Returns the current progress status
#### Returns:
1. `number` progress (0-100)
#### Usage:
* Creates a progressbar, sets the current progress to 50 and prints the current progress
```lua
local mainFrame = basalt.createFrame()
local aProgressbar = mainFrame:addProgressbar()
aProgressbar:setProgress(50)
basalt.debug(aProgressbar:getProgress())
```
## setProgressBar
This function will change the visual display of your progress bar
#### Parameters:
1. `number|color` the expanding progress bar color
2. `char` optional - the bar symbol - default is " " (space)
3. `number|color` optional - the bar symbol color
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a progressbar and sets the progressbar color to green
```lua
local mainFrame = basalt.createFrame()
local aProgressbar = mainFrame:addProgressbar()
aProgressbar:setProgressBar(colors.green, colors.yellow, colors.red)
```
```xml
<progressbar progressColor="green" progressSymbol="yellow" progressSymbolColor="red" />
```
## setBackgroundSymbol
Will change the default background symbol (default is " " - space)
#### Parameters:
1. `char` the background symbol
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a progressbar and sets the progressbar background symbol to X
```lua
local mainFrame = basalt.createFrame()
local aProgressbar = mainFrame:addProgressbar()
aProgressbar:setBackgroundSymbol("X")
```
```xml
<progressbar backgroundSymbol="X" />
```
# Events
## onProgressDone
`onProgressDone(self)`<br>
A custom event which gets triggered as soon as the progress reaches 100.
Here is a example on how to add a onProgressDone event to your progressbar:
```lua
local basalt = require("Basalt")
local mainFrame = basalt.createFrame()
local aProgressbar = mainFrame:addProgressbar()
function progressDone()
basalt.debug("The Progressbar reached 100%!")
end
aProgressbar:onProgressDone(progressDone)
```
Here is also a example how this is done with xml:
```lua
local basalt = require("Basalt")
local mainFrame = basalt.createFrame()
basalt.setVariable("progressDone", function()
basalt.debug("The Progressbar reached 100%!")
end)
```
```xml
<progressbar onDone="progressDone" />
```

229
docs/docs1_6/objects/Radio.md Normal file
View File

@@ -0,0 +1,229 @@
Radios are objects which you can freely place, and the user is then able to select a single item.
If you want to access values inside items this is how the table for single items is made (just a example):
```lua
item = {
text="1. Entry",
bgCol=colors.black,
fgCol=colors.white
args = {}
}
```
Remember Radios also inherits from [Object](objects/Object.md)
## addItem
Adds a item to the radio
#### Parameters:
1. `string` The entry name
2. `number` x position
3. `number` y position
2. `number|color` unique default background color - optional
3. `number|color` unique default text color - optional
4. `any` any value - you could access this later in a :onChange() event (you need to use :getValue()) - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default radio with 3 entries
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
```
```xml
<radio>
<item><text>1. Entry</text><x>5</x><y>2</y></item>
<item><text>2. Entry</text><x>5</x><y>4</y><bg>yellow</bg></item>
<item><text>3. Entry</text><x>5</x><y>6</y><bg>yellow</bg><fg>green</fg></item>
</radio>
```
## removeItem
Removes a item from the radio
#### Parameters:
1. `number` The index which should get removed
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default radio with 3 entries and removes the second one.
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
aRadio:removeItem(2)
```
## editItem
Edits a item from the radio
#### Parameters:
1. `number` The index which should be edited
2. `string` The new item name
3. `number` the new x position
4. `number` the new y position
3. `number|color` the new item background color - optional
4. `number|color` The new item text color - optional
5. `any` New additional information - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default radio with 3 entries and changes the second one.
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
aRadio:editItem(2, "Still 2. Entry", 5, 4, colors.red)
```
## getItem
Returns a item by index
#### Parameters:
1. `number` The index which should be returned
#### Returns:
1. `table` The item table example: {text="1. Entry", bgCol=colors.black, fgCol=colors.white}
#### Usage:
* Creates a default radio with 3 entries and edits the second one.
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
basalt.debug(aRadio:getItem(2).text)
```
## getItemCount
Returns the current item count
#### Returns:
1. `number` The item radio count
#### Usage:
* Creates a default radio with 3 entries and prints the current item count.
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
basalt.debug(aRadio:getItemCount())
```
## getAll
Returns all items as table
#### Returns:
1. `table` All items
#### Usage:
* Creates a default menubar with 3 entries and prints a table.
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
basalt.debug(aRadio:getAll())
```
## selectItem
selects a item in the radio (same as a player would click on a item)
#### Parameters:
1. `number` The index which should get selected
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default radio with 3 entries and selects the second entry.
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
aRadio:selectItem(2)
```
## clear
Removes all items.
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default radio with 3 entries and removes them immediatley. Which makes no sense.
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
aRadio:clear()
```
## getItemIndex
returns the item index of the currently selected item
#### Returns:
1. `number` The current index
#### Usage:
* Creates a default radio with 3 entries selects the second entry and prints the currently selected index.
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
aRadio:selectItem(2)
basalt.debug(aRadio:getItemIndex())
```
## setSelectedItem
Sets the background and the foreground of the item which is currently selected
#### Parameters:
1. `number|color` The background color which should be used
2. `number|color` The text color which should be used
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a default radio with 4 entries and sets the selection background color to green.
```lua
local mainFrame = basalt.createFrame()
local aRadio = mainFrame:addRadio()
aRadio:addItem("1. Entry",5,2)
aRadio:addItem("2. Entry",5,4,colors.yellow)
aRadio:addItem("3. Entry",5,6,colors.yellow,colors.green)
aRadio:addItem("4. Entry",5,8)
aRadio:setSelectedItem(colors.green, colors.red)
```
```xml
<radio selectionBG="green" selectionFG="red">
<item><text>1. Entry</text><x>5</x><y>2</y></item>
<item><text>2. Entry</text><x>5</x><y>4</y><bg>yellow</bg></item>
<item><text>3. Entry</text><x>5</x><y>6</y><bg>yellow</bg><fg>green</fg></item>
</radio>
```

108
docs/docs1_6/objects/Scrollbar.md Normal file
View File

@@ -0,0 +1,108 @@
Scrollbars are objects, the user can scroll vertically or horizontally, this will change a value, which you can access by :getValue().<br>
Remember scrollbar also inherits from [Object](objects/Object.md)
## setSymbol
Changes the scrollbar symbol, default is " "
#### Parameters:
1. `string` symbol
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new scrollbar and changes the symbol to X
```lua
local mainFrame = basalt.createFrame()
local scrollbar = mainFrame:addScrollbar():setSymbol("X")
```
```xml
<scrollbar symbol="X" />
```
## setBackgroundSymbol
Changes the symbol in the background, default is "\127"
#### Parameters:
1. `string` symbol
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new scrollbar and changes the background symbol to X
```lua
local mainFrame = basalt.createFrame()
local scrollbar = mainFrame:addScrollbar():setBackgroundSymbol("X")
```
```xml
<scrollbar backgroundSymbol="X" />
```
## setBarType
Changes the scrollbar to be vertical or horizontal, default is vertical
#### Parameters:
1. `string` vertical or horizontal
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new scrollbar and changes the bar type to horizontal
```lua
local mainFrame = basalt.createFrame()
local scrollbar = mainFrame:addScrollbar():setBarType("horizontal")
```
```xml
<scrollbar barType="horizontal" />
```
## setMaxValue
the default max value is always the width (if horizontal) or height (if vertical), if you change the max value the bar will always calculate the value based on its width or height - example: you set the max value to 100, the height is 10 and it is a vertical bar, this means if the bar is on top, the value is 10, if the bar goes one below, it is 20 and so on.
#### Parameters:
1. `number` maximum
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new scrollbar and changes the max value to 20
```lua
local mainFrame = basalt.createFrame()
local scrollbar = mainFrame:addScrollbar():setMaxValue(20)
```
```xml
<scrollbar maxValue="20" />
```
## setIndex
Changes the current index to your choice, for example you could create a button which scrolls up to 1 by using :setIndex(1)
#### Parameters:
1. `number` the index
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new scrollbar and changes the index to 1 as soon as the button got clicked
```lua
local mainFrame = basalt.createFrame()
local scrollbar = mainFrame:addScrollbar():setMaxValue(20)
local button = mainFrame:addButton(function()
scrollbar:setIndex(1)
end)
```
```xml
<scrollbar index="2" />
```
## getIndex
Returns the current index
#### Returns:
1. `number` index

108
docs/docs1_6/objects/Slider.md Normal file
View File

@@ -0,0 +1,108 @@
Sliders are objects, the user can scroll vertically or horizontally, this will change a value, which you can access by :getValue().<br>
Remember slider also inherits from [Object](objects/Object.md)
## setSymbol
Changes the slider symbol, default is " "
#### Parameters:
1. `string` symbol
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new slider and changes the symbol to X
```lua
local mainFrame = basalt.createFrame()
local slider = mainFrame:addSlider():setSymbol("X")
```
```xml
<slider symbol="X" />
```
## setBackgroundSymbol
Changes the symbol in the background, default is "\140"
#### Parameters:
1. `string` symbol
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new slider and changes the background symbol to X
```lua
local mainFrame = basalt.createFrame()
local slider = mainFrame:addSlider():setBackgroundSymbol("X")
```
```xml
<slider backgroundSymbol="X" />
```
## setBarType
Changes the slider to be vertical or horizontal, default is horizontal
#### Parameters:
1. `string` vertical or horizontal
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new slider and changes the bar type to horizontal
```lua
local mainFrame = basalt.createFrame()
local slider = mainFrame:addSlider():setBarType("vertical")
```
```xml
<slider barType="vertical" />
```
## setMaxValue
the default max value is always the width (if horizontal) or height (if vertical), if you change the max value the bar will always calculate the value based on its width or height - example: you set the max value to 100, the height is 10 and it is a vertical bar, this means if the bar is on top, the value is 10, if the bar goes one below, it is 20 and so on.
#### Parameters:
1. `number` maximum
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new slider and changes the max value to 20
```lua
local mainFrame = basalt.createFrame()
local slider = mainFrame:addSlider():setMaxValue(20)
```
```xml
<slider maxValue="20" />
```
## setIndex
Changes the current index to your choice, for example you could create a button which scrolls up to 1 by using :setIndex(1)
#### Parameters:
1. `number` the index
#### Returns:
1. `object` The object in use
#### Usage:
* Creates a new slider and changes the index to 1 as soon as the button got clicked
```lua
local mainFrame = basalt.createFrame()
local slider = mainFrame:addSlider():setMaxValue(20)
local button = mainFrame:addButton(function()
slider:setIndex(1)
end)
```
```xml
<slider index="2" />
```
## getIndex
Returns the current index
#### Returns:
1. `number` index

161
docs/docs1_6/objects/Textfield.md Normal file
View File

@@ -0,0 +1,161 @@
Textfields are objects, where the user can write something on multiple lines. it act's like the default edit script (without coloring)<br>
Remember textfield inherits from [Object](objects/Object.md)
## getLines
Returns all lines
#### Returns:
1. `table` lines
#### Usage:
* Prints all lines
```lua
local mainFrame = basalt.createFrame("myFirstFrame"):show()
local aTextfield = mainFrame:addTextfield("myFirstTextfield"):show()
basalt.debug(aTextfield:getLines())
```
## getLine
Returns the line on index position
#### Parameteres:
1. `number` index
#### Returns:
1. `string` line
#### Usage:
* Prints one line
```lua
local mainFrame = basalt.createFrame("myFirstFrame"):show()
local aTextfield = mainFrame:addTextfield("myFirstTextfield"):show()
basalt.debug(aTextfield:getLine(1))
```
## editLine
Edits the line on index position
#### Parameteres:
1. `number` index
2. `string` text
#### Returns:
1. `object` The object in use
#### Usage:
* Edits the line
```lua
local mainFrame = basalt.createFrame("myFirstFrame"):show()
local aTextfield = mainFrame:addTextfield("myFirstTextfield"):show()
basalt.debug(aTextfield:editLine(1, "Hello!"))
```
## addLine
Adds a line on index position
#### Parameteres:
1. `string` text
2. `number` index
#### Returns:
1. `object` The object in use
#### Usage:
* Adds a line
```lua
local mainFrame = basalt.createFrame("myFirstFrame"):show()
local aTextfield = mainFrame:addTextfield("myFirstTextfield"):show()
basalt.debug(aTextfield:addLine("Hello!", 1))
```
```xml
<textfield>
<lines>
<line>Hello!</line>
</lines>
</textfield>
```
## removeLine
Removes the line on index position
#### Parameteres:
1. `number` index
2. `string` text
#### Returns:
1. `object` The object in use
#### Usage:
* Removes a line
```lua
local mainFrame = basalt.createFrame("myFirstFrame"):show()
local aTextfield = mainFrame:addTextfield("myFirstTextfield"):show()
basalt.debug(aTextfield:removeLine())
```
## getTextCursor
Gets text cursor position
#### Returns:
1. `number` x position
2. `number` y position
## addKeywords
Adds keywords for special coloring
#### Parameteres:
1. `number|color` color of your choice
2. `table` a list of keywords which should be colored example: {"if", "else", "then", "while", "do"}
#### Returns:
1. `object` The object in use
#### Usage:
* Changes the color of some words to purple
```lua
local mainFrame = basalt.createFrame()
local aTextfield = mainFrame:addTextfield():addKeywords(colors.purple, {"if", "else", "then", "while", "do", "hello"})
```
```xml
<textfield>
<keywords>
<purple>
<keyword>if</keyword>
<keyword>else</keyword>
<keyword>then</keyword>
<keyword>while</keyword>
<keyword>do</keyword>
<keyword>hello</keyword>
</purple>
</keywords>
</textfield>
```
## addRule
Adds a new rule for special coloring
#### Parameteres:
1. `string` a pattern - check out this page: (https://riptutorial.com/lua/example/20315/lua-pattern-matching)
2. `number|color` text color
3. `number|color` background color - optional
#### Returns:
1. `object` The object in use
#### Usage:
* Changes the color of all numbers
```lua
local mainFrame = basalt.createFrame()
local aTextfield = mainFrame:addTextfield():addRule("%d", colors.lightBlue)
```
```xml
<textfield>
<rules>
<rule>
<pattern>%d</pattern>
<fg>lightBlue</fg>
</rule>
</rules>
</textfield>
```

65
docs/docs1_6/objects/Thread.md Normal file
View File

@@ -0,0 +1,65 @@
Threads are being executed simultaneously.
<br>
## start
starts a new thread and executes the function
#### Parameters:
1. `function` the function which should be executed
#### Returns:
1. `object` The object in use
#### Usage:
* Starts a new thread
```lua
local mainFrame = basalt.createFrame()
local aThread = mainFrame:addThread()
local function randomThreadFunction()
while true do
basalt.debug("Thread is active")
os.sleep(1) -- a sleep/coroutine.yield() or pullEvent is required otherwise we will never come back to the main program (error)
end
end
aThread:start(randomThreadfunction)
```
you are also able to start threads via xml:
```lua
basalt.setVariable("myThread", function() while true do os.sleep(1) end end)
```
```xml
<thread thread="myThread" start="true"/>
```
## stop
stops the thread
#### Returns:
1. `object` The object in use
#### Usage:
* Stops the current running thread by clicking on a button
```lua
local mainFrame = basalt.createFrame()
local aThread = mainFrame:addThread()
local function randomThreadFunction()
while true do
basalt.debug("Thread is active")
os.sleep(1) -- a sleep/coroutine.yield() or pullEvent is required otherwise we will never come back to the main program (error)
end
end
aThread:start(randomThreadfunction)
local aButton = mainFrame:addButton():setText("Stop Thread"):onClick(function() aThread:stop() end)
```
## getStatus
gets the current thread status
#### Returns:
1. `string` current status - ("running", "normal", "suspended", "dead")
#### Usage:
```lua
local mainFrame = basalt.createFrame()
local aThread = mainFrame:addThread()
basalt.debug(aThread:getStatus())
```

84
docs/docs1_6/objects/Timer.md Normal file
View File

@@ -0,0 +1,84 @@
Timers can call your functions delay and repeat it as often as you wish
<br>
## setTime
sets the time the timer should wait after calling your function
#### Parameters:
1. `number` the time to delay
2. `number` how often it should be repeated -1 is infinite
#### Returns:
1. `object` The object
```lua
local mainFrame = basalt.createFrame()
local aTimer = mainFrame:addTimer()
aTimer:setTime(2)
```
```xml
<timer time="2" repeat="1"/>
```
## start
Starts the timer
#### Returns:
1. `object` The object
```lua
local mainFrame = basalt.createFrame()
local aTimer = mainFrame:addTimer()
aTimer:setTime(2):start()
```
```xml
<timer time="2" start="true"/>
```
## cancel
Cancels the timer
#### Returns:
1. `object` The object
```lua
local mainFrame = basalt.createFrame()
local aTimer = mainFrame:addTimer()
aTimer:setTime(2):start()
aTimer:cancel()
```
# Events
## onCall
`onCall(self)`<br>
A custom event which gets triggered as soon as the current timer has finished
Here is a example on how to add a onCall event to your timer:
```lua
local basalt = require("Basalt")
local mainFrame = basalt.createFrame()
local aTimer = mainFrame:addTimer()
function call()
basalt.debug("The timer has finished!")
end
aTimer:onCall(call)
```
Here is also a example how this is done with xml:
```lua
local basalt = require("Basalt")
local mainFrame = basalt.createFrame()
basalt.setVariable("call", function()
basalt.debug("The timer has finished!")
end)
```
```xml
<progressbar onDone="call" />
```