Lua Fltk Introduction

Lua Fltk is a binding of the FLTK widget set to the language Lua. It's built on the tolua C++ binding generator. It tries to make the use of Fltk widgets seem natural to Lua programmers; it uses a simple constructor syntax, remaps C++ values onto Lua conventions, and provides direct set/get access to widget properties.

Lua Fltk is a work in progress. There are still some rough edges; in particular, properties and functions that return Widgets do not cast them back to the proper subclass. This manual does not describe lua-fltk-0.9, but it's pretty close; revisions to the binding were made during the editing of this manual. Expect another release soon.

This manual is derived from the FLTK 1.0.7 manual. The widget reference is generated from a set of fdoc files. Many of the function and property descriptions were copied directly from the FLTK manual. Many more were edited.

Properties

A key concept in Lua Fltk is the notion of properties.

In C++, you set a widget's label with w->label("new label") and read it with w->label(). In Lua Fltk, the label appears as a field of the widget directly: w.label = "new label" and w.label.

When C++ get/set functions are mapped directly onto a Lua field, this field is called a property. If only a get function is mapped, it's a readonly property.

In general, when you change properties that affect a widget's appearance, you must call the widget's redraw() function before the changes will be seen.

Constructors

The general syntax for creating a widget is

w = Widget{x,y,width,height}

w = Widget{x,y,width,height; field=value, field=value ...}

As a convenience, a fifth argument is treated as a value for the label property. The following two lines are equivalent:

w = Widget{100,300,80,30,"my label"}

w = Widget{100,300,80,30; label="my label"}

Instances

Widgets can also be used as tables, storing arbitrary information. This is useful to keep data and functions related to the widget.

b = Button{100,100,80,80; label="Hello"; other_label="Goodbye"}

function b:callback()
  local old_label = self.label
  self.label = self.other_label
  self.other_label = old_label
  self:redraw()
end

function b:reset_labels()
  self.label="Hello"
  self.other_label="Goodbye"
  self:redraw()
end

b:reset_labels()

However, if you add an entry that conflicts with a Lua Fltk function, your entry will win and you won't be able to call the function on that object.

Currently this behavior allows you to write to readonly property fields without error; your data will be lost, as the C++ property accessor will be called on get.

The event loop

Most actions in FLTK happen inside the application's event loop. In particular, widgets are actually redrawn before checking for events; also, windows will not appear.

Lua Fltk provides an implicit call to the standard FLTK event loop, Fl:run() after reading all script files specified on the command line. Fl:run() will return when there are no windows shown on the display.

This behavior is inconvenient when not specifying any scripts on the command line---the interpreter would immediately exit since there are initially no windows shown. In this special case you must call Fl:run() yourself after you have a window up.

Specifying -i on the command line allows you to continue to type Lua statements interactively even after Fl:run() begins. This feature appears to be broken on Win32 (surprise) and may have to be replaced with a shell window written in Lua Fltk.