Skip to content

Window

Jump to bottom
flamendless edited this page Sep 19, 2023 · 20 revisions
Table of Contents

Overview

Creating windows are required to render any controls. Below is an example of creating a simple window with a title bar.

Slab.BeginWindow('MyWindow', {Title = "My First Window"})
Slab.EndWindow()

Windows take in a unique Id to identify this window from other windows. Windows with a title bar are movable by default while windows without title bars are not.

Windows by default are set to automatically grow as controls are added to the window.

Slab.BeginWindow('MyWindow', {Title = "My First Window"})
Slab.Text("Hello World")
Slab.Text("Foo Bar")
Slab.Text("This is a very long string")
Slab.EndWindow()

If resizing the window is desired, then the flag 'AutoSizeWindow' must be set to false.

Slab.BeginWindow('MyWindow', {Title = "My First Window", AutoSizeWindow = false})
Slab.Text("Hello World")
Slab.Text("Foo Bar")
Slab.Text("This is a very long string")
Slab.EndWindow()

If the contents of a window cannot fit within the bounds of the window, then scroll bars will be rendered to allow the user to scroll within the window.

Windows using auto-sizing (AutoSizeWindow = false) will have window edge sizers enabled on all sides by default. The SizerFilter option allows developers to choose which sides are enabled.

Slab.BeginWindow('SizerExample', {Title = "SizerExample", AutoSizeWindow = false, SizerFilter = {'W', 'E'}})
Slab.EndWindow()

Each window now has the option of displaying a close button. This is done by passing in the IsOpen option when calling BeginWindow. If this option is not present, the close button will not be displayed. This option is also updated if the user clicks on the button. The caller can check this value to see if the window has been closed.

local Options = {Title = "My Window", IsOpen = true, AutoSizeWindowW = false, W = 150}

function love.update(dt)
	Slab.Update(dt)

	Slab.BeginWindow('IsOpenExample', Options)
	Slab.Text("Hello World")
	Slab.EndWindow()
end

The BeginWindow function also returns a boolean value that indicates if this window is open, giving developers an alternative way to manage the open state of the window.

local IsOpen = true

function love.update(dt)
	Slab.Update(dt)

	IsOpen = Slab.BeginWindow('IsOpenExample', {Title = "My Window", IsOpen = IsOpen, AutoSizeWindowW = false, W = 150})
	Slab.Text("Hello World")
	Slab.EndWindow()
end

API

Below is a list of functions associated with the Window API.

BeginWindow

This function begins the process of drawing widgets to a window. This function must be followed up with an EndWindow call to ensure proper behavior of drawing windows.

Parameter Type Description
Id String A unique string identifying this window in the project.
Options Table List of options that control how this window will behave.
Option Type Description
X Number The X position to start rendering the window at.
Y Number The Y position to start rendering the window at.
W Number The starting width of the window.
H Number The starting height of the window.
ContentW Number The starting width of the content contained within this window.
ContentH Number The starting height of the content contained within this window.
BgColor Table The background color value for this window. Will use the default style WindowBackgroundColor if this is empty.
Title String The title to display for this window. If emtpy, no title bar will be rendered and the window will not be movable.
TitleH Number The height of the title bar. By default, this will be the height of the current font set in the style. If no title is set, this is ignored.
TitleAlignX String Horizontal alignment of the title. The available options are 'left', 'center', and 'right'. The default is 'center'.
TitleAlignY String Vertical alignment of the title. The available options are 'top', 'center', and 'bottom'. The default is 'center'.
AllowMove Boolean Controls whether the window is movable within the title bar area. The default value is true.
AllowResize Boolean Controls whether the window is resizable. The default value is true. AutoSizeWindow must be false for this to work.
AllowFocus Boolean Controls whether the window can be focused. The default value is true.
Border Number The value which controls how much empty space should be left between all sides of the window from the content. The default value is 4.0
NoOutline Boolean Controls whether an outline should not be rendered. The default value is false.
IsMenuBar Boolean Controls whether if this window is a menu bar or not. This flag should be ignored and is used by the menu bar system. The default value is false.
AutoSizeWindow Boolean Automatically updates the window size to match the content size. The default value is true.
AutoSizeWindowW Boolean Automatically update the window width to match the content size. This value is taken from AutoSizeWindow by default.
AutoSizeWindowH Boolean Automatically update the window height to match the content size. This value is taken from AutoSizeWindow by default.
AutoSizeContent Boolean The content size of the window is automatically updated with each new widget. If this is false, the scrollbar will not be shown anymore. The default value is true.
Layer String The layer to which to draw this window. This is used internally and should be ignored by the user.
ResetPosition Boolean Determines if the window should reset any delta changes to its position.
ResetSize Boolean Determines if the window should reset any delta changes to its size.
ResetContent Boolean Determines if the window should reset any delta changes to its content size.
ResetLayout Boolean Will reset the position, size, and content. Short hand for the above 3 flags.
SizerFilter Table Specifies what sizers are enabled for the window. If nothing is specified, all sizers are available. The values can be: NW, NE, SW, SE, N, S, E, W
CanObstruct Boolean Sets whether this window is considered for obstruction of other windows and their controls. The default value is true.
Rounding Number Amount of rounding to apply to the corners of the window.
IsOpen Boolean Determines if the window is open. If this value exists within the options, a close button will appear in the corner of the window and is updated when this button is pressed to reflect the new open state of this window.
NoSavedSettings Boolean Flag to disable saving this window's settings to the state INI file.
ConstrainPosition Boolean Flag to constrain the position of the window to the bounds of the viewport.
ShowMinimize Boolean Flag to show a minimize button in the title bar of the window. Default is true.
ShowScrollbarX Boolean Flag to show the horizontal scrollbar regardless of the window and content internal state. Default is false.
ShowScrollbarY Boolean Flag to show the vertical scrollbar regardless of the window and content internal state. Default is false.
Return Description
Boolean The open state of this window. Useful for simplifying API calls by storing the result in a flag instead of a table. EndWindow must still be called regardless of the result for this value.

EndWindow

This function must be called after a BeginWindow and associated widget calls. If the user fails to call this, an assertion will be thrown to alert the user.

GetWindowPosition

Retrieves the active window's position.

Return Description
Number, Number The X and Y position of the active window.

GetWindowSize

Retrieves the active window's size.

Return Description
Number, Number The width and height of the active window.

GetWindowContentSize

Retrieves the active window's content size.

Return Description
Number, Number The width and height of the active window content.

GetWindowActiveSize

Retrieves the active window's active size minus the borders. This could be the size of the window or the size of the current column.

Return Description
Number, Number The width and height of the window's active bounds.

IsWindowAppearing

Is the current window appearing this frame. This will return true if BeginWindow has not been called for a window over 2 or more frames.

Return Description
Boolean True if the window is appearing this frame. False otherwise.

PushID

Pushes a custom ID onto a stack. This allows developers to differentiate between similar controls such as text controls.

Parameter Type Description
ID String The custom ID to add.

PopID

Pops the last custom ID from the stack.

Clone this wiki locally