Class Overview

Libraries

Class (v9.0)

OVERVIEW

ClassOverview : Class

This module implements inheritance and the creation of objects from classes.

IMPLEMENTS

class = object:getClass()

This function returns the class of an object. If applied to a class instead of an object, it returns its super class, e.g.: 

superclass = Class.getClass(class)

name = object:getClassName()

This function returns the _NAME attribute of the object's class. It is also possible to apply this function to a class instead of an object.

object:getSuper()

Gets the super class of an object or class. For example, to forward a call to a method to its super class, without knowing its class: 

self:getSuper().method(self, ...)

is_descendant = object:instanceOf(class)

Returns true if object is an instance of or descends from the specified class. It is also possible to apply this function to a class instead of an object, e.g.: 

Class.instanceOf(Button, Area)

class, superclass = Class.module(classname, superclassname)

Creates a new class from the specified superclass. superclassname is being loaded and its method Class:newClass() invoked with the _NAME field set to classname. Both class and superclass will be returned.

object = Class.new(class[, object])

Creates and returns a new object of the given class. Optionally, it just prepares the specified object (a table) for inheritance and attaches the class' methods and data.

class = Class.newClass(superclass[, class])

Derives a new class from the specified superclass. Optionally, an existing class (a table) can be specified. If a _NAME field exists in this class, it will be used. Otherwise, or if a new class is created, class._NAME will be composed from superclass._NAME and an unique identifier. The same functionality can be achieved by calling a class like a function, so the following invocations are equivalent: 

class = Class.newClass(superclass)
class = superclass()

The second notation allows a super class to be passed as the second argument to Lua's module function, which will set up a child class inheriting from superclass in the module table.

object:setClass(class)

Changes the class of an object or the super class of a class.

List (v3.2)

OVERVIEW

ClassOverview : Class / List

This class implements a list container.

IMPLEMENTS
ATTRIBUTES
  • Items [I] (table)

    Table of initial list items, indexed numerically

OVERRIDES

pos = List:addItem(entry[, pos])

Adds an item to the list, optionally inserting it at the specified position. Returns the position at which the item was added.

success = List:changeItem(entry, pos)

Changes the item at the specified position in the list. Returns true if an item was changed.

List:clear()

Removes all items from the list.

List:getItem(pos)

Returns the item at the specified position.

List:getN()

Returns the number of elements in the list.

entry = List:remItem(pos)

Removes an item at the specified position in the list. The item is returned to the caller.

Markup (v3.3)

OVERVIEW

ClassOverview : Class / Markup

This class implements a markup parser and converter for producing feature-rich XHTML 1.0 from plain text with special formattings.

IMPLEMENTS

parser = Markup:new(args)

Creates a new markup parser. args can be a table of initial arguments that constitute its behavior. Supported fields in args are:

indentchar Character recognized for indentation, default "\t"
input Filehandle or string, default io.stdin
rdfunc Line reader, by default reads using args.input:lines
wrfunc Writer func, by default io.stdout.write
docname Name of document, default "Manual"
features Feature codes, default "hespcadlint"

The parser supports the following features, which can be combined into a string and passed to the constructor in args.features:

Code Description rough HTML equivalent
h Heading <h1>, <h2>, ...
e Emphasis <strong>
s Separator <hr>
p Preformatted block <pre>
c Code <code>
a Anchor, link <a href="...">
d Definition <dfn>
l List <ul>, <li>
i Image <img>
n Node header <a name="...">
t Table <table>
f Function (undocumented, internal use only)

After creation of the parser, conversion starts by calling Markup:run().

run()

This function starts the conversion.

Object (v14.3)

OVERVIEW

ClassOverview : Class / Object

This class implements notifications.

IMPLEMENTS
OVERRIDES

Object.addClassNotifications(proto)

class method for collecting the standard or default notifications of a class. These notifications remain in place, and are not removed or replaced during runtime.

Object:addNotify(attr, val, dest)

Adds a notification to an object. attr is the name of an attribute to react on setting its value. val is the value that triggers the notification. For val, the placeholder ui.NOTIFY_ALWAYS can be used to react on any change of the value. action is a table describing the action to take when the notification occurs; it has the general form: 

{ object, method, arg1, ... }

object denotes the target of the notification, i.e. the self that will be passed to the method as its first argument. ui.NOTIFY_SELF is a placeholder for the object causing the notification (see below for the additional placeholders ui.NOTIFY_ID, ui.NOTIFY_WINDOW, and ui.NOTIFY_APPLICATION). method can be either a string denoting the name of a function in the addressed object, or ui.NOTIFY_FUNCTION followed by a function value. The following placeholders are supported in the Object class:

  • ui.NOTIFY_SELF - the object causing the notification
  • ui.NOTIFY_VALUE - the value causing the notification
  • ui.NOTIFY_TOGGLE - the logical negation of the value
  • ui.NOTIFY_OLDVALUE - the attributes's value prior to setting it
  • ui.NOTIFY_FORMAT - taking the next argument as a format string for formatting the value
  • ui.NOTIFY_FUNCTION - to pass a function in the next argument

The following additional placeholders are supported if the notification is triggered in a child of the Element class:

  • ui.NOTIFY_ID - to address the Element with the Id given in the next argument
  • ui.NOTIFY_WINDOW - to address the Window the object is connected to
  • ui.NOTIFY_APPLICATION - to address the Application the object is connected to
  • ui.NOTIFY_COROUTINE - like ui.NOTIFY_FUNCTION, but the function will be launched as a coroutine by the Application. See also Application:addCoroutine() for further details.

In any case, the method will be invoked as follows: 

method(object, arg1, ...)

If the destination object or addressed method cannot be determined, nothing else besides setting the attribute will happen.

Notifications should be removed using Object:remNotify() when they are no longer needed, to reduce overhead and memory use.

Object:doNotify(func, ...)

Performs a notification in the object by calling the specified function and passing it the given arguments. If func is a a function value, it will be called directly. Otherwise, it will be used as a key for looking up the function.

object = Object.init(object)

This function is called during Object.new() before passing control to superclass.new(). The original intention was that resources were to be claimed in new(), whereas defaults were to be (re-)initialized during init(). As of 1.04, this usage pattern is discouraged; all initializations should take place in new() now, as this differentiation was insufficient to cover complex reinitializations, and it interferes with fields like Area.TrackDamage, which are now initialization-only.

success = Object:remNotify(attr, val, dest)

Removes a notification from an object and returns true if it was found and removed successfully. You must specify the exact set of arguments as for Object:addNotify() to identify a notification for removal.

Object:setValue(key, value[, notify])

Sets an object's key to the specified value, and, if notify is not false, triggers notifications that were previously registered with the object. If value is nil, the key's present value is reset. To enforce a notification regardless of its value, set notify to true. For details on registering notifications, see Object:addNotify().

Args (v2.4)

OVERVIEW

This library implements an argument parser.

FORMAT DESCRIPTION

A string is parsed into an array of arguments according to a format template. Arguments in the template are separated by commas. Each argument in the template consists of a keyword, optionally followed by one or more aliases delimited by equal signs, and an optional set of modifiers delimited by slashes. Modifiers denote the expected data type, if the argument is mandatory and whether a keyword must precede its value to form a valid argument. Example argument template: 

SOURCE=-s/A/M,DEST=-d/A/K

This template requires one or more arguments to satisfy SOURCE, and exactly one argument to satisfy DEST. Neither can be omitted. Either -d (or its alias DEST) must precede the value to be accepted as the second argument. Example command lines:

SOURCE one two three DEST foo valid
DEST foo -s one valid
DEST foo rejected; source argument missing
one two three foo rejected; keyword missing
one two dest foo valid, keys are case insensitive
one two three -d="foo" four valid, "four" added to SOURCE

An option without modifiers represents an optional string argument. Available modifiers are:

  • /S - Switch; considered a boolean value. When the keyword is present, true will be written into the respective slot in the results array.
  • /N - Number; the value will be converted to a number.
  • /K - Keyword; the keyword (or an alias) must precede its value.
  • /A - Always required; This argument cannot be omitted.
  • /M - Multiple; Any number of strings will be accepted, and all values that cannot be assigned to other arguments will show up in this argument. No more than one /M modifier may appear in a template.
  • /F - Fill; literal rest of line. If present, this must be the last argument.

Quoting and escaping: Double quotes can be used to enclose arguments containing equal signs and spaces.

FUNCTIONS
  • args.read() - Parses a string or table through an argument template
TODO

Backslashes for escaping quotes, spaces and themselves

res, msg = args.read(template, args)

Parses args according to template. args can be a string or a table of strings. If the arguments can be successfully matched against the template, the result will be a table of parsed arguments, indexed by both keywords and numerical order in which they appear in template, and the second argument will be set to the number of arguments in the template. If the arguments cannot be matched against the template, the result will be nil followed by an error message.

Debug (v5.3)

OVERVIEW

Debug library - implements debug output and debug levels:

2 TRACE used for trace messages
4 INFO informational messages, notices
5 WARN something unexpected happened
10 ERROR something went wrong, e.g. resource unavailable
20 FAIL something went wrong that cannot be coped with

The default debug level is WARN. To set the debug level globally, e.g.: 

db = require "tek.lib.debug"
db.level = db.INFO

The default debug output stream is stderr. To override it globally, e.g.: 

db = require "tek.lib.debug"
db.out = io.open("logfile", "w")
FUNCTIONS
VALUES
  • level - Debug level, default 5 (WARN)
  • out - Output stream, default io.stderr

debug.console()

Enters debug console.

debug.dump(table[, outfunc])

Dumps a table as Lua source using outfunc. Cyclic references are silently dropped. The default output function is debug.wrout().

debug.error(msg, ...)

Prints formatted debug info with ERROR debug level

debug.execute(lvl, func, ...)

Executes the specified function if the global debug level is less or equal the specified level.

debug.fail(msg, ...)

Prints formatted debug info with FAIL debug level

debug.format(lvl, msg, ...)

Format error message

debug.info(msg, ...)

Prints formatted debug info with INFO debug level

debug.print(lvl, msg, ...)

Prints formatted text if the global debug level is less or equal the specified level.

debug.stacktrace(debuglevel[, stacklevel])

Prints a stacktrace starting at the function of the given level on the stack (excluding the stracktrace function itself) if the global debug level is less or equal the specified debuglevel.

debug.trace(msg, ...)

Prints formatted debug info with TRACE debug level

debug.warn(msg, ...)

Prints formatted debug info with WARN debug level

debug.wrout(...)

Debug output function, by default 

function(...) out:write(...) end

Exec (v0.83)

FUNCTIONS
TASKS METHODS

child:abort()

Sends the task the abortion signal "a" and synchronizes on its completion.

msg, sender = Exec.getmsg()

Unlinks and returns the next message from the task's message queue, or nil if no messages are present. If a message is returned, then the second argument is the name of the task sending the message.

name = Exec.getname()

Returns the own task's name.

sig = Exec.getsignals([sigset])

Gets and clears the signals in sigset from the own task's signal state, and returns the present signals, one character per signal, concatenated to a string. If no signals are present, returns nil. Possible signals and their meanings are

  • "a" - abort, the Lua program stops due to an error
  • "t" - terminate, the task is asked to quit
  • "c" - child, a child task has finished
  • "m" - message, a message is present at the task

The default for sigset is "tcm". Notes: The abortion signal cannot be cleared from a task. The termination signal is a request that a task may handle, but it is not enforced.

success, res1, ... = child:join()

Synchronizes the caller on completion of the child task. The first return value is boolean and indicative of whether the task completed successfully. While suspended in this function and if an error occurs in the child task, an error is propagated to the caller also, unless error propagation is suppressed - see Exec.run(). If successful, return values from the child task will be converted to strings and returned as additional return values.

child = Exec.run(what[, arg1[, ...]])

Tries to launch a Lua script, function, or chunk, and returns a handle on a child task if successful. The first argument can be a string denoting the filename of a Lua script, a Lua function, or a table. If a table is given, either of the following keys in the table is mandatory:

  • "func", a function value to run,
  • "filename", a string denoting the filename of a Lua script,
  • "chunk", a string value containing a Lua chunk to run.

Optional keys in the table:

  • "taskname", a string denoting the name of the task to run. Task names are immutable during runtime and must be unique; the top-level task's implicit name is "main".
  • "abort", a boolean to indicate whether errors in the child should be propagated to the parent task. Default: true

Additional arguments are passed to the script, in their given order. Methods on the returned child task handle:

  • child:abort() - sends abortion signal and synchronizes on completion of the task
  • child:join() - synchronizes on completion of the task
  • child:sendmsg(msg) - sends a message to a task, see Exec.sendmsg()
  • child:sendport(port, msg) - Sends a message to a named port in the task, see Exec.sendport()
  • child:signal([sigs]) - sends signals to a task, see Exec.signal()
  • child:terminate() - sends termination signal and synchronizes on completion of the task

Note that the returned child handle is subject to garbage collection. If it gets collected (at the latest when the parent task is ending) and the child task is still running, the child will be sent the abortion signal, causing it to raise an error. This error, like any child error, also gets propagated back to the parent task, unless error propagation is suppressed (see above).

success = Exec.sendmsg(taskname, msg)

Sends a message to a named task. The special name "*p" addresses the parent task. Returns true if the task was found and the message sent.

success = Exec.sendport(taskname, portname, msg)

Sends the message to the named message port in the named task. Returns true if the task and port could be found and the message was sent.

success = Exec.signal(taskname[, sigs])

Sends signals to a named task, by default the termination signal "t". The special name "*p" addresses the parent task. Returns true if the task was found and the signals sent. See Exec.getsignals() for details on the signal format.

sig = Exec.sleep([millisecs])

Suspends the task for the given number of 1/1000th seconds. If no timeout is specified, sleeps indefinitely. Returns nil when the timeout has expired, or "a" when an abortion signal occurred or was already present at the task.

success, res1, ... = child:terminate()

This function is equivalent to child:join(), except for that it sends the child task the termination signal "t" before joining.

sig = Exec.wait([sigset])

Suspends the task waiting for any signals from the specified set. The signals from sigset that occured (or were already present at the task) are returned to the caller - see Exec.getsignals() for their format. The default signal set to wait for is "tc". Note: The abortion signal "a" is always included in the set.

msg, sender, sig = Exec.waitmsg([millisecs])

Suspends the task waiting for the given number of 1/1000th seconds or for a message, and returns the next message to the caller. If no timeout is specified, waits indefinitely. Returns nil when no message arrives in the given time, or when the cause for returning was that only a signal showed up in the task. The second return value is the name of the sender task, see Exec.getmsg() for details. The third return value contains the possible signals ("m" and "a") that caused this function to return, or nil if a timeout occurred.

sig = Exec.waittime(millisecs[, sigset])

Suspends the task waiting for the given number of 1/1000th seconds, or for any signals from the specified set. Signals from sigset that occured (or were already present at the task) are returned to the caller - see Exec.getsignals() for details. The default signal set to wait for is "tc". Note: The abortion signal "a" is always included in the signal set.

Region (v11.3)

OVERVIEW

This library implements the management of regions, which are collections of non-overlapping rectangles.

FUNCTIONS

region:andRect(r1, r2, r3, r4)

Logical ands a rectange to a region

region:andRegion(r)

Logically ands a region to a region

success = region:checkIntersect(x0, y0, x1, y1)

Returns a boolean indicating whether a rectangle specified by its coordinates overlaps with a region.

region:forEach(func, obj, ...)

For each rectangle in a region, calls the specified function according the following scheme: 

func(obj, x0, y0, x1, y1, ...)

Extra arguments are passed through to the function.

minx, miny, maxx, maxy = region:get()

Get region's min/max extents

x0, y0, x1, y1 = Region.intersect(d1, d2, d3, d4, s1, s2, s3, s4)

Returns the coordinates of a rectangle where a rectangle specified by the coordinates s1, s2, s3, s4 overlaps with the rectangle specified by the coordinates d1, d2, d3, d4. The return value is nil if the rectangles do not overlap.

region:isEmpty()

Returns true if a region is empty.

region = Region.new(r1, r2, r3, r4)

Creates a new region from the given coordinates.

region:orRect(r1, r2, r3, r4)

Logical ors a rectangle to a region

region:orRegion(r)

Logically ors a region to a region

self = region:setRect(r1, r2, r3, r4)

Resets an existing region to the specified rectangle.

region:shift(dx, dy)

Shifts a region by delta x and y.

self = region:subRect(r1, r2, r3, r4)

Subtracts a rectangle from a region

region:subRegion(region2)

Subtracts region2 from region.

region:xorRect(r1, r2, r3, r4)

Logical xors a rectange to a region

String (v2.0)

OVERVIEW

String management supporting two 31 bit values for each codepoint (intended for character strings and their metadata). Strings are stored internally as UTF-8 encoded snippets which are automatically packed and unpacked on demand. Forward iteration, insertion and deletion is considered fast, even for strings of arbitrary length and at arbitrary positions.

FUNCTIONS

String:erase([p0[, p1]])

Erases a range of characters from a string object. An optional range starts at position p0 and extends to the position p1, which may be negative to indicate the number of characters from the end of the string.

p0, p1 = String:find(utf8[, pos])

Finds the specified UTF-8 encoded string in the string object, and if found, returns the first and last position of its next occurrence from the starting position (default: 1).

length, maxval = String.foreachutf8(utf8string[, arg])

Returns the number of codepoints in utf8string and the highest codepoint number that occured in the string. arg can be a table, in which case each codepoint will be inserted into it as a number value, or a function, which will be called for each codepoint as its first, and the current position as its second argument.

String:free()

Free resources held by a string object

utf8str = String:get([p0[, p1]])

An alias for String:sub()

utf8 = String:getchar(pos)

Returns an UTF-8 encoded character at the given position in a string object.

char, metadata = String:getval(pos)

Returns a character's and its metadata's numeric codepoints at the given position in a string object.

String:insert(string2[, pos])

Inserts string2 into the string object, optionally at the given starting position. The default position is at the end of the string. string2 may be an UTF-8 encoded string or another string object. Metadata from another string object will be inserted accordingly, otherwise it is set to 0.

len = String:len()

Returns the number of characters in the string object.

string = String.new()

Creates a new, initially empty string object.

String:overwrite(utf8str[, pos])

Overwrites a range of characters in a string object from an UTF-8 encoded string, starting at the given position (default: 1). Metadata in the string object at the affected positions will be set to 0.

string = String:set(string2[, p0[, p1]])

Initializes the string object with string2, which can be either an UTF-8 encoded string or another string object. An optional range starts at position p0 and extends to the position p1, which may be negative to indicate the number of characters from the end of the string. Metadata at the affected positions is set to 0. Returns itself.

String:setmetadata(value[, p0[, p1]])

Sets metadata in a string object to the specified value. An optional range starts at position p0 and extends to the position p1, which may be negative to indicate the number of characters from the end of the string.

utf8str = String:sub([p0[, p1]])

Returns an UTF-8 encoded string representing the string object or a range of it. An optional range starts at position p0 and extends to the position p1, which may be negative to indicate the number of characters from the end of the string.

utf8string = String.utf8encode(table or number[, ...])

If the first argument is a table, encodes the numerically indexed codepoints in that table to an UTF-8 string; an optional second argument specifies the first position and an optional third argument the last position in the table. If the first argument is a number, encodes this and the following arguments as codepoints to an UTF-8 string.

Visual (v1.1)

FUNCTIONS

pen = Visual:allocPen(a, r, g, b)

Obtain a colored pen.

Visual:blitRect(x0, y0, x1, y1, dx, dy[, exposetable])

Blits the given rectangle to the destination upper left position dx/dy. Source areas of the blit that were previously obscured but are getting exposed by blitting them into visibility show up as coordinate quartets (x0, y0, x1, y1 each) in the optional exposetable.

Visual:clearInput(inputmask)

For a visual, specifies a set of input message types the caller wishes to remove from the set of messages to be received. For the valid types, see Visual.getMsg().

Visual.close()

Close visual.

Visual.closeFont(font)

Free font and associated resources.

gradient = Visual.createGradient(x0, y0, x1, y1, rgb0, rgb1)

If gradient support is available, creates a gradient object with a gradient from the coordinates x0,y0, with the color rgb0 to x1,y1, with the color rgb1.

pixmap = Visual.createPixmap(src[, width[, height[, alpha[, idx]]]])

Creates a pixmap object from some source. The src argument can be a string, containing a loaded image in some file format (PPM or PNG), an open file, or a table. In case of a string or a file, width and height determine an optional size to scale the image to. If only one of width and height are given, the image is scaled proprtionally. In case of a table, the width and height arguments are mandatory, and the table is expected to contain RGB values starting at table index 0, unless another index is given. The alpha argument can be used to override presence or absence of an alpha channel; the default is determined by the picture, or none in the case of a table source.

Visual:drawImage(table, x0, y0, x1, y1, pen_or_pentab)

Draw a table containing a simple vector image into the specified rectangle, with the specified table of pens, or a single pen. Image table format: 

{
  [1] = { x0, y0, x1, y1, ... }, -- coordinates table
  [4] = boolean, -- is_transparent
  [5] = { -- table of primitive records
    { [1]=fmtcode, [2]=nmpts, [3]={ indices }, [4]=pen_or_table },
    ...
  }
}

fmtcode can be 0x1000 for a strip, 0x2000 for a fan. The coordinates are in the range from 0 to 0xffff.

Visual:drawLine(x0, y0, x1, y1, pen)

Draw a line.

Visual:drawPixmap(pm, x0, y0, x1, y1)

Draw pixmap.

Visual:drawPoint(x, y, pen)

Draw a pixel.

Visual:drawRGB(table, x, y, w, h[, pw[, ph[, has_alpha]])

Draw a table of RGB values as pixels. The table index starts at 0. pw and ph are the "thickness" of pixels, whih allows to stretch the output by the given factor. The default is 1 respectively. The boolean has_alpha determines whether the pixel values are to be interpreted as ARGB and be rendered with alpha channel.

Visual:drawRect(x0, y0, x1, y1, pen)

Draw a rectangle

Visual:drawText(x0, y0, x1, y1, text, fgpen[, bgpaint])

Draw the text into the specified rectangle. fgpen must be a pen, bgpaint is optional and may be a pen, a pixmap, or a gradient. For drawing background with a pixmap or gradient, see also Visual:setTextureOrigin().

Visual:fillRect(x0, y0, x1, y1[, paint])

Draw a filled rectangle. paint may refer to a pen, a pixmap, or a gradient. For drawing with a pixmap or gradient, see also Visual:setTextureOrigin(). If no paint argument is specified, the visual's current background paint is used, see also Visual:setBGPen().

Visual:flush()

Flush all changes to the visual to the display.

Visual:freePen(pen)

Release a colored pen

attr1, ... = Visual:getAttrs(attributes)

Retrieve attributes from a visual. attributes is a string, in which individual characters determine a property each, which are returned in the order of their occurrence. Default: "whxy". Attributes:

  • "w" - number, visual's width in pixels
  • "h" - number, visual's height in pixels
  • "W" - number, screen width in pixels
  • "H" - number, screen height in pixels
  • "x" - number, visual's left edge on the screen
  • "y" - number, visual's top edge on the screen
  • "s" - boolean, whether the visual has a selection
  • "c" - boolean, whether the visual has a clipboard
  • "M" - boolean, whether the screen has a window manager

x0, y0, x1, y1 = Visual:getClipRect()

Get the visual's clipping rectangle that is in effect currently.

attr1, ... = Visual.getDisplayAttrs(attrs)

Queries attributes from the display. Returns one value for each character specified in the attrs string. Attributes:

  • "M" - The display provides a window manager (boolean)

table = Visual.getFontAttrs(font[, table])

Returns font attributes in a table. Field keys as currently defined:

  • "Height" - Height in pixels
  • "UlPosition" - Position of an underline, in pixels
  • "UlThickness" - Thickness of an underline, in pixels

msg = Visual.getMsg()

Get next input message. Fields in a message are indexed numerically:

  • -1 - Userdata, e.g. the window object from which the message originates, or the user message body in case of ui.MSG_USER
  • 0 - Timestamp of the message, milliseconds
  • 1 - Timestamp of the message, seconds
  • 2 - Message type. Types:
    • ui.MSG_CLOSE - the user wishes to close the window
    • ui.MSG_FOCUS - the window received/lost the input focus
    • ui.MSG_NEWSIZE - the window has been resized
    • ui.MSG_REFRESH - a part of the window needs a repaint
    • ui.MSG_MOUSEOVER - the mouse moved over/out of the window
    • ui.MSG_KEYDOWN - a key was pressed down
    • ui.MSG_MOUSEMOVE - the mouse was moved
    • ui.MSG_MOUSEBUTTON - a mouse button was pressed
    • ui.MSG_INTERVAL - a timer interval has passed
    • ui.MSG_KEYUP - a key was released
    • ui.MSG_USER - a user message was send to the application
    • ui.MSG_REQSELECTION - selection or clipboard requested
  • 3 - Message code - depending on the message type, indicates focus on/off, keycode, mouse button number, etc.
  • 4 - Mouse X position on window
  • 5 - Mouse Y position on window
  • 6 - Keyboard Qualifier
  • 7 - Keyboard message: UTF-8 representation of key code, or
  • 7 - Refresh message: X position of damaged area
  • 8 - Refresh message: Y position of damaged area
  • 9 - Refresh message: Width of damaged area
  • 10 - Refresh message: Height of damaged area
  • 11 - Mouse X position on screen
  • 12 - Mouse Y position on screen

A message will be acknowledged implicitely by garbage collection, or by invoking the msg:reply([table]) method on it, in which case extra data can be returned to the sender. Valid fields in table are:

  • UTF8Selection - a string containing the selection buffer, in reply to messages of the type MSG_REQSELECTION

type = Visual:getPaintInfo()

Returns the type of background paint that is currently effective:

  • 0 - undefined
  • 1 - single-color pen
  • 2 - pixmap
  • 3 - gradient

string = Visual:getSelection([type])

Gets the visual's selection of the specified type:

  • 1 - the selection (default)
  • 2 - the clipboard

width, height = Visual.getTextSize(font, text)

Returns the width and height of the specified text when rendered with the given font. See also Visual:textSize().

sec, millis = Visual.getTime()

Returns the system time in seconds and milliseconds.

data = Visual:getUserData()

Get the user data attached to a visual.

visual = Visual.open([args])

Opens a visual. Possible keys and their values in the args table:

  • "UserData" - Lua userdata attached to the visual
  • "Pens" - table, for looking up pens, pixmaps, and gradients
  • "Title" - string, window title (if applicable)
  • "Borderless" - bool, open window borderless (if applicable)
  • "PopupWindow" - bool, the window is used for a popup
  • "Center" - bool, try to open the window centered on the screen
  • "FullScreen" - bool, try to open in fullscreen mode
  • "Width" - number, width in pixels
  • "Height" - number, height in pixels
  • "Left" - number, left edge in pixels on the screen
  • "Top" - number, top edge in pixels on the screen
  • "MinWidth" - number, min. width for the window to shrink to
  • "MinHeight" - number, min. height for the window to shrink to
  • "MaxWidth" - number, max. width for the window to grow to
  • "MaxHeight" - number, max. height for the window to grow to
  • "EventMask" - number, mask of input message types, see also Visual.getMsg() for details
  • "BlankCursor" - bool, clear the mouse pointer over the window
  • "ExtraArgs" - string, extra arugments containing hints for the underlying display driver
  • "MsgFileNo" - number, of a file descriptor to read messages of type MSG_USER from. Default: the file number of stdin

font = Visual.openFont([name[, size[, attrs]]])

Opens a named font and, if successful, returns a handle on it. The size is measured in pixels. attrs is a string with each character representing a hint:

  • "s" - the font should be scalable
  • "b" - the font should be bold
  • "i" - the font should be slanted to the right

It depends on the underlying font resource whether name, size, and attributes must match exactly for this function to succeed, and which of the attributes can and will be taken into account. In the case of the TTF freetype library, for example, it may be more promising to use names of fonts specifically crafted to be of the desired type, e.g. "DejaVuSans-BoldOblique", rather than "DejaVuSans" with the attributes "ib".

Visual:popClipRect()

Pop a rectangle from the top of the stack of clipping rectangles.

Visual:pushClipRect(x0, y0, x1, y1)

Push a rectangle on top of the stack of clipping rectangles.

num = Visual:setAttrs(table)

Set attributes in a visual. Possible fields in the table, as currently defined:

  • "MinWidth" - number, minimum width the visual may shrink to
  • "MinHeight" - number, minimum height the visual may shrink to
  • "MaxWidth" - number, minimum width the visual may grow to
  • "MaxHeight" - number, minimum width the visual may grow to
  • "HaveSelection" - boolean, indicates that the visual has the selection
  • "HaveClipboard" - boolean, indicates that the visual has the clipboard
  • "Left" - number, left edge of the visual on the screen, in pixels
  • "Top" - number, top edge of the visual on the screen, in pixels
  • "Width" - number, width of the visual on the screen, in pixels
  • "Height" - number, height of the visual on the screen, in pixels
  • "WindowHints" - string, with each character acting as a hint to window management. Currently defined:
    • "t" - top, to raise the window on top of all others

Visual:setBGPen(paint[, tx[, ty]])

Set the visual's pen, pixmap or gradient for rendering backgrounds. Also, optionally, sets a pixmap's or gradient's texture origin.

Visual:setClipRect(x0, y0, x1, y1)

Set clipping rectangle

Visual:setFont(font)

Set the visual's current font.

Visual:setInput(inputmask)

For a visual, specifies a set of input message types the caller wishes to add to the set of messages to be received. For the valid types, see Visual.getMsg().

Visual:setSelection(string, [type])

Sets the visual's selection of the specified type:

  • 1 - the selection (default)
  • 2 - the clipboard

Visual:setShift(sx, sy)

Set coordinate displacement in visual

otx, oty = Visual:setTextureOrigin(tx, ty)

Sets the texture origin for the drawing operations Visual:fillRect() and Visual:drawText(), and returns the old texture origin.

Visual.sleep(ms)

Suspends the caller waiting for the specified number of 1/1000th seconds

width, height = Visual:textSize(text)

Get width and height of the given text, if rendered with the visual's current font. See also Visual.getTextSize().

Visual:unsetClipRect()

Unset clipping rectangle

Visual.wait()

Suspends the caller waiting for any event from any window.

ui (v54.0)

OVERVIEW

This module is the user interface toolkit's base library. It implements a class loader and support functions, and it provides a central place for various constants and defaults. To invoke the class loader, simply aquire a class from the tek.ui table, e.g. this will load the tek.ui.class.application class, as well as all subsequently needed classes: 

local ui = require "tek.ui"
ui.Application:new { ...
FUNCTIONS
CONSTANTS
  • VERSION
    • Overall package version number of tekUI, starting at 100 for version 1.00. (Not to be confused with the ui module's _VERSION string, with underscore)
  • VERSIONSTRING
    • String representation of the overall package version number
  • HUGE
    • This constant is used to express a 'huge' spatial extent on a given axis, e.g. Width = ui.HUGE indicates that you wish no specific size limit on the X axis.
DEFAULTS
  • DBLCLICKJITTER
    • Maximum sum of squared delta mouse positions (dx² + dy²) for a pair of mouse clicks to be accepted as a double click. The default is 70. Large touchscreens may require a much larger value.
  • DBLCLICKTIME
    • Maximum number of microseconds between mouse clicks to be recognized as a double click. Default: 32000. Use a larger value for touchscreens.
  • ThemeName
    • Setting this variable overrides the THEME environment variable and enforces the usage of the specified cascade, up to the point where the application's author styles are considered.
  • UserStyles
    • Name of the user stylesheet file. Default: "user". Can be set to false to be disabled.
MESSAGE TYPE CONSTANTS
  • MSG_CLOSE
    • Message sent when a window was closed
  • MSG_FOCUS
    • A window has been activated or deactivated
  • MSG_INTERVAL
    • 50Hz Timer interval message
  • MSG_KEYDOWN
    • Key pressed down
  • MSG_KEYUP
    • Key released
  • MSG_MOUSEBUTTON
    • Mousebutton pressed or released
  • MSG_MOUSEMOVE
    • Mouse pointer moved
  • MSG_MOUSEOVER
    • Mouse pointer has entered or left the window
  • MSG_NEWSIZE
    • A window has been resized
  • MSG_REFRESH
    • A window needs a (partial) refresh
  • MSG_USER
    • User message
  • MSG_SIGNAL
    • System signal message. Msg code indicates type of signal; 0 - abortion signal
NOTIFICATIONS
SEE ALSO

ui = checkVersion(version)

raises an error if the tekUI version number is less than the requested version. This can be used in the following idiom: 

ui = require "tek.ui".checkVersion(107)

hookobject = ui.createHook(realm, classname, parent[, table])

Loads a class of the given realm and classname, instantiates it (optionally passing it table for initialization), connects it to the specified parent element, and calls its setup() method. If classname is the pre-defined name "none", this function returns false. Refer also to ui.loadClass() for further details.

false = ui.destroyHook([hookobject])

Destroys a hook object by invoking its cleanup() and disconnect() methods. Always returns false.

ui.extractKeyCode(string[, shortcutmark])

Extract a shortcut character from a string. The default shortcut marker is an underscore.

catalog = ui.getLocale(appid[, vendordomain[, deflang[, language]]])

Returns a table of locale strings for the given application Id and vendor domain. deflang (default: "en") is used as the default language code if a catalog for the requested language is unavailable. If no language code is specified, then the preferred language will be obtained from the operating system or desktop environment. If no catalog file was found or non-existent keys are used to access the resulting catalog, the key will be echoed with underscores turned into spaces; for example, if catalog contained no string for the given key, accessing catalog.HELLO_WORLD would return the string "HELLO WORLD".

imgobject = ui.getStockImage(name, ...)

Creates an image object of a named class, corresponding to classes found in tek/ui/image. Extra arguments are passed on as imageclass:new(...).

properties, errmsg = ui.getStyleSheet([name])

Aquires a style sheet from memory, by loading it from disk, or by determining properties at runtime. Predefined names are:

  • "minimal" - the hardcoded internal user agent style sheet
  • "desktop" - An external style sheet named "desktop.css", overlayed with the color scheme (and possibly other properties) of the running desktop (if applicable)

Any other name will cause this function to attempt to load an equally named style sheet file.

class = ui.loadClass(realm, classname[, min_version])

Loads a class of the given classname from the specified realm, and optionally with a minimum version requirement. Returns the loaded class or false if the class or realm is unknown, if the version requirement cannot be satisfied, or if an error occured in the module. Currently defined values for realm are:

  • "border" - border classes
  • "class" - user interface element classes
  • "hook" - drawing hook classes
  • "image" - image classes
  • "layout" - group layouting classes

imgobject = ui.loadImage(name)

Loads an image from a file or retrieves it from the image cache. Currently supported are the PPM and PNG file formats. (PPM support is built-in, while PNG support may depend on the build configuration.)

ui.loadLibrary(name[, version])

Loads a library with at least the specified major version, from a local or global path starting with tek/lib.

properties, msg = ui.loadStyleSheet(file)

This function loads a style sheet from the specified file (which can be a name or an open file handle), and parses it into a table of style classes with properties. If parsing failed, the return value is false and msg contains an error message.

table, msg = ui.loadTable(fname)

This function tries to load a file from the various possible locations as defined by ui.LocalPath, interpretes it is as Lua source, and returns its contents as keys and values of a table. If unsuccessful, returns nil followed by an error message.

ui.require(name[, version])

Loads an user interface class with at least the specified major version. This function is a shortcut for ui.loadClass("class", ...) - see ui.loadClass() for more details.

key, quals = ui.resolveKeyCode(code)

Resolves a combined keycode specifier (e.g. "Ctrl+Shift+Q") into a key string and a table of qualifier codes.

Application (v43.1)

OVERVIEW

ClassOverview : Class / Family / Application

This class implements tekUI's application, entrypoint and main loop.

EXAMPLE

A tekUI application can be written in a single, nested expression: 

local ui = require "tek.ui"
ui.Application:new {
  Children = {
    ui.Window:new {
      Children = {
        ui.Button:new { Text = "Hello World" }
      }
    }
  }
}:run()
MEMBERS
  • ApplicationId [IG] (string)

    Name of the application, normally used as an unique identifier in combination with the Domain attribute. Default is "unknown".

  • Author [IG] (string)

    Names of the application's authors. Default: "unknown"

  • AuthorStyles [IG] (string)

    A string containing style sheet notation, overlaying all other properties, including those retrieved using the AuthorStyleSheets attribute.

  • AuthorStyleSheets [IG] (string)

    A string containing the names of author style sheet files overlaying user agent and theme declaration. Multiple style sheets are separated by spaces. The last style sheet has the highest precedence, e.g. "desktop texture" would load the style sheets desktop.css and texture.css.

  • Copyright [IG] (string)

    Copyright notice applying to the application, default "unknown"

  • Display [IG] (Display)

    An initial Display. By default, the application creates a new one during Application.new().

  • Domain [IG] (string)

    An uniquely identifying domain name of the vendor, organization or author manufacturing the application (preferrably without domain parts like "www." if they are not significant for identification). Default is "unknown".

  • GCControl [IG] (boolean or string)

    The application can perform a garbage collection of the specified type directly before getting suspended waiting for input. If set to false, no explicit garbage collection is initiated. If the value is true or "step", the application performs a single garbage collection step. Other values (e.g. "collect") are passed unmodified to collectgarbage(). Default: true

  • ProgramName [IG] (string)

    Name of the application, as displayed to the user. This is also the fallback for the Title attribute in windows. If unset, the default will be "tekUI".

  • Status [G] (string)

    Status of the application, can be "init", "error", "run", "quit".

  • Vendor [IG] (string)

    Name of the vendor or organization responsible for producing the application, as displayed to the user. Default "unknown".

NOTES

The Domain and ApplicationId attributes are UTF-8 encoded strings, so any international character sequence is valid for them. Anyhow, it is recommended to avoid too adventurous symbolism, as its end up in a hardly decipherable, UTF-8 plus URL-encoded form in the file system, e.g. for loading catalog files from tek/ui/locale/<domain>/<applicationid>.

IMPLEMENTS
OVERRIDES

addCoroutine(function, arg1, ...)

Adds the specified function and arguments to the application as a new coroutine, and returns to the caller. The new coroutine is not started immediately, but scheduled for later execution during the application's update procedure. This gives the application an opportunity to service all pending messages and updates before the coroutine is actually started.

addInputHandler(msgtype, object, func)

Adds an object and function to the application's chain of handlers for input of the specified type. Currently, the only message type an appliction is able to react on is ui.MSG_USER. All other message types are specific to a Window. Input handlers are invoked as follows: 

message = function(object, message)

The handler is expected to return the message, which will in turn pass it on to the next handler in the chain. See also Window:addInputHandler() for more information.

connect(parent)

Checks member linkage and connects all children by invoking their connect() methods. Note that unlike Element:connect(), this function is recursive.

selected = easyRequest(title, text, buttontext1[, ...])

This function shows a message box or requester. title will be displayed as the window title; if this argument is false, the application's ProgramName will be used for the title. text (which may contain line breaks) will be used as the requester's body. Buttons are ordered from left to right. The first button has the number 1. If the window is closed using the Escape key or close button, the return value will be false. Note: The caller of this function must be running in a coroutine (see Application:addCoroutine()).

element = getById(id)

Returns the element that was registered with the Application under its unique id. Returns nil if the id was not found.

getChildren()

See Area:getChildren().

getGroup()

See Area:getGroup().

getLocale([deflang[, language]])

Returns a table of locale strings for ApplicationId and Domain. See ui.getLocale() for more information.

c = obtainClipboard([mode])

Obtain clipboard table, optional mode can be "empty".

quit()

Quits the application.

releaseSetClipboard([c])

Release clipboard, optionally setting a new one.

remInputHandler(msgtype, object, func)

Removes an input handler that was previously registered with Application:addInputHandler().

status[, path, selection] = requestFile(args)

Requests a single or multiple files or directories. Possible keys in the args table are:

  • Center - Boolean, whether requester should be opened centered
  • FocusElement - What element to place the initial focus on; see DirList for possible values
  • Height - Height of the requester window
  • Lister - External lister object to operate on
  • Location - Initial contents of the requester's location field
  • OverWindow - Open dialogue centered over the specified window
  • Path - The initial path
  • SelectMode - "multi" or "single" [default "single"]
  • SelectText - Text to show on the select button [default "open"]
  • Title - Window title [default "Select file or directory..."]
  • Width - Width of the requester window

The first return value is a string reading either "selected" or "cancelled". If the status is "selected", the second return value is the path where the requester was left, and the third value is a table of the items that were selected. Note: The caller of this function must be running in a coroutine (see Application:addCoroutine()).

success, status = run()

Runs the application. Returns when all child windows are closed or when the application's Status is set to "quit".

retrig = setLastKey([newkey])

Sets newkey as the key that was last pressed in the application. If no new key is given, the current key is unset. Returns a boolean indicating whether it is the same as the previously registered key.

suspend([window])

Suspends the caller (which must be running in a coroutine) until it is getting rescheduled by the application. Coroutines can use this as a cooperation point, which gives the application an opportunity to service all pending messages and updates. If no argument is given, the application returns to the caller as quickly as possible. If an optional window is specified, the coroutine is put to sleep until something happens in the application, or an interval timer event is present at the window (i.e. the suspended coroutine is rescheduled after no longer than 1/50th of a second).

up()

This function is called when the application is fully initialized and about to enter its main loop. The user can overwrite it e.g. to add a coroutine that shows a splash screen.

Area (v57.5)

OVERVIEW

ClassOverview : Class / Object / Element / Area

This is the base class of all visible user interface elements. It implements an outer margin, layouting, drawing, and the relationships to its neighbour elements.

ATTRIBUTES
  • AutoPosition [I] (boolean)

    When the element receives the focus, this flag instructs it to automatically position itself into the visible area of any Canvas that may contain it. An affected Canvas must have its AutoPosition attribute enabled as well for this option to take effect (but unlike the Area class, in a Canvas it is disabled by default). The boolean (default true) will be translated to the flag FL_AUTOPOSITION, and is meaningless after initialization.

  • BGPen [G] (color specification)

    The current color (or texture) for painting the element's background. This value is set in Area:setState(), where it is derived from the element's current state and the background-color style property. Valid are color names (e.g. "detail", "fuchsia", see also Display for more), a hexadecimal RGB specification (e.g. "#334455", "#f0f"), or an image URL in the form "url(...)".

  • DamageRegion [G] (Region)

    see TrackDamage

  • Disabled [ISG] (boolean)

    If true, the element is in disabled state and loses its ability to interact with the user. This state variable is handled in the Widget class.

  • EraseBG [I] (boolean)

    If true, the element's background is painted automatically using the Area:erase() method. Set this attribute to false if you intend to paint the background yourself in Area:draw(). The boolean (default true) will be translated to the flag FL_ERASEBG, and is meaningless after initialization.

  • Flags [SG] (Flags field)

    This attribute holds various status flags, among others:

    • FL_SETUP - Set in Area:setup() and cleared in Area:cleanup()
    • FL_LAYOUT - Set in Area:layout(), cleared in Area:cleanup()
    • FL_SHOW - Set in Area:show(), cleared in Area:hide()
    • FL_REDRAW - Set in Area:layout(), Area:damage(), Area:setState() and possibly other places to indicate that the element needs to be repainted. Cleared in Area:draw().
    • FL_REDRAWBORDER - To indicate a repaint of the element's borders. Handled in the Frame class.
    • FL_CHANGED - This flag indicates that the contents of an element have changed, i.e. when children were added to a group, or when setting a new text or image should cause a recalculation of its size.
    • FL_POPITEM - Used to identify elements in popups, handled in PopItem.
  • Focus [SG] (boolean)

    If true, the element has the input focus. This state variable is handled by the Widget class. Note: This attribute represents only the current state. If you want to place the initial focus on an element, use the InitialFocus attribute in the Widget class.

  • HAlign [IG] ("left", "center", "right")

    Horizontal alignment of the element in its group. This attribute can be controlled using the halign style property.

  • Height [IG] (number, "auto", "fill", "free")

    Height of the element, in pixels, or

    • "auto" - Reserves the minimum required
    • "free" - Allows the element's height to grow to any size.
    • "fill" - To fill up the height that other elements in the same group have claimed, without claiming more.

    This attribute can be controlled using the height style property.

  • Hilite [SG] (boolean)

    If true, the element is in highlighted state. This state variable is handled by the Widget class.

  • MaxHeight [IG] (number or "none")

    Maximum height of the element, in pixels [default: "none"]. This attribute is controllable via the max-height style property.

  • MaxWidth [IG] (number or "none")

    Maximum width of the element, in pixels [default: "none"]. This attribute is controllable via the max-width style property.

  • MinHeight [IG] (number)

    Minimum height of the element, in pixels [default: 0]. This attribute is controllable via the min-height style property.

  • MinWidth [IG] (number)

    Minimum width of the element, in pixels [default: 0]. This attribute is controllable via the min-width style property.

  • Selected [ISG] (boolean)

    If true, the element is in selected state. This state variable is handled by the Widget class.

  • TrackDamage [I] (boolean)

    If true, the element collects intra-area damages in a Region named DamageRegion, which can be used by class writers to implement minimally invasive repaints. Default: false, the element is repainted in its entirety. The boolean will be translated to the flag FL_TRACKDAMAGE and is meaningless after initialization.

  • VAlign [IG] ("top", "center", "bottom")

    Vertical alignment of the element in its group. This attribute can be controlled using the valign style property.

  • Weight [IG] (number)

    Specifies the weight that is attributed to the element relative to its siblings in the same group. By recommendation, the weights in a group should sum up to 0x10000.

  • Width [IG] (number, "auto", "fill", "free")

    Width of the element, in pixels, or

    • "auto" - Reserves the minimum required
    • "free" - Allows the element's width to grow to any size
    • "fill" - To fill up the width that other elements in the same group have claimed, without claiming more.

    This attribute can be controlled using the width style property.

STYLE PROPERTIES
background-attachment "scollable" or "fixed"
background-color Controls Area.BGPen
fixed coordinates used by the fixed layouter: "x0 y0 x1 y1"
halign controls the Area.HAlign attribute
height controls the Area.Height attribute
margin-bottom the element's bottom margin, in pixels
margin-left the element's left margin, in pixels
margin-right the element's right margin, in pixels
margin-top the element's top margin, in pixels
max-height controls the Area.MaxHeight attribute
max-width controls the Area.MaxWidth attribute
min-height controls the Area.MinHeight attribute
min-width controls the Area.MinWidth attribute
padding-bottom the element's bottom padding
padding-left the element's left padding
padding-right the element's right padding
padding-top the element's top padding
valign controls the Area.VAlign attribute
width controls the Area.Width attribute

Note that repainting elements with a "fixed" background-attachment can be expensive. This variant should be used sparingly, and some classes may implement it incompletely or incorrectly.

IMPLEMENTS
OVERRIDES

minw, minh, maxw, maxh = Area:askMinMax(minw, minh, maxw, maxh)

This method is called during the layouting process for adding the required width and height to the minimum and maximum size requirements of the element, before passing the result on to its super class. minw, minh are cumulative of the minimal size of the element, while maxw, maxw collect the size the element is allowed to expand to.

beginPopup([baseitem])

Prepare element for being used in a popup.

all_present = Area:checkClearFlags(chkflags[, clearflags])

Check for presence of all of the specified chkflags in the element. Optionally clears the clearflags set from the element.

all_present = Area:checkFlags(flags)

Check for presence of all of the specified flags in the element.

can_receive = Area:checkFocus()

Returns true if this element can receive the input focus.

can_hilite = Area:checkHilite()

Returns true if this element can be highlighted, e.g by being hovered over with the pointing device.

Area:cleanup()

Clears all temporary layouting data and the FL_LAYOUT and FL_SETUP flags, before passing on the call to Element:cleanup().

Area:damage(x0, y0, x1, y1)

If the element overlaps with the given rectangle, this function marks it as damaged by setting ui.FL_REDRAW in the element's Flag field. Additionally, if the element's FL_TRACKDAMAGE flag is set, intra-area damage rectangles are collected in DamageRegion.

success = Area:draw()

If the element is marked for a repaint (indicated by the presence of the flag ui.FL_REDRAW in the Flags field), draws the element into the rectangle that was assigned to it by the layouter, clears ui.FL_REDRAW, and returns true. If the flag FL_ERASEBG is set, this function also clears the element's background by calling Area:erase().

When overriding this function, the control flow is roughly as follows: 

function ElementClass:draw()
  if SuperClass.draw(self) then
    -- your rendering here
    return true
  end
end

There are rare occasions in which a class modifies the drawing context, e.g. by setting a coordinate displacement. Such modifications must be performed in Area:drawBegin() and undone in Area:drawEnd(). In this case, the control flow looks like this: 

function ElementClass:draw()
  if SuperClass.draw(self) and self:drawBegin() then
    -- your rendering here
    self:drawEnd()
    return true
  end
end

can_draw = Area:drawBegin()

Prepares the drawing context, returning a boolean indicating success. This function must be overridden if a class wishes to modify the drawing context, e.g. for installing a coordinate displacement.

Area:drawEnd()

Reverts the changes made to the drawing context during Area:drawBegin().

Area:erase()

Clears the element's background. This method is invoked by Area:draw() if the FL_ERASEBG flag is set, and when a repaint is possible and necessary. Area:drawBegin() has been invoked when this function is called, and Area:drawEnd() will be called afterwards.

moved = Area:focusRect([x0, y0, x1, y1])

Tries to shift any Canvas containing the element into a position that makes the element fully visible. Optionally, a rectangle can be specified that is to be made visible. Returns true to indicate that some kind of repositioning has taken place.

bgpen, tx, ty, pos_independent = Area:getBG()

Gets the element's background properties. bgpen is the background paint (which may be a solid color, texture, or gradient). If the element's background-attachment is not "fixed", then tx and ty are the coordinates of the texture origin. pos_independent indicates whether the background is independent of the element's position.

element = Area:getBGElement()

Returns the element that is responsible for painting the surroundings (or the background) of the element. This information is useful for painting transparent or translucent parts of the element, e.g. an inactive focus border.

self = Area:getByXY(x, y)

Returns self if the element covers the specified coordinate.

element = Area:getChildren([mode])

Returns a table containing the element's children, or nil if this element cannot have children. The optional argument mode is the string "init" when this function is called during initialization or deinitialization.

dx, dy = Area:getDisplacement()

Get the element's coordinate displacement

element = Area:getGroup(parent)

Returns the closest Group containing the element. If the parent argument is true, this function will start looking for the closest group at its parent - otherwise, the element itself is returned if it is a group already. Returns nil if the element is not currently connected.

left, top, right, bottom = Area:getMargin()

Returns the element's margins in the order left, top, right, bottom.

minx, miny, maxx, maxy = Area:getMinMax()

Returns the element's calculated minimum and maximum size requirements, which are available after Area:askMinMax().

element = Area:getNext([mode])

Returns the next element in its group. If the element has no successor and the optional argument mode is "recursive", returns the next element in the parent group (and so forth, until it reaches the topmost group).

left, top, right, bottom = Area:getPadding()

Returns the element's padding style properties.

element = Area:getParent()

Returns the element's parent element, or false if it currently has no parent.

element = Area:getPrev([mode])

Returns the previous element in its group. If the element has no predecessor and the optional argument mode is "recursive", returns the previous element in the parent group (and so forth, until it reaches the topmost group).

x0, y0, x1, y1 = Area:getRect()

This function returns the rectangle which the element has been layouted to, or nil if the element has not been layouted yet.

table = Area:getSiblings()

Returns a table containing the element's siblings, which includes the element itself. Returns nil if the element is not currently connected. Note: The returned table must be treated read-only.

Area:hide()

Override this method to free all display-related resources previously allocated in Area:show().

changed = Area:layout(x0, y0, x1, y1[, markdamage])

Layouts the element into the specified rectangle. If the element's (or any of its childrens') coordinates change, returns true and marks the element as damaged, unless the optional argument markdamage is set to false.

msg = Area:passMsg(msg)

If the element has the ui.FL_RECVINPUT flag set, this function receives input messages. Additionally, to receive messages of the type ui.MSG_MOUSEMOVE, the flag ui.FL_RECVMOUSEMOVE must be set. After processing, it is free to return the message unmodified (thus allowing it to be passed on to other elements), or to absorb the message by returning false. You are not allowed to modify any data inside the original message; if you alter it, you must return a copy. The message types ui.MSG_INTERVAL, ui.MSG_USER, and ui.MSG_REQSELECTION are not received by this function. To receive these, you must register an input handler using Window:addInputHandler().

Area:punch(region)

Subtracts the element from (by punching a hole into) the specified Region. This function is called by the layouter.

Area:rethinkLayout([repaint[, check_size]])

Slates an element (and its children) for relayouting, which takes place during the next Window update cycle. If the element's coordinates change, this will cause it to be repainted. The parent element (usually a Group) will be checked as well, so that it has the opportunity to update its FreeRegion. The optional argument repaint can be used to specify additional hints:

  • 1 - marks the element for repainting unconditionally (not implying possible children)
  • 2 - marks the element (and all possible children) for repainting unconditionally

The optional argument check_size (a boolean) can be used to recalculate the element's minimum and maximum size requirements.

setFlags(flags)

Set element's flags. The flags FL_REDRAW, FL_CHANGED, and FL_REDRAWBORDER will additionally cause the flag FL_UPDATE to be set, which will also bubble up in the element hierarchy until it reaches to topmost element.

Area:setState(bg)

Sets the BGPen attribute according to the state of the element, and if it changed, marks the element for repainting.

Area:setup(app, win)

After passing the call on to Element:setup(), initializes fields which are being used by Area:layout(), and sets FL_SETUP in the Flags field to indicate that the element is ready for getting layouted and displayed.

Area:show()

This function is called when the element's window is opened.

Button (v2.1)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Text / Button

The Button class implements a Text element with a button mode (behavior) and button class (appearance). In addition to that, it enables the initialization of a possible keyboard shortcut from a special initiatory character (by default an underscore) preceding a letter in the element's Text attribute.

NOTES

This class adds redundancy, because it differs from the Text class only in that it initializes a few defaults differently in its new() method. To avoid this overhead, use the Text class directly, or create a Button factory like this: 

function newButton(text)
  return ui.Text:new { Mode = "button", Class = "button",
    Text = text, KeyCode = true }
end

Canvas (v37.6)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Canvas

This class implements a scrollable area acting as a managing container for a child element. Currently, this class is used exclusively for child objects of the ScrollGroup class.

ATTRIBUTES
  • AutoPosition [I] (boolean)

    See Area

  • AutoHeight [IG] (boolean)

    The height of the canvas is automatically adapted to the height of the region it is layouted into. Default: false

  • AutoWidth [IG] (boolean)

    The width of the canvas is automatically adapted to the width of the canvas it is layouted into. Default: false

  • CanvasHeight [ISG] (number)

    The height of the canvas in pixels

  • CanvasLeft [ISG] (number)

    Left visible offset of the canvas in pixels

  • CanvasTop [ISG] (number)

    Top visible offset of the canvas in pixels

  • CanvasWidth [ISG] (number)

    The width of the canvas in pixels

  • Child [ISG] (object)

    The child element being managed by the Canvas

  • KeepMinHeight [I] (boolean)

    Report the minimum height of the Canvas' child object as the Canvas' minimum display height. The boolean will be translated to the flag FL_KEEPMINHEIGHT, and is meaningless after initialization.

  • KeepMinWidth [I] (boolean)

    Translates to the flag FL_KEEPMINWIDTH. See also KeepMinHeight, above.

  • UnusedRegion [G] (Region)

    Region of the Canvas which is not covered by its Child

  • UseChildBG [IG] (boolean)

    If true, the Canvas borrows its background properties from its child for rendering its UnusedRegion. If false, the Canvas' own background properties are used. Default: true

  • VIncrement [IG] (number)

    Vertical scroll step, used e.g. for mouse wheels

IMPLEMENTS
OVERRIDES

damageChild(r1, r2, r3, r4)

Damages the specified region in the child area where it overlaps with the visible part of the canvas.

over, x, y = getMouseOver(msg)

From an input message, retrieves the mouse position as seen from the child object. The first return value is false, "child" if the mouse is over the child object, or "canvas" if the mouse is over the canvas.

Canvas:onSetChild()

This handler is invoked when the canvas' Child element has changed.

updateUnusedRegion()

Updates the UnusedRegion attribute, which contains the Canvas' area which isn't covered by its Child.

CheckMark (v9.4)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Text / CheckMark

Specialization of the Text class, implementing a toggle button with a graphical check mark.

ATTRIBUTES
  • Image [IG] (Image)

    Image to be displayed when the CheckMark element is unselected.

  • SelectImage [IG] (Image)

    Image to be displayed when the CheckMark element is selected.

OVERRIDES

DirList (v17.4)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Group / DirList

This class implements a directory lister.

ATTRIBUTES
  • AutoWidth [IG] (boolean)

    Tells the directory lister to adapt its contents dynamically to the width of the element. By default, the column widths remain adjusted to the initial width.

  • DisplayMode [IG] (string)

    What kind of entries to display, "all" or "onlydirs". Default: "all"

  • FocusElement [I] (string)

    What element to focus initially: "path", "location", "list". Default: "list"

  • Kind [IG] (string)

    The visual appearance (or purpose) of the lister, which will determine the presence and arrangement of some interface elements:

    • "requester" - for a standalone file requester
    • "lister" - for a directory lister component
    • "simple" - for the use without accompanying elements

    The default kind is "lister".

  • Location [IG] (string)

    The currently selected entry (may be a file or directory)

  • Path [IG] (string)

    Directory in the file system

  • BasePath (string)

    Filesystem base path in which the lister is allowed to operate

  • Selection [G] (table)

    An array of selected entries

  • SelectMode [IG] (String)

    Selection mode:

    • "single" - allows selections of one entry at a time
    • "multi" - allows selections of multiple entries
  • SelectText [IG] (String)

    The text to display on the selection button. Default: "Open" (or its equivalent in the current locale)

  • Status [G] (string)

    Status of the directory lister:

    • "running" - the lister is currently being shown
    • "selected" - the user has selected one or more entries
    • "cancelled" - the lister has been cancelled by the user
IMPLEMENTS
OVERRIDES

abortScan()

This function aborts the coroutine which is currently scanning the directory. The caller of this function must be running in its own coroutine.

cdir = getCurrentDir()

Returns the current directory. You can override this function to implement your own filesystem semantics.

iterator = getDirIterator(directory)

Returns an iterator function for traversal of the entries in the given directory. You can override this function to get an iterator over arbitrary kinds of listings.

attr = getFileStat(path, name, attr[, idx])

Returns an attribute for the entry of the given path and name; see the documentation of the LuaFileSystem module for the attribute names and their meanings. Currently, only the "mode" and "size" attributes are requested, but if you override this function, it would be smart to implement as many attributes as possible. idx is optional and specifies the entry number inside the list, which is an information that may or may not be supplied by the calling function.

goParent()

Starts reading and displays the parent directory of the current directory.

onSelectEntry(lnr, name, type)

This handler is called when an item in the list was selected by the user. It is passed the line number, name and type of the entry (which can be "file" or "directory").

table, type = scanEntry(path, name, idx)

Scans a single entry name in a directory named path. idx is the entry number with which this scanned entry will appear in the directory listing. table is an array of strings, containing entries like name, size, date, permissions, modification date etc. The type return value corresponds to the return values of DirList:getFileStat().

showDirectory(path)

Starts reading and displays the specified directory.

path, part = splitPath(path)

Splits a path, returning a path and the rearmost path or file part. You can override this function to implement your own file system naming conventions.

Display (v33.6)

OVERVIEW

ClassOverview : Class / Object / Display

This class manages a display.

ATTRIBUTES
  • AspectX [IG] (number)
    • X component of the display's aspect ratio
  • AspectY [IG] (number)
    • Y component of the display's aspect ratio
IMPLEMENTS
STYLE PROPERTIES
  • font
  • font-fixed
  • font-large
  • font-x-large
  • font-xx-large
  • font-menu
  • font-small
  • font-x-small
  • font-xx-small
  • rgb-active
  • rgb-active-detail
  • rgb-background
  • rgb-border-focus
  • rgb-border-legend
  • rgb-border-rim
  • rgb-border-shadow
  • rgb-border-shine
  • rgb-bright
  • rgb-caption-detail
  • rgb-cursor
  • rgb-cursor-detail
  • rgb-dark
  • rgb-detail
  • rgb-disabled
  • rgb-disabled-detail
  • rgb-disabled-detail-shine
  • rgb-fill
  • rgb-focus
  • rgb-focus-detail
  • rgb-group
  • rgb-half-shadow
  • rgb-half-shine
  • rgb-hover
  • rgb-hover-detail
  • rgb-list
  • rgb-list-active
  • rgb-list-active-detail
  • rgb-list-detail
  • rgb-list-alt
  • rgb-menu
  • rgb-menu-active
  • rgb-menu-active-detail
  • rgb-menu-detail
  • rgb-outline
  • rgb-shadow
  • rgb-shine
  • rgb-user1
  • rgb-user2
  • rgb-user3
  • rgb-user4
OVERRIDES

closeFont(font)

Closes the specified font. Always returns false.

a, r, g, b = colorToRGB(key)

Gets the r, g, b values of a color. The color can be a hexadecimal RGB specification or a symbolic name.

image, width, height, transparency = Display.createPixmap(picture)

Creates a pixmap object from a picture file or from a table. See Visual.createPixmap().

h, up, ut = getFontAttrs(font)

Returns the font attributes height, underline position and underline thickness.

image, width, height, transparency = Display.getPaint(imgspec)

Gets a paint object from a specifier, either by loading it from the filesystem, generating it, or by retrieving it from the cache. To resolve symbolic color names, a display instance must be given.

Display.getTime()

Gets the system time.

Display.openDrawable()

Open a drawable

font = openFont(fontspec[, size[, attr]])

Opens a font, cached, and with complex name resolution and fallbacks. For a discussion of the format see Text. The optional size and attr arguments allow to override their respective values in the fontspec argument.

Element (v20.2)

OVERVIEW

ClassOverview : Class / Object / Element

This class implements the connection to a global environment and the registration by Id.

ATTRIBUTES
  • Application [G] (Application)

    The Application the element is registered with. This attribute is set during Element:setup().

  • Class [ISG] (string)

    The name of the element's style class, which can be referenced in a style sheet. Multiple classes can be specified by separating them with spaces, e.g. "button knob warn". Setting this attribute invokes the Element:onSetClass() method.

  • Id [IG] (string)

    An unique Id identifying the element. If present, this Id will be registered with the Application during Element:setup().

  • Parent [G] (object)

    Parent object of the element. This attribute is set during Element:connect().

  • Properties [G] (table)

    A table of properties, resulting from element and user style classes, overlaid with individual and direct formattings, and finally from hardcoded element properties. This table is initialized in Element:decodeProperties().

  • Style [ISG] (string)

    Direct style formattings of the element, overriding class-wide formattings in a style sheet. Example: 

    "background-color: #880000; color: #ffff00"

    Setting this attribute invokes the Element:onSetStyle() method.

  • Window [G] (Window)

    The Window the element is registered with. This attribute is set during Element:setup().

IMPLEMENTS
OVERRIDES

Element:cleanup()

This function unlinks the element from its Application and Window.

success = Element:connect(parent)

Attempts to connect the element to the given parent element; returns a boolean indicating whether the connection succeeded.

Element:decodeProperties(stylesheets)

This function decodes the element's style properties and places them in the Properties table.

Element:disconnect()

Disconnects the element from its parent.

ret1, ... = Element:getAttr(attribute, ...)

This function gets a named attribute from an element, returning nil if the attribute is unknown.

Element:getById(id)

Gets the element with the specified id, that was previously registered with the Application. This function is a shortcut for Application:getById(), applied to self.Application.

pclass = Element:getPseudoClass()

Get an element's pseudo class

Element:onSetClass()

This method is invoked when the Class attribute has changed. The implementation in the Element class invokes Element:onSetStyle().

Element:onSetStyle()

This method is invoked when the Style attribute has changed.

Element:setup(app, window)

This function attaches an element to the specified Application and Window, and registers the element's Id (if any) at the application.

Family (v2.7)

OVERVIEW

ClassOverview : Class / Object / Family

This class implements a container for child objects.

ATTRIBUTES
  • Children [IG] (table)

    Array of child objects

FUNCTIONS

success = addMember(child[, pos])

Invokes the child's connect() method to check for its ability to integrate into the family, and if successful, inserts it into the Family's list of children. Optionally, the child is inserted into the list at the specified position.

success = remMember(child)

Looks up child in the family's list of children, and if it can be found, invokes its disconnect() method and removes it from the list.

FloatText (v22.1)

OVERVIEW

ClassOverview : Class / Object / Element / Area / FloatText

This class implements a scrollable display of text. An object of this class is normally the immediate child of a Canvas.

ATTRIBUTES
  • FGPen [IG] (userdata)

    Pen for rendering the text. This attribute is controllable via the color style property.

  • Font [IG] (string)

    Font specifier; see Text for a format description. This attribute is controllable via the font style property.

  • Preformatted [IG] (boolean)

    Boolean, indicating that the text is already formatted and should not be reformatted to fit the element's width.

  • Text [ISG]] (string)

    The text to be displayed

IMPLEMENTS
STYLE PROPERTIES
color controls the FloatText.FGPen attribute
font controls the FloatText.Font attribute
OVERRIDES

appendLine(text[, movetail])

Append a line of text; if the optional boolean movetail is true, the visible area of the element is moved towards the end of the text.

onSetText()

Handler called when a new Text is set.

Frame (v24.2)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame

This class implements an element's borders. The default border class handles up to three sub borders:

  • The main border is the innermost of the three sub borders. It is used to render the primary border style, which can be inset, outset, ridge, groove, or solid. This border has priority over the other two.
  • The rim border separates the two other borders and may give the composition a more contrastful look. This border has the lowest priority.
  • The focus border (in addition to the element's focus highlighting style) can be used to visualize that the element is currently receiving the input. This is the outermost of the three sub borders. When the element is in unfocused state, this border often appears in the same color as the surrounding group, making it indistinguishable from the surrounding background.

Border classes do not have to implement all sub borders; these properties are all handled by the default border class internally, and more (and other) sub borders and properties may be defined and implemented in the future (or in other border classes). As the Frame class has no notion of sub borders, their respective widths are subtracted from the Element's total border width, leaving only the remaining width for the main border.

ATTRIBUTES
  • BorderRegion [G] (Region)

    Region object holding the outline of the element's border

  • Legend [IG] (string)

    Border legend text

STYLE PROPERTIES
border-bottom-color controls the default border class
border-bottom-width controls Frame.Border
border-class controls Frame.BorderClass
border-color controls the default border class
border-focus-color controls the default border class
border-focus-width controls the default border class
border-left-color controls the default border class
border-left-width controls Frame.Border
border-legend-font controls the default border class
border-legend-align controls the default border class
border-right-color controls the default border class
border-right-width controls Frame.Border
border-rim-color controls the default border class
border-rim-width controls the default border class
border-style controls the default border class
border-top-color controls the default border class
border-top-width controls Frame.Border
border-width controls Frame.Border
IMPLEMENTS
OVERRIDES

Gauge (v17.5)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Numeric / Gauge

This class implements a gauge for the visualization of numerical values.

OVERRIDES

Group (v35.2)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Group

This class implements a container for child elements and various layouting options.

ATTRIBUTES
  • Children [IG] (table)

    A table of the object's children

  • Columns [IG] (number)

    Grid width, in number of elements [Default: 1, not a grid]

  • FreeRegion [G] (Region)

    Region inside the group that is not covered by child elements

  • Layout [IG] (string or Layout)

    The name of a layouter class (or a Layouter object) used for layouting the element's children. Default: "default"

  • Orientation [IG] (string)

    Orientation of the group; can be

    • "horizontal" - The elements are layouted horizontally
    • "vertical" - The elements are layouted vertically

    Default: "horizontal"

  • Rows [IG] (number)

    Grid height, in number of elements. [Default: 1, not a grid]

  • SameSize [IG] (boolean, "width", "height")

    true indicates that the same width and height should be reserved for all elements in the group; the keywords "width" and "height" specify that only the same width or height should be reserved, respectively. Default: false

IMPLEMENTS
OVERRIDES

Handle (v7.2)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Handle

Implements a handle that can be dragged along the axis of the Group's orientation. It reassigns Weights to its flanking elements.

OVERRIDES

ImageWidget (v15.2)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / ImageWidget

This class implements widgets with an image. Images are instances of the Image class, which handles pixmaps and simple vector graphics. They can be obtained by ui.loadImage(), ui.getStockImage(), or by directly instantiating the Image class or derivations thereof.

ATTRIBUTES
  • Image [ISG] (image object)
IMPLEMENTS
OVERRIDES

onSetImage()

This handler is invoked when the element's Image attribute has changed.

Input (v4.8)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Group / ScrollGroup / Input

Text input class

ATTRIBUTES
STYLE PROPERTIES
IMPLEMENTS
OVERRIDES

Layout (v1.1)

OVERVIEW

ClassOverview : Class / Layout

A layouter implements a group's layouting strategy. The "default" layouter implements a dynamic, scalable layout, which adapts to the free space available to the group.

IMPLEMENTS

minw, minh, maxw, maxh = Layout:askMinMax(group, minw, minh, maxw, maxh)

This function queries the specified Group for its size requirements.

Layout:layout(group, x0, y0, x1, y1[, markdamage])

Layouts the Group into the specified rectangle and calculates the new sizes and positions of all of its children. The optional boolean markdamage is passed to subsequent invocations of child:layout(). This function will also call the punch() method on each child for subtracting their new outlines from the group's FreeRegion.

Lister (v32.1)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Text / Lister

This class implements a scrollable list or table. Each item in the list is a table consisting of the following elements: 

{ { "column1", "column2", ... }, userdata, selected, ... }

Description:

  • entry[1] is a table containing the text of each column;
  • entry[2] is a userdata field which can be used at will;
  • entry[3] is a boolean indicating that the line is selected.

The following fields are reserved for internal use by the Lister; you should never rely on their contents or modify them.

ATTRIBUTES
  • AlignColumn [IG] (number)

    A column number to align the right edge of the list to. [Default: unspecified]

  • AlignElement [IG] (Object)

    The object determining the right edge of the list, which is an information needed for the AlignColumn attribute. By default, the Lister's parent Canvas is used, but by use of this attribute it is possible to align the Lister to something else.

  • BGAlt [IG] (userdata)

    A colored pen for painting the background of alternating lines

  • ColumnPadding [IG] (number)

    The padding between columns, in pixels. By default, the Lister's Font is used to determine a reasonable offset.

  • CursorBorderClass [IG] (string)

    Name of the border class used to implement this element's cursor border. Default: "default"

  • CursorLine [ISG] (number)

    The line number of the Lister's cursor; this value may be 0, in which case the cursor is invisible. Changing this value will invoke the Lister:onSetCursor() method.

  • HeaderGroup [IG] (Group)

    A group of elements used for the table header. The Lister may take these elements into account for determining the initial column widths.

  • ListObject [IG] (List)

    The List object the Lister operates on; if none is specified, the Lister creates an empty one.

  • NumSelectedLines [G] (number)

    The number of lines currently selected.

  • SelectedLines [G] (table)

    This attribute is a (sparse) table containing the numbers of selected lines in the list. Use pairs() to iterate it. See also Lister:getSelectedLines() for retrieving a numerically indexed list.

  • SelectedLine [ISG] (number)

    The Lister's current selected line; this value reflects only the line that was most recently selected or unselected - for locating all currently selected lines, you will also need the SelectedLines attribute. Setting this value will invoke the Lister:onSelectLine() method.

  • SelectMode [IG] (string)

    The Lister's selection mode, which can be "none", "single", or "multi".

IMPLEMENTS
STYLE PROPERTIES
  • background-color2
OVERRIDES

addItem(item[, line[, quick]])

Adds an item to the list. If line is unspecified, the entry is added at the end of the list. The boolean quick indicates that the list should not be relayouted and repainted. (For relayouting and repainting the list after mass addition, see also Lister:repaint().)

changeItem(item, line[, quick])

Overwrites the item at the specified line in the list. The boolean quick indicates that the list should not be relayouted and repainted. For relayouting and repainting the list after mass changes, see also Lister:repaint().

changeSelection(mode)

Changes the selection of the entire list; modes supported are:

  • "none": marks all lines as unselected

clear()

Remove all items from the list.

damageLine(lnr)

Marks the specified line for repainting.

getItem(line)

Returns the item at the specified line.

getN()

Returns the number of lines in the list.

getSelectedLines([mode])

Returns a table of all selected entries, sorted by (by default) their line number. Currently defined modes are "ascending" or "descending". Default: "ascending"

onDblClick()

overrides

onSelectLine()

This method is invoked when the SelectedLine attribute is set.

onSetCursor()

This method is invoked when the CursorLine attribute has changed.

remItem(line[, quick])

Removes the item from the list at the specified line. The boolean quick indicates that the list should not be relayouted and repainted. (For relayouting and repainting the list after mass removal, see also Lister:repaint().)

repaint()

Relayouts and repaints the list.

setList(listobject)

Sets a new List object, and relayouts and repaints the list.

ListView (v6.4)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Group / ListView

This class implements a Group containing a ScrollGroup and optionally a group of column headers; its main purpose is to automate the somewhat complicated setup of multi-column lists with headers, but it can be used for single-column lists and lists without column headers as well.

ATTRIBUTES
  • Headers [I] (table)

    An array of strings containing the captions of column headers. [Default: unspecified]

  • HSliderMode [I] (string)

    This attribute is passed on the ScrollGroup - see there.

  • VSliderMode [I] (string)

    This attribute is passed on the ScrollGroup - see there.

MenuItem (v11.1)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Text / PopItem / MenuItem

This class implements basic, recursive items for window and popup menus with a typical menu look; in particular, it displays the PopItem's Shortcut string and an arrow to indicate the presence of a sub menu.

OVERRIDES

Numeric (v5.2)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Numeric

This class implements the management of numerical values. Without further specialization it has hardly any real-life use and may be considered an abstract class. See also Gauge and Slider for some of its child classes.

ATTRIBUTES
  • Default [IG] (number)

    The default for Value, which can be revoked using the Numeric:reset() method.

  • Increment [ISG] (number)

    Default increase/decrease step value [Default: 1]

  • Max [ISG] (number)

    Maximum acceptable Value. Setting this value invokes the Numeric:onSetMax() method.

  • Min [ISG] (number)

    Minimum acceptable Value. Setting this value invokes the Numeric:onSetMin() method.

  • Value [ISG] (number)

    The current value represented by this class. Setting this value causes the Numeric:onSetValue() method to be invoked.

IMPLEMENTS
OVERRIDES

decrease([delta])

Decrease Value by the specified delta. If delta is omitted, the Increment attribute is used in its place.

increase([delta])

Increment Value by the specified delta. If delta is omitted, the Increment attribute is used in its place.

onSetMax()

This handler is invoked when the Numeric's Max attribute has changed.

onSetMin()

This handler is invoked when the Numeric's Min attribute has changed.

onSetValue()

This handler is invoked when the Numeric's Value attribute has changed.

reset()

Reset Value to is Default value.

PageGroup (v19.7)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Group / PageGroup

Implements a group whose children are layouted in individual pages.

ATTRIBUTES
  • PageCaptions [IG] (table)

    An array of strings containing captions for each page in the group. If false, no page captions will be displayed. [Default: false]

  • PageNumber [ISG] (number)

    Number of the page that is initially selected. [Default: 1] Setting this attribute invokes the PageGroup:onSetPageNumber() method.

IMPLEMENTS
OVERRIDES

disablePage(pagenum, onoff)

This function allows to disable or re-enable a page button identified by pagenum.

onSetPageNumber()

This method is invoked when the element's PageNumber attribute has changed.

PopItem (v26.2)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Text / PopItem

This class provides an anchorage for popups. This also works recursively, i.e. elements of the PopItem class may contain other PopItems as their children. The most notable child class of the PopItem is the MenuItem.

ATTRIBUTES
  • Children [I] (table)

    Array of child objects - will be connected to the application while the popup is open.

  • Shortcut [IG] (string)

    Keyboard shortcut for the object; unlike Widget.KeyCode, this shortcut is also enabled while the object is invisible. By convention, only combinations with a qualifier should be used here, e.g. "Alt+C", "Shift+Ctrl+Q". Qualifiers are separated by "+" and must precede the key. Valid qualifiers are:

    • "Alt", "LAlt", "RAlt"
    • "Shift", "LShift", "RShift"
    • "Ctrl", "LCtrl", "RCtrl"
    • "IgnoreCase" - pseudo-qualifier; ignores the Shift key
    • "IgnoreAltShift" - pseudo-qualifier, ignores the Shift and Alt keys

    Alias names for keys are

    • "F1" ... "F12" (function keys),
    • "Left", "Right", "Up", "Down" (cursor keys)
    • "BckSpc", "Tab", "Esc", "Insert", "Overwrite", "PageUp", "PageDown", "Pos1", "End", "Print", "Scroll", and "Pause"}}.
OVERRIDES

PopList (v13.6)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Text / PopItem / PopList

This class is a specialization of a PopItem allowing the user to choose an item from a list.

ATTRIBUTES
  • ListObject [IG] (List)

    List object

  • SelectedLine [ISG] (number)

    Number of the selected entry, or 0 if none is selected. Changing this attribute invokes the PopList:onSelectLine() method.

IMPLEMENTS
OVERRIDES

onSelectLine()

This method is invoked when the SelectedLine attribute has changed.

setList(listobject)

Sets a new List object.

PopupWindow (v5.3)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Group / Window / PopupWindow

This class specializes a Window for the use by a PopItem.

OVERRIDES

RadioButton (v6.2)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Text / CheckMark / RadioButton

Specialization of a CheckMark to implement mutually exclusive 'radio buttons'.

OVERRIDES

ScrollBar (v15.4)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Group / ScrollBar

Implements a group containing a Slider and arrow buttons.

ATTRIBUTES
  • AcceptFocus [IG] (boolean)

    If false, the elements inside the scrollbar (slider, arrows) abstain from receiving the input focus, which means that they can only be operated with the mouse. Default: true

  • Max [ISG] (number)

    The maximum value the slider can accept. Setting this value invokes the ScrollBar:onSetMax() method.

  • Min [ISG] (number)

    The minimum value the slider can accept. Setting this value invokes the ScrollBar:onSetMin() method.

  • Orientation [IG] (string)

    The orientation of the scrollbar, which can be "horizontal" or "vertical"

  • Range [ISG] (number)

    The range of the slider, i.e. the size it represents. Setting this value invokes the ScrollBar:onSetRange() method.

  • Step [IG] (boolean or number)

    See tek.ui.class.slider.

  • Value [ISG] (number)

    The value of the slider. Setting this value invokes the ScrollBar:onSetValue() method.

IMPLEMENTS
OVERRIDES

onSetMax()

This handler is invoked when the ScrollBar's Max attribute has changed. See also Numeric:onSetMax().

onSetMin()

This handler is invoked when the ScrollBar's Min attribute has changed. See also Numeric:onSetMin().

onSetRange()

This handler is invoked when the ScrollBar's Range attribute has changed. See also Slider:onSetRange().

onSetValue()

This handler is invoked when the ScrollBar's Value attribute has changed. See also Numeric:onSetValue().

ScrollGroup (v19.3)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Group / ScrollGroup

This class implements a group containing a scrollable container and accompanying elements such as horizontal and vertical ScrollBars.

ATTRIBUTES
  • AcceptFocus [IG] (boolean)

    This attribute is passed to the scrollbar elements inside the scroll group. See ScrollBar

  • Child [IG] (Canvas)

    Specifies the Canvas which encapsulates the scrollable area and children.

  • HSliderMode [IG] (string)

    Specifies when the horizontal ScrollBar should be visible:

    • "on" - The horizontal scrollbar is displayed
    • "off" - The horizontal scrollbar is not displayed
    • "auto" - The horizontal scrollbar is displayed when the Lister is wider than the currently visible area.

    Note: The use of the "auto" mode is currently (v8.0) discouraged.

  • VSliderMode [IG] (string)

    Specifies when the vertical ScrollBar should be visible:

    • "on" - The vertical scrollbar is displayed
    • "off" - The vertical scrollbar is not displayed
    • "auto" - The vertical scrollbar is displayed when the Lister is taller than the currently visible area.

    Note: The use of the "auto" mode is currently (v8.0) discouraged.

OVERRIDES

Sizeable (v11.4)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Sizeable

This class implements the ability to resize an element without the need to repaint it completely. Its parent must be a Canvas element.

IMPLEMENTS
OVERRIDES

Sizeable:resize(dx, dy, insx, insy)

Resize the element by dx on the x axis and dy on the y axis, inserting or removing space at insx on the x axis and insy on the y axis.

Slider (v27.1)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Numeric / Slider

This class implements a slider for adjusting a numerical value.

ATTRIBUTES
  • AutoCapture [ISG] (boolean)

    If true and the slider is receiving the focus, it reacts on keyboard shortcuts instantly; otherwise, it must be selected first (and deselected afterwards). Default: true

  • Child [IG] (Widget)

    A Widget object for being used as the slider's knob. By default, a knob widget of the style class "knob" is created internally.

  • Kind [IG] (string)

    Kind of the slider:

    • "scrollbar" - for scrollbars. Sets the additional style class "knob-scrollbar".
    • "number" - for adjusting numbers. Sets the additional style class "knob-number".

    Default: false, the kind is unspecified.

  • Orientation [IG] (string)

    Orientation of the slider, which can be "horizontal" or "vertical". Default: "horizontal"

  • Range [ISG] (number)

    The size of the slider, i.e. the range that it represents. Setting this value invokes the Slider:onSetRange() method.

  • Step [ISG] (boolean or number)

    If true or 1, integer steps are enforced. If a number, steps of that size are enforced. If false, the default, the slider knob moves continuously.

IMPLEMENTS

OVERRIDES:

Slider:onSetRange()

This handler is invoked when the Range attribute has changed.

Spacer (v2.3)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Spacer

This class implements a separator that helps to arrange elements in a group.

OVERRIDES

Text (v29.1)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Text

This class implements widgets with text.

ATTRIBUTES
  • KeepMinHeight [I] (boolean)

    After the initial size calculation, keep the minimal height of the element and do not rethink the layout in response to a possible new minimal height (e.g. resulting from a newly set text). The boolean (default false) will be translated to the flag FL_KEEPMINHEIGHT, and is meaningless after initialization.

  • KeepMinWidth [I] (boolean)

    Translates to the flag FL_KEEPMINWIDTH. See also KeepMinHeight, above.

  • Text [ISG] (string)

    The text that will be displayed on the element; it may span multiple lines (see also Text:makeTextRecords()). Setting this attribute invokes the Text:onSetText() method.

STYLE PROPERTIES
color-disabled Secondary color for text in disabled state
font Font specification, see below
text-align "left", "center", "right"
vertical-align "top", "center", "bottom"
FONT SPECIFICATION

A font is specified in the form 

"[fontname1,fontname2,...][:][size]"

Font names, if specified, will be probed in the order of their occurrence; the first font that can be opened will be used. For the font name, the following predefined names are supported:

  • ui-main (or an empty string) - The default font, e.g. for buttons
  • ui-fixed - The default fixed font
  • ui-menu - The default menu font
  • ui-small - The default small font, e.g. for group captions
  • ui-x-small - The default 'extra small' font
  • ui-xx-small - The default 'extra extra small' font
  • ui-large - The default 'large' font
  • ui-x-large - The default 'extra large' font
  • ui-xx-large - The default 'extra extra large' font

If no font name is specified, the main font will be used. The size specification (in pixels) is optional; if absent, the respective font's default size will be used.

Additional hints can be passed alongside with the fontname by appending a slash and option letters, which must be in alphabetical order. Currently, the letter b will be used as a hint for boldface, and i for italic. For example, the string "ui-main/bi" would request the default main font in bold italic.

IMPLEMENTS
OVERRIDES

width, height = getTextSize([textrecord])

This function calculates the total width and height required by the object's text records. Optionally, it can be passed a table of text records which are to be evaluated.

makeTextRecords(text)

This function parses the given text, breaks it along the encountered newline characters into single-line records, and places the resulting table in the element's TextRecords field. Each record has the form 

{ [1]=text, [2]=font, [3]=align-horizontal, [4]=align-vertical,
  [5]=margin-left, [6]=margin-right, [7]=margin-top,
  [8]=margin-bottom, [9]=font-height, [10]=text-width }

More undocumented fields may follow at higher indices. font is taken from opening the font specified in the object's Font attribute, which also determines font-height and is used for calculating the text-width (in pixels). The alignment parameters are taken from the object's TextHAlign and TextVAlign attributes, respectively.

onSetText()

This handler is invoked when the element's Text attribute has changed.

TextEdit (v21.1)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Sizeable / TextEdit

Text editor class

ATTRIBUTES
STYLE PROPERTIES
IMPLEMENTS
OVERRIDES

added = addChar(utf8)

Adds an utf8 character to the text. By adding a newline ("\n") or CR ("\r"), a new line is produced, "\127" (DEL) deletes the character under the cursor, "\008" performs a backspace.

Widget (v31.1)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget

This class implements interactions with the user.

ATTRIBUTES
  • Active [SG] (boolean)

    The Widget's activation state. While true, the position of the pointing device is being verified (which is also reflected by the Hilite attribute, see below). When the Active state variable changes, the Widget's behavior depends on its Mode attribute (see below):

    • in button mode, the Selected attribute is set to the value of the Hilite attribute. When the Selected state changes, the Pressed attribute is set to the value of the Active attribute.
    • in toggle mode, the Selected attribute is inverted logically, and the Pressed attribute is set to true.
    • in touch mode, the Selected and Pressed attributes are set to true, if the Widget was not selected already.

    Changing this attribute invokes the Widget:onActivate() method.

  • DblClick [SG] (boolean)

    Signifies that the element is or has been double-clicked; it is set to true when the element was double-clicked and is still being held, and false when the second press has been released. Changes to this attribute cause the invocation of the Widget:onDblClick() method.

  • FGPen [IG] (color specification)

    A color specification for rendering the foreground details of the element. This attribute is controllable via the color style property.

  • Hold [SG] (boolean)

    Signifies that the element is being pressed for an extended period. While being held, the value is repeatedly set to true in intervals of n/50 seconds, with n taken from the Window's HoldTickRepeat attribute. When the element is released, this attribute is set to false. Changes to this attribute cause the invocation of the Widget:onHold() method.

  • InitialFocus [I] (boolean)

    Specifies that the element should receive the focus initially. If true, the element will set its Focus attribute to true upon invocation of the show method. The boolean will be translated to the flag FL_INITIALFOCUS, and is meaningless after initialization.

  • KeyCode [IG] (string or boolean)

    If set, a keyboard equivalent for activating the element. See PopItem for a discussion of denoting keyboard qualifiers. The Text class allows setting this attribute to true, in which case the element's Text will be examined during setup for an initiatory character (by default an underscore), and if found, the KeyCode attribute will be replaced by the character following this marker.

  • Mode [ISG] (string)

    The element's interaction mode:

    • "inert": The element does not react on input
    • "touch": The element does not rebound and keeps its Selected state; it cannot be unselected by the user and always submits true for the Pressed and Selected attributes.
    • "toggle": The element does not rebound immediately and keeps its Selected state until the next activation.
    • "button": The element rebounds when the pointing device over it is being released, or when it is no longer hovering it.

    See also the Active attribute.

  • Pressed [SG] (boolean)

    Signifies that a button was pressed or released. Changes to this state variable invoke Widget:onPress().

STYLE PROPERTIES
color controls the Widget.FGPen attribute
effect-class name of an class for rendering an overlay effect
effect-color controls the ripple effect hook
effect-color2 controls the ripple effect hook
effect-kind controls the ripple effect hook
effect-maxnum controls the ripple effect hook
effect-maxnum2 controls the ripple effect hook
effect-orientation controls the ripple effect hook
effect-padding controls the ripple effect hook
effect-ratio controls the ripple effect hook
effect-ratio2 controls the ripple effect hook

A possible name for the effect-class property is "ripple". As its name suggests, it can paint various ripple effects (e.g. for slider knobs and bar handles). Effect hooks are loaded from tek.ui.hook and may define their own style properties.

STYLE PSEUDO CLASSES
active for elements in active state
disabled for elements in disabled state
focus for elements that have the input focus
hover for elements that are being hovered by the mouse
IMPLEMENTS
OVERRIDES

Widget:activate([mode])

Activates this or an element's "next" element. mode can be "focus" (the default), "next", or "click".

Widget:onActivate()

This method is invoked when the Active attribute has changed.

Widget:onClick()

This method is called when the Pressed attribute changes from true to false, indicating that the pointing device has been released over the element.

Widget:onDblClick()

This method is invoked when the DblClick attribute has changed. It is true when the double click was initiated and the mouse button is still held, and false when it has been released.

Widget:onDisable()

This method is invoked when the Disabled attribute has changed. The Disabled attribute is defined in the Area class.

Widget:onFocus()

This method is invoked when the Focus attribute has changed. The Focus attribute is defined in the Area class.

Widget:onHilite()

This handler is called when the Hilite attribute has changed. The Hilite attribute is defined in the Area class.

Widget:onHold()

This method is invoked when the Hold attribute has changed.

Widget:onPress()

This handler is called when the Pressed attribute has changed.

Widget:onSelect()

This method is invoked when the Selected attribute has changed. The Selected attribute is defined in the Area class.

Window (v46.5)

OVERVIEW

ClassOverview : Class / Object / Element / Area / Frame / Widget / Group / Window

This class implements a Group which fills up a window on the Display.

ATTRIBUTES
  • Center [IG] (boolean)

    Instructs the Window to open centered.

  • DblClickJitter [IG] (number)

    Maximum sum of squared pixel deltas (dx² + dy²) between mouse positions to be tolerated for a double click. The default is 70. Large touchscreens require a much larger value.

  • DblClickTimeout [IG] (number)

    Maximum number of microseconds between events to be recognized as a double click. Default: 32000. Use a larger value for touchscreens.

  • FullScreen [IG] (boolean)

    Instructs the Window to open borderless and in fullscreen mode.

  • HideOnEscape [IG] (boolean)

    Instructs the window to invoke the Window:onHide() method when the Escape key is pressed. Default: false

  • Left [IG] (number)

    The window's left offset on the display, in pixels

  • Modal [IG] (boolean)

    Instructs all other windows to reject input while this window is open.

  • MouseX [G] (number)
  • MouseY [G] (number)

    The current window coordinates of the pointing device.

  • RootWindow [IG] (boolean)

    Hint that the window can be used as the background or main window that determines the size of the screen or display resolution.

  • Status [ISG] (string)

    Status of the Window, which can be:

    • "initializing" - The window is initializing
    • "hide" - The window is hidden or about to hide; if you initialize the Window with this value, it will be created in hidden state.
    • "opening" - The window is about to open.
    • "show" - The window is shown.
    • "closing" - The Window is about to hide.

    Changing this attribute invokes the Window:onChangeStatus() method.

  • Title [IG] (string)

    The window's title

  • Top [IG] (number)

    The window's top offset on the display, in pixels

IMPLEMENTS
OVERRIDES

addInputHandler(msgtype, object, function)

Adds an object and a function to the window's chain of handlers for input of the specified type. Multiple input types can be handled by one handler by logically or'ing message types. Input handlers are invoked as follows: 

message = function(object, message)

The handler is expected to return the message, which will in turn pass it on to the next handler in the window's chain.

addInterval()

Adds an interval timer to the window, which will furtheron generate MSG_INTERVAL messages 50 times per second. These messages cause a considerable load to the application, therefore each call to this function should be paired with a matching call to Window:remInterval(), which will cause the interval timer to stop when no clients are needing it anymore.

dblclick = checkDblClickTime(as, au, bs, bu)

Check if the two given times (first a, second b) are within the doubleclick interval. Each time is specified in seconds (s) and microseconds (u). Returns true if the two times are indicative of a double click.

clickElement(element)

This function performs a simulated click on the specified element; if element is a string, it will be looked up using Application:getById(). This function is actually a shorthand for Window:setHiliteElement(), followed by Window:setActiveElement() twice (first to enable, then to disable it).

onChangeStatus()

This method is invoked when the Window's Status has changed.

onHide()

This handler is invoked when the window's close button is clicked (or the Escape key is pressed and the HideOnEscape flag is set). The Window class' implementation of this handler is to hide the window by setting the Status attribute to "hide". When the last window is closed, the application is closed down.

postMsg(msg)

This function adds an user message to the Window's message queue.

remInputHandler(msgtype, object, func)

Removes an input handler that was previously registered with the window using Window:addInputHandler().

remInterval()

Decreases the use counter for interval messages and stops sending interval messages to the window when called by the last client that has previously requested an interval timer using Window:addInterval().

setActiveElement(element)

Sets/unsets the element which is currently active (or 'in use'). If element is nil, the currently active element will be deactivated.

setDblClickElement(element)

Sets/unsets the element which is candidate for double click detection. If the element is set twice in a sufficiently short period of time and the pointing device did not move too much since the first event, the double click is triggered by notifying the DblClick attribute in the element. See also Widget for further information.

setFocusElement(element)

Sets/unsets the element which is marked for receiving the keyboard input.

setHiliteElement(element)

Sets/unsets the element which is being hovered by the mouse pointer.

setMovingElement(element)

Sets/unsets the element which is being moved around by the user.

DefaultLayout (v9.2)

OVERVIEW

ClassOverview : Class / Layout / DefaultLayout

This class implements a Group's default layouting strategy. The standard strategy is to adapt a Group's contents dynamically to the free space available. It takes into account an element's HAlign, VAlign, Width, and Height attributes.

OVERRIDES

FixedLayout (v2.2)

OVERVIEW

ClassOverview : Class / Layout / FixedLayout

This class implements a Group's fixed layouting strategy. Using the fixed layouter, the size and position of individual elements in a group is predetermined by the contents of their fixed style property, with the coordinates of the rectangle in the order left, top, right, bottom, e.g.: 

ui.Window:new {
  Layout = "fixed", Width = 400, Height = 400,
  Children = {
    ui.Button:new {
      Style = "fixed: 10 280 60 320"
    }
  }
}
OVERRIDES

Document generated on Wed Feb 4 22:52:39 2015 using gendoc.lua version 1.5