Stfl is a project mainly written in C and C#, based on the LGPL-3.0 license.
My stfl branches and stuff
##########################################################################
##########################################################################
STFL is a library which implements a curses-based widget set for text terminals. The STFL API can be used from C, SPL, Python, Perl and Ruby. The public STFL API is only 14 simple function calls big and there are already generic SWIG bindings. Thus is very easy to port STFL to additional scripting languages.
A special language (the Structured Terminal Forms Language) is used to describe STFL GUIs. The language is designed to be easy and fast to write so an application programmer does not need to spend ages fiddling around with the GUI and can concentrate on the more interesting programming tasks.
There are two different syntaxes for STFL code, one designed to make handwriting of STFL code as easy as possible and one aiming at generated STFL code.
The STFL GUI descriptions (written in STFL code) do not contain any concrete layouting information such as x/y coordinates of widgets. Instead container widgets such as vertical and horizontal boxes as well as tables are used to group widgets and the actual layouting work is done by the STFL library. Thus STFL GUIs can handle terminals of different sizes and terminal resize events transparently for the application programmer.
Simply run 'make' and 'make install'. You might want to edit the Makefile.cfg file before building and installing STFL.
In order to build a full-featured STFL with all scripting language bindings enabled you need to have the following packages installed (including the development packages):
ncursesw
The wide-character ncurses library. On some distributions
this might be part of the ncurses package, on other
distrubutions this might be an extra package.
SWIG
STFL is using SWIG for generating the Perl, Python and Ruby
language bindings.
Perl, Python, Ruby, SPL
In order to create the language bindings you need to have
the languages themself installed.Since STFL is a wide-character library it will only work on systems which do have wide-character support in the system libraries. This might not be the case for in older Linux distributions or other UNIXes.
STFL Forms consist of (instances of) widgets which are organized in a tree. A special language - the Structured Terminal Forms Language - can be used to describe such trees in an efficient and still easy to read and maintain way.
The Structured Terminal Forms Language has only two syntactical constructs: Variable declarations and widget instanciations. Each widget instanciation may contain variable declarations and child widget instanciations.
A widget can be instanciated by simly writing down the type of the widget. Example given:
vboxSometimes one wants to give the instanciated widget a name so the widget can be easily accesed later. This can be done by appending the widget name using square brackets:
label[foobar]Child widgets are instanciated the same way but must be indented:
vbox
label[label1]
label[label2]Note that one must not use tabs for the indenting. Only blanks are allowed.
Variables are declared like child widgets. A variable consists of a key and a value, seperated by a colon. Values can be quoted using single or double quotes when they contain blanks.
vbox
label[label1]
text:"Hello World!"
label[label2]
text:"This is a test.."It is also possible to append an additional name to variables using square brackets so the application can read and write the variable value:
vbox
label[label1]
text[label1_text]:"Hello World!"
label[label2]
text[label2_text]:"This is a test.."Usually variables configure the widget they are directly associated with or store status information from that widget. But sometimes variables contain information about the relationship of the widget they are directly associated with and its parent widget. This variables are always start with a dot.
Example given the .border variable can be used to configure the borders of table cells:
table
label
.border:lrtb
text:"Hello"
label
.border:lrtb
text:"World!"Sometimes one wants to set a variable not only for the current widget but also for all its child widgets. This can be done by prefixing the variable name with he at-sign. Example given:
vbox
@style_normal:fg=white,bg=blue
label
text:"White text.."
label
text:"..on blue background."This kind of variables can also be defined for only one widget type:
vbox
@style_normal:fg=white,bg=blue
@input#style_normal:fg=black,bg=red
label
text:"White text on blue background."
input
text:"Black text on red background."Alternatively it is possible to postfix the widget types with '#classname' and prefix the variables with 'classname#':
vbox
@style_normal:fg=white,bg=blue
@foobar#style_normal:fg=black,bg=red
label
text:"White text on blue background."
input#foobar
text:"Black text on red background."While widget instanciations must alsways be on a new line, variable declarions can also be written on the same line as the widget they are for and it is possible to declare more than one variable in one line:
table
label .border:lrtb text:"Hello"
label
.border:lrtb text:"World!"Sometimes one wants to generate STFL code from scripts. In this cases it can become hard to automatically generate the indenting correctly. For such situations it is possible to use a different format with curly brackets. The following two code fragmentsa are identical:
vbox
hbox
label
.expand:0
text:"Foo: "
input[foo]
text:"Hello"
hbox
label
.expand:0
text:"Bar: "
input[bar]
text:"World!"
{vbox{hbox{label .expand:0 text:"Foo: "}{input[foo] text:"Hello"}
{hbox{label .expand:0 text:"Bar: "}{input[bar] text:"World!"}}}Newline characters are not allowed inside of an STFL code fragment in curly brackets (the example above is just broken up in two line to improve the readability). It is even possible to embed an STFL code fragment in curly brackets in a normal indented code block. Example given:
vbox
{hbox{label .expand:0 text:"Foo: "}{input[foo] text:"Hello"}}
{hbox{label .expand:0 text:"Bar: "}{input[bar] text:"World!"}}It is also possible to include the focus information in STFL code: Simply prefix the widget which shall have the focus with a '!'. Only one widget may have the focus at a time.
The STFL parser can also read external files. This can be done by putting the filename in < > brackets in the STFL file. Note that this is not a varbatim include but calls another parser instance recursively. So there is an extra indenting / curly brackets state for the external file.
Comment lines in STFL code start with a '' character. There must be no statement in the same line as the comment (i.e. only whitespaces are allowed before the '' character). Comment are not allowed within a code fragment in curly brackets.
STFL is using a generic syntax whenever the style (color, etc.) of a text can be specified: A comma seperated key=value list, where the key can be 'bg' for background, 'fg' for foreground and 'attr' for text attributes. Example given the following style string can be used for creating bold blinking white text on blue background:
bg=blue,fg=white,attr=bold,attr=blinkThe following colors are supported:
black
red
green
yellow
blue
magenta
cyan
whiteAnd the following attributes:
standout
underline
reverse
blink
dim
bold
protect
invisOn terminals that support 256 colors it's also possible to use extended colors,
by using "color
The terminal default colors are used when no background or no foreground color is specified. So keep care when only specifying one value. Example given text printed using the style string 'fg=white' can't be seen on terminals with a white default background.
Key descriptings are strings describing a key press event. With some exceptions this are the return values of the ncurses keyname() and key_name() functions. The exceptions are:
ENTER
The return key has been pressed.
SPACE
The space key has been pressed.
TAB
The tabulator key has been pressed.
ESC
The escape key has been pressed.
F0 .. F63
A function key has been pressed.
UNKNOWN
An unkown key has been pressed.
(Usually this is the result of a broken multibyte sequence)A key binding description is a whitespace-seperated list of key descriptions used in bind_* variables to bind keys to widget actions. Each widget provides default bindings for all its actions. If you want to extend the list of bind keys instead of overwriting them you must use the special key-description "**" in the keybinding description to refer to the default bindings.
Key values can e.g. be dumped using the following little Perl script:
perl -mstfl -le '$_ = stfl::create("label text:"Press a key"")->run(0); stfl::reset(); print;'
vbox and hbox
This widgets simply layouts its child widgets vertically or horizontally
repectively. The following variables are supported by both widgets:
bind_left, bind_right
The keybindings in a hbox for changing the focus to the
next or previous child widget. Default values are the
LEFT and RIGHT keys.
bind_up, bind_down
The keybindings in a vbox for changing the focus to the
next or previous child widget. Default values are the UP
and DOWN keys.
style_normal
The background style.
tie
Tie the box containing the widgets to the specified borders.
The value is a string containing the characters 'l' (left
border), 'r' (right border), 't' (top border), 'b' (bottom
border) and 'c' (center). The default value is 'lrtb'.
.tie
Tie this widget within its sub-box to the specified borders.
The value is using the same syntax as the "tie" variable above.
.expand
Contains the information if child widgets should be expanded
to fit the available space. The value is a string that may
contain the characters 'v' (for vertical expansion), 'h' (for
horizontal expansion) and '0' (for no expansion).
The hbox widget ignores the vertical expansion information and
the vbox widget the horizontal expansion information.
The default value is 'vh'.
.height
Hardcode the height of this child widget to the specified
number of lines. Usually one wants to also declare .expand:0
when declaring this variable.
.width
Hardcode the width of this child widget to the specified
number of characters. Usually one wants to also declare
.expand:0 when declaring this variable.
.display
Simply ignore this child widget if this variable is set to '0'.
The default value is '1'.
labelA simple text label. The following variables are supported by this widget:
style_normal
The style used for displaying the text.
text
The text to be displayedinput
A simple input widget for one line of text input. The following variables are
supported by this widget:
bind_left, bind_right
Move the cursor left and right. Default values are the LEFT
and RIGHT keys.
bind_home
Move the cursor to the first character. Default values are
the HOME key or Ctrl-A.
bind_end
Move the cursor after the last character. Default values are
the END key or Ctrl-E.
bind_delete
Delete the character under the cursor. Default value is the
DEL key.
bind_backspace
Delete the character before the cursor. Default value is the
BACKSPACE key.
style_normal
The style of this widget when it does not have the
focus.
style_focus
The style of this widget when it does have the focus.
text
The value displayed in the input box.
pos
The current cursor position in the input box.
offset
The offset of the text displayed in the input box
(when the text is larger then the input box).
tableThe most important container widget. The special widget 'tablebr' is used to mark the begin of a new table row. The following variables are supported by this widget:
bind_left, bind_right, bind_up, bind_down
The keybindings for changing the focus within a table.
Default values are the UP, DOWN, LEFT and RIGHT keys.
style_normal
The style for the table bordes.
.expand
Contains the information if child widgets should be expanded
to fit the available space. The value is a string that may
contain the characters 'v' (for vertical expansion), 'h' (for
horizontal expansion) and '0' (for no expansion).
Since there is just one width for all cells in a column and
just one height for all cells in a row it still may happen
that cells are expanded a bit.
The default value is 'vh'.
.height, .width
Hardcode the height or .width of this table cell to the
specified number of characters. Usually one wants to also
declare .expand:0 when declaring one of this variables.
.colspan, .rowspan
The number of columns or rows for this cell. Default is '1'.
.border
The borders for this cell. This is a string which may contain
the characters 'l', 'r', 't' and 'b' for left, right, top and
bottom borders.
.spacer
Like .border, but only adds a spacer between the cells.
.tie
Tie this table cell within its box to the specified borders.
The value is a string containing the characters 'l' (left
border), 'r' (right border), 't' (top border), 'b' (bottom
border) and 'c' (center). The default value is 'lrtb'.list
The list widget can be used to display a list of items, one per line. The
items are stored as 'listitem' child widgets of the 'list' widget. When
there are more items then the list widget has lines the list widget is
automatically scrolling. The list widget implements the following variables:
bind_up, bind_down
The key bindings for scrolling up or down by line. Default
values are the UP and DOWN keys.
bind_page_up, bind_page_down
The key bindings for scrolling up or down by page. Default
values are the PAGE_UP and PAGE_DOWN keys.
style_focus
Style of the active list item when the widget has the focus.
style_selected
Style of the active list item when the widget has not the
focus.
style_normal
Style of the currently not active list items.
pos
The number of the current list item
pos_name
The widget name of the current list item.
offset
The numer of the list item displayed in the first line (this
becomes >0 when scrolling).
listitemAn in a list widget. Implements the following variables:
text
The text displayed in this list item.textview
A widget for displaying multiline text. The text itself is stored within
listitem child widgets. Implements the following variables:
bind_up, bind_down
The key bindings for scrolling up or down by line. Default
values are the UP and DOWN keys.
bind_page_up, bind_page_down
The key bindings for scrolling up or down by page. Default
values are the PAGE_UP and PAGE_DOWN keys.
style_normal
The style the text itself is displayed.
style_end
The style used for the EOT-Markers.
offset
The number of the first line displayed
(becomes >0 when scrolling).
richtext
Set to '1' to enable richtext support
style_FOOBAR_normal
The style for text after a <FOOBAR>. the </> token can
be used to restore the style_normal settings. this variables
are only used if the 'richtext' variable is set.
Common Variables
----------------
There are some variables which are used by the STFL core to configure some
widget-independent features.
modalA widget which has the modal variable set to '1' will not pass any events to its parent widgets. Eighter the event is handled by the widget itself or it is returned directly to the caller of stfl_run().
autobind
Setting autobind to '0' disables all automatically assigned keybindings for
this widget. Actions which aren't set explicitely bind to keys using the
bind_* variables are left unbind and can't be triggered using the user
interface.
on_*The on* variables can be used to catch keypresses in this widget and return the value of the on variable to the caller of stflrun(). The on variables are evaluated before the keypresses are passed to the widget. The '' part of the on_ variables is a key description. E.g. "on_^X:foobar" will let stfl_run() return the string "foobar" when Ctrl-X is beeing pressed.
STFL has a big C-API which allows a wide range of in-depth operations on widget trees. But most of this C-API is only needed for writing new STFL widgets. The common STFL scripting language API only has a small number of functions and besides the 'form handlers' this functions do only operate on read-only scalar values, so it is pretty easy to write additional bindings for scripting languages not yet supported by STFL.
C API Notes
All functions listed here are also available thru the STFL C-API.
All strings returned by stfl functions are constant and must not be freed or
modified by the caller. When the caller wants to preserve a string for longer
than until the next stfl function call the caller must copy the strings.
All strings passed to STFL functions are considered read-only by STFL and
are neither modified nor freed by STFL.
The functions which may return an undefined value will return a null-pointer
in C. All string parameters which are null-pointers are interpreted as they
where empty strings.
Unicode SupportThe STFL C Library handles all strings as wide character strings (wchar_t*). So the STFL library itself has complete Unicode support.
All current scripting language bindings convert all strings passed between STFL and the scripting language to UTF-8.
Programs using STFL directly might use the STFL "ipool" API for easy conversion betweed wide characters and other encodings.
SPL API Notes
The stfl_free() function is not implemented in SPL because the SPL garbage
collector does call the low-level STFL free function automatically. The
stfl_reset() function is automatically called when the STFL module is unloaded
(i.e. on program termination).
The stfl_quote() function can also be called using the name encode_stfl() so
it can be used with the SPL encoding/quoting operator (::).
Python API NotesThe stfl_free() function is not implemented in Python because the garbage collector does call the low-level STFL free function automatically. The stfl_reset() function is automatically called on program termination.
The functions which take a form as first parameter can also be called as method of the form. All functions are in the "stfl" namespace, so the "stfl_" prefix for the function names is replaced with "stfl." in python.
Perl API Notes
The stfl_free() function is not implemented in Perl because the garbage
collector does call the low-level STFL free function automatically. The
stfl_reset() function is automatically called on program termination.
The functions which take a form as first parameter can also be called as method
of the form. All functions are in the "stfl" namespace, so the "stfl_" prefix
for the function names is replaced with "stfl::" in perl.
Ruby API NotesThe stfl_free() function is not implemented in Perl because the garbage collector does call the low-level STFL free function automatically. The stfl_reset() function is automatically called on program termination.
The functions which take a form as first parameter can also be called as method of the form. All functions are in the "Stfl" namespace, so the "stfl_" prefix for the function names is replaced with "Stfl." in ruby.
stfl_create(text)
Parses the the STFL description text passed as parameter and returns a form
handler. Most of the following functions expect such a form handler as first
parameter.
stfl_free(form)Free all resources associated with this form. On languages with a garbage collector calling this function is optional and might even be implemented as no-op.
stfl_run(form, timeout)
Return the next event. If no more prior generated events are waiting display
the form and process one input character. The event string can be an undefined
value when something chaned in the form (e.g. the user changed the focus of
the current widget) but all inputs have been handled internally inside of STFL.
The event string can be "TIMEOUT" when the timeout has been reached, a key
description is key has been pressed that is not beeing hadled internally in
STFL or the value of an on_* variable can be returned if a keypress has been
catched using such a variable.
The 2nd parameter is a timeout in ms. When no key has been pressed until this
timeout has been reached the function returns with a "TIMEOUT" event. Set this
parameter to 0 to disable the timeout.
When the timeout parameter is set to -1 the form is displayed independent of
the current status of the event queue and the function returns right after
displaying the form without handling any input characters. In this mode always
an undefined value is returned.
When the timeout parameter is set to -2 the displayed is not updated and the
next pending event is returned. If there are no pending events an undefined
value is returned.
When the timeout parameter is set to -3, rendering (and setting the :x, :y, :w
and :h pseudo-variables) is done but the screen is not updated and no events
are fetched. This is usefull for incrementing rendering processes where
appropriate :x, :y, :w and/or :h values are needed for finishing the layout.
stfl_reset()The stfl_run() function automatically activates ncurses. This function can be used to explicitely switch back to normal text mode. In some languages this is automatically done on program termination.
stfl_get(form, name)
Returns the current value of the specified variable. When the variable does not
exist this function returns an undefined value.
stfl_set(form, name, value)This sets the specified variable to the specified value.
stfl_get_focus(form)
Returns the name of the widget which currently has the focus or an undefined
value when the widget having the focus has no name.
stfl_set_focus(form, name)Set the focus to the specified widget.
stfl_quote(text)
Quote the text so it can be savely used as variable value in STFL code.
stfl_dump(form, name, prefix, focus)Return the subtree starting with the widget specified in the 2nd parameter as STFL code fragment. The entire form is return when the 2nd parameter is an empty string or undefined. All widget and variable names in the dump are prefixed with the string in the 3rd parameter. The information which widget has the focus is also included in the dump when the 4th parameter is an integer not equal 0.
The function returns an undefined value when there was an error.
stfl_modify(form, name, mode, text)
Import the STFL code specified in the 4th parameter to an existing form. The
2nd parameter is used to specify a widget which is used as starting point for
the modification. The 3rd parameter is a string specifying how the new STFL
code should be added to the widget tree:
delete
Delete the widget. The 4th parameter is ignored in this mode.
replace
Replace the widget in the tree with the new tree.
replace_inner
Replace the child list of the widget with the child list
of the root element of the new tree.
insert
Add the new tree at the begin of the child list of the widget.
insert_inner
Add the child list of the root element of the new tree at the
begin of the child list of the widget.
append
Add the new tree at the end of the child list of the widget.
append_inner
Add the child list of the root element of the new tree at the
end of the child list of the widget.
before
Add the new tree before the widget.
before_inner
Add the child list of the root element of the new tree before
the widget.
after
Add the new tree after the widget.
after_inner
Add the child list of the root element of the new tree after
the widget.
The widget type of the root element of the tree passed in the 4th parameter
doesn't matter in the *_inner modes.
stfl_lookup(form, path, newname)Lookup widgets in the form using a path and optionally assign a new name.
This function is not implemented yet.
stfl_error()
Return the error status of the last STFL call. This is undefined when no error
occoured and the error message otherwise. An error could e.g. be a parser
error for broken STFL code.
WARNING: This is a planned feature! This version of STFL simply calls abort()
if an internal error is catched.
stfl_error_action(mode)Set the error handling algorithm. The following strings are valid as mode parameter:
abort
Print error message to stderr and call the abort() function.
exit
Print error message to stderr and call exit(1).
print
Print error message to stderr and continue execution.
interactive
Display a little menu and let the user decide what to do.
none
Do nothing - just continue program execution.The default mode is "interactive".
WARNING: This is a planned feature! This version of STFL simply calls abort() if an internal error is catched.
When a widget has a name (declared using the 'widget[name]' syntax in the STFL code), there are also some special pseudo-variables which can only be accessed for reading. Note that this pseudo-variables do only have valid values after the widget has been drawed already. So it is always a good idea to run stfl_run() with a timeout of -1 before accessing the pseudo-variables.
widgetname:x
The absolute x-position of the widget on the screen. (from the left border)
widgetname:yThe absolute y-position of the widget on the screen. (from the upper border)
widgetname:w
The width of the widget.
widgetname:hThe height of the widget.
widgetname:minw
The minimal width (i.e. before expanding) of the widget.
widgetname:minhThe minimal height (i.e. before expanding) of the widget.