source: project/wiki/eggref/4/stfl @ 34892

Last change on this file since 34892 was 34892, checked in by Vasilij Schneidermann, 4 years ago

Add stfl documentation

File size: 7.0 KB
Line 
1== stfl
2
3[[toc:]]
4
5=== Introduction
6
7This egg provides a complete set of bindings to the
8[[http://www.clifford.at/stfl/|STFL]] library.
9
10=== Author
11
12Vasilij Schneidermann
13
14=== Repository
15
16[[https://github.com/wasamasa/stfl]]
17
18=== Current state of the bindings
19
20While the bindings are complete, there's still more work to be done
21
22* Write more examples
23* Vendor STFL to introduce proper error handling
24* Invent an alternative DSL for easier codegen (SXML works pretty good
25  for that)
26
27=== Requirements
28
29Install the STFL library with your operating system's package manager.
30
31=== API
32
33==== init!
34
35<procedure>(init!)</procedure>
36
37Initialize STFL.  Currently this sets the program's locale to the
38global locale to handle UTF-8 correctly and adds the {{clean-up!}}
39procedure to the exit and exception handlers.
40
41==== create
42
43<procedure>(create description)</procedure>
44
45Creates a form from the textual {{DESCRIPTION}} which is described in
46the textual DSL section.  The returned {{form}} record is a required
47argument for many of the following functions, its resources are freed
48automatically by the garbage collector.
49
50==== clean-up!
51
52<procedure>(clean-up!)</procedure>
53
54Frees all STFL-specific resources other than forms.  This is added by
55the {{init!}} procedure to the exit and exception handlers and doesn't
56need to be run if you're using {{init!}}.
57
58==== run!
59
60<procedure>(run! form timeout)</procedure>
61
62Performs an event loop iteration for {{FORM}} and returns a textual
63event description.  It may be {{#f}} if no event happened or
64{{"TIMEOUT"}} if no event has been handled.  The {{TIMEOUT}} argument
65is a timeout in milliseconds.  There are a number of special timeout
66values:
67
68; {{0}} : Disable timeout and wait indefinitely until the next event
69; {{-1}} : Update the form and return immediately with {{#f}}
70; {{-2}} : Update the form and return the next pending event or {{#f}}
71; {{-3}} : Rerender the form, but don't update the screen and don't fetch events
72
73==== reset!
74
75<procedure>(reset!)</procedure>
76
77Switch from ncurses mode to normal text mode.  This is done by the
78{{clean-up!}} procedure when throwing exceptions or quitting the
79program.
80
81==== redraw!
82
83<procedure>(redraw!)</procedure>
84
85Redraw the screen, similar to {{^L}} in ncurses programs.
86
87==== get-value
88
89<procedure>(get-value form name)</procedure>
90
91Return the value of the variable specified by {{NAME}} in {{FORM}} or
92{{#f}} if there's no variable by that name.
93
94==== set-value!
95
96<procedure>(set-value! form name value)</procedure>
97
98Set the value of the variable specified by {{NAME}} in {{FORM}} to
99{{VALUE}}.
100
101==== get-focus
102
103<procedure>(get-focus form)</procedure>
104
105Return the name of the currently focused widget in {{FORM}} or {{#f}}
106if the focused widget doesn't have a name.
107
108==== set-focus!
109
110<procedure>(set-focus! form name)</procedure>
111
112Focus the widget specified by {{NAME}} in {{FORM}}.
113
114==== quote-text
115
116<procedure>(quote-text text)</procedure>
117
118Return a quoted version of {{TEXT}} for usage in the textual DSL.
119
120==== get-text
121
122<procedure>(get-text form name)</procedure>
123
124Return the text value of the text field {{NAME}} in {{FORM}}.  If
125there is more than one, all text values are concatenated to a single
126string.
127
128==== dump
129
130<procedure>(dump form #!key name prefix focus)</procedure>
131
132Returns the textual DSL representing {{FORM}}.  If {{NAME}} is given,
133dump that widget only.  If {{PREFIX}} is given, prepend that string to
134the widget names.  If {{FOCUS}} is {{#t}}, include information about
135what widget has focus.
136
137==== modify!
138
139<procedure>(modify! form name mode #!optional text)</procedure>
140
141Changes the textual DSL in {{FORM}} for the widget specified by
142{{NAME}}.  {{MODE}} must be one of the following strings, with
143{{TEXT}} being an optional argument:
144
145; {{"delete"}} : Delete the widget ({{TEXT}} isn't required)
146; {{"replace"}} : Replace the widget with {{TEXT}}
147; {{"replace_inner"}} : Like {{"replace"}}, but on the child lists
148; {{"insert"}} : Insert {{TEXT}} before the other children
149; {{"insert_inner"}} : Like {{"insert"}}, but on a child list
150; {{"append"}} : Append {{TEXT}} after the other children
151; {{"append_inner"}} : Like {{"append"}}, but on a child list
152; {{"before"}} : Insert {{TEXT}} before the widget
153; {{"before_inner"}} : Like {{"before"}}, but on a child list
154; {{"after"}} : Append {{TEXT}} after the widget
155; {{"after_inner"}} : Like {{"after"}}, but on a child list
156
157==== get-error
158
159<procedure>(get-error)</procedure>
160
161Returns the last error message or {{#f}} if no error occurred.
162
163Don't call this procedure, it hasn't been implemented yet and will
164{{abort()}} your program.
165
166==== set-error-action!
167
168<procedure>(set-error-action! mode)</procedure>
169
170Change the error behavior to {{MODE}} which must be one of the
171following strings: {{("abort" "exit" "print" "interactive" "none")}}.
172
173Don't call this procedure, it hasn't been implemented yet and will
174{{abort()}} your program.
175
176=== Textual DSL
177
178Please consult [[http://svn.clifford.at/stfl/trunk/README|the official
179documentation]] for it.
180
181=== Examples
182
183<enscript highlight="scheme">
184(use extras (prefix stfl stfl:))
185
186(define layout #<<EOT
187table
188  list[list]
189    .expand:h
190    .border:lrtb
191    pos[listpos]:0
192    pos_name[listposname]:li0
193    listitem[li0] text[li0text]:"ListItem 0"
194    listitem[li1] text[li1text]:"ListItem 1"
195    listitem[li2] text[li2text]:"ListItem 2"
196  tablebr
197  label[label]
198    .expand:h
199    .border:lrtb
200    text[labeltext]:
201EOT
202)
203
204(stfl:init!)
205
206(define form (stfl:create layout))
207
208(let loop ()
209  (let* ((event (stfl:run! form 0))
210         (pos (stfl:get-value form "listpos"))
211         (pos-name (stfl:get-value form "listposname"))
212         (text (stfl:get-value form (format "~atext" pos-name)))
213         (label-text (format "List is at position ~a, name ~a, text ~a"
214                             pos pos-name text)))
215    (stfl:set-value! form "labeltext" label-text)
216    (cond
217     ((equal? event "ESC") #f)
218     ((equal? event "^L") (stfl:redraw!) (loop))
219     (else (loop)))))
220</enscript>
221
222Further examples can be found
223[[https://github.com/wasamasa/stfl/tree/master/examples|in the
224repository]].
225
226=== Notes
227
228* Error handling is a crapshoot.  The STFL library just calls
229  {{abort()}}, leaving a useless coredump behind.  This includes, but
230  is not limited to the error handling functions themselves.
231* Don't forget calling {{init!}} to ensure that the locale is set up
232  correctly for UTF-8 handling to work and to clean up resources at
233  exit
234
235=== License
236
237 Copyright 2017 Vasilij Schneidermann
238 
239 This program is free software: you can redistribute it and/or modify
240 it under the terms of the GNU General Public License as published by
241 the Free Software Foundation, either version 3 of the License, or (at
242 your option) any later version.
243 
244 This program is distributed in the hope that it will be useful, but
245 WITHOUT ANY WARRANTY; without even the implied warranty of
246 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
247 General Public License for more details.
248 
249 A full copy of the GPL license can be found at
250 <http://www.gnu.org/licenses/>.
251
252=== Version history
253
254==== 0.1
255
256* Initial release
Note: See TracBrowser for help on using the repository browser.