« back to all changes in this revision
Viewing changes to README
- browse files at revision 4
- compare with another revision
- download diff
- download tarball
- view history from revision 4
- Committer: Bazaar Package Importer
- Author(s): Nico Golde
- Date: 2007-08-07 13:06:54 UTC
- mfrom: (1.1.1 upstream)
- Revision ID: james.westby@ubuntu.com-20070807130654-fmvsraotulj0nbri
Tags: 0.15-3
Again added fPIC to CFLAGS. Hopefully all build issues
are fixed now.
are fixed now.
- files added:
- COPYING
- files removed:
- debian/README.Debian
- files modified:
- Makefile
added
removed
README
2
2
##########################################################################
3
3
# #
4
4
# STFL - The Structured Terminal Forms Language/Library #
5
# Copyright (C) 2006 Clifford Wolf <clifford@clifford.at> #
5
# Copyright (C) 2006, 2007 Clifford Wolf <clifford@clifford.at> #
6
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. #
7
# This library is free software; you can redistribute it and/or #
8
# modify it under the terms of the GNU Lesser General Public #
9
# License as published by the Free Software Foundation; either #
10
# version 3 of the License, or (at your option) any later version. #
11
11
# #
12
12
##########################################################################
13
13
44
44
Simply run 'make' and 'make install'. You might want to edit the Makefile.cfg
45
45
file before building and installing STFL.
46
46
47
In order to build a full-featured STFL with all scripting language bindings
48
enabled you need to have the following packages installed (including the
49
development packages):
50
51
ncursesw
52
The wide-character ncurses library. On some distributions
53
this might be part of the ncurses package, on other
54
distrubutions this might be an extra package.
55
56
SWIG
57
STFL is using SWIG for generating the Perl, Python and Ruby
58
language bindings.
59
60
Perl, Python, Ruby, SPL
61
In order to create the language bindings you need to have
62
the languages themself installed.
63
64
Since STFL is a wide-character library it will only work on systems which
65
do have wide-character support in the system libraries. This might not be
66
the case for in older Linux distributions or other UNIXes.
67
47
68
48
69
The Structured Terminal Forms Language
49
70
--------------------------------------
236
257
white default background.
237
258
238
259
260
Key and Keybinding Descriptions
261
-------------------------------
262
263
Key descriptings are strings describing a key press event. With some
264
exceptions this are the return values of the ncurses keyname() and key_name()
265
functions. The exceptions are:
266
267
ENTER
268
The return key has been pressed.
269
270
SPACE
271
The space key has been pressed.
272
273
TAB
274
The tabulator key has been pressed.
275
276
ESC
277
The escape key has been pressed.
278
279
F0 .. F63
280
A function key has been pressed.
281
282
UNKNOWN
283
An unkown key has been pressed.
284
(Usually this is the result of a broken multibyte sequence)
285
286
A key binding description is a whitespace-seperated list of key descriptions
287
used in bind_* variables to bind keys to widget actions. Each widget provides
288
default bindings for all its actions. If you want to extend the list of bind
289
keys instead of overwriting them you must use the special key-description "**"
290
in the keybinding description to refer to the default bindings.
291
292
Key values can e.g. be dumped using the following little Perl script:
293
294
perl -mstfl -le '$_ = stfl::create("label text:\"Press a key\"")->run(0);
295
stfl::reset(); print;'
296
297
239
298
The STFL Widget Library
240
299
-----------------------
241
300
245
304
This widgets simply layouts its child widgets vertically or horizontally
246
305
repectively. The following variables are supported by both widgets:
247
306
307
bind_left, bind_right
308
The keybindings in a hbox for changing the focus to the
309
next or previous child widget. Default values are the
310
LEFT and RIGHT keys.
311
312
bind_up, bind_down
313
The keybindings in a vbox for changing the focus to the
314
next or previous child widget. Default values are the UP
315
and DOWN keys.
316
248
317
style_normal
249
318
The background style.
250
319
296
365
A simple input widget for one line of text input. The following variables are
297
366
supported by this widget:
298
367
368
bind_left, bind_right
369
Move the cursor left and right. Default values are the LEFT
370
and RIGHT keys.
371
372
bind_home
373
Move the cursor to the first character. Default values are
374
the HOME key or Ctrl-A.
375
376
bind_end
377
Move the cursor after the last character. Default values are
378
the END key or Ctrl-E.
379
380
bind_delete
381
Delete the character under the cursor. Default value is the
382
DEL key.
383
384
bind_backspace
385
Delete the character before the cursor. Default value is the
386
BACKSPACE key.
387
299
388
style_normal
300
389
The style of this widget when it does not have the
301
390
focus.
320
409
mark the begin of a new table row. The following variables are supported by
321
410
this widget:
322
411
412
bind_left, bind_right, bind_up, bind_down
413
The keybindings for changing the focus within a table.
414
Default values are the UP, DOWN, LEFT and RIGHT keys.
415
323
416
style_normal
324
417
The style for the table bordes.
325
418
360
453
list
361
454
~~~~
362
455
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)
456
The list widget can be used to display a list of items, one per line. The
457
items are stored as 'listitem' child widgets of the 'list' widget. When
458
there are more items then the list widget has lines the list widget is
459
automatically scrolling. The list widget implements the following variables:
460
461
bind_up, bind_down
462
The key bindings for scrolling up or down by line. Default
463
values are the UP and DOWN keys.
464
465
bind_page_up, bind_page_down
466
The key bindings for scrolling up or down by page. Default
467
values are the PAGE_UP and PAGE_DOWN keys.
468
469
style_focus
470
Style of the active list item when the widget has the focus.
471
472
style_selected
473
Style of the active list item when the widget has not the
474
focus.
475
476
style_normal
477
Style of the currently not active list items.
478
479
pos
480
The number of the current list item
481
482
pos_name
483
The widget name of the current list item.
484
485
offset
486
The numer of the list item displayed in the first line (this
487
becomes >0 when scrolling).
488
489
490
listitem
491
~~~~~~~~
492
493
An in a list widget. Implements the following variables:
494
495
text
496
The text displayed in this list item.
497
498
textview
499
~~~~~~~~
500
501
A widget for displaying multiline text. The text itself is stored within
502
listitem child widgets. Implements the following variables:
503
504
bind_up, bind_down
505
The key bindings for scrolling up or down by line. Default
506
values are the UP and DOWN keys.
507
508
bind_page_up, bind_page_down
509
The key bindings for scrolling up or down by page. Default
510
values are the PAGE_UP and PAGE_DOWN keys.
511
512
style_normal
513
The style the text itself is displayed.
514
515
style_end
516
The style used for the EOT-Markers.
517
518
offset
519
The number of the first line displayed
520
(becomes >0 when scrolling).
521
522
523
Common Variables
524
----------------
525
526
There are some variables which are used by the STFL core to configure some
527
widget-independent features.
528
529
modal
530
~~~~~
531
532
A widget which has the modal variable set to '1' will not pass any events
533
to its parent widgets. Eighter the event is handled by the widget itself or
534
it is returned directly to the caller of stfl_run().
535
536
autobind
537
~~~~~~~~
538
539
Setting autobind to '0' disables all automatically assigned keybindings for
540
this widget. Actions which aren't set explicitely bind to keys using the
541
bind_* variables are left unbind and can't be triggered using the user
542
interface.
543
544
on_*
545
~~~~
546
547
The on_* variables can be used to catch keypresses in this widget and return
548
the value of the on_* variable to the caller of stfl_run(). The on_* variables
549
are evaluated before the keypresses are passed to the widget. The '*' part
550
of the on_* variables is a key description. E.g. "on_^X:foobar" will let
551
stfl_run() return the string "foobar" when Ctrl-X is beeing pressed.
389
552
390
553
391
554
The Common STFL Scripting Language API
414
577
in C. All string parameters which are null-pointers are interpreted as they
415
578
where empty strings.
416
579
580
Unicode Support
581
~~~~~~~~~~~~~~~
582
583
The STFL C Library handles all strings as wide character strings (wchar_t*). So
584
the STFL library itself has complete Unicode support.
585
586
All current scripting language bindings convert all strings passed between STFL
587
and the scripting language to UTF-8.
588
589
Programs using STFL directly might use the STFL "ipool" API for easy conversion
590
betweed wide characters and other encodings.
591
417
592
SPL API Notes
418
593
~~~~~~~~~~~~~
419
594
476
651
~~~~~~~~~~~~~~~~~~~~~~~
477
652
478
653
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.
654
the form and process one input character. The event string can be an undefined
655
value when something chaned in the form (e.g. the user changed the focus of
656
the current widget) but all inputs have been handled internally inside of STFL.
657
The event string can be "TIMEOUT" when the timeout has been reached, a key
658
description is key has been pressed that is not beeing hadled internally in
659
STFL or the value of an on_* variable can be returned if a keypress has been
660
catched using such a variable.
493
661
494
662
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.
663
timeout has been reached the function returns with a "TIMEOUT" event. Set this
664
parameter to 0 to disable the timeout.
496
665
497
666
When the timeout parameter is set to -1 the form is displayed independent of
498
667
the current status of the event queue and the function returns right after
499
668
displaying the form without handling any input characters. In this mode always
500
669
an undefined value is returned.
501
670
671
When the timeout parameter is set to -2 the displayed is not updated and the
672
next pending event is returned. If there are no pending events an undefined
673
value is returned.
674
502
675
stfl_reset()
503
676
~~~~~~~~~~~~
504
677
603
776
~~~~~~~~~~~~
604
777
605
778
Return the error status of the last STFL call. This is undefined when no error
606
occoured and the error message otherwise.
779
occoured and the error message otherwise. An error could e.g. be a parser
780
error for broken STFL code.
781
782
WARNING: This is a planned feature! This version of STFL simply calls abort()
783
if an internal error is catched.
607
784
608
785
stfl_error_action(mode)
609
786
~~~~~~~~~~~~~~~~~~~~~~~
628
805
629
806
The default mode is "interactive".
630
807
808
WARNING: This is a planned feature! This version of STFL simply calls abort()
809
if an internal error is catched.
810
631
811
632
812
Pseudo Variables
633
813
----------------
634
814
635
DOCUMENTME
636
637
638
Event Handler Variables
639
-----------------------
640
641
DOCUMENTME (Not implemented yet)
642
643
644
STFL Internals
645
--------------
646
647
DOCUMENTME
815
When a widget has a name (declared using the 'widget[name]' syntax in the STFL
816
code), there are also some special pseudo-variables which can only be accessed
817
for reading. Note that this pseudo-variables do only have valid values after
818
the widget has been drawed already. So it is always a good idea to run
819
stfl_run() with a timeout of -1 before accessing the pseudo-variables.
820
821
widgetname:x
822
~~~~~~~~~~~~
823
824
The absolute x-position of the widget on the screen. (from the left border)
825
826
widgetname:y
827
~~~~~~~~~~~~
828
829
The absolute y-position of the widget on the screen. (from the upper border)
830
831
widgetname:w
832
~~~~~~~~~~~~
833
834
The width of the widget.
835
836
widgetname:h
837
~~~~~~~~~~~~
838
839
The height of the widget.
840
841
widgetname:minw
842
~~~~~~~~~~~~~~~
843
844
The minimal width (i.e. before expanding) of the widget.
845
846
widgetname:minh
847
~~~~~~~~~~~~~~~
848
849
The minimal height (i.e. before expanding) of the widget.
648
850
649
851
650
852
TODOs
651
853
-----
652
854
653
855
- Implement so far unimplemented widgets
654
- Common 'on*' event handler variables
655
856
- Missing error handling and reporting
656
857
- Implement stfl_lookup() function
657
858
Loggerhead is a web-based interface for Breezy
Version: 2.0.1