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
  1. Outdated egg!
  2. stfl
    1. Introduction
    2. Author
    3. Repository
    4. Current state of the bindings
    5. Requirements
    6. API
      1. init!
      2. create
      3. clean-up!
      4. run!
      5. reset!
      6. redraw!
      7. get-value
      8. set-value!
      9. get-focus
      10. set-focus!
      11. quote-text
      12. get-text
      13. dump
      14. modify!
      15. get-error
      16. set-error-action!
    7. Textual DSL
    8. Examples
    9. Notes
    10. License
    11. Version history
      1. 0.1

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

Requirements

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

API

init!

[procedure] (init!)

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

[procedure] (create description)

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!

[procedure] (clean-up!)

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!

[procedure] (run! form timeout)

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!

[procedure] (reset!)

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

redraw!

[procedure] (redraw!)

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

get-value

[procedure] (get-value form name)

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

set-value!

[procedure] (set-value! form name value)

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

get-focus

[procedure] (get-focus form)

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

set-focus!

[procedure] (set-focus! form name)

Focus the widget specified by NAME in FORM.

quote-text

[procedure] (quote-text text)

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

get-text

[procedure] (get-text form name)

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

[procedure] (dump form #!key name prefix focus)

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!

[procedure] (modify! form name mode #!optional text)

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

[procedure] (get-error)

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!

[procedure] (set-error-action! mode)

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

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