termbox.h

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