Windows

Windows#

A window is the top level UI element that contains all other elements. Most modules that display some sort of UI to the user will have at least one window.

Windows can only have a single child element. In most cases this child will be a box or grid.

New windows are created with the window() function in the ui module (see below).

Functions#

ui.window(caption)#

Create a new uiwindow.

Parameters:

caption (string) – The window title.

Returns:

A new window.

Return type:

uiwindow

Example#
local ui = require 'ui'

local win = ui.window("My Module")

win:show()

Version History

Version

Notes

0.3.0

Added

classes#

class ui.uiwindow#

A top-level window element. A window can only have a single child, which should be a layout container such as a uibox.

caption([newcaption])#

Set or return the window title.

Parameters:

newcaption (string) – (Optional) The new window title.

Returns:

The current window title.

Return type:

string

Version History

Version

Notes

0.3.0

Added
child(newchild)#

Set the window’s child. This can be any UI element, but in most cases this will be a layout container such as a box.

Note

To clear the child, pass nil.

Parameters:

newchild (uielement)

Version History

Version

Notes

0.3.0

Added
show()#

Show the window.

If the window is already visible this function has no effect.

Version History

Version

Notes

0.3.0

Added
hide()#

Hide the window.

Version History

Version

Notes

0.3.0

Added
settings(settings, path)#

Bind this window to the given settings store.

This allows a window’s position and size to be persisted between overlay sessions.

Parameters:

  • settings (settingsstore)

  • path (string) – The settings path/key to store the window settings.

path is the path within the settings store where the following values will be read and stored:

Value

Description

x

Position X

y

Position Y

width

Width

height

Height

Warning

path should contain (default) values for the above values before this method is called.

Example#
local overlay = require 'overlay'
local ui = require 'ui'

local settings = overlay.settings('my-module.lua')

settings:setdefault('window.x', 50)
settings:setdefault('window.y', 50)
settings:setdefault('window.width', 400)
settings:setdefault('window.height', 200)

local win = ui.window('My Module')
win:settings(settings, 'window')

win:show()

Version History

Version

Notes

0.3.0

Added
resizable(value)#

Set if this window can be resized by the user or not.

A resizable window can be changed by dragging the left, right, or bottom borders.

Parameters:

value (boolean)

Version History

Version

Notes

0.3.0

Added
position(x, y)#

Set the window position.

Parameters:

Note

This accomplishes the same as calling x() and y() but in a single call.

Version History

Version

Notes

0.3.0

Added
titlebar(show)#

Set if the window should show a titlebar with a caption/title.

If no titlebar is shown, the window will not have a caption displayed either.

Parameters:

show (boolean)

Version History

Version

Notes

0.3.0

Added
titlebarbox()#

Returns a uibox that can be used place additional elements, such as buttons, onto the title bar.

Return type:

uibox

Version History

Version

Notes

0.3.0

Added
updatesize()#

Explicitly update the window’s size.

This causes the window to evaluate its child and its children, etc. to recalculate its final size.

This can be used to get a window’s size before it is shown to reposition it.

Version History

Version

Notes

0.3.0

Added
ignoremouse(value)#

Set if this window should ignore all mouse input.

Parameters:

value (boolean)

Note

While the window itself may ignore mouse input, child elements may not.

Warning

If the window ignores all mouse input, it will not be possible to move or resize it.

Version History

Version

Notes

0.3.0

Added
bordercolor(color)#

Set the color used to draw window borders.

Parameters:

color (integer)

Version History

Version

Notes

0.3.0

Added

Note

The following methods are inherited from uielement

x([position])#

Set or get the current position X.

Parameters:

position (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually position an element.

Version History

Version

Notes

0.3.0

Added
y([position])#

Set or get the current position Y.

Parameters:

position (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually position an element.

Version History

Version

Notes

0.3.0

Added
width([value])#

Get or set the element’s width.

Parameters:

width (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually set an element’s size.

Version History

Version

Notes

0.3.0

Added
height([value])#

Get or set the element’s height.

Parameters:

width (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually set an element’s size.

Version History

Version

Notes

0.3.0

Added
bgcolor([color])#

Get or set the element’s background color.

Parameters:

color (integer) – (Optional)

Return type:

integer

Version History

Version

Notes

0.3.0

Added
Contents