Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 1 | PDCurses Implementor's Guide |
| 2 | ============================ |
| 3 | |
| 4 | Version 1.3 - 200?/??/?? - notes about official ports |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 5 | Version 1.2 - 2007/07/11 - added PDC_init_pair(), PDC_pair_content(), |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 6 | version history; removed pdc_atrtab |
| 7 | Version 1.1 - 2007/06/06 - minor cosmetic change |
| 8 | Version 1.0 - 2007/04/01 - initial revision |
| 9 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 10 | This document is for those wishing to port PDCurses to a new platform, |
| 11 | or just wanting to better understand how it works. Nothing here should |
| 12 | be needed for application programming; for that, refer to PDCurses.txt, |
| 13 | as built in doc/, or distributed as a file separate from this source |
| 14 | package. This document assumes that you've read the user-level |
| 15 | documentation and are very familiar with application-level curses |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 16 | programming. |
| 17 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 18 | If you want to submit your port for possible inclusion into the main |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 19 | PDCurses distribution, please follow these guidelines: |
| 20 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 21 | - Don't modify anything in the pdcurses directory or in other port |
| 22 | directories. Don't modify curses.h or curspriv.h unless absolutely |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 23 | necessary. (And prefer modifying curspriv.h over curses.h.) |
| 24 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 25 | - Use the same indentation style, naming and scope conventions as the |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 26 | existing code. |
| 27 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 28 | - Release all your code to the public domain -- no copyright. Code |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 29 | under GPL, BSD, etc. will not be accepted. |
| 30 | |
| 31 | |
| 32 | DATA STRUCTURES |
| 33 | --------------- |
| 34 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 35 | A port of PDCurses must provide acs_map[], a 128-element array of |
| 36 | chtypes, with values laid out based on the Alternate Character Set of |
| 37 | the VT100 (see curses.h). PDC_transform_line() must use this table; when |
| 38 | it encounters a chtype with the A_ALTCHARSET flag set, and an A_CHARTEXT |
| 39 | value in the range 0-127, it must render it using the A_CHARTEXT portion |
| 40 | of the corresponding value from this table, instead of the original |
| 41 | value. Also, values may be read from this table by apps, and passed |
| 42 | through functions such as waddch(), which does no special processing on |
| 43 | control characters (0-31 and 127) when the A_ALTCHARSET flag is set. |
| 44 | Thus, any control characters used in acs_map[] should also have the |
| 45 | A_ALTCHARSET flag set. Implementations should provide suitable values |
| 46 | for all the ACS_ macros defined in curses.h; other values in the table |
| 47 | should be filled with their own indices (e.g., acs_map['E'] == 'E'). The |
| 48 | table can be either hardwired, or filled by PDC_scr_open(). Existing |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 49 | ports define it in pdcdisp.c, but this is not required. |
| 50 | |
| 51 | |
| 52 | FUNCTIONS |
| 53 | --------- |
| 54 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 55 | A port of PDCurses must implement the following functions, with extern |
| 56 | scope. These functions are traditionally divided into several modules, |
| 57 | as indicated below; this division is not required (only the functions |
| 58 | are), but may make it easier to follow for someone familiar with the |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 59 | existing ports. |
| 60 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 61 | Any other functions you create as part of your implementation should |
| 62 | have static scope, if possible. If they can't be static, they should be |
| 63 | named with the "PDC_" prefix. This minimizes the risk of collision with |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 64 | an application's choices. |
| 65 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 66 | Current PDCurses style also uses a single leading underscore with the |
| 67 | name of any static function; and modified BSD/Allman-style indentation, |
| 68 | approximately equivalent to "indent -kr -i8 -bl -bli0", with adjustments |
| 69 | to keep every line under 80 columns. This isn't essential, but a |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 70 | consistent style helps readability. |
| 71 | |
| 72 | |
| 73 | pdcdisp.c: |
| 74 | ---------- |
| 75 | |
| 76 | void PDC_gotoyx(int y, int x); |
| 77 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 78 | Move the physical cursor (as opposed to the logical cursor affected by |
| 79 | wmove()) to the given location. This is called mainly from doupdate(). |
| 80 | In general, this function need not compare the old location with the new |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 81 | one, and should just move the cursor unconditionally. |
| 82 | |
| 83 | void PDC_transform_line(int lineno, int x, int len, const chtype *srcp); |
| 84 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 85 | The core output routine. It takes len chtype entities from srcp (a |
| 86 | pointer into curscr) and renders them to the physical screen at line |
| 87 | lineno, column x. It must also translate characters 0-127 via acs_map[], |
| 88 | if they're flagged with A_ALTCHARSET in the attribute portion of the |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 89 | chtype. |
| 90 | |
| 91 | |
| 92 | pdcgetsc.c: |
| 93 | ----------- |
| 94 | |
| 95 | int PDC_get_columns(void); |
| 96 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 97 | Returns the size of the screen in columns. It's used in resize_term() to |
| 98 | set the new value of COLS. (Some existing implementations also call it |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 99 | internally from PDC_scr_open(), but this is not required.) |
| 100 | |
| 101 | int PDC_get_cursor_mode(void); |
| 102 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 103 | Returns the size/shape of the cursor. The format of the result is |
| 104 | unspecified, except that it must be returned as an int. This function is |
| 105 | called from initscr(), and the result is stored in SP->orig_cursor, |
| 106 | which is used by PDC_curs_set() to determine the size/shape of the |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 107 | cursor in normal visibility mode (curs_set(1)). |
| 108 | |
| 109 | int PDC_get_rows(void); |
| 110 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 111 | Returns the size of the screen in rows. It's used in resize_term() to |
| 112 | set the new value of LINES. (Some existing implementations also call it |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 113 | internally from PDC_scr_open(), but this is not required.) |
| 114 | |
| 115 | |
| 116 | pdckbd.c: |
| 117 | --------- |
| 118 | |
| 119 | bool PDC_check_key(void); |
| 120 | |
| 121 | Keyboard/mouse event check, called from wgetch(). Returns TRUE if |
| 122 | there's an event ready to process. This function must be non-blocking. |
| 123 | |
| 124 | void PDC_flushinp(void); |
| 125 | |
| 126 | This is the core of flushinp(). It discards any pending key or mouse |
| 127 | events, removing them from any internal queue and from the OS queue, if |
| 128 | applicable. |
| 129 | |
| 130 | int PDC_get_key(void); |
| 131 | |
| 132 | Get the next available key, or mouse event (indicated by a return of |
| 133 | KEY_MOUSE), and remove it from the OS' input queue, if applicable. This |
| 134 | function is called from wgetch(). This function may be blocking, and |
| 135 | traditionally is; but it need not be. If a valid key or mouse event |
| 136 | cannot be returned, for any reason, this function returns -1. Valid keys |
| 137 | are those that fall within the appropriate character set, or are in the |
| 138 | list of special keys found in curses.h (KEY_MIN through KEY_MAX). When |
| 139 | returning a special key code, this routine must also set SP->key_code to |
| 140 | TRUE; otherwise it must set it to FALSE. If SP->return_key_modifiers is |
| 141 | TRUE, this function may return modifier keys (shift, control, alt), |
| 142 | pressed alone, as special key codes; if SP->return_key_modifiers is |
| 143 | FALSE, it must not. If modifier keys are returned, it should only happen |
| 144 | if no other keys were pressed in the meantime; i.e., the return should |
| 145 | happen on key up. But if this is not possible, it may return the |
| 146 | modifier keys on key down (if and only if SP->return_key_modifiers is |
| 147 | TRUE). |
| 148 | |
| 149 | int PDC_modifiers_set(void); |
| 150 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 151 | Called from PDC_return_key_modifiers(). If your platform needs to do |
| 152 | anything in response to a change in SP->return_key_modifiers, do it |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 153 | here. Returns OK or ERR, which is passed on by the caller. |
| 154 | |
| 155 | int PDC_mouse_set(void); |
| 156 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 157 | Called by mouse_set(), mouse_on(), and mouse_off() -- all the functions |
| 158 | that modify SP->_trap_mbe. If your platform needs to do anything in |
| 159 | response to a change in SP->_trap_mbe (for example, turning the mouse |
| 160 | cursor on or off), do it here. Returns OK or ERR, which is passed on by |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 161 | the caller. |
| 162 | |
| 163 | void PDC_set_keyboard_binary(bool on); |
| 164 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 165 | Set keyboard input to "binary" mode. If you need to do something to keep |
| 166 | the OS from processing ^C, etc. on your platform, do it here. TRUE turns |
| 167 | the mode on; FALSE reverts it. This function is called from raw() and |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 168 | noraw(). |
| 169 | |
| 170 | |
| 171 | pdcscrn.c: |
| 172 | ---------- |
| 173 | |
| 174 | bool PDC_can_change_color(void); |
| 175 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 176 | Returns TRUE if init_color() and color_content() give meaningful |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 177 | results, FALSE otherwise. Called from can_change_color(). |
| 178 | |
| 179 | int PDC_color_content(short color, short *red, short *green, short *blue); |
| 180 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 181 | The core of color_content(). This does all the work of that function, |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 182 | except checking for values out of range and null pointers. |
| 183 | |
| 184 | int PDC_init_color(short color, short red, short green, short blue); |
| 185 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 186 | The core of init_color(). This does all the work of that function, |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 187 | except checking for values out of range. |
| 188 | |
| 189 | void PDC_init_pair(short pair, short fg, short bg); |
| 190 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 191 | The core of init_pair(). This does all the work of that function, except |
| 192 | checking for values out of range. The values passed to this function |
| 193 | should be returned by a call to PDC_pair_content() with the same pair |
| 194 | number. PDC_transform_line() should use the specified colors when |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 195 | rendering a chtype with the given pair number. |
| 196 | |
| 197 | int PDC_pair_content(short pair, short *fg, short *bg); |
| 198 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 199 | The core of pair_content(). This does all the work of that function, |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 200 | except checking for values out of range and null pointers. |
| 201 | |
| 202 | void PDC_reset_prog_mode(void); |
| 203 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 204 | The non-portable functionality of reset_prog_mode() is handled here -- |
| 205 | whatever's not done in _restore_mode(). In current ports: In OS/2, this |
| 206 | sets the keyboard to binary mode; in Win32, it enables or disables the |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 207 | mouse pointer to match the saved mode; in others it does nothing. |
| 208 | |
| 209 | void PDC_reset_shell_mode(void); |
| 210 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 211 | The same thing, for reset_shell_mode(). In OS/2 and Win32, it restores |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 212 | the default console mode; in others it does nothing. |
| 213 | |
| 214 | int PDC_resize_screen(int nlines, int ncols); |
| 215 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 216 | This does the main work of resize_term(). It may respond to non-zero |
| 217 | parameters, by setting the screen to the specified size; to zero |
| 218 | parameters, by setting the screen to a size chosen by the user at |
| 219 | runtime, in an unspecified way (e.g., by dragging the edges of the |
| 220 | window); or both. It may also do nothing, if there's no appropriate |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 221 | action for the platform. |
| 222 | |
| 223 | void PDC_restore_screen_mode(int i); |
| 224 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 225 | Called from _restore_mode() in kernel.c, this function does the actual |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 226 | mode changing, if applicable. Currently used only in DOS and OS/2. |
| 227 | |
| 228 | void PDC_save_screen_mode(int i); |
| 229 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 230 | Called from _save_mode() in kernel.c, this function saves the actual |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 231 | screen mode, if applicable. Currently used only in DOS and OS/2. |
| 232 | |
| 233 | void PDC_scr_close(void); |
| 234 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 235 | The platform-specific part of endwin(). It may restore the image of the |
| 236 | original screen saved by PDC_scr_open(), if the PDC_RESTORE_SCREEN |
| 237 | environment variable is set; either way, if using an existing terminal, |
| 238 | this function should restore it to the mode it had at startup, and move |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 239 | the cursor to the lower left corner. (The X11 port does nothing.) |
| 240 | |
| 241 | void PDC_scr_free(void); |
| 242 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 243 | Frees the memory for SP allocated by PDC_scr_open(). Called by |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 244 | delscreen(). |
| 245 | |
| 246 | int PDC_scr_open(int argc, char **argv); |
| 247 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 248 | The platform-specific part of initscr(). It's actually called from |
| 249 | Xinitscr(); the arguments, if present, correspond to those used with |
| 250 | main(), and may be used to set the title of the terminal window, or for |
| 251 | other, platform-specific purposes. (The arguments are currently used |
| 252 | only in X11.) PDC_scr_open() must allocate memory for SP, and must |
| 253 | initialize acs_map[] (unless it's preset) and several members of SP, |
| 254 | including lines, cols, mouse_wait, orig_attr (and if orig_attr is TRUE, |
| 255 | orig_fore and orig_back), mono, _restore and _preserve. (Although SP is |
| 256 | used the same way in all ports, it's allocated here in order to allow |
| 257 | the X11 port to map it to a block of shared memory.) If using an |
| 258 | existing terminal, and the environment variable PDC_RESTORE_SCREEN is |
| 259 | set, this function may also store the existing screen image for later |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 260 | restoration by PDC_scr_close(). |
| 261 | |
| 262 | |
| 263 | pdcsetsc.c: |
| 264 | ----------- |
| 265 | |
| 266 | int PDC_curs_set(int visibility); |
| 267 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 268 | Called from curs_set(). Changes the appearance of the cursor -- 0 turns |
| 269 | it off, 1 is normal (the terminal's default, if applicable, as |
| 270 | determined by SP->orig_cursor), and 2 is high visibility. The exact |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 271 | appearance of these modes is not specified. |
| 272 | |
| 273 | |
| 274 | pdcutil.c: |
| 275 | ---------- |
| 276 | |
| 277 | void PDC_beep(void); |
| 278 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 279 | Emits a short audible beep. If this is not possible on your platform, |
| 280 | you must set SP->audible to FALSE during initialization (i.e., from |
| 281 | PDC_scr_open() -- not here); otherwise, set it to TRUE. This function is |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 282 | called from beep(). |
| 283 | |
| 284 | void PDC_napms(int ms); |
| 285 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 286 | This is the core delay routine, called by napms(). It pauses for about |
| 287 | (the X/Open spec says "at least") ms milliseconds, then returns. High |
| 288 | degrees of accuracy and precision are not expected (though desirable, if |
| 289 | you can achieve them). More important is that this function gives back |
| 290 | the process' time slice to the OS, so that PDCurses idles at low CPU |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 291 | usage. |
| 292 | |
| 293 | const char *PDC_sysname(void); |
| 294 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 295 | Returns a short string describing the platform, such as "DOS" or "X11". |
| 296 | This is used by longname(). It must be no more than 100 characters; it |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 297 | should be much, much shorter (existing platforms use no more than 5). |
| 298 | |
| 299 | -------------------------------------------------------------------------- |
| 300 | |
Stefan Reinauer | 5bbc5e5 | 2015-11-10 09:13:43 -0800 | [diff] [blame] | 301 | The following functions are implemented in the platform directories, but |
| 302 | are accessed directly by apps. Refer to the user documentation for their |
Patrick Georgi | 3b77b72 | 2011-07-07 15:41:53 +0200 | [diff] [blame] | 303 | descriptions: |
| 304 | |
| 305 | |
| 306 | pdcclip.c: |
| 307 | ---------- |
| 308 | |
| 309 | int PDC_clearclipboard(void); |
| 310 | int PDC_freeclipboard(char *contents); |
| 311 | int PDC_getclipboard(char **contents, long *length); |
| 312 | int PDC_setclipboard(const char *contents, long length); |
| 313 | |
| 314 | |
| 315 | pdckbd.c: |
| 316 | --------- |
| 317 | |
| 318 | unsigned long PDC_get_input_fd(void); |
| 319 | |
| 320 | |
| 321 | pdcsetsc.c: |
| 322 | ----------- |
| 323 | |
| 324 | int PDC_set_blink(bool blinkon); |
| 325 | void PDC_set_title(const char *title); |