tekUI GUI Toolkit

Version 0.8f

Class Reference Manual


Class Overview

Modules


Class (v6.3)

LINEAGE

ClassOverview : Class

OVERVIEW

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

IMPLEMENTS

is_descendant = object:checkDescend(class)

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

Class.checkDescend(Button, Area)

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

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

LINEAGE

ClassOverview : Class / List

OVERVIEW

This class implements a list container.

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

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

LINEAGE

ClassOverview : Class / Markup

OVERVIEW

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

LINEAGE

ClassOverview : Class / Object

OVERVIEW

This class implements notifications.

ATTRIBUTES:

  • Notifications [I] (table)

    Initial set of notifications. Static initialization of notifications has this form:

    Notifications =
    {
      ["attribute-name1"] =
      {
        [value1] =
        {
          action1,
          action2,
          ...
        }
        [value2] = ...
      },
      ["attribute-name2"] = ...
    }
    

    Refer to Object:addNotify() for the possible placeholders for values and a description of the action data structure.

IMPLEMENTS
OVERRIDES

Object:addNotify(attr, val, dest[, pos])

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. The ui.NOTIFY_ALWAYS placeholder is supported for reacting on any change of the value. dest 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:

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

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

method(object, arg1, ...)

The optional pos argument allows for insertion at the specified position in the list of notifications. By default, notifications are added at the end, and the only reasonable value for pos is 1. 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 = Object.init(object)

This function is called during Object.new() before passing control to superclass.new(); by convention, new() is used to claim resources (e.g. to create tables), whereas the init() function is used to initialize them. Calling init() separately from new() can be sensible for reinitializing and reusing objects.


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

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


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


UTF8String (v2.2)

LINEAGE

ClassOverview : Class / UTF8String

OVERVIEW

This class supports the manipulation of UTF-8 encoded strings.

IMPLEMENTS
OVERRIDES

UTF8String:byte(i[, j])

Equivalent to string.byte(), except for that it may return characters in the Unicode range.


UTF8String.char(...)

Equivalent to string.char(), except for that it accepts character codes in the Unicode range.


UTF8String:erase(i[, j])

Erases the characters at the positions from i to j. The semantics for the range are the same as for UTF8String:sub().


string = UTF8String:get()

Returns the string in UTF-8 encoded form.


UTF8String:insert(string[, position])

Inserts the UTF-8 encoded string at the specified position to the string object. If position is absent, the string is added to the end.


len = UTF8String:len()

Returns the length of the string, in characters.


object = UTF8String.new(class, string)

Creates a string object from an (already UTF-8 encoded) regular string.


UTF8String:overwrite(s[, pos])

Overwrites the string object with the specified (already UTF-8 encoded) string, starting a the given position.


UTF8String:set(s)

Initializes the string object with a new, UTF-8 encoded string.


substring = UTF8String:sub(i[, j])

Returns an UTF-8 encoded substring. The semantics are the same as for string.sub().


args (v2.0)

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 a) the expected datatype, b) if the argument is mandatory and c) 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 would require one or more arguments to satisfy SOURCE, and exactly one argument to satisfy DEST. Neither can be omitted. Either -d or DEST must precede a value to be accepted as the second argument. Examples:

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

TODO

Backslashes for escaping quotes, spaces and themselves


res, msg = 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 (see tek.lib.args for details), 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 (v4.3)

OVERVIEW

Debug library - implements debug output and debug levels:

2 TRACE used for tracking bugs
4 INFO informational messages
5 WARN something unexpected happened
10 ERROR something went wrong, e.g. resource unavailable
20 FAIL something went wrong that can't be coped with

The default debug level is 5 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

console()

Enter the debug console.


dump(table)

Dump a table as Lua source using out as the output stream. Cyclic references are silently dropped.


error(msg, ...)

Prints formatted debug info with ERROR level


execute(lvl, func, ...)

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


fail(msg, ...)

Prints formatted debug info with FAIL level


info(msg, ...)

Prints formatted debug info with INFO level


print(lvl, msg, ...)

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


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.


trace(msg, ...)

Prints formatted debug info with TRACE level


warn(msg, ...)

Prints formatted debug info with WARN level


Region (v7.0)

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:checkOverlap(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.


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 = 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(region)

Logical ors another region to a region


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

Overwrites an existing region with the specified coordinates.


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


ui (v24.0)

OVERVIEW

This is the base library of the user interface toolkit. It implements a class loader and provides a central place for various toolkit constants. 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):

ui = require "tek.ui"
ui.Application:new { ...
FUNCTIONS
CONSTANTS
  • NOTIFY_ALWAYS - see Object
  • NOTIFY_VALUE - see Object
  • NOTIFY_TOGGLE - see Object
  • NOTIFY_FORMAT - see Object
  • NOTIFY_SELF - see Object
  • NOTIFY_OLDVALUE - see Object
  • NOTIFY_FUNCTION - see Object
  • NOTIFY_WINDOW - see Object - defined in tek.ui.class.element
  • NOTIFY_APPLICATION - see Object - defined in tek.ui.class.element
  • NOTIFY_ID - see Object - defined in tek.ui.class.element
  • NOTIFY_COROUTINE - see Object - defined in tek.ui.class.element
  • HUGE - use this value to express a "huge" spatial extent
  • NULLOFFS - table { 0, 0, 0, 0 } (read-only)
  • MSG_CLOSE - Input message type: Window closed
  • MSG_FOCUS - Window activated/deactivated
  • MSG_NEWSIZE - Window resized
  • MSG_REFRESH - Window needs (partial) refresh
  • MSG_MOUSEOVER - Mouse pointer entered/left window
  • MSG_KEYDOWN - Key pressed down
  • MSG_MOUSEMOVE - Mouse pointer moved
  • MSG_MOUSEBUTTON - Mousebutton pressed/released
  • MSG_INTERVAL - Timer interval message (default: 50Hz)
  • MSG_KEYUP - Key released
  • MSG_USER - User message

hookobject = createHook(domain, classname, parent[, object])

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


false = destroyHook([hookobject])

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


extractKeyCode(string[, shortcutmark])

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


catalog = 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 otherwise non-existent keys are used to access the resulting catalog, the key will be mirrored 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 = getStockImage(name, ...)

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


class = loadClass(domain, classname)

Loads a class of the specified domain and the given classname. Returns the loaded class or false if the class or domain name is unknown or if an error was detected in the module. Possible values for domain, as currently defined, are:


imgobject = loadImage(name)

Loads an image from a file or retrieves it from the image cache. Note that currently only the PPM file format is recognized.


properties, msg = loadStyleSheet(name)

This function loads a style sheet 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 = loadTable(fname)

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


key, quals = resolveKeyCode(code)

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


table, msg = sourceTable(file[, environment])

Interprete a file as a Lua source, containing the keys and values forming a table. If file is a string, it will be used for opening and reading the named file, otherwise it will be assumed to be an open file handle. Either way, the file will be read using the file:read("*a") method and closed afterwards. By default, the source will be executed in an empty environment, unless an environment is specified. The resulting table is returned to the caller, or nil followed by an error message.


testFlag(flag, field)

Test a bit flag in a flags field


Application (v21.0)

LINEAGE

ClassOverview : Class / Family / Application

OVERVIEW

This class implements the framework's entrypoint and main loop.

MEMBERS
  • ApplicationId [IG]

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

  • Author [IG]

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

  • Copyright [IG]

    Copyright notice applying to the application, default "unknown"

  • Display [IG]

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

  • Domain [IG]

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

  • GCControl [IG]

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

  • ProgramName [IG]

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

  • Status [G]

    Status of the application, can be "connected", "connecting", "disconnected", "disconnecting", "initializing", "error", "running".

  • Theme [IG]

    Name of a theme, which usually maps to an equally named style sheet file (with the extension ".css") under tek/ui/style/. Themes with reserved meaning are:

    • "internal": Uses the hardcoded internal style properties and does not try to load a style sheet file.
    • "desktop": Tries to import the desktop's color scheme, besides trying to load a style sheet named "desktop.css".

    Default: "desktop"

  • Vendor [IG]

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


quit()

Quits the application.


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:

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


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


Area (v21.0)

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

ATTRIBUTES
  • AutoPosition [IG] (boolean)

    When the element receives the focus, this flag instructs it to position itself automatically 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, the Canvas class disables it by default.

  • BGPen [IG] (number)

    A pen number for painting the background of the element

  • DamageRegion [G] (Region)

    see TrackDamage

  • Disabled [ISG] (boolean)

    If true, the element is in disabled state. This attribute is handled by the Gadget class.

  • EraseBG [IG] (boolean)

    If false, the element's background is painted by the Area class using the Area:erase() method. Child classes can set this attribute to true, indicating that they wish to paint the background themselves.

  • Focus [ISG] (boolean)

    If true, the element has the input focus. This attribute is handled by the Gadget class.

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

    Horizontal alignment of the element in its group

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

    Height of the element, in pixels, or

    • false - unspecified; during initialization, the class' default will be used
    • "auto" - Reserves the minimal height needed for the element.
    • "free" - Allows the element's height to grow to any size.
    • "fill" - Completely fills up the height that other elements in the same group have left, but does not claim more.

    Note: Normally, "fill" is useful only once per group.

  • Hilite [SG] (boolean)

    If true, the element is in highlighted state. This attribute is handled by the Gadget class.

  • Margin [IG] (table)

    An array of four offsets for the element's outer margin in the order left, right, top, bottom [pixels]. If unspecified during initialization, the class' default margins are used.

  • MaxHeight [IG] (number)

    Maximum height of the element, in pixels [default: ui.HUGE]

  • MaxWidth [IG] (number)

    Maximum width of the element, in pixels [default: ui.HUGE]

  • MinHeight [IG] (number)

    Minimum height of the element, in pixels [default: 0]

  • MinWidth [IG] (number)

    Minimum width of the element, in pixels [default: 0]

  • Padding [IG] (table)

    An array of four offsets for the element's inner padding in the order left, right, top, bottom [pixels]. If unspecified during initialization, the class' default paddings are used.

  • Selected [ISG] (boolean)

    If true, the element is in selected state. This attribute is handled by the Gadget class.

  • TrackDamage [IG] (boolean)

    If true, the element gathers intra-area damages in a Region named DamageRegion, which can be used by class writers for minimally invasive repaints. Default: false, the element is redrawn in its entirety.

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

    Vertical alignment of the element in its group

  • Weight [IG] (number)

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

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

    Width of the element, in pixels, or

    • false - unspecified; during initialization, the class' default will be used
    • "auto" - Reserves the minimal width needed for the element
    • "free" - Allows the element's width to grow to any size
    • "fill" - Completely fills up the width that other elements in the same group have left, but does not claim more.

    Note: Normally, "fill" is useful only once per group.

STYLE PROPERTIES
  • background-color
  • background-position
  • height
  • horizontal-grid-align
  • margin
  • margin-bottom
  • margin-left
  • margin-right
  • margin-top
  • max-height
  • max-width
  • min-height
  • min-width
  • padding
  • padding-bottom
  • padding-left
  • padding-right
  • padding-top
  • vertical-grid-align
  • width
IMPLEMENTS
OVERRIDES

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

This method is called during the layouting process for adding the required spatial extents (width and height) of this object to the min/max values passed from a child class, before passing them 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. Use ui.HUGE to indicate a (practically) unlimited size.


can_receive = checkFocus()

Returns true if this element can receive the input focus.


can_hover = checkHover()

Returns true if this element can react on being hovered over by the pointing device.


damage(x0, y0, x1, y1)

If the element overlaps with the given rectangle, this function marks it as damaged.


draw()

Draws the element into the rectangle assigned to it by the layouter; the coordinates can be found in the element's Rect table. Note: Applications are not allowed to call this function directly.


erase()

Clears the element's background.


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.


bgpen[, tx, ty] = getBG()

Gets the element's background properties. bgpen is the background pen (which may be a texture). If the element background is scrollable, then tx and ty are the coordinates of the texture origin, otherwise (if the background is fixed) nil.


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


element = getChildren(init)

Returns a table containing the element's children, or nil if this element cannot have children. If the optional init argument is true, this signals that this function is called during initialization or deinitialization.


self = getElementByXY(x, y)

Returns self if the element covers the specified coordinate.


element = getGroup(parent)

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


element = getNext()

Returns the next element in the group, or, if the element has no successor, the next element in the parent group (and so forth, until it reaches the topmost group). Returns nil if the element is not currently connected.


element = getParent()

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


element = getPrev()

Returns the previous element in the group, or, if the element has no predecessor, the next element in the parent group (and so forth, until it reaches the topmost group). Returns nil if the element is not currently connected.


x0, y0, x1, y1 = getRect()

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


element = getSiblings()

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


hide()

Clears a drawable from an element. Override this method to free all display-related resources previously allocated in Area:show().


changed = 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 = passMsg(msg)

This function filters the specified input message. After processing, it is free to return the message unmodified (thus passing it on to the next message handler), to return a copy that has certain fields in the message modified, or to 'swallow' the message by returning false. If you override this function, you are not allowed to modify any data inside the original message; to alter a message, you must operate on and return a copy.


punch(region) [internal]

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


refresh() [internal]

Redraws the element (and all possible children) if they are marked as damaged. This function is called in the Window's update procedure.


found[, changed] = relayout(element, x0, y0, x1, y1) [internal]

Traverses the element tree searching for the specified element, and if this class (or the class of one of its children) is responsible for it, layouts it to the specified rectangle. Returns true if the element was found and its layout updated. A secondary return value of true indicates whether relayouting actually caused a change, i.e. a damage to the object.


rethinkLayout([damage])

This method causes a relayout of the element and possibly the Group in which it resides (and even parent groups thereof if necessary). The optional numeric argument damage indicates the kind of damage to apply to the element:


setState(bg)

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


show(drawable)

Passes an element the Drawable it will be rendered to.


Button (v1.4)

LINEAGE

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

OVERVIEW

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 specifies a few attributes 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 (v16.0)

LINEAGE

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

OVERVIEW

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 [IG] (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 [IG] (boolean)

    Report the minimum height of the Canvas's child object as the Canvas' minimum display height

  • KeepMinWidth [IG] (boolean)

    Report the minimum width of the Canvas's child object as the Canvas' minimum display width

  • 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

  • VScrollStep [IG] (number)

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

IMPLEMENTS
OVERRIDES

sx, sy = checkArea(x, y)

Checks if x, y are inside the element's rectangle, and if so, returns the canvas shift by x and y [internal]


damageChild(r1, r2, r3, r4)

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


Canvas:onSetChild(child)

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

LINEAGE

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

OVERVIEW

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

LINEAGE

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

OVERVIEW

This class implements a directory lister.

ATTRIBUTES
  • Kind [IG] (string)

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

    • "requester" - for a standalone file requester
    • "lister" - for a directory lister component
    • "simple" - without accompanying user interface 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

  • Selection [G] (table)

    An array of selected entries

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

    Text to display on the selection button. Default: "Open".

  • Status [G] (string)
    • "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()

Get current directory


iterator = getDirIterator(path)

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; for the attribute names and their meanings, see the documentation of the LuaFileSystem module. Currently, only the "mode" and "size" attributes are actually requested, but if you override this function, it would be smart to implement as many attributes as possible. idx is optional and determines 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.


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

LINEAGE

ClassOverview : Class / Object / Display

OVERVIEW

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-huge
  • font-large
  • font-menu
  • font-small
  • rgb-active
  • rgb-active-detail
  • rgb-background
  • rgb-border-focus
  • rgb-border-legend
  • rgb-border-rim
  • rgb-border-shadow
  • rgb-border-shine
  • rgb-cursor
  • rgb-cursor-detail
  • rgb-dark
  • rgb-detail
  • rgb-disabled
  • rgb-disabled-detail
  • rgb-disabled-detail2
  • 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-list2
  • 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, and always returns false.


r, g, b = colorToRGB(colspec[, defcolspec])

Converts a color specification to RGB. If colspec is not a valid color, the optional defcolspec can be used as a fallback. Valid color specifications are #rrggbb (each color component is noted in 8 bit hexadecimal) and #rgb (each color component is noted in 4 bit hexadecimal).


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

Creates a pixmap object from data in a picture file format. Currently only the PPM file format is recognized.


h, up, ut = getFontAttrs(font)

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


name, r, g, b = getPaletteEntry(index)

Gets the name and red, green, blue components of a color of the given index in the Display's symbolic color palette.


image, width, height, transparency = Display.getPixmap(fname)

Gets a pixmap object, either by loading it from the filesystem or by retrieving it from the cache.


Display:getTime()

Gets the system time.


image, width, height, transparency = Display.loadPixmap(filename)

Creates a pixmap object from an image file in the file system. Currently only the PPM file format is recognized.


font = openFont(fontname)

Opens the named font. For a discussion of the fontname format, see Text.


Drawable (v16.0)

LINEAGE

ClassOverview : Class / Object / Drawable

OVERVIEW

This class implements a graphical context which can be painted on.

IMPLEMENTS
OVERRIDES

closeFont(font)

Closes a font.


copyArea(x0, y0, x1, y1, deltax, deltay, exposures)

Copy the specified rectangle to the position determined by the relative coordinates deltax and deltay. The exposures argument is a table used for collecting the raw coordinates of rectangles getting exposed as a result of the copy operation.


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

Draws a line using the specified pen.


drawPlot(x0, y0, pen)

Draws a point.


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

Draws an unfilled rectangle.


drawText(x0, y0, text, fgpen[, bgpen])

Renders text with the specified foreground pen. If the optional background pen is specified, the background under the text is filled in this color.


fillRect(x0, y0, x1, y1, pen)

Draws a filled rectangle.


msg = getMsg([msg])

Gets the next pending message from the Drawable. Optionally, the fields of the new message are inserted into the specified table.


shiftx, shifty = getShift()

Get the Drawable's current coordinate displacement.


width, height = getTextSize(text)

Determines the width and height of a text using the font which is currently set on the Drawable.


font = openFont(fname)

Opens a font.


popClipRect()

Pop the topmost cliprect from the Drawable.


pushClipRect(x0, y0, x1, y1)

Pushes a new cliprect on the top of the drawable's stack of cliprects.


setFont(font)

Sets the specified font.


setShift(deltax, deltay)

Add a delta to the Drawable's coordinate displacement.


Element (v14.2)

LINEAGE

ClassOverview : Class / Object / Element

OVERVIEW

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, or false; this attribute is set during Element:setup().

  • Class [IG] (string)

    The name of the element's style class, which can be referenced in a style sheet, or false. Multiple classes can be specified by separating them with spaces, e.g. "button knob warn".

  • Id [IG] (string)

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

  • Parent [G] (object)

    Parent object of the element, or false. This attribute is set in the Element:connect() method.

  • Style [IG] (string)

    Direct style formattings of the element, overriding class-wide formattings in a style sheet, or false. Example: "background-color: #880000; color: #ffff00"

  • Window [G] (Window)

    The window the element is registered with, or false. This attribute is set during Element:setup().

IMPLEMENTS
OVERRIDES

cleanup()

This function is used to unlink the element from its Application and Window.


success = connect(parent)

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


decodeProperties(props)

Invokes the element's Element:getProperties() function, possibly multiple times, passing it (in turn) the decoded properties from the element's Style attribute, and global properties from one or more style sheets. [internal]


disconnect()

Disconnects the formerly connected element from its parent.


ret1, ... = getAttr(attr, ...)

This function gets an attribute from an element, and returns nil if the attribute is unknown. This mechanism can be used for elements that wish to exchange data with each other, without having to break in upon their common base class (which may not be under their control), for adding a getter method.


getById(id)

Gets the element with the specified id, under which it was previously registered with the Application. See also Application:getById().


value = getNumProperty(properties, pseudoclass, attribute)

Gets a property and converts it to a number value. See also Element:getProperty().


getProperties(properties, pseudoclass)

This function is called after connecting the element, for retrieving style properties from a style sheet or from decoding the element's Style attribute ("direct formatting"). It can be invoked multiple times with different pseudo classes and properties. When overriding this function, among the reasonable things to do is to query properties using the Element:getProperty() function, passing it the properties and pseudoclass arguments. First recurse into your super class with the pseudo classes your class defines (if any), and finally pass the call to your super class with the pseudoclass you received.


value = getProperty(properties, pseudoclass, attribute)

Returns the value of a style attribute from the specified properties table, or false if the attribute is undefined. pseudoclass can be the name of a pseudo class, false if no pseudo class is used, or true for looking up the attribute in the properties table directly (rather than in a sub table determined by the element's class - this is used for direct formattings).


setup(app, window)

This function is used to pass the element the environment determined by an Application and a Window.


Family (v2.4)

LINEAGE

ClassOverview : Class / Object / Family

OVERVIEW

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

LINEAGE

ClassOverview : Class / Object / Element / Area / FloatText

OVERVIEW

Implements a scrollable text display. 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(text)

Handler called when a new Text is set.


Frame (v8.0)

LINEAGE

ClassOverview : Class / Object / Element / Area / Frame

OVERVIEW

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 seperates the two other borders and may give the composition a more contrastful appearance. 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 border is designed as 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, which makes it indistinguishable from the background.

Border classes (which are organized as plug-ins) do not need to implement all sub borders; in fact, these properties are all internally handled by the "default" border class, 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
  • Border [IG] (table)

    An array of four widths (in pixels) for the element's border, in the order left, right, top, bottom. This attribute is controllable via the border-width style property.

  • BorderClass [IG] (table)

    Name of the border class used to implement this element's border. This attribute is controllable via the border-class style property. Default: "default"

  • BorderRegion [G] (Region)

    Region object holding the outline of the element's border

  • Legend [IG] (string)

    Border legend text [Default: false]

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

drawBorder()

Draws an element's border.


border = getBorder()

Returns an element's border widths in the order left, top, right, bottom.


Gadget (v14.0)

LINEAGE

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

OVERVIEW

This class implements interactivity.

ATTRIBUTES
  • Active [SG] (boolean)

    Signifies a change of the Gadget's activation state. While active, the position of the mouse pointer is being verified (which is also reflected by the Hover attribute). When the Active state changes, the Gadget's behavior depends on its Mode (see below):

    • in "button" mode, the Selected attribute is set to the value of the Hover attribute. The Pressed attribute is set to the value of the Active attribute, if it caused a change of the Selected state.
    • in "toggle" mode, the Selected attribute of the Gadget is logically toggled, and the Pressed attribute is set to true.
    • in "touch" mode, the Selected and Pressed attributes are set to true, if the Gadget wasn't selected already.

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

  • DblClick [SG] (boolean)

    Signifies that the element was doubleclicked; is is set to true when the element was doubleclicked and is still being held, and false when it was doubleclicked and then released. This attribute usually needs to get a notification handler attached to it before it is useful.

  • Disabled [ISG] (boolean)

    Determines the Gadget's ability to interact with the user. If changed, it invokes the Gadget:onDisable() method. When an element is getting disabled, it loses its focus, too.

  • Effect [IG (string)

    Name of a hook class for rendering an overlay effect. A possible overlay effect is named "ripple", and, as its name suggests, can paint various ripple effects (used e.g. for sliders and handles). Effect hooks are stored in tek/ui/hook and may define their own style properties. This attribute is controllable via the effect style property.

  • FGPen [IG] (userdata)

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

  • InitialFocus [IG] (boolean)

    Specifies that the element should receive the focus initially. If true, the element will notify Focus=true to itself upon invocation of the Area:show() method. Default: false

  • Hilite [SG] (boolean)

    Signifies a change of the Gadget's highligting state. Invokes Gadget:onHilite().

  • Hold [SG] (boolean)

    Signifies that the element is being held. Invokes Gadget:onHold().

  • Hover [SG] (boolean)

    Signifies a change of the Gadget being hovered by the pointing device. Invokes Gadget:onHover().

  • KeyCode [IG] (string or boolean)

    If set, a keyboard equivalent for activating the element. See also PopItem for a discussion of denoting keyboard qualifiers. The Text class allows this attribute to be set 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 [IG] (string)

    The element's interaction mode:

    • "inert": The element does not react to input
    • "toggle": The element does not rebound and keeps its Selected state; it cannot be unselected by the user
    • "touch": The element rebounds immediately and acts as a strobe, always submitting true for Pressed and Selected
    • "button": The element sets the Pressed attribute only if the mouse pointer is released when hovering it.

    See also the Active attribute.

  • Pressed [SG] (boolean)

    Signifies that a button was pressed or released. Invokes Gadget:onPress().

  • Selected [ISG] (boolean)

    Signifies a change of the gadget's selection state. Invokes Gadget:onSelect().

STYLE PROPERTIES
  • color - controls the Gadget.FGPen attribute
  • effect - controls the Gadget.Effect attribute
  • 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
STYLE PSEUDO CLASSES
  • active - for elements in active state
  • disabled - for elements in disabled state
  • focus - for elements that have the focus
  • hover - for elements that are being hovered by the mouse
IMPLEMENTS
OVERRIDES

onActivate(active)

This method is invoked when the gadget's Active attribute has changed.


onDisable(disabled)

This method is invoked when the gadget's Disabled attribute has changed.


Gadget:onFocus(focused)

This method is invoked when the element's Focus attribute has changed (see also Area).


onHilite(selected)

This method is invoked when the gadget's Selected attribute has changed.


onHold(held)

This method is invoked when the gadget's Hold attribute is set. While the gadget is being held, repeated Hold = true events are submitted in intervals of n/50 seconds determined by the Window.HoldTickInitRepeat attribute.


onHover(hovered)

This method is invoked when the gadget's Hover attribute has changed.


onPress(pressed)

This method is invoked when the gadget's Pressed attribute has changed.


onSelect(selected)

This method is invoked when the gadget's Selected attribute has changed.


Gauge (v7.0)

LINEAGE

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

OVERVIEW

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

OVERRIDES

Group (v19.0)

LINEAGE

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

OVERVIEW

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

  • 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/string)

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

IMPLEMENTS
OVERRIDES

Handle (v3.4)

LINEAGE

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

OVERVIEW

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

OVERRIDES

ListGadget (v19.0)

LINEAGE

ClassOverview : Class / Object / Element / Area / Frame / Gadget / Text / ListGadget

OVERVIEW

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 ListGadget; 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 ListGadget's parent Canvas is used, but by use of this attribute it is possible to align the ListGadget to something else.

  • BGPenAlt [IG] (userdata)

    A colored pen for painting the background of alternating lines

  • ColumnPadding [IG] (number)

    The padding between columns, in pixels. By default, the ListGadget'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 ListGadget's cursor; this value may be 0, in which case the cursor is invisible. Changing this value will invoke the ListGadget:onSetCursor() method.

  • Font [IG] (string)

    Font specifier for determining the font used for list entries. See Text for details on its format.

  • HeaderGroup [IG] (Group)

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

  • ListObject [IG] (List)

    The List object the ListGadget operates on; if none is specified, the ListGadget 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 ListGadget:getSelectedLines() for retrieving a numerically indexed list.

  • SelectedLine [ISG] (number)

    The ListGadget'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 ListGadget:onSelectLine() method.

  • SelectMode [IG] (string)

    The ListGadget'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 ListGadget:repaint().)


changeItem(item, line[, quick])

Overwrites the item at the specified line in the list. The boolean quick indicates that the list the list after mass changes, see also ListGadget:repaint().)


changeSelection(mode)

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


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"


onSelectLine(line)

This method is invoked when the SelectedLine attribute is set.


onSetCursor(line, oldline)

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 ListGadget:repaint().)


repaint()

Relayouts and repaints the list.


setList(listobject)

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


ListView (v5.0)

LINEAGE

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

OVERVIEW

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

LINEAGE

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

OVERVIEW

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

LINEAGE

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

OVERVIEW

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.

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

  • Step [ISG] (number)

    Default step value [Default: 1]

  • 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 Step attribute is used in its place.


increase([delta])

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


onSetMax(max)

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


onSetMin(min)

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


onSetValue(val)

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


reset()

Reset Value to is Default value.


PageGroup (v11.1)

LINEAGE

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

OVERVIEW

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

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


PopItem (v9.3)

LINEAGE

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

OVERVIEW

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

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

LINEAGE

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

OVERVIEW

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

This method is invoked when the SelectedLine attribute is set.


setList(listobject)

Sets a new List object.


PopupWindow (v3.0)

LINEAGE

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

OVERVIEW

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

OVERRIDES

RadioButton (v4.0)

LINEAGE

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

OVERVIEW

Specialization of a CheckMark to implement mutually exclusive 'radio buttons'; they really make sense only if more than one of their kind are grouped together.

OVERRIDES

ScrollBar (v8.5)

LINEAGE

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

OVERVIEW

Implements a group containing a Slider and arrow buttons.

ATTRIBUTES
  • Integer [IG] (boolean)

    If true, integer steps are enforced. By default, the slider moves continuously.

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

  • Value [ISG] (number)

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

IMPLEMENTS
OVERRIDES

onSetMax(max)

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


onSetMin(min)

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


onSetRange(range)

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


onSetValue(val)

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


ScrollGroup (v11.0)

LINEAGE

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

OVERVIEW

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

ATTRIBUTES
  • 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 ListGadget 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 ListGadget is taller than the currently visible area.

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

OVERRIDES

Slider (v11.0)

LINEAGE

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

OVERVIEW

This class implements a slider for adjusting a numerical value.

ATTRIBUTES
  • AutoFocus [IG] (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: false

  • Child [IG] (Gadget)

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

  • Integer [IG] (boolean)

    If true, integer steps are enforced. By default, the slider knob moves continuously.

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

IMPLEMENTS

OVERRIDES:


onSetRange(range)

This handler is invoked when the Slider's Range attribute has changed.


Spacer (v1.5)

LINEAGE

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

OVERVIEW

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

OVERRIDES

Text (v17.1)

LINEAGE

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

OVERVIEW

This gadget implements text rendering.

ATTRIBUTES
  • Font [IG] (string)

    A font specification in the form

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

    Font names, if specified, will be probed in the order of their occurence in the string; the first font that can be opened will be used. For the font names, the following placeholders with predefined meanings are supported:

    • "ui-fixed": The default fixed font
    • "ui-main" or "": The default main font, e.g. for buttons and menus
    • "ui-small": The default small font, e.g. for group captions
    • "ui-large": The default 'large' font
    • "ui-huge": The default 'huge' font

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

  • KeepMinHeight [IG] (boolean)

    After the initial size calculation, keep the minimal height of the element and do not rethink the layout in regard to a possible new minimal height (e.g. resulting from a newly set text).

  • KeepMinWidth [IG] (boolean)

    After the initial size calculation, keep the minimal width of the element and do not rethink the layout in regard to a possible new minimal width (e.g. resulting from a newly set text).

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

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

    The text's horizontal alignment, which will be used in Text:makeTextRecords(). If false during initialization, the class' default will be used. [Default: "center"]

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

    The text's vertical alignment, which will be used in Text:makeTextRecords(). If false during initialization, the class' default will be used. [Default: "center"]

IMPLEMENTS
STYLE PROPERTIES
  • color2 - secondary color used in disabled state
  • font
  • text-align
  • vertical-align
OVERRIDES

width, height = getTextSize([textrecord])

This function calculates the total space occupied by the object's text records. Optionally, the user can pass a table of text records which are to be evaluated.


makeTextRecords(text)

This function parses a string and breaks it along the encountered newline characters into single-line records. 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(text)

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


TextInput (v10.1)

LINEAGE

ClassOverview : Class / Object / Element / Area / Frame / Gadget / Text / TextInput

OVERVIEW

This class implements a gadget for entering and editing text.

ATTRIBUTES
  • Enter [SG] (string)

    The text that is being entered (by pressing the Return key) into the input field. Setting this value causes the invocation of the TextInput:onEnter() method.

  • EnterNext [IG] (boolean)

    Indicates that by pressing the Return key, the focus should advance to the next element that can receive input.

  • TabEnter [IG] (boolean)

    Indicates that leaving the element by pressing the Tab key should set the Enter attribute and invoke the respective handler.

STYLE PROPERTIES
  • cursor-background-color
  • cursor-color
IMPLEMENTS
OVERRIDES

a rethinkLayout()


addChar(utf8s)

Perform add character


backSpace()

Perform backspace


delChar()

Perform delete character


char = getChar([pos])

Get the character under the cursor, or at the specified position.


self:getCursor()

Get cursor position


success = moveCursorLeft()

Advance the cursor position by 1 to the left.


success = moveCursorRight()

Advance the cursor position by 1 to the right.


onEnter(text)

This method is called when the Enter attribute is set. It can be overridden for reacting on entering text by pressing the return key. This method also sets the Text attribute (see Text).


self:setCursor(pos)

Set absolute cursor position. If pos is "eol", the cursor is positioned to the end of the string.


Theme (v6.23)

LINEAGE

ClassOverview : Class / Theme

IMPLEMENTS

stylesheet = Theme.getStyleSheet([themename])

Returns a style sheet for a named theme. Theme names currently defined are:

Any other theme name will cause this function to try to load an equally named style sheet, falling back to the hardcoded internal style sheet if unavailable. The default for themename is "default".


Window (v16.0)

LINEAGE

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

OVERVIEW

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.

  • 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 an 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(status)

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 standard behavior is to hide the window by setting the Status field 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 Gadget 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.


Layout (v3.7)

LINEAGE

ClassOverview : Class / Layout

OVERVIEW

Implements a Groups's standard layouting strategy. It is designed as a plug-in so that it can be replaced easily and on a per-Group-basis

IMPLEMENTS
OVERRIDES

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

This function queries the specified Group for its size requirements, which will subsequently invoke child:askMinMax() on all of its children.


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

Layouts the Group into the specified rectangle and calculates the 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.


Document generated on Sat May 23 15:01:59 2009