chickadee » stfl

stfl

Introduction

This egg provides a complete set of bindings to the STFL library.

Author

Vasilij Schneidermann

Repository

https://depp.brause.cc/stfl

Current state of the bindings

While the bindings are complete, there's still more work to be done

Requirements

Install the STFL library with your operating system's package manager.

API

init!

init!procedure

Initialize STFL. Currently this sets the program's locale to the global locale to handle UTF-8 correctly and adds the clean-up! procedure to the exit and exception handlers.

create

create descriptionprocedure

Creates a form from the textual DESCRIPTION which is described in the textual DSL section. The returned form record is a required argument for many of the following functions, its resources are freed automatically by the garbage collector.

clean-up!

clean-up!procedure

Frees all STFL-specific resources other than forms. This is added by the init! procedure to the exit and exception handlers and doesn't need to be run if you're using init!.

run!

run! form timeoutprocedure

Performs an event loop iteration for FORM and returns a textual event description. It may be #f if no event happened or "TIMEOUT" if no event has been handled. The TIMEOUT argument is a timeout in milliseconds. There are a number of special timeout values:

0
Disable timeout and wait indefinitely until the next event
-1
Update the form and return immediately with #f
-2
Update the form and return the next pending event or #f
-3
Rerender the form, but don't update the screen and don't fetch events

reset!

reset!procedure

Switch from ncurses mode to normal text mode. This is done by the clean-up! procedure when throwing exceptions or quitting the program.

redraw!

redraw!procedure

Redraw the screen, similar to ^L in ncurses programs.

get-value

get-value form nameprocedure

Return the value of the variable specified by NAME in FORM or #f if there's no variable by that name.

set-value!

set-value! form name valueprocedure

Set the value of the variable specified by NAME in FORM to VALUE.

get-focus

get-focus formprocedure

Return the name of the currently focused widget in FORM or #f if the focused widget doesn't have a name.

set-focus!

set-focus! form nameprocedure

Focus the widget specified by NAME in FORM.

quote-text

quote-text textprocedure

Return a quoted version of TEXT for usage in the textual DSL.

get-text

get-text form nameprocedure

Return the text value of the text field NAME in FORM. If there is more than one, all text values are concatenated to a single string.

dump

dump form #!key name prefix focusprocedure

Returns the textual DSL representing FORM. If NAME is given, dump that widget only. If PREFIX is given, prepend that string to the widget names. If FOCUS is #t, include information about what widget has focus.

modify!

modify! form name mode #!optional textprocedure

Changes the textual DSL in FORM for the widget specified by NAME. MODE must be one of the following strings, with TEXT being an optional argument:

"delete"
Delete the widget (TEXT isn't required)
"replace"
Replace the widget with TEXT
"replace_inner"
Like "replace", but on the child lists
"insert"
Insert TEXT before the other children
"insert_inner"
Like "insert", but on a child list
"append"
Append TEXT after the other children
"append_inner"
Like "append", but on a child list
"before"
Insert TEXT before the widget
"before_inner"
Like "before", but on a child list
"after"
Append TEXT after the widget
"after_inner"
Like "after", but on a child list

get-error

get-errorprocedure

Returns the last error message or #f if no error occurred.

Don't call this procedure, it hasn't been implemented yet and will abort() your program.

set-error-action!

set-error-action! modeprocedure

Change the error behavior to MODE which must be one of the following strings: ("abort" "exit" "print" "interactive" "none").

Don't call this procedure, it hasn't been implemented yet and will abort() your program.

Textual DSL

Please consult the official documentation for it.

Examples

(import (chicken format)
(import (prefix stfl stfl:))

(define layout #<<EOT
table
  list[list]
    .expand:h
    .border:lrtb
    pos[listpos]:0
    pos_name[listposname]:li0
    listitem[li0] text[li0text]:"ListItem 0"
    listitem[li1] text[li1text]:"ListItem 1"
    listitem[li2] text[li2text]:"ListItem 2"
  tablebr
  label[label]
    .expand:h
    .border:lrtb
    text[labeltext]:
EOT
)

(stfl:init!)

(define form (stfl:create layout))

(let loop ()
  (let* ((event (stfl:run! form 0))
         (pos (stfl:get-value form "listpos"))
         (pos-name (stfl:get-value form "listposname"))
         (text (stfl:get-value form (format "~atext" pos-name)))
         (label-text (format "List is at position ~a, name ~a, text ~a"
                             pos pos-name text)))
    (stfl:set-value! form "labeltext" label-text)
    (cond
     ((equal? event "ESC") #f)
     ((equal? event "^L") (stfl:redraw!) (loop))
     (else (loop)))))

Further examples can be found in the repository.

Notes

License

Copyright 2017 Vasilij Schneidermann

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>.

Version history

1.1

1.0

0.1

Contents »