rote.h.in

   1 /* ROTE - Our Own Terminal Emulation library
   2  * Copyright (c) 2004 Bruno T. C. de Oliveira
   3  * All rights reserved
   4  *
   5  * 2004-08-25
   6  */
   7
   8 /*
   9 LICENSE INFORMATION:
  10 This program is free software; you can redistribute it and/or
  11 modify it under the terms of the GNU Lesser General Public
  12 License (LGPL) as published by the Free Software Foundation.
  13
  14 Please refer to the COPYING file for more information.
  15
  16 This program is distributed in the hope that it will be useful,
  17 but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19 General Public License for more details.
  20
  21 You should have received a copy of the GNU Lesser General Public
  22 License along with this program; if not, write to the Free Software
  23 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  24
  25 Copyright (c) 2004 Bruno T. C. de Oliveira
  26 */
  27
  28
  29 #ifndef btco_ROTE_rote_h
  30 #define btco_ROTE_rote_h
  31
  32 #define _GNU_SOURCE
  33 #if @USE_UTF8@ /* USE_UTF8 */
  34 # include <wchar.h>
  35 #endif
  36
  37 #if @USE_NCURSES@ /* USE_NCURSES */
  38 # if @USE_UTF8@ /* USE_UTF8 */
  39 #  include <ncursesw/ncurses.h>
  40 # else
  41 #  include <ncurses.h>
  42 # endif
  43 #endif
  44 #include <stdbool.h>
  45 #include <sys/types.h>
  46 #include <unistd.h>
  47 #include <stdlib.h>
  48
  49 /* Color codes: 0 = black, 1 = red, 2 = green, 3 = yellow, 4 = blue,
  50  *              5 = magenta, 6 = cyan, 7 = white.
  51  *
  52  * An 'attribute' as used in this library means an 8-bit value that conveys
  53  * a foreground color code, a background color code, and the bold
  54  * and blink bits. Each cell in the virtual terminal screen is associated
  55  * with an attribute that specifies its appearance. The bits of an attribute,
  56  * from most significant to least significant, are
  57  *
  58  *  bit:      7 6 5 4 3 2 1 0
  59  *  content:  S F F F H B B B
  60  *            | `-,-' | `-,-'
  61  *            |   |   |   |
  62  *            |   |   |   `----- 3-bit background color code (0 - 7)
  63  *            |   |   `--------- blink bit (if on, text is blinking)
  64  *            |   `------------- 3-bit foreground color code (0 - 7)
  65  *            `----------------- bold bit
  66  *
  67  * It is however recommended that you use the provided macros rather
  68  * than dealing with this format directly.
  69  *
  70  * Sometimes we will call the 'SFFF' nibble above the 'extended
  71  * foreground color code', and the 'HBBB' nibble the 'extended background
  72  * color code'. So the extended color codes are just the regular
  73  * color codes except that they have an additional bit (the most significant
  74  * bit) indicating bold/blink.
  75  */
  76
  77 /* retrieve attribute fields */
  78 #define ROTE_ATTR_BG(attr)              ((attr) & 0x07)
  79 #define ROTE_ATTR_FG(attr)              (((attr) & 0x70) >> 4)
  80
  81 /* retrieve 'extended' color codes (see above for info) */
  82 #define ROTE_ATTR_XBG(attr)             ((attr) & 0x0F)
  83 #define ROTE_ATTR_XFG(attr)             (((attr) & 0xF0) >> 4)
  84
  85 /* set attribute fields. This requires attr to be an lvalue, and it will
  86  * be evaluated more than once. Use with care. */
  87 #define ROTE_ATTR_MOD_BG(attr, newbg)    attr &= 0xF8, attr |= (newbg)
  88 #define ROTE_ATTR_MOD_FG(attr, newfg)    attr &= 0x8F, attr |= ((newfg) << 4)
  89 #define ROTE_ATTR_MOD_XBG(attr, newxbg)  attr &= 0xF0, attr |= (newxbg)
  90 #define ROTE_ATTR_MOD_XFG(attr, newxfg)  attr &= 0x0F, attr |= ((newxfg) << 4)
  91 #define ROTE_ATTR_MOD_BOLD(attr, boldbit) \
  92                                attr &= 0x7F, attr |= (boldbit)?0x80:0x00
  93 #define ROTE_ATTR_MOD_BLINK(attr, blinkbit) \
  94                                attr &= 0xF7, attr |= (blinkbit)?0x08:0x00
  95
  96 /* these return non-zero for 'yes', zero for 'no'. Don't rely on them being
  97  * any more specific than that (e.g. being exactly 1 for 'yes' or whatever). */
  98 #define ROTE_ATTR_BOLD(attr)            ((attr) & 0x80)
  99 #define ROTE_ATTR_BLINK(attr)           ((attr) & 0x08)
 100
 101 #if @USE_UTF8@ /* USE_UTF8 */
 102    typedef wchar_t char_t;
 103 #else
 104    typedef unsigned int char_t;
 105 #endif
 106
 107 /* Represents each of the text cells in the terminal screen */
 108 typedef struct RoteCell_ {
 109    char_t ch;           /* >= 32, that is, control characters are not
 110                          * allowed to be on the virtual screen */
 111 #if @USE_UTF8@ /* USE_UTF8 */
 112    bool empty; /* if this column is empty or not. */
 113
 114    size_t fcount; /* the number of the columns consumed by this unicode character */
 115
 116    size_t findex; /* the fragment number for this column. */
 117 #endif
 118
 119    unsigned char attr;  /* a color attribute, as described previously */
 120 } RoteCell;
 121
 122 /* Declaration of opaque rote_Term_Private structure */
 123 typedef struct RoteTermPrivate_ RoteTermPrivate;
 124
 125 /* Represents a virtual terminal. You may directly access the fields
 126  * of this structure, but please pay close attention to the fields
 127  * marked read-only or with special usage notes. */
 128 typedef struct RoteTerm_ {
 129    int rows, cols;              /* terminal dimensions, READ-ONLY. You
 130                                  * can't resize the terminal by changing
 131                                  * this (a segfault is about all you will
 132                                  * accomplish). */
 133
 134    RoteCell **cells;            /* matrix of cells. This
 135                                  * matrix is indexed as cell[row][column]
 136                                  * where 0 <= row < rows and
 137                                  *       0 <= col < cols
 138                                  *
 139                                  * You may freely modify the contents of
 140                                  * the cells.
 141                                  */
 142
 143    int crow, ccol;              /* cursor coordinates. READ-ONLY. */
 144
 145    unsigned char curattr;       /* current attribute, that is the attribute
 146                                  * that will be used for newly inserted
 147                                  * characters */
 148
 149    pid_t childpid;              /* pid of the child process running in the
 150                                  * terminal; 0 for none. This is READ-ONLY. */
 151
 152    RoteTermPrivate *pd;         /* private state data */
 153
 154    bool insert;                 /* insert or replace mode */
 155    /* --- dirtiness flags: the following flags will be raised when the
 156     * corresponding items are modified. They can only be unset by YOU
 157     * (when, for example, you redraw the term or something) --- */
 158    bool curpos_dirty;           /* whether cursor location has changed */
 159    bool *line_dirty;            /* whether each row is dirty  */
 160    /* --- end dirtiness flags */
 161 } RoteTerm;
 162
 163 /* Creates a new virtual terminal with the given dimensions. You
 164  * must destroy it with rote_vt_destroy after you are done with it.
 165  * The terminal will be initially blank and the cursor will
 166  * be at the top-left corner.
 167  *
 168  * Returns NULL on error.
 169  */
 170 RoteTerm *rote_vt_create(int rows, int cols);
 171
 172 /* Resizes the associated virtual terminal to the given size and
 173  * sends SIGWINCH to the child process if there is any
 174  *
 175  * Returns NULL on error.
 176  */
 177 RoteTerm *rote_vt_resize(RoteTerm *rt, int rows, int cols);
 178
 179 /* Destroys a virtual terminal previously created with
 180  * rote_vt_create. If rt == NULL, does nothing. */
 181 void rote_vt_destroy(RoteTerm *rt);
 182
 183 /* Starts a forked process in the terminal. The <command> parameter
 184  * is a shell command to execute (it will be interpreted by '/bin/sh -c')
 185  * Returns the pid of the forked process.
 186  *
 187  * Some useful reminders: If you want to be notified when child processes exit,
 188  * you should handle the SIGCHLD signal.  If, on the other hand, you want to
 189  * ignore exitting child processes, you should set the SIGCHLD handler to
 190  * SIG_IGN to prevent child processes from hanging around the system as 'zombie
 191  * processes'.
 192  *
 193  * Continuing to write to a RoteTerm whose child process has died does not
 194  * accomplish a lot, but is not an error and should not cause your program
 195  * to crash or block indefinitely or anything of that sort :-)
 196  * If, however, you want to be tidy and inform the RoteTerm that its
 197  * child has died, call rote_vt_forsake_child when appropriate.
 198  *
 199  * If there is an error, returns -1. Notice that passing an invalid
 200  * command will not cause an error at this level: the shell will try
 201  * to execute the command and will exit with status 127. You can catch
 202  * that by installing a SIGCHLD handler if you want.
 203  */
 204 pid_t rote_vt_forkpty(RoteTerm *rt, const char *command);
 205
 206 /* Disconnects the RoteTerm from its forked child process. This function
 207  * should be called when the child process dies or something of the sort.
 208  * It is not strictly necessary to call this function, but it is
 209  * certainly tidy. */
 210 void rote_vt_forsake_child(RoteTerm *rt);
 211
 212 /* Does some data plumbing, that is, sees if the sub process has
 213  * something to write to the terminal, and if so, write it. If you
 214  * called rote_vt_fork to start a forked process, you must call
 215  * this function regularly to update the terminal.
 216  *
 217  * This function will not block, that is, if there is no data to be
 218  * read from the child process it will return immediately. */
 219 void rote_vt_update(RoteTerm *rt);
 220
 221 /* Puts data into the terminal: if there is a forked process running,
 222  * the data will be sent to it. If there is no forked process,
 223  * the data will simply be injected into the terminal (as in
 224  * rote_vt_inject) */
 225 void rote_vt_write(RoteTerm *rt, const char *data, int length);
 226
 227 /* Inject data into the terminal. <data> needs NOT be 0-terminated:
 228  * its length is solely determined by the <length> parameter. Please
 229  * notice that this writes directly to the terminal, that is,
 230  * this function does NOT send the data to the forked process
 231  * running in the terminal (if any). For that, you might want
 232  * to use rote_vt_write.
 233  */
 234 void rote_vt_inject(RoteTerm *rt, const char *data, int length);
 235
 236 #if @USE_NCURSES@ /* USE_NCURSES */
 237 /* Paints the virtual terminal screen on the given window, putting
 238  * the top-left corner at the given position. The cur_set_attr
 239  * function must set the curses attributes given a Rote attribute
 240  * byte. It should, for example, do wattrset(win, COLOR_PAIR(n)) where
 241  * n is the colorpair appropriate for the attribute and such.
 242  *
 243  * If you pass NULL for cur_set_attr, the default implementation will
 244  * set the color pair given by (bg * 8 + 7 - fg), which seems to be
 245  * a common mapping, and the bold and blink attributes will be mapped
 246  * to A_BOLD and A_BLINK.
 247  *
 248  * At the end of the function, the cursor will be left where the virtual
 249  * cursor of the terminal is supposed to be.
 250  *
 251  * This function does not call wrefresh(win); you have to do that yourself.
 252  * This function automatically calls rote_vt_update prior to drawing
 253  * so that the drawn contents are accurate.
 254  */
 255 void rote_vt_draw(RoteTerm *rt, WINDOW *win, int startrow, int startcol,
 256                   void (*cur_set_attr)(WINDOW *win, unsigned char attr));
 257
 258 #endif
 259 /* Indicates to the terminal that the given key has been pressed.
 260  * This will cause the terminal to rote_vt_write() the appropriate
 261  * escape sequence for that key (that is, the escape sequence
 262  * that the linux text-mode console would produce for it). The argument,
 263  * keycode, must be a CURSES EXTENDED KEYCODE, the ones you get
 264  * when you use keypad(somewin, TRUE) (see man page). */
 265 void rote_vt_keypress(RoteTerm *rt, int keycode);
 266
 267 /* Takes a snapshot of the current contents of the terminal and
 268  * saves them to a dynamically allocated buffer. Returns a pointer
 269  * to the newly created buffer, which you can pass to
 270  * rote_vt_restore_snapshot. Caller is responsible for free()'ing when
 271  * the snapshot is no longer needed. */
 272 void *rote_vt_take_snapshot(RoteTerm *rt);
 273
 274 /* Restores a snapshot previously taken with rote_vt_take_snapshot.
 275  * This function does NOT free() the passed buffer */
 276 void rote_vt_restore_snapshot(RoteTerm *rt, void *snapbuf);
 277
 278 /* Returns the pseudo tty descriptor associated with the given terminal.
 279  * Please don't do weird things with it (like close it for instance),
 280  * or things will break
 281  *
 282  * This function returns -1 if the given terminal does not yet have
 283  * an associated pty. A pty is only associated to a terminal when
 284  * needed, e.g. on a call to rote_vt_forkpty. */
 285 int rote_vt_get_pty_fd(RoteTerm *rt);
 286
 287 /* Declaration of custom escape sequence callback type. See the
 288  * rote_vt_add_es_handler function for more info */
 289 typedef int (*rote_es_handler_t)(RoteTerm *rt, const char *es);
 290
 291 /* Installs a custom escape sequence handler for the given RoteTerm.
 292  * The handler will be called by the library every time it tries to
 293  * recognize an escape sequence; depending on the return value of the
 294  * handler, it will proceed in a different manner. See the description
 295  * of the possible return values (ROTE_HANDLERESULT_* constants) below
 296  * for more info.
 297  *
 298  * This handler will be called EACH TIME THE ESCAPE SEQUENCE BUFFER
 299  * RECEIVES A CHARACTER. Therefore, it must execute speedily in order
 300  * not to create too heavy a performance penalty. In particular, the
 301  * writer of the handler should take care to quickly test for invalid
 302  * or incomplete escape sequences before trying to do more elaborate
 303  * parsing.
 304  *
 305  * The handler will NOT be called with an empty escape sequence (i.e.
 306  * one in which only the initial ESC was received).
 307  *
 308  * The custom handler receives the terminal it pertains to and the
 309  * escape sequence as a string (without the initial escape character).
 310  *
 311  * The handler may of course modify the terminal as it sees fit, taking
 312  * care not to corrupt it of course (in particular, it should appropriately
 313  * raise the line_dirty[] and curpos_dirty flags to indicate what it has
 314  * changed).
 315  */
 316 void rote_vt_install_handler(RoteTerm *rt, rote_es_handler_t handler);
 317
 318 /* Possible return values for the custom handler function and their
 319  * meanings: */
 320 #define ROTE_HANDLERESULT_OK 0      /* means escape sequence was handled */
 321
 322 #define ROTE_HANDLERESULT_NOTYET 1  /* means the escape sequence was not
 323                                      * recognized yet, but there is hope that
 324                                      * it still will once more characters
 325                                      * arrive (i.e. it is not yet complete).
 326                                      *
 327                                      * The library will thus continue collecting
 328                                      * characters and calling the handler as
 329                                      * each character arrives until
 330                                      * either OK or NOWAY is returned.
 331                                      */
 332
 333 #define ROTE_HANDLERESULT_NOWAY 2   /* means the escape sequence was not
 334                                      * recognized, and there is no chance
 335                                      * that it will even if more characters
 336                                      * are added to it. */
 337
 338 #endif
 339