termbox.h (11999B)
1 #pragma once 2 3 #include <stdint.h> 4 5 /* for shared objects */ 6 #if __GNUC__ >= 4 7 #define SO_IMPORT __attribute__((visibility("default"))) 8 #else 9 #define SO_IMPORT 10 #endif 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /* Key constants. See also struct tb_event's key field. 17 * 18 * These are a safe subset of terminfo keys, which exist on all popular 19 * terminals. Termbox uses only them to stay truly portable. 20 */ 21 #define TB_KEY_F1 (0xFFFF-0) 22 #define TB_KEY_F2 (0xFFFF-1) 23 #define TB_KEY_F3 (0xFFFF-2) 24 #define TB_KEY_F4 (0xFFFF-3) 25 #define TB_KEY_F5 (0xFFFF-4) 26 #define TB_KEY_F6 (0xFFFF-5) 27 #define TB_KEY_F7 (0xFFFF-6) 28 #define TB_KEY_F8 (0xFFFF-7) 29 #define TB_KEY_F9 (0xFFFF-8) 30 #define TB_KEY_F10 (0xFFFF-9) 31 #define TB_KEY_F11 (0xFFFF-10) 32 #define TB_KEY_F12 (0xFFFF-11) 33 #define TB_KEY_INSERT (0xFFFF-12) 34 #define TB_KEY_DELETE (0xFFFF-13) 35 #define TB_KEY_HOME (0xFFFF-14) 36 #define TB_KEY_END (0xFFFF-15) 37 #define TB_KEY_PGUP (0xFFFF-16) 38 #define TB_KEY_PGDN (0xFFFF-17) 39 #define TB_KEY_ARROW_UP (0xFFFF-18) 40 #define TB_KEY_ARROW_DOWN (0xFFFF-19) 41 #define TB_KEY_ARROW_LEFT (0xFFFF-20) 42 #define TB_KEY_ARROW_RIGHT (0xFFFF-21) 43 #define TB_KEY_MOUSE_LEFT (0xFFFF-22) 44 #define TB_KEY_MOUSE_RIGHT (0xFFFF-23) 45 #define TB_KEY_MOUSE_MIDDLE (0xFFFF-24) 46 #define TB_KEY_MOUSE_RELEASE (0xFFFF-25) 47 #define TB_KEY_MOUSE_WHEEL_UP (0xFFFF-26) 48 #define TB_KEY_MOUSE_WHEEL_DOWN (0xFFFF-27) 49 50 /* These are all ASCII code points below SPACE character and a BACKSPACE key. */ 51 #define TB_KEY_CTRL_TILDE 0x00 52 #define TB_KEY_CTRL_2 0x00 /* clash with 'CTRL_TILDE' */ 53 #define TB_KEY_CTRL_A 0x01 54 #define TB_KEY_CTRL_B 0x02 55 #define TB_KEY_CTRL_C 0x03 56 #define TB_KEY_CTRL_D 0x04 57 #define TB_KEY_CTRL_E 0x05 58 #define TB_KEY_CTRL_F 0x06 59 #define TB_KEY_CTRL_G 0x07 60 #define TB_KEY_BACKSPACE 0x08 61 #define TB_KEY_CTRL_H 0x08 /* clash with 'CTRL_BACKSPACE' */ 62 #define TB_KEY_TAB 0x09 63 #define TB_KEY_CTRL_I 0x09 /* clash with 'TAB' */ 64 #define TB_KEY_CTRL_J 0x0A 65 #define TB_KEY_CTRL_K 0x0B 66 #define TB_KEY_CTRL_L 0x0C 67 #define TB_KEY_ENTER 0x0D 68 #define TB_KEY_CTRL_M 0x0D /* clash with 'ENTER' */ 69 #define TB_KEY_CTRL_N 0x0E 70 #define TB_KEY_CTRL_O 0x0F 71 #define TB_KEY_CTRL_P 0x10 72 #define TB_KEY_CTRL_Q 0x11 73 #define TB_KEY_CTRL_R 0x12 74 #define TB_KEY_CTRL_S 0x13 75 #define TB_KEY_CTRL_T 0x14 76 #define TB_KEY_CTRL_U 0x15 77 #define TB_KEY_CTRL_V 0x16 78 #define TB_KEY_CTRL_W 0x17 79 #define TB_KEY_CTRL_X 0x18 80 #define TB_KEY_CTRL_Y 0x19 81 #define TB_KEY_CTRL_Z 0x1A 82 #define TB_KEY_ESC 0x1B 83 #define TB_KEY_CTRL_LSQ_BRACKET 0x1B /* clash with 'ESC' */ 84 #define TB_KEY_CTRL_3 0x1B /* clash with 'ESC' */ 85 #define TB_KEY_CTRL_4 0x1C 86 #define TB_KEY_CTRL_BACKSLASH 0x1C /* clash with 'CTRL_4' */ 87 #define TB_KEY_CTRL_5 0x1D 88 #define TB_KEY_CTRL_RSQ_BRACKET 0x1D /* clash with 'CTRL_5' */ 89 #define TB_KEY_CTRL_6 0x1E 90 #define TB_KEY_CTRL_7 0x1F 91 #define TB_KEY_CTRL_SLASH 0x1F /* clash with 'CTRL_7' */ 92 #define TB_KEY_CTRL_UNDERSCORE 0x1F /* clash with 'CTRL_7' */ 93 #define TB_KEY_SPACE 0x20 94 #define TB_KEY_BACKSPACE2 0x7F 95 #define TB_KEY_CTRL_8 0x7F /* clash with 'BACKSPACE2' */ 96 97 /* These are non-existing ones. 98 * 99 * #define TB_KEY_CTRL_1 clash with '1' 100 * #define TB_KEY_CTRL_9 clash with '9' 101 * #define TB_KEY_CTRL_0 clash with '0' 102 */ 103 104 /* 105 * Alt modifier constant, see tb_event.mod field and tb_select_input_mode function. 106 * Mouse-motion modifier 107 */ 108 #define TB_MOD_ALT 0x01 109 #define TB_MOD_MOTION 0x02 110 111 /* Colors (see struct tb_cell's fg and bg fields). */ 112 #define TB_DEFAULT 0x00 113 #define TB_BLACK 0x01 114 #define TB_RED 0x02 115 #define TB_GREEN 0x03 116 #define TB_YELLOW 0x04 117 #define TB_BLUE 0x05 118 #define TB_MAGENTA 0x06 119 #define TB_CYAN 0x07 120 #define TB_WHITE 0x08 121 122 /* Attributes, it is possible to use multiple attributes by combining them 123 * using bitwise OR ('|'). Although, colors cannot be combined. But you can 124 * combine attributes and a single color. See also struct tb_cell's fg and bg 125 * fields. 126 */ 127 #define TB_BOLD 0x0100 128 #define TB_UNDERLINE 0x0200 129 #define TB_REVERSE 0x0400 130 131 /* A cell, single conceptual entity on the terminal screen. The terminal screen 132 * is basically a 2d array of cells. It has the following fields: 133 * - 'ch' is a unicode character 134 * - 'fg' foreground color and attributes 135 * - 'bg' background color and attributes 136 */ 137 struct tb_cell { 138 uint32_t ch; 139 uint16_t fg; 140 uint16_t bg; 141 }; 142 143 #define TB_EVENT_KEY 1 144 #define TB_EVENT_RESIZE 2 145 #define TB_EVENT_MOUSE 3 146 147 /* An event, single interaction from the user. The 'mod' and 'ch' fields are 148 * valid if 'type' is TB_EVENT_KEY. The 'w' and 'h' fields are valid if 'type' 149 * is TB_EVENT_RESIZE. The 'x' and 'y' fields are valid if 'type' is 150 * TB_EVENT_MOUSE. The 'key' field is valid if 'type' is either TB_EVENT_KEY 151 * or TB_EVENT_MOUSE. The fields 'key' and 'ch' are mutually exclusive; only 152 * one of them can be non-zero at a time. 153 */ 154 struct tb_event { 155 uint8_t type; 156 uint8_t mod; /* modifiers to either 'key' or 'ch' below */ 157 uint16_t key; /* one of the TB_KEY_* constants */ 158 uint32_t ch; /* unicode character */ 159 int32_t w; 160 int32_t h; 161 int32_t x; 162 int32_t y; 163 }; 164 165 /* Error codes returned by tb_init(). All of them are self-explanatory, except 166 * the pipe trap error. Termbox uses unix pipes in order to deliver a message 167 * from a signal handler (SIGWINCH) to the main event reading loop. Honestly in 168 * most cases you should just check the returned code as < 0. 169 */ 170 #define TB_EUNSUPPORTED_TERMINAL -1 171 #define TB_EFAILED_TO_OPEN_TTY -2 172 #define TB_EPIPE_TRAP_ERROR -3 173 174 /* Initializes the termbox library. This function should be called before any 175 * other functions. Function tb_init is same as tb_init_file("/dev/tty"). 176 * After successful initialization, the library must be 177 * finalized using the tb_shutdown() function. 178 */ 179 SO_IMPORT int tb_init(void); 180 SO_IMPORT int tb_init_file(const char* name); 181 SO_IMPORT int tb_init_fd(int inout); 182 SO_IMPORT void tb_shutdown(void); 183 184 /* Returns the size of the internal back buffer (which is the same as 185 * terminal's window size in characters). The internal buffer can be resized 186 * after tb_clear() or tb_present() function calls. Both dimensions have an 187 * unspecified negative value when called before tb_init() or after 188 * tb_shutdown(). 189 */ 190 SO_IMPORT int tb_width(void); 191 SO_IMPORT int tb_height(void); 192 193 /* Clears the internal back buffer using TB_DEFAULT color or the 194 * color/attributes set by tb_set_clear_attributes() function. 195 */ 196 SO_IMPORT void tb_clear(void); 197 SO_IMPORT void tb_set_clear_attributes(uint16_t fg, uint16_t bg); 198 199 /* Synchronizes the internal back buffer with the terminal. */ 200 SO_IMPORT void tb_present(void); 201 202 #define TB_HIDE_CURSOR -1 203 204 /* Sets the position of the cursor. Upper-left character is (0, 0). If you pass 205 * TB_HIDE_CURSOR as both coordinates, then the cursor will be hidden. Cursor 206 * is hidden by default. 207 */ 208 SO_IMPORT void tb_set_cursor(int cx, int cy); 209 210 /* Changes cell's parameters in the internal back buffer at the specified 211 * position. 212 */ 213 SO_IMPORT void tb_put_cell(int x, int y, const struct tb_cell *cell); 214 SO_IMPORT void tb_change_cell(int x, int y, uint32_t ch, uint16_t fg, uint16_t bg); 215 216 /* Copies the buffer from 'cells' at the specified position, assuming the 217 * buffer is a two-dimensional array of size ('w' x 'h'), represented as a 218 * one-dimensional buffer containing lines of cells starting from the top. 219 * 220 * (DEPRECATED: use tb_cell_buffer() instead and copy memory on your own) 221 */ 222 SO_IMPORT void tb_blit(int x, int y, int w, int h, const struct tb_cell *cells); 223 224 /* Returns a pointer to internal cell back buffer. You can get its dimensions 225 * using tb_width() and tb_height() functions. The pointer stays valid as long 226 * as no tb_clear() and tb_present() calls are made. The buffer is 227 * one-dimensional buffer containing lines of cells starting from the top. 228 */ 229 SO_IMPORT struct tb_cell *tb_cell_buffer(void); 230 231 #define TB_INPUT_CURRENT 0 /* 0000 */ 232 #define TB_INPUT_ESC 1 /* 0001 */ 233 #define TB_INPUT_ALT 2 /* 0010 */ 234 #define TB_INPUT_MOUSE 4 /* 0100 */ 235 #define TB_INPUT_SPACE 8 /* 1000 */ 236 237 /* Sets the termbox input mode. Termbox has two input modes: 238 * 1. Esc input mode. 239 * When ESC sequence is in the buffer and it doesn't match any known 240 * ESC sequence => ESC means TB_KEY_ESC. 241 * 2. Alt input mode. 242 * When ESC sequence is in the buffer and it doesn't match any known 243 * sequence => ESC enables TB_MOD_ALT modifier for the next keyboard event. 244 * 245 * You can also apply TB_INPUT_MOUSE via bitwise OR operation to either of the 246 * modes (e.g. TB_INPUT_ESC | TB_INPUT_MOUSE). If none of the main two modes 247 * were set, but the mouse mode was, TB_INPUT_ESC mode is used. If for some 248 * reason you've decided to use (TB_INPUT_ESC | TB_INPUT_ALT) combination, it 249 * will behave as if only TB_INPUT_ESC was selected. 250 * 251 * TB_INPUT_SPACE may be bitwise OR'd as well to treat space as a regular 252 * character rather than a special/function key. 253 * 254 * If 'mode' is TB_INPUT_CURRENT, it returns the current input mode. 255 * 256 * Default termbox input mode is TB_INPUT_ESC. 257 */ 258 SO_IMPORT int tb_select_input_mode(int mode); 259 260 #define TB_OUTPUT_CURRENT 0 261 #define TB_OUTPUT_NORMAL 1 262 #define TB_OUTPUT_256 2 263 #define TB_OUTPUT_216 3 264 #define TB_OUTPUT_GRAYSCALE 4 265 266 /* Sets the termbox output mode. Termbox has three output options: 267 * 1. TB_OUTPUT_NORMAL => [1..8] 268 * This mode provides 8 different colors: 269 * black, red, green, yellow, blue, magenta, cyan, white 270 * Shortcut: TB_BLACK, TB_RED, ... 271 * Attributes: TB_BOLD, TB_UNDERLINE, TB_REVERSE 272 * 273 * Example usage: 274 * tb_change_cell(x, y, '@', TB_BLACK | TB_BOLD, TB_RED); 275 * 276 * 2. TB_OUTPUT_256 => [0..256] 277 * In this mode you can leverage the 256 terminal mode: 278 * 0x00 - 0x07: the 8 colors as in TB_OUTPUT_NORMAL 279 * 0x08 - 0x0f: TB_* | TB_BOLD 280 * 0x10 - 0xe7: 216 different colors 281 * 0xe8 - 0xff: 24 different shades of grey 282 * 283 * Example usage: 284 * tb_change_cell(x, y, '@', 184, 240); 285 * tb_change_cell(x, y, '@', 0xb8, 0xf0); 286 * 287 * 3. TB_OUTPUT_216 => [0..216] 288 * This mode supports the 3rd range of the 256 mode only. 289 * But you don't need to provide an offset. 290 * 291 * 4. TB_OUTPUT_GRAYSCALE => [0..23] 292 * This mode supports the 4th range of the 256 mode only. 293 * But you dont need to provide an offset. 294 * 295 * Execute build/src/demo/output to see its impact on your terminal. 296 * 297 * If 'mode' is TB_OUTPUT_CURRENT, it returns the current output mode. 298 * 299 * Default termbox output mode is TB_OUTPUT_NORMAL. 300 */ 301 SO_IMPORT int tb_select_output_mode(int mode); 302 303 /* Wait for an event up to 'timeout' milliseconds and fill the 'event' 304 * structure with it, when the event is available. Returns the type of the 305 * event (one of TB_EVENT_* constants) or -1 if there was an error or 0 in case 306 * there were no event during 'timeout' period. 307 */ 308 SO_IMPORT int tb_peek_event(struct tb_event *event, int timeout); 309 310 /* Wait for an event forever and fill the 'event' structure with it, when the 311 * event is available. Returns the type of the event (one of TB_EVENT_* 312 * constants) or -1 if there was an error. 313 */ 314 SO_IMPORT int tb_poll_event(struct tb_event *event); 315 316 /* Utility utf8 functions. */ 317 #define TB_EOF -1 318 SO_IMPORT int tb_utf8_char_length(uint8_t c); 319 SO_IMPORT int tb_utf8_char_to_unicode(uint32_t *out, uint8_t *c); 320 SO_IMPORT int tb_utf8_unicode_to_char(char *out, uint32_t c); 321 322 #ifdef __cplusplus 323 } 324 #endif