Technical overview

TekUI is not a binding to an existing GUI library, and it makes no attempt to conform to the looks of a host's native GUI (although this can be emulated to a certain degree – see below for details). The implementation is comparatively fast and resource-friendly, despite its script-heavy nature. Among the benefits for developers are its simplicity, transparency and modularity; in particular, custom interface elements can be created with little effort.

General features

  • Strictly event-driven
  • Automatic layouting and scalability
  • Font-sensitivity, support for antialiased fonts
  • UTF-8 and localization support, Unicode/metadata strings
  • Support for cascading style sheets (CSS) and themes
  • Allows for multi-windowed, tabbed and fullscreen applications
  • Incremental refresh logic with minimal overdraw
  • Concurrency thanks to inbuilt support for dispatching to coroutines, preemptive tasks also supported
  • Applications can be written in Lua code, nested expressions, or XML. The XML launcher can validate against the actual implementation
  • Works unmodified with stock (double precision), single precision and integer versions of the Lua VM
  • Supplied with a documentation system supporting tekUI's object model
  • Support for textures, color gradients and transparency
  • A text editor is included as an example

Supported interface elements

  • Canvas
  • Checkmark
  • Directory lister
  • File requester
  • Floating text
  • Gauge
  • Group (horizontal, vertical, grids, in pages, scrollable)
  • Handle for group balancing
  • Images
  • Lister, also multi-column and multi-selection
  • Menu (popup and window), also nested
  • Popup item, also nested
  • Popup list ('combo box')
  • Radiobutton
  • Scrollgroup
  • Slider
  • Spacer
  • Text button (and label), also multi-line
  • Text input (single and multi-line, passwords, scrolling, ...)


Languages and formats currently supported for writing applications in are Lua, and to some lesser extent, XML. Applications can communicate with their host using

  • C bindings
  • I/O streams (see meter example)
  • datagram sockets (see socketmessage example, using LuaSocket)
  • pipes between parent and child process (see childprocess example, using luaposix)
  • inter-task messages and signals (see childtask and childnotify examples)

See also Future plans and Writing applications in XML.

Style sheets and themes

TekUI comes with a cascading style sheets (CSS) engine for the declaration of styles for element classes, custom classes, pseudo classes, as well as for individual, direct and hardcoded class formattings.

The only admission to a more common appearance is that tekUI tries to import the color scheme found in a GTK+ configuration file, if the "desktop" style sheet is used (which is the default, see also environment variables). If you are using KDE and check the Apply colors to non-KDE applications option, KDE, GTK+ and tekUI all share the same color scheme.

C library

The C library is based on the TEKlib middleware project. All required modules are contained in tekUI's source code distribution, to reduce the hassle of building and installing the software.

The C library isolates from the host and provides performance-critical routines (e.g. the region management, default layouter and string library). Rendering and input handling are implemented as display drivers, which allow for easy exchangeability.

Aside from the display driver interface, the C library implements OS-like facilities such as portable threads, a timer device and can support a virtual filesystem interface.

Lua, C and object model

Regardless of whether classes are written in Lua or C, they share a common, single-inheritance object model, which is determined by the Lua virtual machine and provides a referencing scheme and automatic memory management.

Classes can be written in Lua and C interchangeably, meaning that they can inherit from each other regardless of the language they are written in. This makes it possible to prototype applications quickly, and, should the need arise, to replace performance-crititcal classes with their counterparts in C. When porting classes to C, there is a certain degree of freedom in how much reliance on the Lua VM and its automatic resource management is desired.

Writing applications in XML

TekUI applications can be written as nested expressions in Lua, and this makes it easy to convert hierarchically structured formats such as XML to fully functional applications that can be executed on the Lua virtual machine. An examplary XML runner is included, e.g.:

# bin/runxml.lua -e tutorial-5.xml

One benefit of writing an application in XML is that some validity checks can be performed against a document type, and also against tekUI's actual implementation:

# bin/runxml.lua -c tutorial-5.xml

For this, it is required that you are using a debug version of tekUI's base class, see Debugging objects.

XML support is still somewhat experimental. See the accompanying examples on how to express interactions between elements using notifications and the embedding of methods.

Documentation system

TekUI comes with a documentation generator supporting its own object model. It is capable of generating a function reference and hierarchical class index from specially crafted comments in the source code. To regenerate the full documentation, invoke

# make docs

Note that you need LuaFileSystem for the document generator to process the file system hierarchy.

Fitness for the use in embedded systems

TekUI is as embeddable as Lua itself. Global data is basically absent; there are a few extras requiring them, ENABLE_XSHM and ENABLE_LAZY_SINGLETON, that can be disabled or reworked. Resting on an OS-like abstraction, it can be taken to environments with no operating system at all, if just memory and a minimal threading API is present (create, wait, signal, and e.g. atomic in-/decrement). A display driver can be written on that premise and tekUI's C library alone.

Complete solutions based on tekUI are in the reach of 512KiB ROM or flash memory: A typical application and the required modules, if compiled to Lua bytecode, can fit into 256KiB. Add to that approx. 128KiB for the C modules and another 128KiB for the Lua virtual machine.

Generic, unmodified versions of tekUI have been deployed on PPC, ARM, x86, and MIPS based microcontrollers with clock rates as low as 200MHz, while maintaining good reactivity and a pleasant look & feel. Lower clock rates are workable with some adaptations, by disabling expensive features like style sheet support, by porting certain classes to C, using display drivers which are more tightly connected to the hardware, etc.

LuaExec multitasking interface

TekUI rests on a C library that can provide preemptive multitasking not only to GUI programs, but to all kinds of Lua applications. It is fully contained in the tekUI package, but it can be used independently and is also available as a separate project, LuaExec, which also provides a tutorial and primer on multitasking.

Future plans

Since version 1.12 tekUI supports messaging and signals between preemptive tasks. While these are already available to Lua programs, future versions shall additionally provide a C library interface for the same purpose. See also above on tekUI's multitasking interface.

One future development goal is to fold the tekUI framework into a freestanding C library, which enables applications to create asynchronous GUI objects, communicating with their main program using an application-level protocol. From this, the following benefits are envisioned:

  • GUIs integrate smoothly even into I/O-burdened applications (clients, servers)
  • strict separation of GUI and functionality; the GUI runs in a thread or process of its own
  • Faulty GUI application code, as it is written in a safe language, cannot corrupt the heap or otherwise crash the device, even if it is without a MMU.

Lua would continue to act as the toolkit's internal scripting language, which can be used for complex interconnections between GUI elements as well as many application tasks.