source: project/wiki/eggref/5/termbox @ 38135

Last change on this file since 38135 was 38135, checked in by justinmeiners, 9 months ago

example corrections. add constants.

File size: 5.6 KB
Line 
1== chicken-termbox
2[[toc:]]
3[[http://call-cc.org/|Chicken Scheme]] bindings for
4the library [[https://github.com/nsf/termbox|termbox]].
5The API attempts to match the original library as closely as possible,
6with some slight scheme conveniences.
7This is done to maximize compatiblity and performance,
8but can appear a bit too "low-level".
9It is expected that you will write higher level abstractions,
10see the examples section.
11
12
13=== Author
14
15[[https://justinmeiners.github.io/|Justin Meiners]]
16
17
18=== API
19
20<procedure> (termbox-init)</procedure>
21<procedure> (termbox-shutdown)</procedure>
22
23Initializes the termbox library.
24The init function should be called before any other functions.
25Shutdown must be called before exiting, otherwise the terminal
26may be left in an unusable state.
27
28
29<procedure> (termbox-width) -> integer</procedure>
30<procedure> (termbox-height) -> integer</procedure>
31
32Returns the size of the internal back buffer (which is the same as terminal's window size in characters).
33
34<procedure> (termbox-clear) </procedure>
35
36Clears the internal back buffer using default color or the
37color/attributes set by termbox-set-clear function.
38
39<procedure> (termbox-set-clear [fg u16] [bg u16] ) </procedure>
40
41Specifies the values that will be applied when calling termbox-clear.
42
43<procedure> (termbox-present) </procedure>
44
45Synchronizes the internal back buffer with the terminal.
46In other words, presents changes to the terminal.
47
48<procedure> (termbox-change-cell [x integer] [y integer] [c char] [fg u16] [bg u16])</procedure>
49
50Changes cell's parameters in the internal back buffer at the specified position.
51
52<procedure> (termbox-set-cursor [x integer] [y integer])</procedure>
53
54Sets the position of the cursor. Upper-left character is (0, 0).
55Cursor is hidden by default.
56
57<procedure> (termbox-hide-cursor)</procedure>
58
59Hides the cursor. Cursor can be shown again by calling termbox-set-cursor.
60
61<procedure> (termbox-poll-event) -> list </procedure>
62
63Wait for an event forever and fill the 'event' structure with it, when the event is available.
64See below for event structure.
65
66<procedure> (termbox-peek-event [timeout-millis integer]) -> list </procedure>
67
68Wait for an event up to 'timeout' milliseconds and return the event when available.
69An event is a list containing the following:
70    (TYPE MOD KEY CHAR W H X Y).
71
72<procedure> (termbox-copy-buffer [char-buffer u32vector] [fg-buffer u32vector] [bg-vector u32vector]) </procedure>
73
74Copy data from vectors into the internal buffer.
75The char-buffer is the character codes for the characters.
76
77<procedure> (termbox-blit [x integer] [y integer] [char-buffer u32vector] [fg-buffer u32vector] [bg-vector u32vector]) </procedure>
78
79Copy data from vectors into a part of the internal buffer at a specific location.
80The char-buffer is the character codes for the characters.
81
82<procedure> (termbox-select-input-mode [mode integer]) </procedure>
83
84Sets the termbox input mode. Termbox has two input modes:
851. Esc input mode.
86When ESC sequence is in the buffer and it doesn't match any known
87ESC sequence => ESC means tb/key/esc.
88
892. Alt input mode.
90When ESC sequence is in the buffer and it doesn't match any known
91sequence => ESC enables tb/mod/alt modifier for the next keyboard event.
92
93You can also apply tb/input/mouse via bitwise OR operation to either of the
94modes (e.g. tb/input/esc | tb/input/mouse). If none of the main two modes
95were set, but the mouse mode was, tb/input/esc mode is used. If for some
96reason you've decided to use (tb/input/esc | tb/input/alt) combination, it
97will behave as if only tb/input/esc was selected.
98 
99If 'mode' is tb/input/current, it returns the current input mode.
100Default termbox input mode is tb/input/esc.
101
102<procedure> (termbox-select-output-mode [mode integer]) </procedure>
103
104Sets the termbox output mode. Termbox has three output options:
1051. `tb/output/normal`  => [1..8]
106This mode provides 8 different colors:
107black, red, green, yellow, blue, magenta, cyan, white
108
109Shortcut: tb/color/black, tb/color/red, ...
110Attributes: tb/attrib/bold, tb/attrib/underline, tb/attrib/reverse
111
112Example usage:
113    (tb-change-cell x y #\@ (bitwise-ior tb/color/black tb/attrib/bold) tb/color/red)
114 
1152. tb/output/256 => [0..256]
116In this mode you can leverage the 256 terminal mode:
117* 0x00 - 0x07: the 8 colors as in tb/output/normal
118* 0x08 - 0x0f: tb/color/_* | tb/attrib/bold
119* 0x10 - 0xe7: 216 different colors
120* 0xe8 - 0xff: 24 different shades of grey
121
122Example usage:
123    (tb-change-cell x  y #\@ 184 240)
124    (tb-change-cell x  y #\@ #xb8 #xf0)
125
1263. tb/output/216 => [0..216]
127This mode supports the 3rd range of the 256 mode only.
128But you don't need to provide an offset.
129
1304. tb/output/grayscale  => [0..23]
131This mode supports the 4th range of the 256 mode only.
132But you dont need to provide an offset.
133
134If 'mode' is tb/output/current, it returns the current output mode.
135Default termbox output mode is tb/output/normal
136
137====  Constants
138
139Modifiers
140
141<constant> tb/mod/alt </constant>
142
143<constant> tb/mod/motion </constant>
144
145Colors
146
147<constant> tb/color/default </constant>
148
149<constant> tb/color/black </constant>
150
151<constant> tb/color/red </constant>
152
153<constant> tb/color/green </constant>
154
155<constant> tb/color/yellow </constant>
156
157<constant> tb/color/blue </constant>
158
159<constant> tb/color/magenta </constant>
160
161<constant> tb/color/cyan </constant>
162
163<constant> tb/color/white </constant>
164
165Attributes
166
167<constant> tb/attrib/bold </constant>
168
169<constant> tb/attrib/underline </constant>
170
171<constant> tb/attrib/reverse </constant>
172
173
174===  Examples
175
176Convert string to character buffer:
177
178    (list->u32vector (map char->integer (string-list "hello world")))
179
180===  License
181
182[[https://raw.githubusercontent.com/nsf/termbox/master/COPYING|MIT license]]
183
184
Note: See TracBrowser for help on using the repository browser.