tset.de » lui: a simple cross platform gui library for lua » lui: reference

lui Documentation

lui is a cross platform gui library for lua, basically a wrapper for libui (https://github.com/andlabs/libui).

Table of contents

Module lui

Functions

init

lui.init()

initialize lui, must be called before anything else.

finalize

lui.finalize()

finalize lui and clean up any used resources. May be omitted as lui is finalized when the program terminates.

main

lui.main()

enter the main event processing loop.

mainsteps

lui.mainsteps()

initialize your own main loop with lui.mainstep() instead of using lui.main()

mainstep

running = lui.mainstep(wait = false)

perform one round of the main event processing loop. Returns true if the program should continue to run, or false if it should quit (i.e. lui.quit() was called).

queuemain

lui.queuemain(function)

register a function to be called the next time when there are no events pending. This function will only be called once.

quit

lui.quit()

terminate the main event processing loop. After calling this, lui.main() returns and lui.mainstep() returns false.

onshouldquit

lui.onshouldquit(function)

register a function to be called when the quit menu item (see above) is clicked.

openfile

filename = lui.openfile(window)

open a system file open dialog. Returns the path and name of the file to open, or nil if the dialog was cancelled.

savefile

filename = lui.savefile(window)

open a system file save dialog. Returns the path and name of the file to save to, or nil if the dialog was cancelled.

msgbox

lui.msgbox(window, title, text)

open a system message box.

errorbox

lui.errorbox(window, title, text)

open a system error message box.

draw.listfontfamilies

list = draw.listfontfamilies()

returns a list of all available font families in a table.

Objects

control

Generic UI control methods and properties. All controls have these. In addition, all constructor methods can take a table of properties and associated values as their last argument. If such a table is passed as an argument, those properties are set after the control has been created.

Properties

toplevel
true if the conrol is a toplevel control (i.e. window), false if not. This is a read-only property.
visible
true if the control is / should be visible, false if not. Default is true.
enabled
true if the control is / should be enabled, false if not. Default is true.

Methods

numchildren
num = control:numchildren()
return the number of children a control has.
getchild
control = control:getchild(num)
return the num'th child of a control, or nil if there is no such child.
getparent
control = control:getparent()
return the parent of a control or nil if it has no parent.
destroy
control:destroy()
destroy a control. You usually do not need to call this directly as controls are destroyed by the garbage collector when they're no longer referenced or when the program terminates. Controls with children have their children destroyed automatically.
type
control:type()
return the type name for a control

window

Constructors

window
win = lui.window(title, width, height, hasmenubar = false, properties = nil)
create a new window. If hasmenubar is true, the menu must have been created before the window is created.

Properties

margined
get / set the title of a window. true if the window has / should have a margin around its contents, false if not. Default is false.
fullscreen
true if the window is / should be a fullscreen, false if not. Default is false.
onclosing
a function bool onclosing(window) to be called when the user requested to close the window. Must return true if the window can be closed, false or nil if not.
onpositionchanged
a function onpositionchanged(window) to be called when the user changes the window position.
oncontentsizechanged
a function oncontentsizechanged(window) to be called when the user changes the window size.

Methods

position
x, y = window:position(x = nil, y = nil)
set and get the position for a window. Sets the position if the arguments x and y are not nil, returns the position of the window.
contentsize
w, h = window:contentsize(h = nil, h = nil)
set and get the content size for a window. Sets the size if the arguments w and h are not nil, returns the content size of the window.
center
window:center()
centers the window on the screen.
setchild
control = window:setchild(control)
set the child control for a window. Returns the child control.

box

a container for multiple controls. Automatically arranges contents vertically (for a vbox) or horizontally (for a hbox).

Constructors

hbox
hbox = lui.hbox(properties = nil)
creates a new box whose children are arranged horizontally.
vbox
vbox = lui.vbox(properties = nil)
creates a new box whose children are arranged vertically.

Properties

padded
true if there is / should be padding between the boxes contained controls, false if not. Default is false.

Methods

append
control = box:append(control, stretchy = false)
append a control to a box. If stretchy is set to true, the control will be expanded to fill all available space. Returns the appended control.
delete
box:delete(index)
delete a control by index from a box. index starts at 1

tab

a container whose children are arranged in individual tabs.

Constructors

tab
tab = lui.tab(properties = nil)
create a new tabbed container.

Properties

margined
(TODO) not implemented
numpages
returns the number of pages in a tabbed container. This is a read-only property.

Methods

append
control = tab:append(title, control)
append a control to a tabbed container. This should be a container control like a box. Returns the appended control.
insertat
control = tab:insertat(title, before, control)
insert a control before a position into a tabbed container. before is an index starting at 1. Returns the inserted control.
delete
tab:delete(index)
delete a control and its tab by index from a tabbed container. index starts at 1

group

a labelled container control.

Constructors

group
group = lui.group(title, properties = nil)
create a new group control.

Properties

title
the label of the group
margined
true if the group has / should have a margin around its contents, false if not. Default is false.

Methods

setchild
group:setchild(control)
set the child control for a group control. Returns the child control.

form

a container, which arranges its children vertically and aligns the labels and controls.

Constructors

form
form = lui.form(properties = nil)
create a new form control.

Properties

padded
true if there is / should be padding between the forms children, false if not. Default is false.

Methods

append
control = form:append(label, control, stretchy = false)
append a control to a form. If stretchy is set to true, the control will be expanded to fill all available space. Returns the appended control.
delete
form:delete(control, index)
delete a control by index from a form. index starts at 1.

grid

a container, which arranges its children in a grid.

Constructors

grid
grid = lui.grid(properties = nil)
create a new grid control.

Properties

padded
true if there is / should be padding between the grids children, false if not. Default is false.

Methods

append
control = grid:append(control, left, top, xspan = 1, yspan = 1, hexpand = false, halign = "fill", vexpand = false, valign = "fill")
append a control to a grid. left and top are the coordinates of the cell where the control should be placed, starting at 1. xspan and yspan are how many cells the control spans in either direction, minimum is 1. Set hexpand to true to horizontally expand the control to fill available space, false to not do that. Set halign to "fill", "start", "center" or "end", or lui.enum.align.fill, ... to set horizontal alignment. vexpand and valign are the same for the vertical case.
insertat
control = grid:insertat(control, existing, at, xspan = 1, yspan = 1, hexpand = false, halign = "fill", vexpand = false, valign = "fill")
insert a control into a grid relative to another control that already exists in the grid. at is any of "leading", "trailing", "top" or "bottom", or lui.enum.at.leading, .... The other arguments have the same meaning as with grid:append().

button

a button control

Constructors

button
btn = lui.button(text, properties = nil)
create a new button. text is the text on the button.

Properties

text
the text on the button
onclicked
a function onclicked(button) that is called when the button is clicked by the user.

entry

an entry control.

Constructors

entry
entry = lui.entry(properties = nil)
create a new entry control.
passwordentry
entry = lui.passwordentry(properties = nil)
create a new entry control that is suitable for entering passwords.
searchentry
entry = lui.searchentry(properties = nil)
create a new entry control that is suitable to be used as a search entry.

Properties

text
the text the entry contains.
readonly
true if the entry control is / should be read only, false if not.
onchanged
a function onchanged(entry) that is called when the contents of the entry is changed by the user.

checkbox

a checkbox control.

Constructors

checkbox
checkbox = lui.checkbox(text, properties = nil)
create a new checkbox with label text.

Properties

text
the label of the checkbox.
checked
true if the entry is / should be chacked, false if not.
ontoggled
a function ontoggled(checkbox) that is called when the checkbox is toggled by the user.

label

a label control.

Constructors

label
label = lui.label(text)
create a new label.

Properties

text
the text on the label.

spinbox

a spinbox control.

Constructors

spinbox
spinbox = lui.spinbox(min, max, properties = nil)
create a new spinbox where the value can be changed between integers min and max (both inclusive).

Properties

value
the current value of the spinbox control.
onchanged
a function function(spinbox) that is called when the value of the spinbox is changed by the user.

progressbar

a progressbar control.

Constructors

progressbar
progressbar = lui.progressbar(properties = nil)
create a new progressbar control.

Properties

value
the value (0-100) of the progress bar. Set to -1 for an indeterminate value.

slider

a slider control.

Constructors

slider
slider = lui.slider(min, max, properties = nil)
create a new slider where the value can be changed between integers min and max.

Properties

value
the value of the slider.
onchanged
a function onchanged(slider) that is called when the value of the slider is changed by the user.

separator

a separator control

Constructors

hseparator
separator = lui.hseparator(vertical = false)
create a new horizontal separator control.
vseparator
separator = lui.vseparator(vertical = false)
create a new vertical separator control.

combobox

a combobox control.

Constructors

combobox
combobox = lui.combobox(properties = nil)
create a new combobox control.

Properties

selected
the index of the selected option.
text
the text of the selected option. This is a read-only property.
onselected
a function onselected(combobox) that is called when the value of the combobox is changed by the user.

Methods

append
combobox:append(entry, ...)
append one or more entries to a combobox.

editablecombobox

an editable combobox control.

Constructors

editablecombobox
editablecombobox = lui.editablecombobox(properties = nil)
create a new editable combobox.

Properties

text
the current value of the editable combobox.
onchanged
a function onchanged(editablecombobox) that is called when the value of the editable combobox is changed by the user.

Methods

append
editablecombobox:append(entry, ...)
append one or more entries to an editable combobox.

radiobuttons

a radiobuttons control.

Constructors

radiobuttons
radiobuttons = lui.radiobuttons()
create a radiobuttons control.

Properties

selected
the index of the selected option.
text
the text of the selected option. This is a read-only property.
onselected
a function onselected(radiobuttons) that is called when the value of the radiobuttons is changed by the user.

Methods

append
radiobuttons:append(option, ...)
append one or more options to a radiobuttons control.

datetimepicker

not fully implemented

Constructors

datetimepicker
datetimepicker = lui.datetimepicker()
datepicker
datetimepicker = lui.datepicker()
timepicker
datetimepicker = lui.timepicker()

multilineentry

a multiline entry control

Constructors

multilineentry
multilineentry = lui.multilineentry(nowrapping = false, properties = nil)
create a new multilineentry control. if nowrapping is true, the text will not wrap around when it exceeds the width of the control, but will be accessible via horizontal scrollbars instead.

Properties

text
the text the multiline entry contains.
readonly
true if the multiline entry is / should be read only, false if not.
onchanged
a function onchanged(multilineentry) that is called when the contents of the multilineentry is changed by the user.

Methods

append
multilineentry:append(text, ...)
append one or more text pieces to the multilineentry control.

menuitem

a single menu item, as returned by the menu:append*() methods. This is not a control, so it does not have the standard control methods and properties.

Properties

text
the text of the menu item, as passed into menu:append() or menu:appendcheckable(). The other menu:append*() methods fill this with default names. This is a read-only property.
enabled
true if the menuitem is / should be enabled, false if not. Default is true.
checked
true if the checkable menu item is / should be checked, false if not. Default is false.
onclicked
a function onclicked(menuitem, window) that is called when this menu item is clicked. Note that quit menuitems don't call their onclicked handler, and checkable menu items call the handler after the checked status has changed.

menu

a menu for a window. All menus must be created before the window they should be attached to. Once a window with menus has been created, you can not create any more menus for other windows. This is not a control, so it does not have the standard control methods and properties.

Constructors

menu
menu = lui.menu(title)
create a new menu with title.

Methods

append
menuitem = menu:append(text, menuitemproperties = nil)
append a standard item to a menu.
appendcheckable
menuitem = menu:appendcheckable(text, menuitemproperties = nil)
append a checkable item to a menu. Default status is unchecked.
appendquit
menuitem = menu:appendquit(menuitemproperties = nil)
append a quit item to a menu. The text property for this item will be "quit". quit menu items can not have an onclicked handler
appendpreferences
menuitem = menu:appendpreferences(menuitemproperties = nil)
append a preferences item to a menu. The text property for this item will be "preferences".
appendabout
menuitem = menu:appendabout(menuitemproperties = nil)
append an about item to a menu. The text property for this item will be "about".
appendseparator
menuitem = menu:appendseparator()
append a separator to a menu.

area

a rendering area for graphics or extended text rendering. Note that all handlers are currently experiments, their arguments may change.

Constructors

area
area = lui.area(width = 0, height = 0, properties = nil)
create a new area. Setting width and height to a value other than 0 makes the area a scrolling area.

Properties

ondraw
a function ondraw(area, context, x, y, w, h, areaw, areah) that is called when the area needs redrawing. area is the area this handler is called for. context is a draw.context object for this area. x, y, w, h are the position and size of the rectangle within the area to redraw. areaw, areah are the full width and height of the area.
onmouse
a function onmouse(area, which, button, x, y, count, modifiers, areaw, areah) that is called when there is mouse action in the area. which is the type of action that occurred, and can be "down", "up", "move", "enter" and "leave". The arguments after which are empty for the events "enter" and leave". For the other events: button is the number of th button that was pressed. It is 0 for the "move" event. x, y is the position within the area, where the event occurred. count is a counter for mouse clicks. It can be used to determine whether a click is a double click. modifiers are the modifier keys. areaw, areah are the full width and height of the area.
onkey
a function bool onkey(area, key, extkey, modifiers, up) that is called when there is a key event for the area. key is the code of the key pressed, if it is none of the special keys. extkey is the name of the key if it is a special key. modifiers is an or'ed mask of the currently active modifiers, the names of which can be found in lui.enum.keymod. So, in order to determine of a modifier is active, you check for it using for example modifier | lui.enum.keymod.shift.

Methods

setsize
area:setsize(width, height)
change the size of an area.
queueredraw
area:queueredraw(...)
not implemented
queueredrawall
area:queueredrawall()
force a redraw of the entire area.
scrollto
area:scrollto(x, y, w, h)
make x, y, w, h the currently visible portion of the area.

fontbutton

a button to open a font selector.

Constructors

fontbutton
fontbutton = lui.fontbutton(properties = nil)
create a new fontbutton.

Properties

font
The font that was last selected via the font selector, or nil if none has been selected yet. This is a read-only property.
onchanged
a function onchanged(fontbutton) that is called when a new font was selected.

colorbutton

a button to open a color selector.

Constructors

colorbutton
colorbutton = lui.colorbutton(properties = nil)
create a new colorbutton.

Properties

color
a table with r, g, b, a fields with values set to the currently selected color. Defaults to 0 for each of r, g, b, a.
onchanged
a function onchanged(colorbutton) that is called when a new color was selected.

draw.brush

a brush spec to draw with.

Constructors

draw.brush
brush = lui.draw.brush(properties = nil)
create a new draw.brush object

Properties

type
may be any of the strings "solid", "lineargradient", "radialgradient", "image" or lui.enum.brushtype.solid ..., will always return type name on read.
color
color of the brush
x0
(TODO)
y0
(TODO)
x1
(TODO)
y1
(TODO)
outerradius
(TODO)
gradientstops
{ { pos, r=?, g=?, b=?, a=?}, ... }, don't modify what you read (TODO)

draw.strokeparams

a stroke spec to draw with

Constructors

draw.strokeparams
strokeparams = lui.draw.strokeparams(properties = nil)
create a new draw.strokeparams object

Properties

linecap
any of the strings "flat", "round", "square", or lui.enum.linecap.flat...
linejoin
any of the strings "miter", "round", "bevel", or lui.enum.linejoin.miter ...
thickness
line thickness. Default is 1.
miterlimit
line join miter limit. Default is 10.
dashphase
(TODO)
dashes
{ len1, len2, ... }, don't modify what you read (TODO)

draw.matrix

a transformation matrix for drawing operations

Constructors

draw.matrix
matrix = lui.draw.matrix()
creates a new draw.matrix object, initialized to identity.

Methods

setidentity
matrix = matrix:setidentity()
reset the matrix to identity. Returns the changed matrix.
translate
matrix = matrix:translate(x, y)
multiply the matrix with a matrix translating by x, y. Returns the changed matrix.
scale
matrix = matrix:scale(x, y, xcenter = 0, ycenter = 0)
multiply the matrix with a matrix scaling by x, y around xcenter, ycenter. Returns the changed matrix.
rotate
matrix = matrix:rotate(x, y, angle)
multiply the matrix with a matrix rotating by angle around x, y. angle is in radians. Returns the changed matrix.
skew
matrix = matrix:skew(x, y, xamount, yamount)
multiply the matrix with a matrix skewing around x, y by xamount, yamount Returns the changed matrix.
multiply
matrix = matrix:multiply(matrix)
multiply the matrix with another matrix. Returns the changed matrix.
invertible
ok = matrix:invertible()
return true if the matrix is invertible, false if not.
invert
ok = matrix:invert()
invert the matrix. Returns true if that went ok, false if not.
transformpoint
x, y = matrix:transformpoint(x, y)
transforms input coordinates x, y with the matrix. Returns the transformed coordinates.
transformsize
x, y = matrix:transformsize(x, y)
transforms input size x, y with the matrix. Returns the transformed size.

draw.path

a path to draw to a draw.context

Constructors

draw.path
path = lui.draw.path(fillmode = "winding")
create a new draw.path object. fillmode may be "winding" or "alternate", or lui.enum.fillmode.winding...

Methods

newfigure
path:newfigure(x, y)
add a new figure to a path. x, y is the coordinate where the figure starts.
newfigurewitharc
path:newfigurewitharc(xcenter, ycenter, radius, start, sweep, negative)
add a new figure to a path. (TODO) details
lineto
path:lineto(x, y)
add a line to a path. A line can only be added when a figure is open.
arcto
path:arcto(xcenter, ycenter, radius, start, sweep, negative = false)
add an arc to a path. An arc can only be added when a figure is open.
bezierto
path:bezierto(c1x, c1y, c2x, c2y, endx, endy)
add a bezier curve to a path. A bezier curve can only be added when a figure is open.
closefigure
path:closefigure()
close the last opened figure.
addrectangle
path:addrectangle(x, y, width, height)
add a rectangle to a path. A rectangle can be added if no figure is open.
done
path:done()
signal that you are finished composing the path.

draw.font

a font to draw text into an area with.

Constructors

loadclosestfont
font = lui.draw.loadclosestfont(name, size, weight = 0, italic = 0, stretch = 0)
load a font from the system and create a draw.font object from it. Tries to match fonts with your wishes. If name is empty (""), a default font is used.

Methods

describe
family, size, weight, italic, stretch = font:describe()
(TODO)
getmetrics
ascent, descent, leading, underlinepos, underlinethickness = font:getmetrics()
(TODO)

draw.textlayout

a combination of a text, a font and colors to draw text to an area.

Constructors

draw.textlayout
textlayout = lui.draw.textlayout(text, font, fmtwidth = -1, properties = nil)
create a new draw.textlayout object. text is the text to layout, font is the font to use. fmtwidth is the formatting width for the text, set to -1 or leave empty for no restrictions.

Properties

fmtwidth
the text format width. Set to -1 for no restrictions, otherwise the text will be formatted to this width.
width
the current rendering width of the layout object. This is a read-only property.
height
the current rendering height of the layout object. This is a read-only property.

Methods

setcolor
textlayout:setcolor(startchar, endchar, r, g, b, a)
textlayout:setcolor(startchar, endchar, {r=r, g=g, b=b, a=a})

set the color for a section of a layout object. startchar and endchar are the first and last char respectively to set to this color.

draw.context

a drawing context object, passed to area.ondraw handler

Methods

fill
context:fill(drawpath, brush)
draw a filled path. The path is filled according to the fillmode set when creating the path. brush is the brush to use for filling the path.
stroke
context:stroke(path, brush, strokeparams)
draw a non-filled path. brush is the brush to use for the path outline. strokeparams is the description of the strokes to use for the path.
transform
context:transform(matrix)
transform everything that is drawn to the path according to the transformations in the draw.matrix.
clip
context:clip(path)
clip all that is rendered against the path.
save
context:save()
push the current drawing context state to a stack
restore
context:restore()
restore the current drawing context state from a stack
text
context:text(x, y, textlayout)
draw a draw.textlayout object. x, y are the positions to place the layout object at.