Outdated egg!
This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.
If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.
stfl
TOC »
Introduction
This egg provides a complete set of bindings to the STFL library.
Author
Vasilij Schneidermann
Repository
https://github.com/wasamasa/stfl
Current state of the bindings
While the bindings are complete, there's still more work to be done
- Write more examples
- Vendor STFL to introduce proper error handling
- Invent an alternative DSL for easier codegen (SXML works pretty good for that)
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
(use extras (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
- Error handling is a crapshoot. The STFL library just calls abort(), leaving a useless coredump behind. This includes, but is not limited to the error handling functions themselves.
- Don't forget calling init! to ensure that the locale is set up correctly for UTF-8 handling to work and to clean up resources at exit
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
0.1
- Initial release