Small docs update

This commit is contained in:
Robert Jelic
2023-05-22 20:12:19 +02:00
parent 4feeaa7942
commit cfb4a197cd
5 changed files with 429 additions and 34 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.2 KiB

Binary file not shown.

Binary file not shown.

View File

@@ -1,50 +1,153 @@
A Flexbox is a layout container designed to facilitate the creation of flexible and responsive UI designs. It allows you to efficiently arrange and align its child elements within it.
Flexbox is an incredibly powerful tool for layout design in Basalt, it allows for dynamic positioning of elements in both rows and columns. This can make your program look much neater, and also simplify the placement and resizing of elements.
The Flexbox Container is still a WIP and i will add more methods from the CSS Flexbox Implementation.
In addition to the methods inherited from ScrollableFrame, Frame, Container, VisualObject and Object, Flexbox has the following methods:
In addition to the methods inherited from Frame, Container, VisualObject and Object, Flexbox has the following methods:
| | |
|---|---|
|[setSpacing](objects/Flexbox/setSpacing.md)|Defines the gap between child objects within the Flexbox
|[getSpacing](objects/Flexbox/getSpacing.md)|Returns the current gap size between child objects
|[setDirection](objects/Flexbox/setDirection.md)|Sets the direction for the arrangement of child objects (row/column)
|[getDirection](objects/Flexbox/getDirection.md)|Returns the currently set arrangement direction of child objects
|[setJustifyContent](objects/Flexbox/setJustifyContent.md)|Sets the alignment of child objects along the main axis (flex-start, center, flex-end, space-between, space-around, space-evenly)
|[getJustifyContent](objects/Flexbox/getJustifyContent.md)|Returns the current alignment setting for child objects along the main axis
|[setWrap](objects/Flexbox/setWrap.md)|Determines if child objects should wrap onto the next line when they run out of space
|[getWrap](objects/Flexbox/getWrap.md)|Returns the current wrapping behavior for child objects
|[updateLayout](objects/Flexbox/updateLayout.md)|Manually triggers a layout update for the Flexbox
|[addBreak](objects/Flexbox/addBreak.md)|Introduces a line break within the Flexbox, forcing subsequent child objects to the next line
|[setDirection](objects/BaseFrame/getOffset.md)|Sets the direction in which the children will be placed
|[getDirection](objects/BaseFrame/getOffset.md)|Returns the direction
|[setSpacing](objects/BaseFrame/setOffset.md)|Sets the space between objects
|[getSpacing](objects/BaseFrame/setOffset.md)|Returns the space
|[setJuustifyContent](objects/BaseFrame/getOffset.md)|Determines how the children are aligned along the main axis
|[getJuustifyContent](objects/BaseFrame/getOffset.md)|Returns the justify content
Child objects added via the Flexbox have the following additional methods:
## Examples
| | |
|---|---|
|[getFlexGrow](objects/Flexbox/getFlexGrow.md)|Returns the flex grow factor of the child object
|[setFlexGrow](objects/Flexbox/setFlexGrow.md)|Sets the flex grow factor of the child object
|[getFlexShrink](objects/Flexbox/getFlexShrink.md)|Returns the flex shrink factor of the child object
|[setFlexShrink](objects/Flexbox/setFlexShrink.md)|Sets the flex shrink factor of the child object
|[getFlexBasis](objects/Flexbox/getFlexBasis.md)|Returns the flex basis of the child object
|[setFlexBasis](objects/Flexbox/setFlexBasis.md)|Sets the flex basis of the child object
### Nested Flexbox
### Example
Flexboxes can be nested within each other to create more complex layouts. This example demonstrates how to nest flexboxes.
Here's an example of how to create a Flexbox object:
<details>
<summary>Click here to show code</summary>
```lua
local flex = main:addFlexbox():setWrap("wrap"):setBackground(colors.lightGray):setPosition(1, 1):setSize("parent.w", "parent.h")
flex:addButton():setSize(10, 3)
flex:addButton():setSize(15, 3)
flex:addButton():setSize(8, 3)
flex:addButton():setSize(20, 3)
flex:addButton()
flex:addButton():setSize(10, 3)
flex:addButton():setSize(15, 3)
flex:addButton():setSize(8, 3)
flex:addButton():setSize(20, 3)
```
</details>
<br>
![Flexbox example](../_media/flexbox-example.png "Flexbox example")
### FlexGrow Property
<details>
<summary>Click here to show code</summary>
```lua
local basalt = require("basalt")
local main = basalt.createFrame()
local flexbox = main:addFlexbox()
:setDirection("column")
:setJustifyContent("space-between")
:setSpacing(5)
:setWrap("wrap")
flexbox:addButton()
local function makeResizeable(frame, minW, minH, maxW, maxH)
minW = minW or 4
minH = minH or 4
maxW = maxW or 99
maxH = maxH or 99
local btn = frame:addButton()
:ignoreOffset()
:setPosition("parent.w", "parent.h")
:setSize(1, 1)
:setText("/")
:setForeground(colors.black)
:setBackground(colors.gray)
:onDrag(function(self, _, _, xOffset, yOffset)
local w, h = frame:getSize()
local wOff, hOff = w, h
if(w+xOffset-1>=minW)and(w+xOffset-1<=maxW)then
wOff = w+xOffset-1
end
if(h+yOffset-1>=minH)and(h+yOffset-1<=maxH)then
hOff = h+yOffset-1
end
frame:setSize(wOff, hOff)
end)
end
local flexFrame = main:addMovableFrame():setSize(23, 12):setPosition(2, 2):setBackground(colors.gray):setBorder(colors.black)
local flex = flexFrame:addFlexbox():setWrap("wrap"):setPosition(2, 2):setSize("parent.w - 2", "parent.h - 2"):setBackground(colors.gray):setForeground(colors.black):setTheme({ButtonBG=colors.black, ButtonText=colors.lightGray})
flex:addButton():setFlexBasis(1):setFlexGrow(1)
flex:addButton():setFlexBasis(1):setFlexGrow(1)
flex:addButton():setFlexBasis(1):setFlexGrow(1)
flex:addButton():setFlexBasis(1):setFlexGrow(1)
flex:addButton():setFlexBasis(1):setFlexGrow(1)
flex:addButton():setFlexBasis(1):setFlexGrow(1)
flex:addButton():setFlexBasis(1):setFlexGrow(1)
flex:addButton():setFlexBasis(1):setFlexGrow(1)
makeResizeable(flexFrame, 11, 6)
basalt.autoUpdate()
```
Alternatively, you can create a flexbox using an XML layout:
</details>
<br>
<video width="600" controls autoplay loop muted>
<source src="./_media/flexgrow-property.mp4" type="video/mp4">
</video>
```xml
<flexbox direction="column" justifyContent="space-between" spacing="1" wrap="wrap">
#### Another example
This is another example, which shows how frames work with flexbox
<details>
<summary>Click here to show code</summary>
```lua
local basalt = require("BasaltDev2")
local main = basalt.createFrame()
local function makeResizeable(frame, minW, minH, maxW, maxH)
minW = minW or 4
minH = minH or 4
maxW = maxW or 99
maxH = maxH or 99
local btn = frame:addButton()
:ignoreOffset()
:setPosition("parent.w", "parent.h")
:setSize(1, 1)
:setText("/")
:setForeground(colors.black)
:setBackground(colors.gray)
:onDrag(function(self, _, _, xOffset, yOffset)
local w, h = frame:getSize()
local wOff, hOff = w, h
if(w+xOffset-1>=minW)and(w+xOffset-1<=maxW)then
wOff = w+xOffset-1
end
if(h+yOffset-1>=minH)and(h+yOffset-1<=maxH)then
hOff = h+yOffset-1
end
frame:setSize(wOff, hOff)
end)
end
local flexFrame = main:addMovableFrame():setSize(23, 12):setPosition(2, 2):setBackground(colors.gray):setBorder(colors.black)
local flex = flexFrame:addFlexbox():setWrap("wrap"):setPosition(2, 2):setSize("parent.w - 2", "parent.h - 2"):setBackground(colors.gray):setForeground(colors.black):setTheme({ButtonBG=colors.black, ButtonText=colors.lightGray})
local f1 = flex:addFrame():setBackground(colors.black):setSize(25, 10):setFlexBasis(1):setFlexGrow(1)
local f2 = flex:addFrame():setBackground(colors.black):setSize(25, 10):setFlexBasis(1):setFlexGrow(1)
f1:addLabel():setForeground(colors.lightGray):setText("Frame 1"):setPosition("parent.w/2-self.w/2", 2)
f1:addButton():setText("Button"):setPosition(2, 4):setBackground(colors.gray):setForeground(colors.black):setSize("math.floor(parent.w - 2)", 3)
f2:addLabel():setForeground(colors.lightGray):setSize("parent.w", "parent.h"):setText("lorem ipsum dolor sit amet, consectetur adipiscing elit. sed non risus. suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor. cras elementum ultrices diam. maecenas ligula massa, varius a, semper congue, euismod non, mi. proin porttitor, orci nec nonummy molestie, enim est eleifend mi, non fermentum diam nisl sit amet erat. Duis semper. Duis arcu massa, scelerisque vitae, consequat in, pretium a, enim. Pellentesque congue. Ut in risus volutpat libero pharetra tempor. Cras vestibulum bibendum augue. Praesent egestas leo in pede. Praesent blandit odio eu enim. Pellentesque sed dui ut augue blandit sodales. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Aliquam nibh. Mauris ac mauris sed pede pellentesque fermentum. Maecenas adipiscing ante non diam sodales hendrerit.")
makeResizeable(flexFrame, 11, 6)
basalt.autoUpdate()
```
</details>
<br>
<video width="600" controls autoplay loop muted>
<source src="./_media/frame-flexgrow-property.mp4" type="video/mp4">
</video>

View File

@@ -6,3 +6,295 @@ In addition to the methods inherited from Container, VisualObject and Object, Fr
|---|---|
|[getOffset](objects/BaseFrame/getOffset.md)|Returns the current offset of the BaseFrame object
|[setOffset](objects/BaseFrame/setOffset.md)|Sets a new offset for the BaseFrame object
## Examples
Here are some examples on how you can use frames to create very advanced programs. Because of the screen size limitation of CC:Tweaked frames can become very useful in almost every scenario. You will find some examples here on how you could implement them.
### Menubar for switching frames
In this example, we create a menubar that helps you switch between frames, without any animations involved.
<details>
<summary>Click here to show code</summary>
```lua
local basalt = require("basalt") -- we need basalt here
local main = basalt.createFrame():setTheme({FrameBG = colors.lightGray, FrameFG = colors.black}) -- we change the default bg and fg color for frames
local sub = { -- here we create a table where we gonna add some frames
main:addFrame():setPosition(1, 2):setSize("parent.w", "parent.h - 1"), -- obviously the first one should be shown on program start
main:addFrame():setPosition(1, 2):setSize("parent.w", "parent.h - 1"):hide(),
main:addFrame():setPosition(1, 2):setSize("parent.w", "parent.h - 1"):hide(),
}
local function openSubFrame(id) -- we create a function which switches the frame for us
if(sub[id]~=nil)then
for k,v in pairs(sub)do
v:hide()
end
sub[id]:show()
end
end
local menubar = main:addMenubar():setScrollable() -- we create a menubar in our main frame.
:setSize("parent.w")
:onChange(function(self, val)
openSubFrame(self:getItemIndex()) -- here we open the sub frame based on the table index
end)
:addItem("Example 1")
:addItem("Example 2")
:addItem("Example 3")
-- Now we can change our sub frames, if you want to access a sub frame just use sub[subid], some examples:
sub[1]:addButton():setPosition(2, 2)
sub[2]:addLabel():setText("Hello World!"):setPosition(2, 2)
sub[3]:addLabel():setText("Now we're on example 3!"):setPosition(2, 2)
sub[3]:addButton():setText("No functionality"):setPosition(2, 4):setSize(18, 3)
basalt.autoUpdate()
```
</details>
<br>
<video width="600" controls autoplay loop muted>
<source src="./_media/frames-with-menubars.mp4" type="video/mp4">
</video>
### Sidebar with buttons to switch frames
This example illustrates how to create a sidebar with buttons that can be used to switch between frames. Also note that :setZIndex(25) is used to ensure that the sidebar frame is always displayed on top of the normal subframes.
<details>
<summary>Click here to show code</summary>
```lua
local basalt = require("basalt") -- we need basalt here
local main = basalt.createFrame():setTheme({FrameBG = colors.lightGray, FrameFG = colors.black})
--[[
Here we create the sidebar, on focus it should change the position to parent.w - (self.w-1) which "opens the frame"
when the focus gets lost we simply change the position to "parent.w"
As you can see we add :setZIndex(25) - this makes sure the sidebar frame is always more important than our normal sub frames.
:setScrollable just makes the sidebar frame scrollable (in case you're adding more frames)
]]
local sidebar = main:addFrame():setBackground(colors.gray):setPosition("parent.w", 1):setSize(15, "parent.h"):setZIndex(25):setScrollable()
:onGetFocus(function(self)
self:setPosition("parent.w - (self.w-1)")
end)
:onLoseFocus(function(self)
self:setPosition("parent.w")
end)
-- Once again we add 3 frames, the first one should be immediatly visible
local sub = {
main:addFrame():setPosition(1, 1):setSize("parent.w", "parent.h"),
main:addFrame():setPosition(1, 1):setSize("parent.w", "parent.h"):hide(),
main:addFrame():setPosition(1, 1):setSize("parent.w", "parent.h"):hide(),
}
--This part of the code adds buttons based on the sub table.
local y = 2
for k,v in pairs(sub)do
sidebar:addButton():setText("Example "..k) -- creating the button and adding a name k is just the index
:setBackground(colors.black)
:setForeground(colors.lightGray)
:setSize("parent.w - 2", 3)
:setPosition(2, y)
:onClick(function() -- here we create a on click event which hides ALL sub frames and then shows the one which is linked to the button
for a, b in pairs(sub)do
b:hide()
v:show()
end
end)
y = y + 4
end
sub[1]:addButton():setPosition(2, 2)
sub[2]:addLabel():setText("Hello World!"):setPosition(2, 2)
sub[3]:addLabel():setText("Now we're on example 3!"):setPosition(2, 2)
sub[3]:addButton():setText("No functionality"):setPosition(2, 4):setSize(18, 3)
basalt.autoUpdate()
```
</details>
<br>
<video width="600" controls autoplay loop muted>
<source src="./_media/frames-with-sidebar.mp4" type="video/mp4">
</video>
### Movable frames with a program object
In this example, we will demonstrate how to create movable frames with a program object inside. This will also demonstrate how you can dynamically add new frames.
<details>
<summary>Click here to show code</summary>
```lua
local basalt = require("basalt")
local main = basalt.createFrame():setTheme({FrameBG = colors.lightGray, FrameFG = colors.black})
local id = 1
local processes = {}
local function openProgram(path, title, x, y, w, h)
local pId = id
id = id + 1
local f = main:addFrame()
:setMovable()
:setSize(w or 30, h or 12)
:setPosition(x or math.random(2, 12), y or math.random(2, 8))
f:addLabel()
:setSize("parent.w", 1)
:setBackground(colors.black)
:setForeground(colors.lightGray)
:setText(title or "New Program")
f:addProgram()
:setSize("parent.w", "parent.h - 1")
:setPosition(1, 2)
:execute(path or "rom/programs/shell.lua")
f:addButton()
:setSize(1, 1)
:setText("X")
:setBackground(colors.black)
:setForeground(colors.red)
:setPosition("parent.w", 1)
:onClick(function()
f:remove()
processes[pId] = nil
end)
processes[pId] = f
return f
end
openProgram("rom/programs/fun/worm.lua")
main:addButton():setPosition("parent.w - 16", 2):setText("Open"):onClick(function()
openProgram()
end)
basalt.autoUpdate()
```
</details>
<br>
<video width="600" controls autoplay loop muted>
<source src="./_media/dynamic-frames.mp4" type="video/mp4">
</video>
### Resizable frames
This example shows how to make your frames resizable manually, as Basalt does not offer a built-in way to do this. It is, however, a straightforward process.
<details>
<summary>Click here to show code</summary>
```lua
local basalt = require("basalt")
local main = basalt.createFrame():setTheme({FrameBG = colors.black, FrameFG = colors.lightGray})
local sub = main:addFrame():setSize(25, 12):setPosition(3, 3)
local function makeResizeable(frame, minW, minH, maxW, maxH)
minW = minW or 4
minH = minH or 4
maxW = maxW or 99
maxH = maxH or 99
local btn = frame:addButton()
:setPosition("parent.w", "parent.h")
:setSize(1, 1)
:setText("/")
:setForeground(colors.blue)
:setBackground(colors.black)
:onDrag(function(self, event, btn, xOffset, yOffset)
local w, h = frame:getSize()
local wOff, hOff = w, h
if(w+xOffset-1>=minW)and(w+xOffset-1<=maxW)then
wOff = w+xOffset-1
end
if(h+yOffset-1>=minH)and(h+yOffset-1<=maxH)then
hOff = h+yOffset-1
end
frame:setSize(wOff, hOff)
end)
end
makeResizeable(sub, 8, 4)
sub:addLabel():setText("Hello World")
basalt.autoUpdate()
```
</details>
<br>
<video width="600" controls autoplay loop muted>
<source src="./_media/resizable-frames.mp4" type="video/mp4">
</video>
### Scrollable frames
In this example, you will see how to make frames scrollable. Basalt only supports vertical scrolling, but we will also provide an example of how to implement horizontal scrolling.
<details>
<summary>Click here to show code</summary>
```lua
local basalt = require("basalt")
local main = basalt.createFrame():setTheme({FrameBG = colors.black, FrameFG = colors.lightGray})
-- Vertical scrolling is pretty simple, as you can tell:
local sub1 = main:addFrame():setScrollable():setSize(20, 15):setPosition(2, 2)
sub1:addLabel():setPosition(3, 2):setText("Scrollable")
sub1:addLabel():setPosition(3, 12):setText("Inside")
sub1:addLabel():setPosition(3, 20):setText("Outside")
-- Here we create a custom scroll event as you can see we dont add a :setScrollable() method to our frame, instead we add a custom scroll event
local objects = {}
local sub2 = main:addFrame():setPosition(23, 2):setSize(25, 5):onScroll(function(self, event, dir)
local maxScroll = 0
for k,v in pairs(objects)do -- here we iterate trough every object and get their x position + width this way we can find out what's the maximum allowed value to scroll
local x = v:getX()
local w = v:getWidth()
maxScroll = x + w > maxScroll and x + w or maxScroll -- if you don't understand this line, http://lua-users.org/wiki/TernaryOperator
end
local xOffset = self:getOffset()
if(xOffset+dir>=0 and xOffset+dir<=maxScroll-self:getWidth())then
self:setOffset(xOffset+dir, 0)
end
end)
-- Because we need to iterate the objects, we add them into a table.
table.insert(objects, sub2:addButton():setPosition(2, 2):setText("Scrollable"))
table.insert(objects, sub2:addButton():setPosition(16, 2):setText("Inside"))
table.insert(objects, sub2:addButton():setPosition(30, 2):setText("Outside"))
basalt.autoUpdate()
```
</details>
<br>
<video width="600" controls autoplay loop muted>
<source src="./_media/scrollable-frames.mp4" type="video/mp4">
</video>