« back to all changes in this revision
Viewing changes to README
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Nico Golde
- Date: 2007-03-31 12:16:20 UTC
- Revision ID: james.westby@ubuntu.com-20070331121620-nzaxq7a287387r54
Tags: upstream-0.8
Import upstream version 0.8
- files added:
- perl5
- python
- ruby
- spl
- swig
- widgets
added
removed
README
1
2
##########################################################################
3
# #
4
# STFL - The Structured Terminal Forms Language/Library #
5
# Copyright (C) 2006 Clifford Wolf <clifford@clifford.at> #
6
# #
7
# This program is free software; you can redistribute it and/or modify #
8
# it under the terms of the GNU General Public License as published by #
9
# the Free Software Foundation; either version 2 of the License, or #
10
# (at your option) any later version. #
11
# #
12
##########################################################################
13
14
15
STFL - Structured Terminal Forms Language/Library
16
=================================================
17
18
STFL is a library which implements a curses-based widget set for text
19
terminals. The STFL API can be used from C, SPL, Python, Perl and Ruby. The
20
public STFL API is only 14 simple function calls big and there are already
21
generic SWIG bindings. Thus is very easy to port STFL to additional scripting
22
languages.
23
24
A special language (the Structured Terminal Forms Language) is used to
25
describe STFL GUIs. The language is designed to be easy and fast to write
26
so an application programmer does not need to spend ages fiddling around
27
with the GUI and can concentrate on the more interesting programming tasks.
28
29
There are two different syntaxes for STFL code, one designed to make
30
handwriting of STFL code as easy as possible and one aiming at generated
31
STFL code.
32
33
The STFL GUI descriptions (written in STFL code) do not contain any concrete
34
layouting information such as x/y coordinates of widgets. Instead container
35
widgets such as vertical and horizontal boxes as well as tables are used to
36
group widgets and the actual layouting work is done by the STFL library. Thus
37
STFL GUIs can handle terminals of different sizes and terminal resize events
38
transparently for the application programmer.
39
40
41
Building and Installing STFL
42
----------------------------
43
44
Simply run 'make' and 'make install'. You might want to edit the Makefile.cfg
45
file before building and installing STFL.
46
47
48
The Structured Terminal Forms Language
49
--------------------------------------
50
51
STFL Forms consist of (instances of) widgets which are organized in a tree. A
52
special language - the Structured Terminal Forms Language - can be used to
53
describe such trees in an efficient and still easy to read and maintain way.
54
55
The Structured Terminal Forms Language has only two syntactical constructs:
56
Variable declarations and widget instanciations. Each widget instanciation
57
may contain variable declarations and child widget instanciations.
58
59
A widget can be instanciated by simly writing down the type of the widget.
60
Example given:
61
62
vbox
63
64
Sometimes one wants to give the instanciated widget a name so the widget
65
can be easily accesed later. This can be done by appending the widget name
66
using square brackets:
67
68
label[foobar]
69
70
Child widgets are instanciated the same way but must be indented:
71
72
vbox
73
label[label1]
74
label[label2]
75
76
Note that one must not use tabs for the indenting. Only blanks are allowed.
77
78
Variables are declared like child widgets. A variable consists of a key and
79
a value, seperated by a colon. Values can be quoted using single or double
80
quotes when they contain blanks.
81
82
vbox
83
label[label1]
84
text:"Hello World!"
85
label[label2]
86
text:"This is a test.."
87
88
It is also possible to append an additional name to variables using square
89
brackets so the application can read and write the variable value:
90
91
vbox
92
label[label1]
93
text[label1_text]:"Hello World!"
94
label[label2]
95
text[label2_text]:"This is a test.."
96
97
Usually variables configure the widget they are directly associated with or
98
store status information from that widget. But sometimes variables contain
99
information about the relationship of the widget they are directly associated
100
with and its parent widget. This variables are always start with a dot.
101
102
Example given the .border variable can be used to configure the borders of
103
table cells:
104
105
table
106
label
107
.border:lrtb
108
text:"Hello"
109
label
110
.border:lrtb
111
text:"World!"
112
113
Sometimes one wants to set a variable not only for the current widget but also
114
for all its child widgets. This can be done by prefixing the variable name
115
with he at-sign. Example given:
116
117
vbox
118
@style_normal:fg=white,bg=blue
119
label
120
text:"White text.."
121
label
122
text:"..on blue background."
123
124
This kind of variables can also be defined for only one widget type:
125
126
vbox
127
@style_normal:fg=white,bg=blue
128
@input#style_normal:fg=black,bg=red
129
label
130
text:"White text on blue background."
131
input
132
text:"Black text on red background."
133
134
Alternatively it is possible to postfix the widget types with '#classname'
135
and prefix the variables with 'classname#':
136
137
vbox
138
@style_normal:fg=white,bg=blue
139
@foobar#style_normal:fg=black,bg=red
140
label
141
text:"White text on blue background."
142
input#foobar
143
text:"Black text on red background."
144
145
While widget instanciations must alsways be on a new line, variable declarions
146
can also be written on the same line as the widget they are for and it is
147
possible to declare more than one variable in one line:
148
149
table
150
label .border:lrtb text:"Hello"
151
label
152
.border:lrtb text:"World!"
153
154
Sometimes one wants to generate STFL code from scripts. In this cases it can
155
become hard to automatically generate the indenting correctly. For such
156
situations it is possible to use a different format with curly brackets. The
157
following two code fragmentsa are identical:
158
159
vbox
160
hbox
161
label
162
.expand:0
163
text:"Foo: "
164
input[foo]
165
text:"Hello"
166
hbox
167
label
168
.expand:0
169
text:"Bar: "
170
input[bar]
171
text:"World!"
172
173
{vbox{hbox{label .expand:0 text:"Foo: "}{input[foo] text:"Hello"}
174
{hbox{label .expand:0 text:"Bar: "}{input[bar] text:"World!"}}}
175
176
Newline characters are not allowed inside of an STFL code fragment in curly
177
brackets (the example above is just broken up in two line to improve the
178
readability). It is even possible to embed an STFL code fragment in curly
179
brackets in a normal indented code block. Example given:
180
181
vbox
182
{hbox{label .expand:0 text:"Foo: "}{input[foo] text:"Hello"}}
183
{hbox{label .expand:0 text:"Bar: "}{input[bar] text:"World!"}}
184
185
It is also possible to include the focus information in STFL code: Simply
186
prefix the widget which shall have the focus with a '!'. Only one widget
187
may have the focus at a time.
188
189
The STFL parser can also read external files. This can be done by putting the
190
filename in < > brackets in the STFL file. Note that this is not a varbatim
191
include but calls another parser instance recursively. So there is an extra
192
indenting / curly brackets state for the external file.
193
194
Comment lines in STFL code start with a '*' character. There must be no
195
statement in the same line as the comment (i.e. only whitespaces are allowed
196
before the '*' character). Comment are not allowed within a code fragment
197
in curly brackets.
198
199
200
The STFL Style Descriptions
201
---------------------------
202
203
STFL is using a generic syntax whenever the style (color, etc.) of a text
204
can be specified: A comma seperated key=value list, where the key can be
205
'bg' for background, 'fg' for foreground and 'attr' for text attributes.
206
Example given the following style string can be used for creating bold
207
blinking white text on blue background:
208
209
bg=blue,fg=white,attr=bold,attr=blink
210
211
The following colors are supported:
212
213
black
214
red
215
green
216
yellow
217
blue
218
magenta
219
cyan
220
white
221
222
And the following attributes:
223
224
standout
225
underline
226
reverse
227
blink
228
dim
229
bold
230
protect
231
invis
232
233
The terminal default colors are used when no background or no foreground color
234
is specified. So keep care when only specifying one value. Example given text
235
printed using the style string 'fg=white' can't be seen on terminals with a
236
white default background.
237
238
239
The STFL Widget Library
240
-----------------------
241
242
vbox and hbox
243
~~~~~~~~~~~~~
244
245
This widgets simply layouts its child widgets vertically or horizontally
246
repectively. The following variables are supported by both widgets:
247
248
style_normal
249
The background style.
250
251
tie
252
Tie the box containing the widgets to the specified borders.
253
The value is a string containing the characters 'l' (left
254
border), 'r' (right border), 't' (top border), 'b' (bottom
255
border) and 'c' (center). The default value is 'lrtb'.
256
257
.tie
258
Tie this widget within its sub-box to the specified borders.
259
The value is using the same syntax as the "tie" variable above.
260
261
.expand
262
Contains the information if child widgets should be expanded
263
to fit the available space. The value is a string that may
264
contain the characters 'v' (for vertical expansion), 'h' (for
265
horizontal expansion) and '0' (for no expansion).
266
267
The hbox widget ignores the vertical expansion information and
268
the vbox widget the horizontal expansion information.
269
270
The default value is 'vh'.
271
272
.height
273
Hardcode the height of this child widget to the specified
274
number of lines. Usually one wants to also declare .expand:0
275
when declaring this variable.
276
277
.width
278
Hardcode the width of this child widget to the specified
279
number of characters. Usually one wants to also declare
280
.expand:0 when declaring this variable.
281
282
label
283
~~~~~
284
285
A simple text label. The following variables are supported by this widget:
286
287
style_normal
288
The style used for displaying the text.
289
290
text
291
The text to be displayed
292
293
input
294
~~~~~
295
296
A simple input widget for one line of text input. The following variables are
297
supported by this widget:
298
299
style_normal
300
The style of this widget when it does not have the
301
focus.
302
303
style_focus
304
The style of this widget when it does have the focus.
305
306
text
307
The value displayed in the input box.
308
309
pos
310
The current cursor position in the input box.
311
312
offset
313
The offset of the text displayed in the input box
314
(when the text is larger then the input box).
315
316
table
317
~~~~~
318
319
The most important container widget. The special widget 'tablebr' is used to
320
mark the begin of a new table row. The following variables are supported by
321
this widget:
322
323
style_normal
324
The style for the table bordes.
325
326
.expand
327
Contains the information if child widgets should be expanded
328
to fit the available space. The value is a string that may
329
contain the characters 'v' (for vertical expansion), 'h' (for
330
horizontal expansion) and '0' (for no expansion).
331
332
Since there is just one width for all cells in a column and
333
just one height for all cells in a row it still may happen
334
that cells are expanded a bit.
335
336
The default value is 'vh'.
337
338
.height, .width
339
Hardcode the height or .width of this table cell to the
340
specified number of characters. Usually one wants to also
341
declare .noexpand:1 when declaring one of this variables.
342
343
.colspan, .rowspan
344
The number of columns or rows for this cell. Default is '1'.
345
346
.border
347
The borders for this cell. This is a string which may contain
348
the characters 'l', 'r', 't' and 'b' for left, right, top and
349
bottom borders.
350
351
.spacer
352
Like .border, but only adds a spacer between the cells.
353
354
.tie
355
Tie this table cell within its box to the specified borders.
356
The value is a string containing the characters 'l' (left
357
border), 'r' (right border), 't' (top border), 'b' (bottom
358
border) and 'c' (center). The default value is 'lrtb'.
359
360
list
361
~~~~
362
363
DOCUMENTME
364
365
button
366
~~~~~~
367
368
DOCUMENTME (Not implemented yet)
369
370
checkbox
371
~~~~~~~~
372
373
DOCUMENTME (Not implemented yet)
374
375
textarea
376
~~~~~~~~
377
378
DOCUMENTME (Not implemented yet)
379
380
virtual
381
~~~~~~~
382
383
DOCUMENTME (Not implemented yet)
384
385
overlay
386
~~~~~~~
387
388
DOCUMENTME (Not implemented yet)
389
390
391
The Common STFL Scripting Language API
392
--------------------------------------
393
394
STFL has a big C-API which allows a wide range of in-depth operations on
395
widget trees. But most of this C-API is only needed for writing new STFL
396
widgets. The common STFL scripting language API only has a small number of
397
functions and besides the 'form handlers' this functions do only operate
398
on read-only scalar values, so it is pretty easy to write additional bindings
399
for scripting languages not yet supported by STFL.
400
401
C API Notes
402
~~~~~~~~~~~
403
404
All functions listed here are also available thru the STFL C-API.
405
406
All strings returned by stfl functions are constant and must not be freed or
407
modified by the caller. When the caller wants to preserve a string for longer
408
than until the next stfl function call the caller must copy the strings.
409
410
All strings passed to STFL functions are considered read-only by STFL and
411
are neither modified nor freed by STFL.
412
413
The functions which may return an undefined value will return a null-pointer
414
in C. All string parameters which are null-pointers are interpreted as they
415
where empty strings.
416
417
SPL API Notes
418
~~~~~~~~~~~~~
419
420
The stfl_free() function is not implemented in SPL because the SPL garbage
421
collector does call the low-level STFL free function automatically. The
422
stfl_reset() function is automatically called when the STFL module is unloaded
423
(i.e. on program termination).
424
425
The stfl_quote() function can also be called using the name encode_stfl() so
426
it can be used with the SPL encoding/quoting operator (::).
427
428
Python API Notes
429
~~~~~~~~~~~~~~~~
430
431
The stfl_free() function is not implemented in Python because the garbage
432
collector does call the low-level STFL free function automatically. The
433
stfl_reset() function is automatically called on program termination.
434
435
The functions which take a form as first parameter can also be called as method
436
of the form. All functions are in the "stfl" namespace, so the "stfl_" prefix
437
for the function names is replaced with "stfl." in python.
438
439
Perl API Notes
440
~~~~~~~~~~~~~~
441
442
The stfl_free() function is not implemented in Perl because the garbage
443
collector does call the low-level STFL free function automatically. The
444
stfl_reset() function is automatically called on program termination.
445
446
The functions which take a form as first parameter can also be called as method
447
of the form. All functions are in the "stfl" namespace, so the "stfl_" prefix
448
for the function names is replaced with "stfl::" in perl.
449
450
Ruby API Notes
451
~~~~~~~~~~~~~~
452
453
The stfl_free() function is not implemented in Perl because the garbage
454
collector does call the low-level STFL free function automatically. The
455
stfl_reset() function is automatically called on program termination.
456
457
The functions which take a form as first parameter can also be called as method
458
of the form. All functions are in the "Stfl" namespace, so the "stfl_" prefix
459
for the function names is replaced with "Stfl." in ruby.
460
461
stfl_create(text)
462
~~~~~~~~~~~~~~~~~
463
464
Parses the the STFL description text passed as parameter and returns a form
465
handler. Most of the following functions expect such a form handler as first
466
parameter.
467
468
stfl_free(form)
469
~~~~~~~~~~~~~~~
470
471
Free all resources associated with this form. On languages with a garbage
472
collector calling this function is optional and might even be implemented
473
as no-op.
474
475
stfl_run(form, timeout)
476
~~~~~~~~~~~~~~~~~~~~~~~
477
478
Return the next event. If no more prior generated events are waiting display
479
the form and process one input character. The following events are generated
480
directly by the STFL core:
481
482
TIMEOUT
483
The timeout has been reached.
484
485
ENTER
486
The return key has been pressed.
487
488
ESC
489
The escape key has been pressed.
490
491
F0 .. F63
492
A function key has been pressed.
493
494
The 2nd parameter is a timeout in ms. When no key has been pressed until this
495
timeout has been reached. Set this parameter to 0 to disable the timeout.
496
497
When the timeout parameter is set to -1 the form is displayed independent of
498
the current status of the event queue and the function returns right after
499
displaying the form without handling any input characters. In this mode always
500
an undefined value is returned.
501
502
stfl_reset()
503
~~~~~~~~~~~~
504
505
The stfl_run() function automatically activates ncurses. This function
506
can be used to explicitely switch back to normal text mode. In some
507
languages this is automatically done on program termination.
508
509
stfl_get(form, name)
510
~~~~~~~~~~~~~~~~~~~~
511
512
Returns the current value of the specified variable. When the variable does not
513
exist this function returns an undefined value.
514
515
stfl_set(form, name, value)
516
~~~~~~~~~~~~~~~~~~~~~~~~~~~
517
518
This sets the specified variable to the specified value.
519
520
stfl_get_focus(form)
521
~~~~~~~~~~~~~~~~~~~~
522
523
Returns the name of the widget which currently has the focus or an undefined
524
value when the widget having the focus has no name.
525
526
stfl_set_focus(form, name)
527
~~~~~~~~~~~~~~~~~~~~~~~~~~
528
529
Set the focus to the specified widget.
530
531
stfl_quote(text)
532
~~~~~~~~~~~~~~~~
533
534
Quote the text so it can be savely used as variable value in STFL code.
535
536
stfl_dump(form, name, prefix, focus)
537
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
538
539
Return the subtree starting with the widget specified in the 2nd parameter as
540
STFL code fragment. The entire form is return when the 2nd parameter is an
541
empty string or undefined. All widget and variable names in the dump are
542
prefixed with the string in the 3rd parameter. The information which widget has
543
the focus is also included in the dump when the 4th parameter is an integer
544
not equal 0.
545
546
The function returns an undefined value when there was an error.
547
548
stfl_modify(form, name, mode, text)
549
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
550
551
Import the STFL code specified in the 4th parameter to an existing form. The
552
2nd parameter is used to specify a widget which is used as starting point for
553
the modification. The 3rd parameter is a string specifying how the new STFL
554
code should be added to the widget tree:
555
556
replace
557
Replace the widget in the tree with the new tree.
558
559
replace_inner
560
Replace the child list of the widget with the child list
561
of the root element of the new tree.
562
563
insert
564
Add the new tree at the begin of the child list of the widget.
565
566
insert_inner
567
Add the child list of the root element of the new tree at the
568
begin of the child list of the widget.
569
570
append
571
Add the new tree at the end of the child list of the widget.
572
573
append_inner
574
Add the child list of the root element of the new tree at the
575
end of the child list of the widget.
576
577
before
578
Add the new tree before the widget.
579
580
before_inner
581
Add the child list of the root element of the new tree before
582
the widget.
583
584
after
585
Add the new tree after the widget.
586
587
after_inner
588
Add the child list of the root element of the new tree after
589
the widget.
590
591
The replace mode simply deletes the widget and the replace_inner mode deletes
592
all existing childs of the widget when an empty string is passed as 4th
593
parameter.
594
595
stfl_lookup(form, path, newname)
596
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
597
598
Lookup widgets in the form using a path and optionally assign a new name.
599
600
This function is not implemented yet.
601
602
stfl_error()
603
~~~~~~~~~~~~
604
605
Return the error status of the last STFL call. This is undefined when no error
606
occoured and the error message otherwise.
607
608
stfl_error_action(mode)
609
~~~~~~~~~~~~~~~~~~~~~~~
610
611
Set the error handling algorithm. The following strings are valid as mode
612
parameter:
613
614
abort
615
Print error message to stderr and call the abort() function.
616
617
exit
618
Print error message to stderr and call exit(1).
619
620
print
621
Print error message to stderr and continue execution.
622
623
interactive
624
Display a little menu and let the user decide what to do.
625
626
none
627
Do nothing - just continue program execution.
628
629
The default mode is "interactive".
630
631
632
Pseudo Variables
633
----------------
634
635
DOCUMENTME
636
637
638
Event Handler Variables
639
-----------------------
640
641
DOCUMENTME (Not implemented yet)
642
643
644
STFL Internals
645
--------------
646
647
DOCUMENTME
648
649
650
TODOs
651
-----
652
653
- Implement so far unimplemented widgets
654
- Common 'on*' event handler variables
655
- Missing error handling and reporting
656
- Implement stfl_lookup() function
657
Loggerhead is a web-based interface for Breezy
Version: 2.0.1