((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/stfl" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "stfl" (toc) (section 3 "Introduction" (p "This egg provides a complete set of bindings to the " (link "http://www.clifford.at/stfl/" "STFL") " library.")) (section 3 "Author" (p "Vasilij Schneidermann")) (section 3 "Repository" (p (link "https://github.com/wasamasa/stfl"))) (section 3 "Current state of the bindings" (p "While the bindings are complete, there's still more work to be done") (ul (li "Write more examples") (li "Vendor STFL to introduce proper error handling") (li "Invent an alternative DSL for easier codegen (SXML works pretty good for that)"))) (section 3 "Requirements" (p "Install the STFL library with your operating system's package manager.")) (section 3 "API" (section 4 "init!" (def (sig (procedure "(init!)" (id init!))) (p "Initialize STFL.  Currently this sets the program's locale to the global locale to handle UTF-8 correctly and adds the " (tt "clean-up!") " procedure to the exit and exception handlers."))) (section 4 "create" (def (sig (procedure "(create description)" (id create))) (p "Creates a form from the textual " (tt "DESCRIPTION") " which is described in the textual DSL section.  The returned " (tt "form") " record is a required argument for many of the following functions, its resources are freed automatically by the garbage collector."))) (section 4 "clean-up!" (def (sig (procedure "(clean-up!)" (id clean-up!))) (p "Frees all STFL-specific resources other than forms.  This is added by the " (tt "init!") " procedure to the exit and exception handlers and doesn't need to be run if you're using " (tt "init!") "."))) (section 4 "run!" (def (sig (procedure "(run! form timeout)" (id run!))) (p "Performs an event loop iteration for " (tt "FORM") " and returns a textual event description.  It may be " (tt "#f") " if no event happened or " (tt "\"TIMEOUT\"") " if no event has been handled.  The " (tt "TIMEOUT") " argument is a timeout in milliseconds.  There are a number of special timeout values:") (dl (dt (tt "0")) (dd "Disable timeout and wait indefinitely until the next event") (dt (tt "-1")) (dd "Update the form and return immediately with " (tt "#f")) (dt (tt "-2")) (dd "Update the form and return the next pending event or " (tt "#f")) (dt (tt "-3")) (dd "Rerender the form, but don't update the screen and don't fetch events")))) (section 4 "reset!" (def (sig (procedure "(reset!)" (id reset!))) (p "Switch from ncurses mode to normal text mode.  This is done by the " (tt "clean-up!") " procedure when throwing exceptions or quitting the program."))) (section 4 "redraw!" (def (sig (procedure "(redraw!)" (id redraw!))) (p "Redraw the screen, similar to " (tt "^L") " in ncurses programs."))) (section 4 "get-value" (def (sig (procedure "(get-value form name)" (id get-value))) (p "Return the value of the variable specified by " (tt "NAME") " in " (tt "FORM") " or " (tt "#f") " if there's no variable by that name."))) (section 4 "set-value!" (def (sig (procedure "(set-value! form name value)" (id set-value!))) (p "Set the value of the variable specified by " (tt "NAME") " in " (tt "FORM") " to " (tt "VALUE") "."))) (section 4 "get-focus" (def (sig (procedure "(get-focus form)" (id get-focus))) (p "Return the name of the currently focused widget in " (tt "FORM") " or " (tt "#f") " if the focused widget doesn't have a name."))) (section 4 "set-focus!" (def (sig (procedure "(set-focus! form name)" (id set-focus!))) (p "Focus the widget specified by " (tt "NAME") " in " (tt "FORM") "."))) (section 4 "quote-text" (def (sig (procedure "(quote-text text)" (id quote-text))) (p "Return a quoted version of " (tt "TEXT") " for usage in the textual DSL."))) (section 4 "get-text" (def (sig (procedure "(get-text form name)" (id get-text))) (p "Return the text value of the text field " (tt "NAME") " in " (tt "FORM") ".  If there is more than one, all text values are concatenated to a single string."))) (section 4 "dump" (def (sig (procedure "(dump form #!key name prefix focus)" (id dump))) (p "Returns the textual DSL representing " (tt "FORM") ".  If " (tt "NAME") " is given, dump that widget only.  If " (tt "PREFIX") " is given, prepend that string to the widget names.  If " (tt "FOCUS") " is " (tt "#t") ", include information about what widget has focus."))) (section 4 "modify!" (def (sig (procedure "(modify! form name mode #!optional text)" (id modify!))) (p "Changes the textual DSL in " (tt "FORM") " for the widget specified by " (tt "NAME") ".  " (tt "MODE") " must be one of the following strings, with " (tt "TEXT") " being an optional argument:") (dl (dt (tt "\"delete\"")) (dd "Delete the widget (" (tt "TEXT") " isn't required)") (dt (tt "\"replace\"")) (dd "Replace the widget with " (tt "TEXT")) (dt (tt "\"replace_inner\"")) (dd "Like " (tt "\"replace\"") ", but on the child lists") (dt (tt "\"insert\"")) (dd "Insert " (tt "TEXT") " before the other children") (dt (tt "\"insert_inner\"")) (dd "Like " (tt "\"insert\"") ", but on a child list") (dt (tt "\"append\"")) (dd "Append " (tt "TEXT") " after the other children") (dt (tt "\"append_inner\"")) (dd "Like " (tt "\"append\"") ", but on a child list") (dt (tt "\"before\"")) (dd "Insert " (tt "TEXT") " before the widget") (dt (tt "\"before_inner\"")) (dd "Like " (tt "\"before\"") ", but on a child list") (dt (tt "\"after\"")) (dd "Append " (tt "TEXT") " after the widget") (dt (tt "\"after_inner\"")) (dd "Like " (tt "\"after\"") ", but on a child list")))) (section 4 "get-error" (def (sig (procedure "(get-error)" (id get-error))) (p "Returns the last error message or " (tt "#f") " if no error occurred.") (p "Don't call this procedure, it hasn't been implemented yet and will " (tt "abort()") " your program."))) (section 4 "set-error-action!" (def (sig (procedure "(set-error-action! mode)" (id set-error-action!))) (p "Change the error behavior to " (tt "MODE") " which must be one of the following strings: " (tt "(\"abort\" \"exit\" \"print\" \"interactive\" \"none\")") ".") (p "Don't call this procedure, it hasn't been implemented yet and will " (tt "abort()") " your program.")))) (section 3 "Textual DSL" (p "Please consult " (link "http://svn.clifford.at/stfl/trunk/README" "the official documentation") " for it.")) (section 3 "Examples" (highlight scheme "(use extras (prefix stfl stfl:))\n\n(define layout #<<EOT\ntable\n  list[list]\n    .expand:h\n    .border:lrtb\n    pos[listpos]:0\n    pos_name[listposname]:li0\n    listitem[li0] text[li0text]:\"ListItem 0\"\n    listitem[li1] text[li1text]:\"ListItem 1\"\n    listitem[li2] text[li2text]:\"ListItem 2\"\n  tablebr\n  label[label]\n    .expand:h\n    .border:lrtb\n    text[labeltext]:\nEOT\n)\n\n(stfl:init!)\n\n(define form (stfl:create layout))\n\n(let loop ()\n  (let* ((event (stfl:run! form 0))\n         (pos (stfl:get-value form \"listpos\"))\n         (pos-name (stfl:get-value form \"listposname\"))\n         (text (stfl:get-value form (format \"~atext\" pos-name)))\n         (label-text (format \"List is at position ~a, name ~a, text ~a\"\n                             pos pos-name text)))\n    (stfl:set-value! form \"labeltext\" label-text)\n    (cond\n     ((equal? event \"ESC\") #f)\n     ((equal? event \"^L\") (stfl:redraw!) (loop))\n     (else (loop)))))") (p "Further examples can be found " (link "https://github.com/wasamasa/stfl/tree/master/examples" "in the repository") ".")) (section 3 "Notes" (ul (li "Error handling is a crapshoot.  The STFL library just calls " (tt "abort()") ", leaving a useless coredump behind.  This includes, but is not limited to the error handling functions themselves.") (li "Don't forget calling " (tt "init!") " to ensure that the locale is set up correctly for UTF-8 handling to work and to clean up resources at exit"))) (section 3 "License" (pre "Copyright 2017 Vasilij Schneidermann\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or (at\nyour option) any later version.\n\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\nGeneral Public License for more details.\n\nA full copy of the GPL license can be found at\n<http://www.gnu.org/licenses/>.")) (section 3 "Version history" (section 4 "0.1" (ul (li "Initial release"))))))