Frame

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

local myFrame = basalt.createFrame("myFirstFrame")

addFrame

Creates a child frame on the frame, the same as basalt.createFrame 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.
   

Usage:

• Create a frame with id "myFirstFrame" then create a child of that frame, named "myFirstSubFrame"

local mainFrame = basalt.createFrame("myFirstFrame")
local myFrame = mainFrame:addFrame("myFirstSubFrame")

setBar

Sets the text, background, and foreground of the upper bar of the frame, accordingly.

Parameters:

1. string The text to set the bar to
2. number The background color
3. number The foreground color

Returns:

1. frame The frame being used

Usage:

• Set the title to "My first frame!", with a background of gray and a foreground of light gray.

frame:setBar("My first Frame!", colors.gray, colors.lightGray)

• Store the frame, use the named frame variable after assigning.

local mainFrame = basalt.createFrame("myFirstFrame")
local myFrame = MainFrame:addFrame("myFirstSubFrame")
myFrame:setBar("My first Frame!")

• This abuses the call-chaining that Basalt uses.

local mainFrame = basalt.createFrame("myFirstFrame")
local myFrame = mainFrame:addFrame("myFirstSubFrame"):setBar("My first 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.

local mainFrame = myFrame:setBar("My first Frame!"):setBarTextAlign("right")

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.

local mainFrame = myFrame:setBar("Hello World!"):showBar()

isModifierActive

Disabled, this function is a WIP

Returns true if the user is currently holding the respective key down

Parameters:

1. number | string - Any os.queueEvent("key") key, or you can use the following strings: "shift", "ctrl", "alt"

Returns:

1. boolean - Whether the user is holding the key down

Usage:

• Checks if the "shift" modifier is active on the myFrame frame

local isActive = myFrame:isModifierActive("shift")

• Creates a label, changing the text to "Shift is inactive oh no :(" and "Shift is active yay!", accordingly.

local aLabel = myFrame:addLabel("myFirstLabel"):setText("Shift is inactive oh no :(")
myFrame:addButton("myFirstButton"):setText("Click"):onClick(
        function() 
            if myFrame:isModifierActive("shift") then 
                aLabel:setText("Shift is active yay!") 
            else 
                aLabel:setText("Shift is inactive oh no :(") 
            end 
        end
)

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

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

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 button with id "myFirstButton", sets the focused object to the previously mentioned button

local aButton = myFrame:addButton("myFirstButton")
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 button with id "myFirstButton", then removes the focus from that button

local aButton = myFrame:addButton("myFirstButton")
myFrame:removeFocusedObject(aButton)

getFocusedObject

Gets the currently focused object

Parameters:

Returns:

1. object The currently focused object

Usage:

• Gets the currently focused object from the frame, storing it in a variable

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

local myFrame = basalt.createFrame("myFirstFrame"):setMovable(true)

setMoveable

Deprecated in favor of setMovable

Sets whether the frame can be moved. In order to move the frame use 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

local myFrame = basalt.createFrame("myFirstFrame"):setMoveable(true)

setOffset

Sets the frame's coordinate offset. The frame's child objects will receive the frame's coordinate offset. For example, when using the 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 be supplied negative offsets

Parameters:

1. number The x direction offset (+/-)
2. number The y direction offset (+/-)

Returns:

1. frame The frame being used

Usage:

• Creates "myFirstFrame" with an x offset of 5 and a y offset of 3

local myFrame = basalt.createFrame("myFirstFrame"):setOffset(5, 3)

• Creates "myFirstFrame" with an 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)

local myFrame = basalt.createFrame("myFirstFrame"):setOffset(5, -5)