2ad212e0e553c553809d3b399ccbd00906d1c2dd
[apps/madtty.git] / madtty.h
1 /*
2     LICENSE INFORMATION:
3     This program is free software; you can redistribute it and/or
4     modify it under the terms of the GNU Lesser General Public
5     License (LGPL) as published by the Free Software Foundation.
6
7     Please refer to the COPYING file for more information.
8
9     This program is distributed in the hope that it will be useful,
10     but WITHOUT ANY WARRANTY; without even the implied warranty of
11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12     General Public License for more details.
13
14     You should have received a copy of the GNU Lesser General Public
15     License along with this program; if not, write to the Free Software
16     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
17
18     Copyright © 2004 Bruno T. C. de Oliveira
19     Copyright © 2006 Pierre Habouzit
20  */
21
22 #ifndef MADTTY_MADTTY_H
23 #define MADTTY_MADTTY_H
24
25 #ifdef USE_NCURSES
26 #include <ncurses.h>
27 #else
28 #include <stdbool.h>
29 #endif
30 #include <sys/types.h>
31 #include <unistd.h>
32 #include <stdlib.h>
33
34 /* Color codes: 0 = black, 1 = red, 2 = green, 3 = yellow, 4 = blue,
35  *              5 = magenta, 6 = cyan, 7 = white. 
36  *
37  * An 'attribute' as used in this library means an 8-bit value that conveys
38  * a foreground color code, a background color code, and the bold
39  * and blink bits. Each cell in the virtual terminal screen is associated
40  * with an attribute that specifies its appearance. The bits of an attribute,
41  * from most significant to least significant, are 
42  *
43  *  bit:      7 6 5 4 3 2 1 0
44  *  content:  S F F F H B B B
45  *            | `-,-' | `-,-'
46  *            |   |   |   |
47  *            |   |   |   `----- 3-bit background color code (0 - 7)
48  *            |   |   `--------- blink bit (if on, text is blinking)
49  *            |   `------------- 3-bit foreground color code (0 - 7)
50  *            `----------------- bold bit
51  *
52  * It is however recommended that you use the provided macros rather
53  * than dealing with this format directly.
54  *
55  * Sometimes we will call the 'SFFF' nibble above the 'extended
56  * foreground color code', and the 'HBBB' nibble the 'extended background
57  * color code'. So the extended color codes are just the regular
58  * color codes except that they have an additional bit (the most significant
59  * bit) indicating bold/blink.
60  */
61
62 /* retrieve attribute fields */
63 #define ROTE_ATTR_BG(attr)              ((attr) & 0x07)
64 #define ROTE_ATTR_FG(attr)              (((attr) & 0x70) >> 4)
65
66 /* retrieve 'extended' color codes (see above for info) */
67 #define ROTE_ATTR_XBG(attr)             ((attr) & 0x0F)
68 #define ROTE_ATTR_XFG(attr)             (((attr) & 0xF0) >> 4)
69
70 /* set attribute fields. This requires attr to be an lvalue, and it will
71  * be evaluated more than once. Use with care. */
72 #define ROTE_ATTR_MOD_BG(attr, newbg)    attr &= 0xF8, attr |= (newbg)
73 #define ROTE_ATTR_MOD_FG(attr, newfg)    attr &= 0x8F, attr |= ((newfg) << 4)
74 #define ROTE_ATTR_MOD_XBG(attr, newxbg)  attr &= 0xF0, attr |= (newxbg)
75 #define ROTE_ATTR_MOD_XFG(attr, newxfg)  attr &= 0x0F, attr |= ((newxfg) << 4)
76 #define ROTE_ATTR_MOD_BOLD(attr, boldbit) \
77     attr &= 0x7F, attr |= (boldbit)?0x80:0x00
78 #define ROTE_ATTR_MOD_BLINK(attr, blinkbit) \
79     attr &= 0xF7, attr |= (blinkbit)?0x08:0x00
80
81 /* these return non-zero for 'yes', zero for 'no'. Don't rely on them being 
82  * any more specific than that (e.g. being exactly 1 for 'yes' or whatever). */
83 #define ROTE_ATTR_BOLD(attr)            ((attr) & 0x80)
84 #define ROTE_ATTR_BLINK(attr)           ((attr) & 0x08)
85
86 /* Represents each of the text cells in the terminal screen */
87 typedef struct RoteCell_ {
88     unsigned char ch;    /* >= 32, that is, control characters are not
89                           * allowed to be on the virtual screen */
90
91     unsigned char attr;  /* a color attribute, as described previously */
92 } RoteCell;
93
94 /* Declaration of opaque rote_Term_Private structure */
95 typedef struct RoteTermPrivate_ RoteTermPrivate;
96
97 /* Represents a virtual terminal. You may directly access the fields
98  * of this structure, but please pay close attention to the fields
99  * marked read-only or with special usage notes. */
100 typedef struct RoteTerm_ {
101     int rows, cols;              /* terminal dimensions, READ-ONLY. You
102                                   * can't resize the terminal by changing
103                                   * this (a segfault is about all you will 
104                                   * accomplish). */
105
106     RoteCell **cells;            /* matrix of cells. This
107                                   * matrix is indexed as cell[row][column]
108                                   * where 0 <= row < rows and
109                                   *       0 <= col < cols
110                                   *
111                                   * You may freely modify the contents of
112                                   * the cells.
113                                   */
114
115     int crow, ccol;              /* cursor coordinates. READ-ONLY. */
116
117     unsigned char curattr;       /* current attribute, that is the attribute
118                                   * that will be used for newly inserted
119                                   * characters */
120
121     int   pty;                   /* pty of the process */
122     pid_t childpid;              /* pid of the child process running in the
123                                   * terminal; 0 for none. This is READ-ONLY. */
124
125     RoteTermPrivate *pd;         /* private state data */
126
127     bool insert;                 /* insert or replace mode */
128
129     /* --- dirtiness flags: the following flags will be raised when the
130      * corresponding items are modified. They can only be unset by YOU
131      * (when, for example, you redraw the term or something) --- */
132     bool curpos_dirty;           /* whether cursor location has changed */
133     bool *line_dirty;            /* whether each row is dirty  */
134     /* --- end dirtiness flags */
135 } RoteTerm;
136
137 /* Creates a new virtual terminal with the given dimensions. You
138  * must destroy it with rote_vt_destroy after you are done with it.
139  * The terminal will be initially blank and the cursor will
140  * be at the top-left corner. 
141  *
142  * Returns NULL on error.
143  */
144 RoteTerm *rote_vt_create(int rows, int cols);
145
146 /* Destroys a virtual terminal previously created with
147  * rote_vt_create. If rt == NULL, does nothing. */
148 void rote_vt_destroy(RoteTerm *rt);
149
150 /* Starts a forked process in the terminal. The <command> parameter
151  * is a shell command to execute (it will be interpreted by '/bin/sh -c') 
152  * Returns the pid of the forked process. 
153  *
154  * Some useful reminders: If you want to be notified when child processes exit,
155  * you should handle the SIGCHLD signal.  If, on the other hand, you want to
156  * ignore exitting child processes, you should set the SIGCHLD handler to
157  * SIG_IGN to prevent child processes from hanging around the system as 'zombie
158  * processes'. 
159  *
160  * Continuing to write to a RoteTerm whose child process has died does not
161  * accomplish a lot, but is not an error and should not cause your program
162  * to crash or block indefinitely or anything of that sort :-)
163  * If, however, you want to be tidy and inform the RoteTerm that its
164  * child has died, call rote_vt_forsake_child when appropriate.
165  *
166  * If there is an error, returns -1. Notice that passing an invalid
167  * command will not cause an error at this level: the shell will try
168  * to execute the command and will exit with status 127. You can catch
169  * that by installing a SIGCHLD handler if you want.
170  */
171 pid_t rote_vt_forkpty(RoteTerm *rt, const char *path, const char *argv[]);
172
173 /* Disconnects the RoteTerm from its forked child process. This function
174  * should be called when the child process dies or something of the sort.
175  * It is not strictly necessary to call this function, but it is
176  * certainly tidy. */
177 void rote_vt_forsake_child(RoteTerm *rt);
178
179 int rote_vt_read(RoteTerm *rt, char *buf, int buflen);
180
181 /* Puts data into the terminal: if there is a forked process running,
182  * the data will be sent to it. If there is no forked process,
183  * the data will simply be injected into the terminal (as in
184  * rote_vt_inject) */
185 void rote_vt_write(RoteTerm *rt, const char *data, int length);
186
187 /* Inject data into the terminal. <data> needs NOT be 0-terminated:
188  * its length is solely determined by the <length> parameter. Please
189  * notice that this writes directly to the terminal, that is,
190  * this function does NOT send the data to the forked process
191  * running in the terminal (if any). For that, you might want
192  * to use rote_vt_write.
193  */
194 void rote_vt_inject(RoteTerm *rt, const char *data, int length);
195
196 #ifdef USE_NCURSES
197 /* Paints the virtual terminal screen on the given window, putting
198  * the top-left corner at the given position. The cur_set_attr
199  * function must set the curses attributes given a Rote attribute
200  * byte. It should, for example, do wattrset(win, COLOR_PAIR(n)) where
201  * n is the colorpair appropriate for the attribute and such.
202  *
203  * If you pass NULL for cur_set_attr, the default implementation will
204  * set the color pair given by (bg * 8 + 7 - fg), which seems to be
205  * a common mapping, and the bold and blink attributes will be mapped 
206  * to A_BOLD and A_BLINK.
207  *
208  * At the end of the function, the cursor will be left where the virtual 
209  * cursor of the terminal is supposed to be.
210  *
211  * This function does not call wrefresh(win); you have to do that yourself.
212  */
213 void rote_vt_draw(RoteTerm *rt, WINDOW *win, int startrow, int startcol,
214                   void (*cur_set_attr)(WINDOW *win, unsigned char attr));
215
216 #endif
217 /* Indicates to the terminal that the given key has been pressed.
218  * This will cause the terminal to rote_vt_write() the appropriate
219  * escape sequence for that key (that is, the escape sequence
220  * that the linux text-mode console would produce for it). The argument,
221  * keycode, must be a CURSES EXTENDED KEYCODE, the ones you get
222  * when you use keypad(somewin, TRUE) (see man page). */
223 void rote_vt_keypress(RoteTerm *rt, int keycode);
224
225 /* Takes a snapshot of the current contents of the terminal and
226  * saves them to a dynamically allocated buffer. Returns a pointer
227  * to the newly created buffer, which you can pass to
228  * rote_vt_restore_snapshot. Caller is responsible for free()'ing when
229  * the snapshot is no longer needed. */
230 void *rote_vt_take_snapshot(RoteTerm *rt);
231
232 /* Restores a snapshot previously taken with rote_vt_take_snapshot.
233  * This function does NOT free() the passed buffer */
234 void rote_vt_restore_snapshot(RoteTerm *rt, void *snapbuf);
235
236 #endif /* MADTTY_MADTTY_H */