Skip to content

Window

Jump to bottom
coding.jackalope edited this page May 24, 2020 · 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, by default, will have sizers for all sides active. Through the SizerFilter option, only certain sides of a window can be resized.

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.
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. 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.
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.
Clone this wiki locally