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

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

added repository link

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