Reference

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
    • errorbox
    • finalize
    • init
    • main
    • mainstep
    • mainsteps
    • msgbox
    • onshouldquit
    • openfile
    • queuemain
    • quit
    • savefile
  • Objects
    • area
    • box
    • button
    • checkbox
    • colorbutton
    • combobox
    • control
    • datetimepicker
    • draw.brush
    • draw.context
    • draw.matrix
    • draw.path
    • draw.strokeparams
    • editablecombobox
    • entry
    • fontbutton
    • form
    • grid
    • group
    • label
    • menu
    • menuitem
    • multilineentry
    • progressbar
    • radiobuttons
    • separator
    • slider
    • spinbox
    • tab
    • text.attributedstring
    • text.font
    • text.layout
    • window

Module lui

Functions

errorbox

lui.errorbox(window, title, text)
open a system error message box.

finalize

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

init

lui.init()
initialize lui, must be called before anything else.

main

lui.main()
enter the main event processing loop.

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).

mainsteps

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

msgbox

lui.msgbox(window, title, text)
open a system message box.

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.

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.

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.

Objects

area

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

Constructors

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.

• forceredraw area:forceredraw()
  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.

• beginuserwindowmove area:beginuserwindowmove()
  only usable within mouse events

• beginuserwindowresize area:beginuserwindowresize(edge)
  only usable within mouse events. An enumeration of the edges can be found in lui.enum.edge, or you may enter the name directly.

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

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.

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.

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.

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.

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

datetimepicker

a date / time picker control.

Constructors

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

Properties

• day the selected day, range from 1-31
• mon the selected month, range from 1-12
• year the selected year
• hour the selected hour, range from 0-23
• min the selected minute, range from 0-63
• sec thee selected second, range from 0-63
• date a table with fields day, mon, year
• time a table with fields hour, min, sec
• datetime a table with fields day, mon, year, hour, min, sec
• onchanged a function onchanged(datetimepicker) that is called when the contents of the datetimepicker is changed by the user.

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.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.

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.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)

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.

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.

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.

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().

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.

label

a label control.

Constructors

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

Properties

• text the text on the label.

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.

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.

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.

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.

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.

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.

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.

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.

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

text.attributedstring

a string with formatting attributes, that can be used to create a textlayout object

Constructors

• text.attributedstring attributedstring = lui.text.attributedstring(string = "")
  create a new text.attributedstring object

Properties

• text A string representing the textual content of the attributedstring. Note that this string will not reflect the contents of the atttributedstring any more if insert, delete or the append operator has been used on that. This is a read-only property.

Methods

• append astr = astr:append(other)
  appends a string to an attributedstring. other may be a lua string, in which case it is appended without attributes, or an attributedstring, in which case the attributes are copied as well. This modifies the attributedstring this method was called on. Returns the attributedstring the operation was called on.

• .. (concatenation operator) astr = astr .. other
  returns a new attributedstring that is the concatenation of the left and the right side of the .. operator.

• len length = astr:len()
  returns the length of the attributedstring in bytes. len is also available via the length operator (#)

• numchars num = astr:numchars()
  returns the number of visible chars in a string. A visible char is a single renderable unit, a.k.a a grapheme.

• chartobytepos bytepos = astr:chartobytepos(charpos)
  converts a byte position to a visible char position in an attributedstring.

• bytetocharpos charpos = astr:bytetocharpos(bytepos)
  converts a visible char position to a byte position in an attributedstring.

• insert astr = astr:insert(other, pos)
  inserts another string into an attributedstring at position pos. other may be a lua string, in which case it is appended without attributes, or an attributedstring, in which case the attributes are copied as well. This modifies the attributedstring this method was called on. Returns the attributedstring the operation was called on.

• delete astr = astr:delete(start, end)
  deletes all bytes between (and including) start and end from the attributedstring. This modifies the attributedstring this method was called on. Returns the attributedstring the operation was called on.

• setattributes astr = astr:setattributes(attr, start = 1, end = #astr)
  sets the attributes for a section of the string. atr may be a text.font, or a table with attribute names as keys and attribute values as values. start is the first byte and end is the last byte to set the attributes for. This modifies the attributedstring this method was called on. Returns the attributedstring the operation was called on. Valid attribute names and values are: - family: font family - size: font size - weight: font weight, any of the strings “minimum”, “thin”, “ultralight”, “light”, “book”, “normal”, “medium”, “semibold”, “bold”, “ultrabold”, “heavy”, “ultraheavy”, “maximum”, or lui.enum.weight.minimum, … or an integer between 0 and 1000. - italic: font italicness, any of the strings “normal”, “oblique”, “italic”, or lui.enum.italic.normal, … - stretch: font width, any of the strings “ultracondensed”, “extracondensed”, “condensed”, “semicondensed”, “normal”, “semiexpanded”, “expanded”, “extraexpanded”, “ultraexpanded”, or lui.enum.stretch.ultracondensed, … - color: foreground color, a table { r = red, g = green, b = blue, a = alpha }, where the values range from 0.0 to 1.0 - bgcolor: background color, value as for color. - underline: underline style, any of he strings “none”, “single”, “double”, “suggestion”, - ulcolor: underline color, any of the strings “spelling”, “grammar”, “auxiliary”, or a rgba table as for color.

• getattributes attrlist = astr:getattributes(start = nil, end = start)
  returns a list of all active attributes. If start and end are positive integers, then only those attributes are returned, that are active between start and end in the attributedstring. If start is a positive integer and end is omitted, then the attributes at position start are returned. If both start and end are omittted, all attributes of the string are returned. The return value is a table whose entries are tables of the form { attr, start, end }, where attr, start and end are the same as the arguments to setattributes.

text.font

a font to draw text into an area with.

Properties

• family Font family. This is a read-only property.
• size Font size. This is a read-only property.
• weight Font weight. This is a read-only property.
• italic Font italic-ness. This is a read-only property.
• stretch Font stretch. This is a read-only property.

text.layout

a font to draw text into an area with.

Constructors

• text.layout brush = lui.text.layout(astr, font, width, align = "left")
  create a new text.layout object. astr may be a plain string or an attributedstring. font is the default font to use. width is the rendering width for the string. align is the alignment, may be any of “left”, “center” or “right”.

Properties

• width the width of the textlayout object This is a read-only property.
• height the height of the textlayout object This is a read-only property.

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.
• oncontentsizechanged a function oncontentsizechanged(window) to be called when the user changes the window size.

Methods

• 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.

• setchild control = window:setchild(control)
  set the child control for a window. Returns the child control.