payloads/libpayload/curses/PDCurses/IMPLEMNT

   1 PDCurses Implementor's Guide
   2 ============================
   3
   4 Version 1.3 - 200?/??/?? - notes about official ports
   5 Version 1.2 - 2007/07/11 - added PDC_init_pair(), PDC_pair_content(),
   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
  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
  16 programming.
  17
  18 If you want to submit your port for possible inclusion into the main
  19 PDCurses distribution, please follow these guidelines:
  20
  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
  23    necessary. (And prefer modifying curspriv.h over curses.h.)
  24
  25  - Use the same indentation style, naming and scope conventions as the
  26    existing code.
  27
  28  - Release all your code to the public domain -- no copyright. Code
  29    under GPL, BSD, etc. will not be accepted.
  30
  31
  32 DATA STRUCTURES
  33 ---------------
  34
  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
  49 ports define it in pdcdisp.c, but this is not required.
  50
  51
  52 FUNCTIONS
  53 ---------
  54
  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
  59 existing ports.
  60
  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
  64 an application's choices.
  65
  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
  70 consistent style helps readability.
  71
  72
  73 pdcdisp.c:
  74 ----------
  75
  76 void    PDC_gotoyx(int y, int x);
  77
  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
  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
  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
  89 chtype.
  90
  91
  92 pdcgetsc.c:
  93 -----------
  94
  95 int     PDC_get_columns(void);
  96
  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
  99 internally from PDC_scr_open(), but this is not required.)
 100
 101 int     PDC_get_cursor_mode(void);
 102
 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
 107 cursor in normal visibility mode (curs_set(1)).
 108
 109 int     PDC_get_rows(void);
 110
 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
 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
 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
 153 here. Returns OK or ERR, which is passed on by the caller.
 154
 155 int     PDC_mouse_set(void);
 156
 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
 161 the caller.
 162
 163 void    PDC_set_keyboard_binary(bool on);
 164
 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
 168 noraw().
 169
 170
 171 pdcscrn.c:
 172 ----------
 173
 174 bool    PDC_can_change_color(void);
 175
 176 Returns TRUE if init_color() and color_content() give meaningful
 177 results, FALSE otherwise. Called from can_change_color().
 178
 179 int     PDC_color_content(short color, short *red, short *green, short *blue);
 180
 181 The core of color_content(). This does all the work of that function,
 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
 186 The core of init_color(). This does all the work of that function,
 187 except checking for values out of range.
 188
 189 void    PDC_init_pair(short pair, short fg, short bg);
 190
 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
 195 rendering a chtype with the given pair number.
 196
 197 int     PDC_pair_content(short pair, short *fg, short *bg);
 198
 199 The core of pair_content(). This does all the work of that function,
 200 except checking for values out of range and null pointers.
 201
 202 void    PDC_reset_prog_mode(void);
 203
 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
 207 mouse pointer to match the saved mode; in others it does nothing.
 208
 209 void    PDC_reset_shell_mode(void);
 210
 211 The same thing, for reset_shell_mode(). In OS/2 and Win32, it restores
 212 the default console mode; in others it does nothing.
 213
 214 int     PDC_resize_screen(int nlines, int ncols);
 215
 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
 221 action for the platform.
 222
 223 void    PDC_restore_screen_mode(int i);
 224
 225 Called from _restore_mode() in kernel.c, this function does the actual
 226 mode changing, if applicable. Currently used only in DOS and OS/2.
 227
 228 void    PDC_save_screen_mode(int i);
 229
 230 Called from _save_mode() in kernel.c, this function saves the actual
 231 screen mode, if applicable. Currently used only in DOS and OS/2.
 232
 233 void    PDC_scr_close(void);
 234
 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
 239 the cursor to the lower left corner. (The X11 port does nothing.)
 240
 241 void    PDC_scr_free(void);
 242
 243 Frees the memory for SP allocated by PDC_scr_open(). Called by
 244 delscreen().
 245
 246 int     PDC_scr_open(int argc, char **argv);
 247
 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
 260 restoration by PDC_scr_close().
 261
 262
 263 pdcsetsc.c:
 264 -----------
 265
 266 int     PDC_curs_set(int visibility);
 267
 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
 271 appearance of these modes is not specified.
 272
 273
 274 pdcutil.c:
 275 ----------
 276
 277 void    PDC_beep(void);
 278
 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
 282 called from beep().
 283
 284 void    PDC_napms(int ms);
 285
 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
 291 usage.
 292
 293 const char *PDC_sysname(void);
 294
 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
 297 should be much, much shorter (existing platforms use no more than 5).
 298
 299 --------------------------------------------------------------------------
 300
 301 The following functions are implemented in the platform directories, but
 302 are accessed directly by apps. Refer to the user documentation for their
 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);