MoonFLTK Reference Manual

Preface

This is the reference manual of MoonFLTK, which is a Lua binding library for the Fast Light Toolkit (FLTK). ^[1]

It is assumed that the reader is familiar with both FLTK and the Lua programming language.

For convenience of reference, this document contains external (deep) links to the Lua Reference Manual and the FLTK Programming Manual.

Getting and installing

For installation intructions, refer to the README file in the MoonFLTK official repository on GitHub.

Module organization

The MoonFLTK module is loaded using Lua’s require() and returns a table containing the functions it provides (as usual with Lua modules). This manual assumes that such table is named fl, i.e. that it is loaded with:

 fl = require("moonfltk")

but nothing forbids the use of a different name.

Examples

Examples can be found in the examples/ directory of the release package (the examples/fltk subdirectory contains portings to MoonFLTK of most of the examples that come with the FLTK distribution).

License

MoonFLTK is released under the MIT/X11 license (same as Lua, and with the same only requirement to give proper credits to the original author). The copyright notice is in the LICENSE file in the base directory of the official repository on GitHub.

Introduction

MoonFLTK exposes FLTK functions and static methods as Lua functions contained in the fl table. For example, fl.draw( ) exposes fl_draw( ), fl.run( ) exposes Fl::run( ), and so on.

FLTK classes are exposed as Lua 'objects', that is, userdata with methods. For each (concrete) class there is a constructor function in the fl table that instantiates an object of that class, bounds it to a userdatum and returns the latter. For example:

win = fl.double_window(0, 0, 600, 400) -- creates an Fl_Double_Window.
win:label('My Window') -- a method

MoonFLTK userdata preserve the FLTK class hierarchy: the win object in the above example is not only a double_window, but also a window, a group, and a widget. This means that it inherits their methods and it can be used wherever a window, a group, or a widget is expected.

Exposed functions, classes, and their methods are listed in the sections that follow. For most of them, their functionalities and usages are not described in this manual (please refer to the FLTK Programming Manual instead).

Classes

Widgets

Widget hierarchy

widget (sub)
├─ box (sub)
├─ button (sub)
│ ├─ light_button
│ │ ├─ check_button
│ │ ├─ radio_light_button
│ │ └─ round_button
│ │ └─ radio_round_button
│ ├─ radio_button
│ ├─ repeat_button
│ ├─ return_button
│ └─ toggle_button
├─ chart
├─ clock_output
│ └─ clock
│ └─ round_clock
├─ group (sub)
│ ├─ browser_
│ │ ├─ browser (sub)
│ │ │ ├─ file_browser
│ │ │ ├─ hold_browser
│ │ │ ├─ multi_browser
│ │ │ └─ select_browser
│ │ └─ check_browser
│ ├─ color_chooser
│ ├─ help_view
│ ├─ input_choice
│ ├─ pack
│ ├─ scroll
│ ├─ spinner
│ ├─ table (sub)
│ │ └─ table_row (sub)
│ ├─ tabs (sub)
│ ├─ text_display
│ │ └─ text_editor
│ ├─ tile
│ ├─ tree
│ ├─ window (sub)
│ │ ├─ double_window (sub)
│ │ │ └─ overlay_window (sub)
│ │ ├─ gl_window (sub)
│ │ └─ single_window (sub)
│ │ └─ menu_window (sub)
│ └─ wizard
├─ input_
│ └─ input
│ ├─ file_input
│ ├─ float_input
│ ├─ int_input
│ ├─ multiline_input
│ ├─ output
│ │ └─ multiline_output
│ └─ secret_input
├─ menu_
│ ├─ choice
│ ├─ menu_bar
│ └─ menu_button
├─ progress
└─ valuator
├─ adjuster
├─ counter
│ └─ simple_counter
├─ dial
│ ├─ fill_dial
│ └─ line_dial
├─ roller (sub)
├─ slider (sub)
│ ├─ fill_slider
│ ├─ hor_fill_slider
│ ├─ hor_nice_slider
│ ├─ hor_slider
│ ├─ nice_slider
│ ├─ scrollbar
│ └─ value_slider
│ └─ hor_value_slider
├─ value_input
└─ value_output

Rfr: Fl_Widget.
No constructor (abstract class).

:activate( )
boolean = :active( )
boolean = :active_r( )
:align(alignment)
alignment = :align( )
:argument(arg)
arg = :argument( )
arg: any Lua value.
:box(boxtype)
:box( )
→ boxtype

:callback(func [, arg])
func = :callback( )
The func callback (a Lua function) is executed as func(widget, arg).
The optional argument arg may be any Lua value.
boolean = :changed( )
:clear_active( )
:clear_changed( )
:clear_damage(damagebits)
:clear_output( )
:clear_visible( )
:clear_visible_focus( )
:color(bgcolor [, selcolor])
bgcolor = :color( )
boolean = :contains(widget)
:damage(damagebits) :damage(x, y, w, h, damagebits)
damagebits = :damage( )
:deactivate( )
:deimage(image)
image = :deimage( )
:do_callback([arg])
The optional argument arg may be any Lua value.
If arg is not passed, the current argument is used.
If arg=nil, the callback receives nil as argument.

Protected methods, exposed for subclassing:

:draw_backdrop( )
:draw_box( )
:draw_box(boxtype, color)
:draw_box(boxtype, x, y, w, h, color)
:draw_focus( )
:draw_focus(boxtype, x, y, w, h, color)

box

Rfr: Fl_Box.
Inherits from: widget.

box = fl.box(x, y, w, h, [label])
box = fl.box(boxtype, x, y, w, h, [label])

button

Rfr: Fl_Button.
Inherits from: widget.
RTTI: 'normal', 'toggle', 'radio', 'hidden'.

button = fl.button(x, y, w, h, [label])
boolean = :clear( )
:down_box(boxtype)
boxtype = :down_box( )
boolean = :set( )
:setonly( )
:shortcut(shortcut)
shortcut = :shortcut( )
:value(boolean)
boolean = :value( )

light_button

Rfr: Fl_Light_Button.
Inherits from: widget, button.

light_button = fl.light_button(x, y, w, h, [label])

check_button

Rfr: Fl_Check_Button.
Inherits from: widget, button, light_button.

check_button = fl.check_button(x, y, w, h, [label])

radio_light_button

Rfr: Fl_Radio_Light_Button.
Inherits from: widget, button, light_button.

radio_light_button = fl.radio_light_button(x, y, w, h, [label])

round_button

Rfr: Fl_Round_Button.
Inherits from: widget, button, light_button.

round_button = fl.round_button(x, y, w, h, [label])

radio_round_button

Rfr: Fl_Radio_Round_Button.
Inherits from: widget, button, light_button, round_button.

radio_round_button = fl.radio_round_button(x, y, w, h, [label])

radio_button

Rfr: Fl_Radio_Button.
Inherits from: widget, button.

radio_button = fl.radio_button(x, y, w, h, [label])

repeat_button

Rfr: Fl_Repeat_Button.
Inherits from: widget, button.

repeat_button = fl.repeat_button(x, y, w, h, [label])
:deactivate( )

return_button

Rfr: Fl_Return_Button.
Inherits from: widget, button.

return_button = fl.return_button(x, y, w, h, [label])

toggle_button

Rfr: Fl_Toggle_Button.
Inherits from: widget, button.

toggle_button = fl.toggle_button(x, y, w, h, [label])

chart

Rfr: Fl_Chart.
Inherits from: widget.
RTTI: 'bar', 'horbar', 'line', 'fill', 'spike', 'pie', 'specialpie'.

chart = fl.chart(x, y, w, h, [label])
:autosize(boolean)
boolean = :autosize( )
:add(value, [label], [color])
:bounds(lower, upper)
lower, upper = :bounds( )
:clear( )
:insert(pos, value, [label], [color])
:maxsize(n)
n = :maxsize( )
:replace(pos, value, [label], [color])
:size(w, h)
n = :size( )
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )

clock_output

Rfr: Fl_Clock_Output.
Inherits from: widget.

clock_output = fl.clock_output(x, y, w, h, [label])
hour = :hour( )
minute = :minute( )
second = :second( )
:value(sec_since_epoch)
sec_since_epoch = :value( )

clock

Rfr: Fl_Clock.
Inherits from: widget, clock_output.

clock = fl.clock(x, y, w, h, [label])

round_clock

Rfr: Fl_Round_Clock.
Inherits from: widget, clock_output, clock.

round_clock = fl.round_clock(x, y, w, h, [label])

group

Rfr: Fl_Group.
Inherits from: widget.

group = fl.group(x, y, w, h, [label])
:add(widget)
:add_resizable(widget)
:begin( )
widget = :child(n)
nchildren = :children( )

Note	Children are indexed from 1 to group:children() inclusive.

:clear( )
:clip_children(boolean)
boolean = :clip_children( )

Note	:end is replaced by :done('end' is a reserved keyword in Lua).

:done( )
n = :find(widget)
Returns group:children()+1 if widget is nil or not found.
:init_sizes( )
:insert(widget, n)
:insert(widget, beforewidget)
:remove(widget)
:resizable(widget) widget = :resizable( )
If widget is nil, then all widget remain a fixed size and distance from the top-left corner.
(Note that :resizable() differs from :resizable(nil): the former is a 'get', while the latter is a 'set' operation.)

The following are (un)protected methods to be used only when subclassing.

:draw_child(widget)
:draw_children( )
:draw_outside_label(widget)
:update_child(widget)

browser_

Rfr: Fl_Browser_.
Inherits from: widget, group.
RTTI: 'normal', 'select', 'hold', 'multi'.
No constructor (abstract class).

boolean = :deselect( )
:has_scrollbars(scrollbarsmode)
scrollbarsmode = :has_scrollbars( )
:hposition(pos)
pos = :hposition( )
:position(pos)
pos = :position( )
:scrollbar_left( )
:scrollbar_right( )
:scrollbar_size(size)
size = :scrollbar_size( )
:sort(order)
order: 'ascending' or 'descending'.
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )

browser

Rfr: Fl_Browser.
Inherits from: widget, group, browser_.

browser = fl.browser(x, y, w, h, [label])
:add([text], [data])
:bottomline(line)
:clear( )
:column_char(c)
c = :column_char( )
c: ASCII character.
:column_widths(w₁, w₂, …, w_N)
w₁, w₂, …, w_N = :column_widths( )

:data(line, data)
data = :data(line)
data: an integer value to associate with the item (defaults to 0).
This value may be used as index in a Lua table containing more complex data associated with the item.
boolean = :displayed(line)
:format_char(c)
c = :format_char( )
c: ASCII character.
:hide(line)
:hide( )
:icon(line, image)
image = :icon(line)
:insert(line, [text], [data])
:lineposition(line, linepos)
ok, err = :load(filename)
Returns true or false and an error string.
:make_visible(line)
:middleline(line)
:move(to, from)
:remove(line)
:remove_icon(line)
boolean = :select(line, [boolean])
boolean = :selected(line)
:show(line)
:show( )
:swap(line₁, line₂)
:size(w, h)
nlines = :size( )
:text(line, [text])
text = :text(line)
:topline(line)
line = :topline( )
boolean = :visible(line)
:value(line)
line = :value( )

file_browser

Rfr: Fl_File_Browser.
Inherits from: widget, group, browser_, browser.

file_browser = fl.file_browser(x, y, w, h, [label])
:filetype(filetype)
filetype = :filetype( )
:filter(pattern)
pattern = :filter( )
:iconsize(size)
size = :iconsize( )
boolean = :load(filename, [sortfunc])

hold_browser

Rfr: Fl_Hold_Browser.
Inherits from: widget, group, browser_, browser.

hold_browser = fl.hold_browser(x, y, w, h, [label])

multi_browser

Rfr: Fl_Multi_Browser.
Inherits from: widget, group, browser_, browser.

multi_browser = fl.multi_browser(x, y, w, h, [label])

select_browser

Rfr: Fl_Select_Browser.
Inherits from: widget, group, browser_, browser.

select_browser = fl.select_browser(x, y, w, h, [label])

check_browser

Rfr: Fl_Check_Browser.
Inherits from: widget, group, browser_.

check_browser = fl.check_browser(x, y, w, h, [label])
index = :add([text], [boolean])

Note	The item index is an integer in the range 1 to check_browser:nitems() inclusive.

:check_all( )
:check_none( )
:checked(index, boolean)
boolean = :checked(index)
:clear( )
n = :nchecked( )
n = :nitems( )
n = :remove(index)
:set_checked(index)
text = :text(index)
index = :value( )

color_chooser

Rfr: Fl_Color_Chooser.
Inherits from: widget, group.

color_chooser = fl.color_chooser(x, y, w, h, [label])
hue = :hue( )
:mode(colorchoosermode)
colorchoosermode = :mode( )
r = :r( )
g = :g( )
b = :b( )
boolean = :rgb(r, g, b)
saturation = :saturation( )
brightness = :value( )

help_view

Rfr: Fl_Help_View.
Inherits from: widget, group.

help_view = fl.help_view(x, y, w, h, [label])
:clear_selection( )
dirname = :directory( )
filename = :filename( )
line = :find(string, [pos])
Returns nil if string is not found.
:leftline(p)
p = :leftline( )
:link(func)
The func callback (a function) is executed as func(help_view, uri) where help_view is this widget and uri is an URI or a pathname. It must return a pahname that can be opened as a local file, or nil (see Fl_Help_View::link() in the FLTK manual for more details).
:load(filename)
:scrollbar_size(pixels)
pixels = :scrollbar_size( )
Do not use this function, use fl.scrollbar_size( ) instead.
:select_all( )
:size(w, h)
size = :size( )
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )
title = :title( )
:topline(line)
:topline(name)
line = :topline( )
:value(text)
text = :value( )

input_choice

Rfr: Fl_Input_Choice.
Inherits from: widget, group.

input_choice = fl.input_choice(x, y, w, h, [label])
:add(item)
item: a string.
boolean = :changed( )
:clear( )
:clear_changed( )
:down_box(boxtype)
boxtype = :down_box( )
input = :input( )
menu_button = :menubutton( )
:set_changed( )
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )
:value(index)
:value(item)
item = :value( )

pack

Rfr: Fl_Pack.
Inherits from: widget, group.
RTTI: 'horizontal', 'vertical'.

pack = fl.pack(x, y, w, h, [label])
:spacing(pixels)
pixels = :spacing( )

scroll

Rfr: Fl_Scroll.
Inherits from: widget, group.
RTTI: 'no scrollbar', 'horizontal', 'vertical', 'both', 'always on' 'horizontal always', 'vertical always', 'both always'.

scroll = fl.scroll(x, y, w, h, [label])
:clear( )
scrollbar = :hscrollbar( )
Returns a reference to the horizontal scrollbar widget.
scrollbar = :scrollbar( )
Returns a reference to the vertical scrollbar widget.
:scrollbar_size(pixels)
pixels = :scrollbar_size( )
:scroll_to(x, y)
x :xposition( )
y :yposition( )

spinner

Rfr: Fl_Spinner.
Inherits from: widget, group.
RTTI: 'float', 'int'.

spinner = fl.spinner(x, y, w, h, [label])
:format(fmt)
fmt = :format( )
:maximum(number)
number = :maximum( )
:minimum(number)
number = :minimum( )
:range(min, max)
:step(number)
number = :step( )
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )
:value(number)
number = :value( )

table

Rfr: Fl_Table.
Inherits from: widget, group.

table = fl.table(x, y, w, h, [label])

Note	Row and column numbers, as well as children indices, are 1-based (Lua-style).

tablecontext = :callback_context( )
col = :callback_col( )
row = :callback_row( )
:col_header(boolean)
boolean = :col_header( )
:col_header_color(color)
color = :col_header_color( )
:col_header_height(h)
h = :col_header_height( )
:col_position(col)
col = :col_position( )
:col_resize(boolean)
boolean = :col_resize( )
:col_resize_min(val)
val = :col_resize_min( )
:col_width(col, w)
w = :col_width(col)
:col_width_all(w)
ncols = :cols( )

:draw_cell(tablecontext, r, c, x, y, w, h)
x, y, w, h = :find_cell(tablecontext, row, col)
row_top, col_left, row_bottom, col_right = :get_selection( )
boolean = :is_interactive_resize( )
boolean = :is_selected(row, col)
boolean = :move_cursor(deltarow, deltacol, [shiftselect])
row = :current_row( )
col = :current_col( )
Return nil if none is selected.
:row_header(boolean)
boolean = :row_header( )
:row_header_color(color)
color = :row_header_color( )
:row_header_width(w)
w = :row_header_width( )
:row_height(row, h)
h = :row_height(row)
:row_height_all(h)
:row_position(row)
row = :row_position( )
:row_resize(boolean)
boolean = :row_resize( )
:row_resize_min(val)
val = :row_resize_min( )
nrows = :rows( )
:scrollbar_size(val)
val = :scrollbar_size( )
:set_selection(row_top, col_left, row_bottom, col_right)
:table_box(boxtype)
boxtype = :table_box( )
:tab_cell_nav(boolean)
boolean = :tab_cell_nav( )
row₁, row₂, col₁, col₂ = :visible_cells( )

table_row

Rfr: Fl_Table_Row.
Inherits from: widget, group, table.
RTTI: 'none', 'single', 'multi'.

table_row = fl.table_row(x, y, w, h, [label])

Note	Row and column numbers, as well as children indices, are 1-based (Lua-style).

boolean = :row_selected(row)
Returns nil, errmsg if row is out of range.
:rows(nrows)
nrows = :rows( )
:select_all_rows([option])
option = 'deselect', 'select' (default), 'toggle'.
boolean = :select_row(row, [option])
option = 'deselect', 'select' (default), 'toggle'.
Returns nil, errmsg if row is out of range.

tabs

Rfr: Fl_Tabs.
Inherits from: widget, group.

tabs = fl.tabs(x, y, w, h, [label])
x, y, w, h = :client_area([tabh])
widget = :push( )

widget = :value( )
boolean = :value(widget)
widget = :which(event_x, event_y)

text_display

Rfr: Fl_Text_Display.
Inherits from: widget, group.

Important

See text_buffer indexing.

text_display = fl.text_display(x, y, w, h, [label])
:buffer(text_buffer) text_buffer = :buffer( )
nlines = :count_lines(start, [end], [islinestart])
:cursor_color(color)
color = :cursor_color( )
:cursor_style(cursorstyle)
:hide_cursor( )
:highlight_data(stylebuffer, styletable, [unfinishedstyle, func])
stylebuffer: a text_buffer.
styletable: an array (integer-indexed table) of style-describing arrays, each of which in the form: { color, font, fontsize, fontattr } (fontattr is optional and defaults to 0). Characters in the stylebuffer indicate styles in the styletable: 'A', denotes the first style, 'B' the second, and so on (up to '~').
unfinishedstyle: (optional) the character denoting the unfinished style that triggers the callback below.
func: (optional) callback triggered by unfinishedstyle. The callback is executed as func(text_display, pos) where text_display is this widget.
boolean = :in_selection(x, y)
:insert(text)
:insert_position(pos)
pos = :insert_position( )
pos = :line_end(pos, [islinestart])
pos = :line_start(pos)
:linenumber_align(alignment)
alignment = :linenumber_align( )
:linenumber_bgcolor(color)
color = :linenumber_bgcolor( )
:linenumber_fgcolor(color)
color = :linenumber_fgcolor( )
:linenumber_font(font)
font = :linenumber_font( )
:linenumber_format(fmt)
fmt = :linenumber_format( )
:linenumber_size(fontsize)
fontsize = :linenumber_size( )
:linenumber_width(w)
w = :linenumber_width( )
boolean = :move_down( )
boolean = :move_left( )
boolean = :move_right( )
boolean = :move_up( )
:next_word( )
:overstrike( )
x, y = :position_to_xy(pos)
Returns nil if character is vertically out of view.
:previous_word( )
:redisplay_index(start, end)
pos = :rewind_lines(start, nlines)
:scrollbar_align(alignment)
alignment = :scrollbar_align( )
:scrollbar_width(w)
w = :scrollbar_width( )
:shortcut(shortcut)
shortcut = :shortcut( )
:show_cursor(boolean)
:show_insert_position( )
pos = :skip_lines(start, nlines, [islinestart])
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )
end + 1 = :word_end(pos)
start = :word_start(pos)
:wrap_mode(wrapmode, margin)

text_editor

Rfr: Fl_Text_Editor.
Inherits from: widget, group, text_display.

text_editor = fl.text_editor(x, y, w, h, [label])
:insert_mode(boolean)
boolean = :insert_mode( )

:key_callback(func)
Registers func as the callback for key bindings. A text_editor may have only one key callback, and this will handle all the (key, modifiers) combinations bound with the key_bind( ) method. The callback is executed as func(editor, key, modifiers) and must return a boolean (the modifiers argument is passed as integer code).

:key_bind(key, modifiers)
Binds (key, modifiers) to the key callback.
:key_unbind(key, modifiers)
Unbinds (key, modifiers). This method can be used also to unbind default key bindings, not only for keys bound to the key callback.
:remove_all_key_bindings( )

Built-in key handling functions are available as members of the fl table and may be used in the key callback:

boolean = fl.kf_default(key, text_editor)
boolean = fl.kf_ignore(key, text_editor)
boolean = fl.kf_backspace(key, text_editor)
boolean = fl.kf_enter(key, text_editor)
boolean = fl.kf_move(key, text_editor)
boolean = fl.kf_shift_move(key, text_editor)
boolean = fl.kf_ctrl_move(key, text_editor)
boolean = fl.kf_c_s_move(key, text_editor)
boolean = fl.kf_meta_move(key, text_editor)
boolean = fl.kf_m_s_move(key, text_editor)
boolean = fl.kf_home(key, text_editor)
boolean = fl.kf_end(key, text_editor)
boolean = fl.kf_left(key, text_editor)
boolean = fl.kf_up(key, text_editor)
boolean = fl.kf_right(key, text_editor)
boolean = fl.kf_down(key, text_editor)
boolean = fl.kf_page_up(key, text_editor)
boolean = fl.kf_page_down(key, text_editor)
boolean = fl.kf_insert(key, text_editor)
boolean = fl.kf_delete(key, text_editor)
boolean = fl.kf_copy(key, text_editor)
boolean = fl.kf_cut(key, text_editor)
boolean = fl.kf_paste(key, text_editor)
boolean = fl.kf_select_all(key, text_editor)
boolean = fl.kf_undo(key, text_editor)

tile

Rfr: Fl_Tile.
Inherits from: widget, group.

tile = fl.tile(x, y, w, h, [label])
:position(oldx, oldy, newx, newy)

tree

Rfr: Fl_Tree.
Inherits from: widget, group.
RTTI: see treeselect.

Note

In MoonFLTK, tree items are identified by their pathname and the tree they belong to (orphaned items are not supported). The Fl_Tree_Item class in not directly exposed, while its methods are exposed as methods of the fl.tree object (renamed with a leading item_ prefix, and accepting the item’s pathname as first argument). Children items' indices are 1-based.

tree = fl.tree(x, y, w, h, [label])
:add(pathname)
:argument(arg)
arg + = :argument( )
arg: any Lua value.
:callback(func, [arg])
func + = :callback( )
The func callback (a Lua function) is executed as func(tree, pathname, reason, arg), where pathname is the affected item and reason is the reason for calling back (see treereason). The optional argument arg may be any Lua value.
:clear([pathname])
If pathname is passed, clears the item’s subtree, otherwise clears the whole tree.
:closeicon(image)
image = :closeicon( )
:connectorcolor(color)
color = :connectorcolor( )
:connectorstyle(treeconnector)
treeconnector = :connectorstyle( )
:connectorwidth(pixels)
pixels = :connectorwidth( )
:extend_selection_up(from, to, [op], [visible])
n = :extend_selection_down(from, to, [op], [visible])
from, to: items pathnames.
op: 'select' (default), 'deselect', 'toggle'.
visible: boolean (default=false).
pathname = :first( )
pathname = :first_selected_item( )
pathname = :first_visible_item( )
pathname = :get_item_focus( )
:hposition(h)
h = :hposition( )
pathname = :insert_above(above, name)
above: pathname of the item above which the new item has to be inserted.
name: name of the new item.
Returns the pathname of the newly inserted item.
pathname = :insert(parent, name, index)
parent: pathname of the parent item.
name: name of the new item.
Returns the pathname of the newly inserted item.
boolean = :is_hscroll_visible( )
boolean = :is_vscroll_visible( )
:labelmarginleft(pixels)
pixels = :labelmarginleft( )
pathname = :last( )
pathname = :last_selected_item( )
pathname = :last_visible_item( )
:linespacing(pixels)
pixels = :linespacing( )
:marginleft(pixels)
pixels = :marginleft( )
:margintop(pixels)
pixels = :margintop( )
pathname = :next(pathname)
pathname = :next_selected_item(pathname)
pathname = :next_visible_item(pathname)
:openicon(image)
image = :openicon( )
:openchild_marginbottom(pixels)
pixels = :openchild_marginbottom( )
pathname = :prev(pathname)
pathname = :prev_selected_item(pathname)
pathname = :prev_visible_item(pathname)
:remove(pathname)
:root_label(name)
name = :root( )
:scrollbar_size(pixels)
pixels = :scrollbar_size( )
:show_item([pathname], [yoffset])
:show_item_bottom([pathname])
:show_item_middle([pathname])
:show_item_top([pathname])
:selectbox(boxtype)
boxtype = :selectbox( )
:selectmode(treeselect)
treeselect = :selectmode( )
:set_item_focus([pathname])
:showcollapse(boolean)
boolean = :showcollapse( )
:showroot(boolean)
boolean = :showroot( )
:show_self( )
:sortorder(treesort)
treesort = :sortorder( )
:usericon(image)
image = :usericon( )
:usericon_marginleft(pixels)
pixels = :usericon_marginleft( )
:vposition(v)
v = :vposition( )
:item_activate(pathname)
pathname = :item_child(pathname, index)
n = :item_children(pathname)
boolean = :item_close(pathname, [docallback])
:item_deactivate(pathname)
n = :item_depth(pathname)
boolean = :item_deselect([pathname], [docallback])
boolean = :item_deselect_all([pathname], [docallback])
:item_display([pathname])
boolean = :item_displayed([pathname])
index = :item_find_child(pathname, name)
Returns nil if the item pathname has no child named name, otherwise returns its index (1-based).
h = :item_h(pathname)
boolean = :item_has_children(pathname)
boolean = :item_is_active(pathname)
boolean = :item_is_activated(pathname)
boolean = :item_is_close(pathname)
boolean = :item_is_open(pathname)
boolean = :item_is_root(pathname)
boolean = :item_is_selected(pathname)
boolean = :item_is_visible(pathname)
:item_label(pathname, label)
label = :item_label(pathname)
x = :item_label_x(pathname)
y = :item_label_y(pathname)
w = :item_label_w(pathname)
h = :item_label_h(pathname)
:item_labelbgcolor([pathname], color)
color = :item_labelbgcolor([pathname])
pathname=nil to set/get the default color.
:item_labelfgcolor([pathname], color)
color = :item_labelfgcolor([pathname])
pathname=nil to set/get the default color.
:item_labelcolor: alias for :item_labelfgcolor.
:item_labelfont([pathname], font)
font = :item_labelfont([pathname])
pathname=nil to set/get the default font.
:item_labelsize([pathname], fontsize)
fontsize = :item_labelsize([pathname])
pathname=nil to set/get the default font size.
boolean = :item_open(pathname, [docallback])
boolean = :item_open_toggle(pathname, [docallback])
pathname = :item_parent(pathname)
:item_show_self(pathname, [indent])
boolean = :item_select([pathname], [docallback])
boolean = :item_select_all([pathname], [docallback])
boolean = :item_select_only([pathname], [docallback])
boolean = :item_select_toggle([pathname], [docallback])
:item_swap_children(pathname, name₁, name₂)
:item_user_data(pathname, val)
val = :item_user_data(pathname)
val: integer value to associate with the item (may be used to index a Lua table containing more complex data).
:item_usericon(pathname, image)
image = :item_usericon(pathname)
:item_visible(pathname)
boolean = :item_visible_r(pathname)
w = :item_w(pathname)
:item_widget(pathname, widget)
widget = :item_widget(pathname)
x = :item_x(pathname)
y = :item_y(pathname)

window

Rfr: Fl_Window.
Inherits from: widget, group.

window = fl.window(x, y, w, h, [label])
window = fl.window(w, h, [label])
:border(boolean)
boolean = :border( )
:clear_border( )
:clear_modal_states( )
:cursor(cursortype)
:cursor(rgb_image, hotx, hoty)
height = :decorated_h( )
width = :decorated_w( )
:default_cursor(cursortype)
:fullscreen( )
boolean = :fullscreen_active( )
:fullscreen_off( )
:fullscreen_off(x, y, w, h)
:fullscreen_screens(top, bottom, left, right)
:hotspot(widget, [offscreen])
:hotspot(x, y, [offscreen])
:icon(rgb_image)
:iconize( )
:iconlabel(label)
label = :iconlabel( )
:label(label)
label = :label( )
:make_current( )
boolean = :menu_window( )
boolean = :modal( )
boolean = :non_modal( )
boolean = :override( )
:set_menu_window( )
:set_modal( )
:set_non_modal( )
:set_override( )
:set_tooltip_window( )
:shape(image)

:show( )
:show(progname)
:show(args)
:show(progname, [args])
progname: a string denoting the program name.
args: a table with the command-line arguments in its array part (i.e starting from index=1).
(A typical invocation is window:show(arg[0], arg)).
boolean = :shown( )
:size_range(minw, minh, [maxw, maxh, dw, dh, aspect])
boolean = :tooltip_window( )
:wait_for_expose( )
xclass = :xclass( )
x = :x_root( )
y = :y_root( )

double_window

Rfr: Fl_Double_Window.
Inherits from: widget, group, window.

double_window = fl.double_window(x, y, w, h, [label])
double_window = fl.double_window(w, h, [label])
:flush( )

overlay_window

Rfr: Fl_Overlay_Window.
Inherits from: widget, group, window, double_window.
No constructor (abstract class).

boolean = :can_do_overlay( )

gl_window

Rfr: Fl_Gl_Window.
Inherits from: widget, group, window.
No constructor (abstract class).

:can_do( )
boolean = :can_do_overlay( )
:context_valid(boolean)
boolean = :context_valid( )
:hide_overlay( )
:invalidate( )
:flush( )
:make_current( )
:make_overlay_current( )
:mode(mode)
mode = :mode( )
:redraw_overlay( )
:swap_buffers( )
:valid(boolean)
boolean = :valid( )

single_window

Rfr: Fl_Single_Window.
Inherits from: widget, group, window.

single_window = fl.single_window(x, y, w, h, [label])
single_window = fl.single_window(w, h, [label])

menu_window

Rfr: Fl_Menu_Window.
Inherits from: widget, group, window.

menu_window = fl.menu_window(x, y, w, h, [label])
menu_window = fl.menu_window(w, h, [label])
:clear_overlay( )
:erase( )
:flush( )
:set_overlay( )
boolean = :overlay( )

wizard

Rfr: Fl_Wizard.
Inherits from: widget, group.

wizard = fl.wizard(x, y, w, h, [label])
:next( ) :prev( )
:value(widget)
widget = :value( )

input_

Rfr: Fl_Input_.
Inherits from: widget.
RTTI: 'normal', 'float', 'int', 'hidden', 'multiline', 'secret'.
No constructor (abstract class).

boolean = :copy(clipboard)
clipboard: 0 for current text selection, 1 for cut&paste clipboard.
boolean = :copy_cuts( )
:cursor_color(color)
color = :cursor_color( )
boolean = :cut( )
boolean = :cut(n)
boolean = :cut(n₁, n₂)
ucs4 = :index(n)
:input_type(rtti)
rtti = :input_type( )
boolean = :insert(text)
boolean = :mark(m)
m = :mark( )
:maximum_size(nchars)
nchars = :maximum_size( )
:position(pos)
boolean = :position(pos, m)
pos = :position( )
:readonly(boolean)
boolean = :readonly( )
boolean = :replace(begin, end, text)
:shortcut(shortcut)
shortcut = :shortcut( )
:size(w, h)
nbytes = :size( )
:tab_nav(boolean)
boolean = :tab_nav( )
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )
boolean = :undo( )
boolean = :value(text)
text = :value( )
:wrap(boolean)
boolean = :wrap( )

input

Rfr: Fl_Input.
Inherits from: widget, input_.

input = fl.input(x, y, w, h, [label])

file_input

Rfr: Fl_File_Input.
Inherits from: widget, input_, input.

file_input = fl.file_input(x, y, w, h, [label])
:down_box(boxtype)
boxtype = :down_box( )
:errorcolor(color)
color = :errorcolor( )
boolean = :value(text)
text = :value( )

float_input

Rfr: Fl_Float_Input.
Inherits from: widget, input_, input.

float_input = fl.float_input(x, y, w, h, [label])

int_input

Rfr: Fl_Int_Input.
Inherits from: widget, input_, input.

int_input = fl.int_input(x, y, w, h, [label])

multiline_input

Rfr: Fl_Multiline_Input.
Inherits from: widget, input_, input.

multiline_input = fl.multiline_input(x, y, w, h, [label])

output

Rfr: Fl_Output.
Inherits from: widget, input_, input.

output = fl.output(x, y, w, h, [label])

multiline_output

Rfr: Fl_Multiline_Output.
Inherits from: widget, input_, input, output.

multiline_output = fl.multiline_output(x, y, w, h, [label])

secret_input

Rfr: Fl_Secret_Input.
Inherits from: widget, input_, input.

secret_input = fl.secret_input(x, y, w, h, [label])

menu_

Rfr: Fl_Menu_.
Inherits from: widget.
No constructor (abstract class).

index = :add(pathname, [shortcut], [func], [argument], [menuitemflags])
The func callback, if any, is executed as func(menu, pathname, argument).
The argument may be any valid Lua value.

Note

In MoonFLTK a menu item is identified by its pathname and the menu it belongs to (the index is not used). There is no menu_item object. Instead, the methods of the Fl_Menu_Item class are exposed as methods of the menu_ userdata, they are renamed with a leading 'item_' prefix and they accept the item’s pathname as first argument. Similarly, FLTK menu methods accepting or returning an item index or an item pointer map to MoonFLTK menu_ methods accepting or returning the item’s pathname.

:clear( )
:clear_submenu(pathname)
:down_box(boxtype)
boxtype = :down_box( )
:global( )
:mode(pathname, menuitemflags)
menuitemflags = :mode(pathname)
pathname = :mvalue( )
:remove(pathname)
:replace(pathname, newlabel)
:shortcut(pathname, shortcut)
shortcut = :shortcut(pathname)
:size(w, h)
nitems = :size( )
pathname = :test_shortcut( )
label = :text([pathname])
If pathname is not passed, the label of the last picked item is returned (i.e., pathname defaults to menu:mvalue()).
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )
changed = :value(pathname)
pathname = :value( )

:item_activate(pathname)
boolean = :item_active(pathname)
boolean = :item_activevisible(pathname)
:item_argument(pathname, argument)
argument = :item_argument(pathname)
:item_callback(pathname, func)
func = :item_callback(pathname)
boolean = :item_checkbox(pathname)
:item_clear(pathname)
:item_deactivate(pathname)
menuitemflags = :item_flags(pathname)
:item_hide(pathname)
:item_image(pathname, image)
:item_label(pathname, label)
:item_label(pathname, labeltype, label)
label = :item_label(pathname)
:item_labelcolor(pathname, color)
color = :item_labelcolor(pathname)
:item_labelfont(pathname, font)
font = :item_labelfont(pathname)
:item_labelsize(pathname, fontsize)
fontsize = :item_labelsize(pathname)
:item_labeltype(pathname, labeltype)
labeltype = :item_labeltype(pathname)
boolean = :item_radio(pathname)
:item_set(pathname)
:item_setonly(pathname)
:item_shortcut(pathname, shortcut)
shortcut = :item_shortcut(pathname)
:item_show(pathname)
nitems = :item_size(pathname)
Returns the no. of items from this one to the end.
boolean = :item_submenu(pathname)
boolean = :item_value(pathname)
boolean = :item_visible(pathname)

choice

Rfr: Fl_Choice.
Inherits from: widget, menu_.

choice = fl.choice(x, y, w, h, [label])
changed = :value(pathname)
pathname = :value( )

menu_bar

Rfr: Fl_Menu_Bar.
Inherits from: widget, menu_.

menu_bar = fl.menu_bar(x, y, w, h, [label])

menu_button

Rfr: Fl_Menu_Button.
Inherits from: widget, menu_.
RTTI: 'popup1', 'popup2', 'popup12', 'popup3', 'popup13', 'popup23', 'popup123'.

menu_button = fl.menu_button(x, y, w, h, [label])
pathname = :popup( )

progress

Rfr: Fl_Progress.
Inherits from: widget.

progress = fl.progress(x, y, w, h, [label])
:maximum(number)
number = :maximum( )
:minimum(number)
number = :minimum( )
:value(number)
number = :value( )

valuator

Rfr: Fl_Valuator.
Inherits from: widget.
No constructor (abstract class).

:bounds(min, max)
number = :clamp(number)
string = :format( )
number = :increment(step, n)
:maximum(number)
number = :maximum( )
:minimum(number)
number = :minimum( )
:precision(ndigits)
:range(min, max)
number = :round(number)
:step(number)
:step(a, n)
number = :step( )
changed = :value(number)
number = :value( )

adjuster

Rfr: Fl_Adjuster.
Inherits from: widget, valuator.

adjuster = fl.adjuster(x, y, w, h, [label])
:soft(boolean)
boolean = :soft( )

counter

Rfr: Fl_Counter.
Inherits from: widget, valuator.
RTTI: 'normal', 'simple'.

counter = fl.counter(x, y, w, h, [label])
:lstep(number)
:step(number)
:step(step, lstep)
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )

simple_counter

Rfr: Fl_Simple_Counter.
Inherits from: widget, valuator, counter.

simple_counter = fl.simple_counter(x, y, w, h, [label])

dial

Rfr: Fl_Dial.
Inherits from: widget, valuator.
RTTI: 'normal', 'line', 'fill'.

dial = fl.dial(x, y, w, h, [label])
:angle1(deg)
deg = :angle1( )
:angle2(deg)
deg = :angle2( )
:angles(deg₁, deg₂)

fill_dial

Rfr: Fl_Fill_Dial.
Inherits from: widget, valuator, dial.

fill_dial = fl.fill_dial(x, y, w, h, [label])

line_dial

Rfr: Fl_Line_Dial.
Inherits from: widget, valuator, dial.

line_dial = fl.line_dial(x, y, w, h, [label])

roller

Rfr: Fl_Roller.
Inherits from: widget, valuator.
RTTI: 'vertical', 'horizontal'.

roller = fl.roller(x, y, w, h, [label])

slider

Rfr: Fl_Slider.
Inherits from: widget, valuator.
RTTI: 'vertical', 'horizontal', 'vertical fill', 'horizontal fill', 'vertical nice', 'horizontal nice'.

slider = fl.slider(x, y, w, h, [label])
:bounds(min, max)
number = :scrollvalue(pos, size, first, total)
:slider(boxtype)
boxtype = :slider( )
:slider_size(fraction)
fraction = :slider_size( )

fill_slider

Rfr: Fl_Fill_Slider.
Inherits from: widget, valuator, slider.

fill_slider = fl.fill_slider(x, y, w, h, [label])

hor_fill_slider

Rfr: Fl_Hor_Fill_Slider.
Inherits from: widget, valuator, slider.

hor_fill_slider = fl.hor_fill_slider(x, y, w, h, [label])

hor_nice_slider

Rfr: Fl_Hor_Nice_Slider.
Inherits from: widget, valuator, slider.

hor_nice_slider = fl.hor_nice_slider(x, y, w, h, [label])

hor_slider

Rfr: Fl_Hor_Slider.
Inherits from: widget, valuator, slider.

hor_slider = fl.hor_slider(x, y, w, h, [label])

nice_slider

Rfr: Fl_Nice_Slider.
Inherits from: widget, valuator, slider.

nice_slider = fl.nice_slider(x, y, w, h, [label])

scrollbar

Rfr: Fl_Scrollbar.
Inherits from: widget, valuator, slider.
RTTI: 'vertical', 'horizontal'.

scrollbar = fl.scrollbar(x, y, w, h, [label])
:linesize(step)
step = :linesize( )
boolean = :value(pos)
boolean = :value(pos, winsize, first, total)
pos = :value( )

value_slider

Rfr: Fl_Value_Slider.
Inherits from: widget, valuator, slider.

value_slider = fl.value_slider(x, y, w, h, [label])
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )

hor_value_slider

Rfr: Fl_Hor_Value_Slider.
Inherits from: widget, valuator, slider, value_slider.

hor_value_slider = fl.hor_value_slider(x, y, w, h, [label])

value_input

Rfr: Fl_Value_Input.
Inherits from: widget, valuator.

value_input = fl.value_input(x, y, w, h, [label])
:cursor_color(color)
color = :cursor_color( )
:shortcut(shortcut)
shortcut = :shortcut( )
:soft(boolean)
boolean = :soft( )
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )

value_output

Rfr: Fl_Value_Output.
Inherits from: widget, valuator.

value_output = fl.value_output(x, y, w, h, [label])
:soft(boolean)
boolean = :soft( )
:textcolor(color)
color = :textcolor( )
:textfont(font)
font = :textfont( )
:textsize(fontsize)
fontsize = :textsize( )

Images

Image hierarchy

image
├─ bitmap
│ └─ xbm_image
├─ pixmap
│ ├─ gif_image
│ └─ xpm_image
├─ rgb_image
│ ├─ bmp_image
│ ├─ jpeg_image
│ ├─ png_image
│ └─ pnm_image
├─ shared_image
└─ tiled_image

image

Rfr: Fl_Image.
Inherits from: - .

image = fl.image(w, h, d)
fl.rgb_scaling(rgbscaling)
rgbscaling = fl.rgb_scaling( )
:color_average(color, amount)
amount: 0.0 to 1.0.
image = :copy([w, h])
count = :count( )
depth = :d( )
height = :h( )
width = :w( )
:desaturate( )
:draw(x, y, [w, h], [cx, cy])
:inactive( )
:label(widget)
:label(menu, pathname)
The couple (menu, pathname) identifies a menu item.
size = :ld( )
:uncache( )

bitmap

Rfr: Fl_Bitmap.
Inherits from: image.

bitmap = fl.bitmap(data, w, h)

xbm_image

Rfr: Fl_XBM_Image.
Inherits from: image, bitmap.

xbm_image = fl.xbm_image(filename)

pixmap

Rfr: Fl_Pixmap.
Inherits from: image.

pixmap = fl.pixmap(data)
data: a table containing, in its array part, the strings defining the pixmap image.

gif_image

Rfr: Fl_GIF_Image.
Inherits from: image, pixmap.

gif_image = fl.gif_image(filename)

xpm_image

Rfr: Fl_XPM_Image.
Inherits from: image, pixmap.

xpm_image = fl.xpm_image(filename)

rgb_image

Rfr: Fl_RGB_Image.
Inherits from: image.

rgb_image = fl.rgb_image(pixmap, [bgcolor])
rgb_image = fl.rgb_image(bits, w, h, [d=3], [ld=0]) bits: a binary string.
fl.rgb_max_size(size)
size = fl.rgb_max_size( )

bmp_image

Rfr: Fl_BMP_Image.
Inherits from: image, rgb_image.

bmp_image = fl.bmp_image(filename)

jpeg_image

Rfr: Fl_JPEG_Image.
Inherits from: image, rgb_image.

jpeg_image = fl.jpeg_image(filename)

png_image

Rfr: Fl_PNG_Image.
Inherits from: image, rgb_image.

png_image = fl.png_image(filename)

pnm_image

Rfr: Fl_PNM_Image.
Inherits from: image, rgb_image.

pnm_image = fl.pnm_image(filename)

shared_image

Rfr: Fl_Shared_Image.
Inherits from: image.

shared_image = fl.shared_image_get(name, [w, h])
shared_image = fl.shared_image_find(name, [w, h])
shared_image = :copy([w, h])
name = :name( )
refcount = :refcount( )

Note	The release() method is not exposed. It is automatically called when the shared_image object is garbage collected (to release a shared_image, just unreference it).

:reload( )

tiled_image

Rfr: Fl_Tiled_Image.
Inherits from: image.

tiled_image = fl.tiled_image(image, [w , h])
image = :image( )

Devices

Not implemented (yet).

Other classes

help_dialog
native_file_chooser
text_buffer

help_dialog

Rfr: Fl_Help_Dialog.
Inherits from: - .

help_dialog = fl.help_dialog( )
:hide( )
:load(filename)
:position(x, y)
:resize(x, y, w, h)
:show( )
:show(progname)
:show(args)
:show(progname, [args])
Same as window:show()( ).
:textsize(fontsize)
fontsize = :textsize( )
:topline(name)
:topline(n)
:value(text)
text = :value( )
boolean = :visible( )
x = :x( )
y = :y( )
w = :w( )
h = :h( )

native_file_chooser

Rfr: Fl_Native_File_Chooser.
RTTI: 'file' (default), 'directory', 'multi file', 'multi directory', 'save file', 'save directory'.

native_file_chooser = fl.native_file_chooser([rtti])
nitems = :count( )
:directory(dirname)
dirname = :directory( )
errmsg = :errmsg( )
filename = :filenames([i = 1])
The optional i argument must be in the range 1 .. count().
filename₁, …, filename_N = :filenames()
Returns the names of all the selected items (N=count()).
:filter(filter)
filter = :filter( )
:filter_value(i)
i = :filter_value( )
The i argument must be in the range 1 .. filters().
nfilters = :filters( )
:options(opt₁, …, opt_N)
opt₁, …, opt_N = :options( )
opt: 'no options', 'saveas confirm', 'new folder', 'preview', 'use filter ext'.
:preset_file(filename)
filename = :preset_file( )
retval = :show( )
retval: 'ok', 'cancel' or error message (same as errmsg()).
:title(title)
title = :title( )
:type(rtti)
rtti = :type( )

text_buffer

Rfr: Fl_Text_Buffer.

Note	All indices in text buffers are 1-based (Lua-style). Indices denoting a range - usually named start and end - are inclusive (when end is optional it defaults to the buffer’s length). The indices start and end = start - 1 denote a zero length range right before start.

text_buffer indexing example

buf = fl.text_buffer()
buf:text("hello")
                   -- position: 123456789
print(buf:text())           --> hello
print(buf:text_range(1,1))  --> h
print(buf:text_range(1,2))  --> he
print(buf:text_range(1))    --> hello
buf:replace(1,0,"xxx")      --  replaces an empty range (i.e. inserts) before pos=1
print(buf:text())           --> xxxhello

text_buffer = fl.text_buffer([reqsize], [prefgapsize]])
:append(text)
ok, errmsg = :appendfile(filename, [buflen])
byte = :byte_at(pos)
Returns the raw byte found at pos.
:can_undo(boolean)
char, codepoint = :char_at(pos)
Returns the UTF-8 encoded character containing the byte at pos, and its codepoint. The pos argument need not be at a character boundary (the method takes care of aligning it).
:copy(from, start, end, pos)
from is the source text_buffer, (start, end) is the range to be copied and pos is the destination position.
nchars = :count_displayed_characters(linestartpos, targetpos)
nlines = :count_lines(startpos, endpos)
This actually counts the number of newlines ('\n'). Notice that the total number of lines is _count_lines(1) + 1.
:findchar_backward(start, char)
pos = :findchar_forward(start, char)
char: UTF8 encoded character. Returns nil if char is not found.
:highlight(start, [end])
boolean = :highlight( )
start, end = :highlight_position( )
text = :highlight_text( )
boolean = :input_file_was_transcoded( )
:insert(pos, text)
ok, errmsg = :insertfile(filename, pos, [buflen])
nbytes = :length( )
end = :line_end(pos)
start = :line_start(pos)
text = :line_text(pos)
ok, errmsg = :loadfile(filename, [buflen])
start, end = :next_char([pos])
Returns the boundaries of the character following the one containing the byte at pos, or nil if there are none. If pos is none or nil, returns the boundaries of the first character (i.e. start = 1, end = whatever).
ok, errmsg = :outputfile(filename, start, [end], [buflen])
start, end = :prev_char(pos)
Returns the boundaries of the character preceding the one containing the byte at pos, or nil if there are none. If pos is none or nil, returns the boundaries of the last character (i.e. start = whatever, end = length()).
:remove(start, [end])
:remove_secondary_selection( )
:remove_selection( )
:replace(start, end, text)
:replace_secondary_selection(text)
:replace_selection(text)
pos = :rewind_lines(start, nlines)
ok, errmsg = :savefile(filename, [buflen])
pos = :search_backward(start, text, [matchcase])
pos = :search_forward(start, text, [matchcase])
Returns nil if text is not found.
:secondary_select(start, [end])
boolean = :secondary_selected( )
start, end = :secondary_selection_position( )
text = :secondary_selection_text( )
:secondary_unselect( )
:select(start, [end])
boolean = :selected( )
start, end = :selection_position( )
text = :selection_text( )
offset = :skip_displayed_characters(linestart, nchars)
pos = :skip_lines(start, nlines)
:tabs_distance(n)
n = :tabs_distance( )
:text(text)
text = :text( )
text = :text_range(start, [end])
Returns the text between start and end. Raises an error if start is greater than end or than the buffer’s length.
pos = :undo( )
:unhighlight( )
:unselect( )
pos = :utf8_align(pos)
start, end = :word(pos)
text = :word_at(pos)
Returns the UTF-8 encoded word containing the byte at pos.

Modify and predelete callbacks

:call_modify_callback( )
:call_predelete_callback( )
:modify_callback(func, [argument])
If func = nil, unregisters the current callback and argument, otherwise registers func (a function) as the 'modify callback' for this text_buffer. The optional argument may be any valid Lua type.
The callback is executed as func(buf, pos, nins, ndel, nrest, deltext, argument), where buf is this text_buffer, and the other parameters have the same meaning as in the Fl_Text_Modify_Cb type.
:predelete_callback(func, [argument])
If func = nil, unregisters the current callback and argument, otherwise registers func (a function) as the 'predelete callback' for this text_buffer. The optional argument may be any valid Lua type.
The callback is executed as func(buf, pos, ndel, argument), where buf is this text_buffer, and the other parameters have the same meaning as in the Fl_Text_Predelete_Cb type.

Subclassing

Rfr: Adding and Extending Widgets.

In order to extend widgets, and to use widgets such as gl_window that require subclassing, MoonFLTK provides subclass objects. These are Lua userdata bound to instances of subclasses of FLTK widgets, and provided with means to override a few methods of their superclass (draw( ), handle( ), etc.), and to invoke those of the superclass.

Note	Widgets that currently support subclassing are tagged with '(sub)' in the widget hierarchy tree.

The following example shows how to subclass the window widget:

Window subclassing example

fl = require("moonfltk")

-- Subclass 'constructor':
function MyWindow(w, h, label)
    -- Create a 'window sub' object:
    local win = fl.window_sub(w, h, label)
    print("created window", win)
    -- Override the basic window methods:
    win:override_draw(mydraw)
    win:override_handle(myhandle)
    win:override_hide(myhide)
    win:override_resize(myresize)
    return win
end

function mydraw(win)
   assert(win == mywin)
   print("draw()")
   win:super_draw() -- this executes window:draw()
end

function myhandle(win, event)
   assert(win == mywin)
   print("handle('" .. event .. "')")
   -- this must return true or false (see Fl_Widget::handle())
   return win:super_handle(event)
end

function myhide(win)
   assert(win == mywin)
   print("hide()")
   win:super_hide()
end

function myresize(win, x, y, w, h)
   assert(win == win)
   print(string.format("resize(%d, %d, %d, %d)", x, y, w, h))
   win:super_resize(x, y, w, h)
end

mywin = MyWindow(340, 180, arg[0])
mywin:resizable(mywin) -- so that we can try myresize()
mywin:done()
mywin:show()
return fl.run()

A subclass object is instantiated by means of the subclass constructor function (fl.window_sub ( ) in the above example). This function accepts the same parameters as the constructor of the super-class (fl.window ( ), in the example), and has the same name but with a trailing '_sub'.

The object inherits all the methods of the superclass (except for the overridable ones), plus those listed hereafter.

Methods available to all subclasses:

subwidget:override_draw (func)
Overrides the draw( ) method with the func callback, which will be executed as func(subwidget).
subwidget:override_handle (func)
Overrides the handle( ) method with the func callback, which will be executed as func(subwidget, event) and must return a boolean indicating whether the event has been consumed or not.
subwidget:override_hide (func)
Overrides the hide( ) method with the func callback, which will be executed as func(subwidget).
subwidget:override_resize (func)
Overrides the resize( ) method with the func callback, which will be executed as func(subwidget, x, y, w, h).
subwidget:override_show (func)
Overrides the show( ) method with the func callback, which will be executed as func(subwidget).
subwidget:super_draw ( )
Executes the draw( ) method of the superclass.
subwidget:super_handle (event)
→ boolean
Executes the handle( ) method of the superclass.
subwidget:super_hide ( )
Executes the hide( ) method of the superclass.
subwidget:super_resize (x, y, w, h)
Executes the resize( ) method of the superclass.
subwidget:super_show ( )
Executes the show( ) method of the superclass.

Methods available only to overlay_window_sub:

subwidget:override_draw_overlay (func)
Overrides the draw_overlay( ) method with the func callback, which will be executed as func(subwidget).

Methods available only to table_sub and table_row_sub:

subwidget:override_draw_cell (func)
Overrides the draw_cell( ) method with the func callback, which will be executed as func(subwidget, context, r, c, x, y, w, h).
subwidget:super_draw_cell (context, r, c, x, y, w, h)
Executes the draw_cell( ) method of the superclass.

Functions

Main loop

Rfr: Fl.

fl.args(progname, [args])
fl.args(args)
progname: string,
args: {string}.
boolean = fl.check( )
boolean = fl.damage( )
fl.display(string)
fl.flush( )
boolean = fl.gl_visual(mode)
boolean = fl.is_scheme(name)
fl.option(option, boolean)
boolean = fl.option(option)

boolean = fl.ready( )
fl.redraw( )
fl.reload_scheme( )
fl.scheme(name)
name = fl.scheme( )
boolean = fl.run( )
number = fl.version( )
fl.visible_focus(boolean)
boolean = fl.visible_focus( )
boolean = fl.visual(mode)
fl.wait([seconds])
boolean = fl.wait( )
Returns nil if an error occurred.

Windows handling

Rfr: Windows handling functions.

fl.first_window(window)
window = fl.first_window( )
fl.grab(window)
window = fl.grab( )
window = fl.modal( )
window = fl.next_window(window)

Events handling

Rfr: Events handling functions.

fl.belowmouse(widget)
widget = fl.belowmouse( )
fl.disable_im( )
fl.enable_im( )
event = fl.event( )
boolean = fl.event_alt( )
button = fl.event_button( )
button: 'left', 'middle', 'right' (or nil).
boolean = fl.event_button1( )
boolean = fl.event_button2( )
boolean = fl.event_button3( )
left, middle, right = fl.event_buttons( )
left, middle, right: booleans.
fl.event_clicks(nclicks)
nclicks = fl.event_clicks( )
image = fl.event_clipboard( )
Returns nil if the pasted data is not an image.
clipboardtype = fl.event_clipboard_type( )
boolean = fl.event_command( )
boolean = fl.event_ctrl( )
n = fl.event_dx( )
n = fl.event_dy( )
fl.event_inside(x, y, w, h)
boolean = fl.event_inside(widget)
fl.event_is_click(boolean)
boolean = fl.event_is_click( )
fl.event_key(key)
key = fl.event_key( )
n = fl.event_lenght( )
boolean = fl.event_shift( )
modifiers = fl.event_state( )
boolean = fl.event_state(modifiers)
text = fl.event_text( )
pos = fl.event_x( )
pos = fl.event_x_root( )
pos = fl.event_y( )
pos = fl.event_y_root( )
fl.focus(widget)
widget = fl.focus( )
boolean = fl.get_key(key)
x, y = fl.get_mouse( )

Selection & Clipboard

Rfr: Selection & Clipboard functions.

fl.add_clipboard_notify([func])
Registers func as 'clipboard notify callback'. If func is none or nil, unregisters the current callback.
The callback is executed as func(source) where source (a string) may be either 'selection buffer' or 'clipboard'.
boolean = fl.clipboard_contains(clipboardtype)
fl.copy(text, [destination])
destination: 'selection buffer' or 'clipboard'.
fl.dnd( )
fl.dnd_text_ops(boolean)
boolean = fl.dnd_text_ops( )
fl.paste(receiver, source, [clipboardtype])
receiver: a widget.
destination: 'selection buffer' or 'clipboard'.
fl.remove_clipboard_notify( )
Unregisters the current 'clipboard notify callback', if any.
fl.selection(owner, text)
owner: a widget.

Screen

Rfr: Screen functions.

Note	Screens are numbered from 1 to fl.screen_count( ) inclusive.

nscreens = fl.screen_count( )
h, v = fl.screen_dpi([screen = 1])
screen = fl.screen_num(x, y [,w, h])
x, y, w, h = fl.screen_work_area(mx, my)
x, y, w, h = fl.screen_work_area(screen)
x, y, w, h = fl.screen_work_area( )
x, y, w, h = fl.screen_xywh( )
x, y, w, h = fl.screen_xywh(mx, my)
x, y, w, h = fl.screen_xywh(screen)
x, y, w, h = fl.screen_xywh(mx, my, mw, mh)
x = fl.x( )
y = fl.y( )
w = fl.w( )
h = fl.h( )
x, y, w, h = fl.xywh( )

Colors

Rfr: Color & Font functions - Fl.

fl.background(r, g, b)
fl.background2(r, g, b)
fl.color(color)
fl.color(r, g, b)
color = fl.color( )
color = fl.color_average(color₁, color₂, weight)

color = fl.color_cube(r, g, b)
r, g, b: 0 .. fl.NUM_RED/GREEN/BLUE - 1. See FL/Enumerations.H.
color = fl.contrast(fgcolor, bgcolor)
color = fl.darker(color)
fl.free_color(index, [overlay]
fl.foreground(r, g, b)
color, r, g, b = fl.get_color(index)
fl.get_system_colors( )
color = fl.gray_ramp(n)
n: 0 .. fl.NUM_GRAY - 1. See FL/Enumerations.H.
r, g, b = fl.hsv2rgb(h, s, v)
Binding to Fl_Color_Chooser::hsv2rgb().
color = fl.inactive(color)
color = fl.lighter(color)
fl.own_colormap( )
color = fl.rgb_color(r, g, b)
color = fl.rgb_color(n)
Returns the color value closer to (r,g,b), or to n (grayscale). See FL/Enumerations.H.
h, s, v = fl.rgb2hsv(r, g, b)
Binding to Fl_Color_Chooser::rgb2hsv().
fl.set_color(index, fromindex)
fl.set_color(r, g, b)
color = fl.show_colormap(oldcolor)
xpixel = fl.xpixel(index)
xpixel = fl.xpixel(r, g, b)

Fonts

Rfr: Color & Font functions - Fl.

d = fl.descent( )
fl.font(font, [fontsize])
font = fl.font( )
height = fl.height( )
height = fl.height(font, fontsize)
descr = fl.get_font(font)
fontname, fontattr = fl.get_font_name(font)
size₁, …, size_N = fl.get_font_sizes(font)
Returns nil if font is scalable.
fl.latin1_to_local(text, [n])
text = fl.local_to_latin1(text, [n])
nfonts = fl.nfonts( )
Returns the number of available fonts (i.e. the first free font index).
fl.set_font(index, fromindex)
fl.set_font(index, name)
nfonts = fl.setfonts([xstarname])
dx, dy, w, h = fl.text_extents(text)
fontsize = fl.size( )
width = fl.width(text)

Drawing

Rfr: Drawing functions - Fl.

fl.arc(x, y, w, h, a₁, a₂)
fl.arc(x, y, r, start, end)
fl.begin_complex_polygon( )
fl.begin_line( )
fl.begin_loop( )
fl.begin_points( )
fl.begin_polygon( )
offset = fl.box_dh(boxtype)
offset = fl.box_dw(boxtype)
offset = fl.box_dy(boxtype)
offset = fl.box_dz(boxtype)
code = fl.boxtype_code(boxtype)
Returns the 0-255 code for boxtype.
boxdrawfunc = fl.get_boxtype(boxtype)
fl.set_boxtype(boxtype, boxdrawfunc, dx, dy, dw, dh)
fl.set_boxtype(boxtype, fromboxtype)
Get/set the draw function for boxtype. The draw function is executed as boxdrawfunc(x, y, w, h, color).
boolean = fl.can_do_alpha_blending( )
fl.circle(x, y, r)
x, y, w, h = fl.clip_box(x, y, w, h)
fl.cursor(cursortype, [fgcolor], [bgcolor])
fl.curve(x₀, y₀, x₁, y₁, x₂, y₂, x₃, y₃)
fl.draw(deg, text, x, y)
fl.draw(text, x, y)
fl.draw(text, x, y, w, h, alignment, [image], [drawsymbols], [func])
Only the integer code form for alignment is admitted here.
The func text drawing callback, if any, is executed as func(text, x, y).
fl.draw_box(boxtype, x, y, w, h, color)
boolean = fl.draw_box_active( )
fl.draw_image(data, x, y, w, h, depth, linedata)
fl.draw_image_mono(data, x, y, w, h, depth, linedata)
data: a binary string.
fl.draw_pixmap(data, x, y, [color])
data: a table containing, in its array part, the strings defining the pixmap image.
boolean = fl.draw_symbol(label, x, y, w, h, color)
fl.end_complex_polygon( )
fl.end_line( )
fl.end_loop( )
fl.end_points( )
fl.end_polygon( )
fl.frame(s, x, y, w, h)
fl.frame2(s, x, y, w, h)
fl.gap( )
fl.line(x, y, x₁, y₁, [x₂, y₂])
fl.line_style(linestyle, [width], [dashlen₁, dashlen₂, …])
Only the integer code form for linestyle is admitted here.
fl.loop(x, y, x₁, y₁, x₂, y₂, [x₃, y₃])
w, h = fl.measure(text, [w], [drawsymbols] )
w, h = fl.measure_pixmap(data)
data: a table containing, in its array part, the strings defining the pixmap image.
fl.mult_matrix(a, b, c, d, x, y)
boolean = fl.not_clipped(s, x, y, w, h)
fl.overlay_clear( )
fl.overlay_rect(x, y, w, h)
fl.pie(x, y, w, h, a₁, a₂)
fl.point(x, y)
fl.polygon(x, y, x₁, y₁, x₂, y₂, [x₃, y₃])
fl.pop_clip( )
fl.pop_matrix( )
fl.push_clip(x, y, w, h)
fl.push_matrix( )
fl.push_no_clip( )
data = fl.read_image(x, y, w, h, [alpha])
data: binary string containing the RGB or RGBA values.
fl.rect(x, y, w, h, [color])
fl.rectf(x, y, w, h, [color])
fl.rectf(x, y, w, h, r, g, b)
fl.reset_spot( )
fl.restore_clip( )
fl.rotate(deg)
fl.rtl_draw(text, x, y)
fl.scale(x, [y])
fl.scroll(x, y, w, h , dx, dy, func)
The func area drawing callback is executed as func(x, y, w, h).

pixels = fl.scrollbar_size(pixels)
pixels = fl.scrollbar_size( )
fl.set_spot(font, size, x, y, w, h, [window])
fl.set_status(x, y, w, h)
text = fl.shortcut_label(shortcut)
val = fl.transform_dx(x, y)
val = fl.transform_dy(x, y)
val = fl.transform_x(x, y)
val = fl.transform_y(x, y)
fl.transformed_vertex(x, y)
fl.translate(x, y)
fl.vertex(x, y)
fl.xyline(x, y, x₁, [y₂, x₃]))
fl.yxline(x, y, y₁, [x₂, y₃]))

Multithreading

Rfr: Multithreading support functions.

MoonFLTK can be used in conjunction with multithreading libraries such as LuaLanes (thanks to Oliver).

The full "moonfltk" module may be required only by one main thread (the 'foreground thread'). This is the thread where the widgets are to be created and updated.

Any other thread ('background thread') is only allowed to require the "moonfltk.background" module, which is a limited version of MoonFLTK containing only the fl.awake( ) function described below and a few other thread-safe utilities (currently, those listed in the sections 'File names and URI', and 'Unicode and UTF-8').

boolean = fl.awake([message])
Only available in background threads.
Awakes the main thread, optionally queueing a string message.
Returns true if the message was successfully queued or no message was given.
message = fl.thread_message( )
Removes and returns the next message (string) queued with fl.awake( ), or nil if the queue is empty.

Unicode and UTF-8

Rfr: Unicode and UTF-8 functions.
See also Lua’s native UTF-8 Support.

string = fl.utf_tolower(string)
string = fl.utf_toupper(string)
-1|0|+1 = fl.utf_strcasecmp(string₁, string₂)

Common Dialogs

Rfr: Common Dialogs classes functions.

fl.alert(message)
fl.beep(beep)
fl.color_chooser_b(label, r, g, b, [colorchoosermode])
r, g, b = fl.color_chooser_f(label, r, g, b, [colorchoosermode])
Returns nil if the user cancelled the dialog.
The '_b' version works with byte components (0 .. 255), while the '_f' version works with floating point components (0.0 .. 1.0).
dirname = fl.dir_chooser(message, dirname, [relative])
Returns nil if the user cancelled the dialog.
relative: a boolean (true for relative path return, false for absolute path).
filename = fl.file_chooser(message, pattern, filename, [relative])
Returns nil if the user cancelled the dialog.
relative: a boolean (true for relative path return, false for absolute path).
fl.file_chooser_callback([func])
If func is nil or none, unregisters the current file chooser callback (if any).
The func callback is executed as func(filename).
fl.file_chooser_ok_label(label)
fl.message(message)
fl.message_hotspot(boolean)
boolean = fl.message_hotspot( )
fl.message_title(title)
fl.message_title_default(title)
text = fl.password(message, [default])
Returns nil if the user cancelled the dialog.

File names and URI

Rfr: File names and URI utility functions.

uri = fl.decode_uri(uri)
filename = fl.filename_absolute(filename)
filename = fl.filename_expand(filename)
extension = fl.filename_ext(filename)
Returns nil if filename has no extension.
boolean = fl.filename_isdir(filename)
filename1, …, filenameN = fl.filename_list(dirname, [filesort])
boolean = fl.filename_match(string, pattern)
filename = fl.filename_name(pathname)
filename = fl.filename_relative(filename)
extension = fl.filename_setext(filename, extension)
boolean, msg = fl.open_uri(uri)

Tooltips

Rfr: Fl_Tooltip.

fl.tooltip_color(color)
color = fl.tooltip_color( )
fl.tooltip_current(widget)
widget = fl.tooltip_current( )
fl.tooltip_delay(seconds)
seconds = fl.tooltip_delay( )
fl.tooltip_disable( )
fl.tooltip_enable([boolean])
boolean = fl.tooltip_enabled( )
fl.tooltip_font(font)
font = fl.tooltip_font( )
fl.tooltip_hoverdelay(seconds)
seconds = fl.tooltip_hoverdelay( )
fl.tooltip_margin_height(pixels)
pixels = fl.tooltip_margin_height( )
fl.tooltip_margin_width(pixels)
pixels = fl.tooltip_margin_width( )
fl.tooltip_size(fontsize)
fontsize = fl.tooltip_size( )
fl.tooltip_textcolor(color)
color = fl.tooltip_textcolor( )
fl.tooltip_wrap_width(pixels)
pixels = fl.tooltip_wrap_width( )

Handlers

Rfr: Fl.

Check handler

boolean = fl.has_check( )
Returns true if the check handler is set and has not yet been called, false otherwise.
fl.set_check(func)
Sets func (a function) as the check handler. It will be executed as func() (i.e. passing it no arguments). If called with no arguments, removes the handler.

Note	There is a single check handler in MoonFLTK. If multiple handlers are needed, multiplex it in Lua.

File descriptors handler

boolean = fl.has_fd_handler( )
Returns true if the fd handler is set, false otherwise.

fl.set_fd_handler(func)
Sets func (a function) as the fd handler. It will be executed as func(fd) where fd is the affected file handler. If called with no arguments, removes the handler.

Note	There is a single fd handler in MoonFLTK to handle all file descriptors registered with fl.add_fd( ). The file descriptor for a Lua io library file handle can be obtained with the fl.fileno( ) function.

fl.add_fd(fd, whenfd)
Monitor the file descriptor fd. When the file descriptor is ready (depending on the whenfd argument) the fd handler is executed.
fl.remove_fd(fd)
Stop monitoring the file descriptor fd.

Idle handler

boolean = fl.has_idle( )
Returns true if the idle handler is set, false otherwise.
fl.set_idle(func)
Sets func (a function) as the idle handler. It will be executed as func()(i.e. passing it no arguments). If called with no arguments, removes the handler.

Note	There is a single idle handler in MoonFLTK. If multiple handlers are needed, multiplex it in Lua.

Timeout handler

boolean = fl.has_timeout( )
Returns true if the timeout handler is set, false otherwise.

fl.set_timeout(seconds, repeat, func)
Sets the timer so to expire after seconds. At the timer expiration, the func callback will be executed as func() (passing it no arguments). If repeat is true, the timer is automatically restarted at its expiration. If called with no arguments, this function stops the timer and unregisters the callback.

Note	There is a single timeout handler in MoonFLTK. If multiple concurrent timers are needed, the moonfltk.timer module can be used to multiplex it.

moonfltk.timer module

MoonFLTK comes with an optional Lua module, named moonfltk.timer, that uses the single timeout handler to implement a timer heap. The following example shows how to use it.

moonfltk.timer example

fl = require("moonfltk")
timer = require("moonfltk.timer")

-- Init the timer module
timer.init()

tname = {}  -- tname[tid] = timer name
tstart = {} -- tstart[tid] = starting time

-- Callback for timers' expiration:
function texpired(tid)
   local now = fl.gettime()
   print(string.format("timer %s expired (elapsed time: %g seconds)",
          tname[tid], now - tstart[tid]))
   -- restart timer:
   tstart[tid] = timer.start(tid)
end

-- Create a few timers:
t1 = timer.create(2, texpired)
tname[t1] = "T1"
t2 = timer.create(3.1, texpired)
tname[t2] = "T2"

-- Start them:
tstart[t1], errmsg = timer.start(t1)
tstart[t2], errmsg = timer.start(t2)

-- Enter the FLTK main loop:
while true do
   fl.wait(0)
end

The moonfltk.timer module provides the functions described below. Time values are obtained with the fl.gettime( ) function. On error, all these functions return nil followed by an error message.

timer.init( )
Inits the module.
tid = timer.create(timeout, func)
Creates a new timer and returns a unique timer identifier (tid) for subsequent operations. The timeout argument is the default timeout in seconds, which will be used to compute the expiration time if it is not specified when the timer is started. The func argument (a function) is the callback that will be executed as func(tid) at timer expiration.
timer.delete(tid)
Deletes the timer identified by tid.
timer.deleteall( )
Deletes all the timers.
startime = timer.start(tid, [exptime])
Starts the timer identified by tid so to expire at the time exptime.
timer.stop(tid)
Stops the timer identified by tid.
timeut = timer.timeout(tid, [timeout])
Gets/sets the default timeout (in seconds) for the timer identified by tid.
func = timer.callback(tid, [func])
Gets/sets the callback for the timer identified by tid.
boolean, exptime = timer.isrunning(tid)
If the timer is running, returns true and the expiration time, otherwise returns false.

Additional utilities

code = fl.alignment(s₁, …, s_N)
s₁, …, s_N = fl.alignment(code)
Encodes/decodes the FLTK alignment code from/to the string values s₁, …, s_N.

code = fl.damagebits(s₁, …, s_N)
s₁, …, s_N = fl.damagebits(code)
Encodes/decodes the FLTK damagebits code from/to the string values s₁, …, s_N.

fd = fl.fileno(file)
Returns the file descriptor for the Lua io library file handle.

seconds = fl.gettime( )
Returns the current time in seconds.
code = fl.key(s)
s = fl.key(code)
Translates the FLTK key code to/from the corresponding string value s.

code = fl.linestyle(s₁, …, s_N)
s₁, …, s_N = fl.linestyle(code)
Encodes/decodes the FLTK linestyle code from/to the string values s₁, …, s_N.

code = fl.menuitemflags(s₁, …, s_N)
s₁, …, s_N = fl.menuitemflags(code)
Encodes/decodes the FLTK menuitemflags code from/to the string values s₁, …, s_N.

code = fl.mode(s₁, …, s_N)
s₁, …, s_N = fl.mode(code)
Encodes/decodes the FLTK mode code from/to the string values s₁, …, s_N.

code = fl.modifiers(s₁, …, s_N)
s₁, …, s_N = fl.modifiers(code)
Encodes/decodes the FLTK modifiers code from/to the string values s₁, …, s_N.
uuid = fl.new_uuid( )
Binding to Fl_Preferences::newUUID( ), returns an universally unique identifier.

trace_object(boolean)
Enables/disables tracing on stdout of objects creation and deletion (default is disabled).

code = fl.shortcut(s₁, …, s_N)
Encodes an FLTK shortcut code by combining the string values s₁, …, s_N, which must comprise one (and only one) key and zero or more modifiers. For example, this produces the code for the 'Ctrl+S' shortcut: code = fl.shortcut('Ctrl', 's'). Beware that the 'Shift' modifier is implicit in upper-case keys, so passing 'S' instead of 's' would produce the code for the shortcut 'Ctrl+Shift+S'.
s₁, …, s_N = fl.shortcut(code)
Decodes an FLTK shortcut.
fl.sleep(seconds)
Sleep for seconds. This function should not be used, it has been added only to emulate work in progress in the examples.

fl.unreference(object)
Remove the anchor of the MoonFLTK object to the Lua registry (see Unreferencing objects).

code = fl.whenflags(s₁, …, s_N)
s₁, …, s_N = fl.whenflags(code)
Encodes/decodes the FLTK whenflags code from/to the string values s₁, …, s_N.

Enumerations, bitfields, etc.

An enumeration is a string (a literal) from a well defined set of values.

A bitfield, when used as a function argument it may be passed either as an integer code, or as a sequence of strings from a well defined set of values. When it is not the last argument of the function, it may be passed only as an integer code. Functions returning a bitfield return the integer code only (utilities are provided to encode/decode bitfields, if needed).

alignment: bitfield.
Code: a combination of fl.ALIGN_XXX values (corresponding to FL_ALIGN_XXX defines).
Strings: 'default', 'center', 'top', 'bottom', 'left', 'right', 'inside', 'outside', 'text over image', 'image over text', 'image next to text', 'text next to image', 'image backdrop', 'clip', 'no clip', 'wrap', 'no wrap'.

beep: enumeration.
Values: 'default', 'message', 'error', 'question', 'password', 'notification'.

boxtype: enumeration or 0-255 integer code (rfr: Fl_Boxtype).
Values: 'no box', 'flat box', 'up box', 'down box', 'up frame', 'down frame', 'thin up box', 'thin down box', 'thin up frame', 'thin down frame', 'engraved box', 'embossed box', 'engraved frame', 'embossed frame', 'border box', 'shadow box', 'border frame', 'shadow frame', 'rounded box', 'rshadow box', 'rounded frame', 'rflat box', 'round up box', 'round down box', 'diamond up box', 'diamond down box', 'oval box', 'oshadow box', 'oval frame', 'oflat box', 'plastic up box', 'plastic down box', 'plastic up frame', 'plastic down frame', 'plastic thin up box', 'plastic thin down box', 'plastic round up box', 'plastic round down box', 'gtk up box', 'gtk down box', 'gtk up frame', 'gtk down frame', 'gtk thin up box', 'gtk thin down box', 'gtk thin up frame', 'gtk thin down frame', 'gtk round up box', 'gtk round down box', 'gleam up box', 'gleam down box', 'gleam up frame', 'gleam down frame', 'gleam thin up box', 'gleam thin down box', 'gleam round up box', 'gleam round down box', 'free boxtype'.

clipboardtype: enumeration.
Values: 'text/plain', 'image'.

color: RGBI integer code.
FLTK defines for colors are available as fields of the fl table (e.g. fl.FOREGROUND_COLOR for FL_FOREGROUND_COLOR, fl.RED for FL_RED, etc).

colorchoosermode: enumeration.
Values: 'default', 'rgb', 'byte', 'hex', 'hsv'.

cursorstyle: enumeration.
Values: 'normal', 'caret', 'dim', 'block', 'heavy', 'simple'.

cursortype: enumeration.
Values: 'default', 'arrow', 'cross', 'wait', 'insert', 'hand', 'help', 'move', 'ns', 'we', 'nwse', 'nesw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw', 'none'.

damagebits: bitfield.
Code: a combination of fl.DAMAGE_XXX values (corresponding to FL_DAMAGE_XXX defines).
Strings: 'nothing', 'child', 'expose', 'scroll', 'overlay', 'user1', 'user2', 'all'.

event: enumeration.
Values: 'no event', 'push', 'release', 'enter', 'leave', 'drag', 'focus', 'unfocus', 'keydown', 'keyup', 'close', 'move', 'shortcut', 'deactivate', 'activate', 'hide', 'show', 'paste', 'selectionclear', 'mousewheel', 'dnd enter', 'dnd drag', 'dnd leave', 'dnd release', 'screen configuration changed', 'fullscreen'.

filesort: enumeration.
Values: 'alphasort', 'casealphasort', 'numericsort', 'casenumericsort'.

filetype: enumeration.
Values: 'files' or 'directories'.

font: integer code encoding the font index and attributes.
FLTK defines for fonts are available as fields of the fl table (e.g. fl.HELVETICA for FL_HELVETICA, fl.ITALIC for FL_ITALIC, etc).

key: enumeration.
Values: 'button1' .. 'button8', 'backspace', 'tab', 'iso key', 'enter', 'pause', 'scroll lock', 'escape', 'kana', 'eisu', 'yen', 'jis underscore', 'home', 'left', 'up', 'right', 'down', 'page up', 'page down', 'end', 'print', 'insert', 'menu', 'help', 'num lock', 'kp 0' .. 'kp 9', 'kp +', 'kp -', 'kp *', 'kp /', 'kp .', 'kp =', 'kp enter', 'kp middle', 'f1' .. 'f20', 'shift l', 'shift r', 'control l', 'control r', 'caps lock', 'meta l', 'meta r', 'alt l', 'alt r', 'alt gr', 'delete', 'volume down', 'volume mute', 'volume up', 'media play', 'media stop', 'media prev', 'media next', 'home page', 'mail', 'search', 'back', 'forward', 'stop', 'refresh', 'sleep', 'favorites', and any printable UTF-8 character in the code-point range 0..255 (see Fl::event_key( )).

labeltype: enumeration.
Values: 'none', 'normal', 'shadow', 'engraved', 'embossed'.

lineposition: enumeration.
Values: 'top', 'middle', 'bottom'.

linestyle: bitfield.
Code: a combination of fl.XXX values corresponding to FL_XXX defines for line styles (i.e. FL_SOLID, FL_CAP_FLAT, etc.);
Strings: 'solid', 'dash', 'dot', 'dashdot', 'dashdotdot', 'cap flat', 'cap round', 'cap square', 'join miter', 'join round', 'join bevel'.

menuitemflags: bitfield.
Code: a combination of fl.MENU_XXX values (corresponding to FL_MENU_XXX defines);
Strings: 'inactive', 'toggle', 'value', 'radio', 'invisible', 'submenu', 'divider', 'horizontal'.

mode: bitfield.
Code: a combination of fl.XXX values corresponding to FL_XXX defines for mode (i.e. FL_RGB, FL_DOUBLE, etc.);
Strings: 'rgb', 'index', 'single', 'double', 'accum', 'alpha', 'depth', 'stencil', 'rgb8', 'multisample', 'stereo', 'fake single'.

modifiers: bitfield.
Code: a combination of fl.XXX values corresponding to FL_XXX defines for modifiers (i.e. FL_SHIFT, FL_CAPS_LOCK, etc.);
Strings: 'Shift', 'Caps Lock', 'Ctrl', 'Alt', 'Num Lock', 'Meta', 'Scroll Lock', 'Button1' .. 'Button8'.

mousebutton: enumeration.
Values: 'left', 'middle', 'right'.

nativefilechooseroption: sequence of strings.
Values: 'no options', 'saveas confirm', 'new folder', 'preview', 'use filter ext'.

option: enumeration.
Values: 'arrow focus', 'visible focus', 'dnd text', 'show tooltips', 'uses gtk'.

rgbscaling: enumeration.
Values: 'nearest' , 'bilinear'.

rtti: integer code or enumeration.
The FLTK 'RTTI' integer code for the Fl_Widget:type() method, or a string value, if applicable for the specific class (admitted RTTI string values are listed at the beginning of each section describing a class).

scrollbarmode: enumeration.
Values: 'none', 'horizontal', 'vertical', 'both', 'always on', 'horizontal always', 'vertical always', 'both always'.

shortcut: FLTK shortcut integer code.
May be produced with the fl.shortcut( ) utility.

tablecontext: enumeration.
Values: 'none', 'startpage', 'endpage', 'row header', 'col header', 'cell', 'table', 'rc resize'.

treeconnector: enumeration.
Values: 'none', 'dotted', 'solid'.

treereason: enumeration.
Values: 'none', 'startpage', 'endpage', 'row header', 'col header', 'cell', 'table', 'rc resize'.

treeselect: enumeration.
Values: 'none', 'single', 'multi', 'single draggable'.

treesort: enumeration.
Values: 'none', 'ascending', 'descending'.

whenfd: bitfield.
Code: a combination of fl.READ, fl.WRITE and fl.EXCEPT values;
Strings: 'read', 'write', 'except'.

whenflags: bitfield.
Code: a combination of fl.WHEN_XXX values (corresponding to FL_WHEN_XXX defines);
Strings: 'never', 'changed', 'not changed', 'release', 'enter key'.

wrapmode: enumeration.
Values: 'none', 'at column', 'at pixel', 'at bounds'.

Unreferencing objects

Usually you need not care about deletion of MoonFLTK objects (widgets, images, etc) because they are automatically garbage collected when the process exits, provided it exits cleanly closing the Lua state.

There may be, however, situations when you want objects to be collected before than that. For example if you dynamically create lots of them for temporary use only.

To force garbage collection of an object, you need to remove all the references to it and let the Lua garbage collector do its job, like you would do with any other Lua value you want to be collected.

Besides the variables holding the object, there are other references to remove. One is the anchor to the Lua registry (all MoonFLTK objects are anchored to the Lua registry when they are created): this counts as a reference, that you can remove with the fl.unreference( ) function. Other references are the callbacks' arguments: if you use the object as argument for some callback (e.g. if you pass it as arg to the widget:callback( ) method), this also creates a reference that you need to remove; you can do this by unregistering the callback, or by changing its argument to something different than the object you want to delete.

Implementation notes

The following FLTK (1.3.3) features are not - or not yet - implemented in MoonFLTK:

Most Unicode and UTF-8 functions (notice however that Lua already provides basic UTF-8 Support).
Safe widget deletion support functions.
Cairo support functions and classes.
Mac OS X-specific stuff.
GLUT compatibility.
Forms compatibility and most forms classes.
The Fl_Preferences class (Lua itself is good at handling configuration files).
The following classes: Fl_File_Icon, Fl_File_Chooser, Fl_Device and descendants.
The following functionalities of the Fl class: the Fl::readqueue( ) callback mechanism, Fl::set/get_labeltype(), system handlers (Fl::add_system_handler( )), Fl::default_at_close( ), Fl::warning/error/fatal( ).
Fl_Tooltip::enter_area( ).
A few other things here and there (that is, this list is not exhaustive).

Class index

A adjuster

B bitmap - bmp_image - box - browser_ - browser - button

C chart - check_browser - check_button - choice - clock - clock_output - color_chooser - counter

D dial - double_window

F file_browser - file_input - fill_dial - fill_slider - float_input

G gif_image - gl_window - group

H help_dialog - help_view - hold_browser - hor_fill_slider - hor_nice_slider - hor_slider - hor_value_slider

I image - input_choice - input_ - input - int_input

J jpeg_image

L light_button - line_dial

M menu_bar - menu_button - menu_ - menu_item - menu_window - multi_browser - multiline_input - multiline_output

N native_file_chooser - nice_slider

O output - overlay_window

P pack - pixmap - png_image - pnm_image - progress

R radio_button - radio_light_button - radio_round_button - repeat_button - return_button - rgb_image - roller - round_button - round_clock

S scrollbar - scroll - secret_input - select_browser - shared_image - simple_counter - single_window - slider - spinner

T table - table_row - tabs - text_buffer - text_display - text_editor - tiled_image - tile - toggle_button - tooltip - tree

V valuator - value_input - value_output - value_slider

W widget - window - wizard

X xbm_image - xpm_image

1. This manual is written in AsciiDoc, rendered with AsciiDoctor and a CSS from the AsciiDoctor Stylesheet Factory. The PDF version is produced with AsciiDoctor-Pdf.