Doc/lib/libcurses.tex

   1 \section{\module{curses} ---
   2          Terminal independant console handling}
   3
   4 \declaremodule{extension}{curses}
   5 \sectionauthor{Moshe Zadka}{mzadka@geocities.com}
   6 \modulesynopsis{An interface to the curses library.}
   7
   8 The \module{curses} module provides an interface to the curses \UNIX{}
   9 library, the de-facto standard for portable advanced terminal
  10 handling.
  11
  12 While curses is most widely used in the \UNIX{} environment, versions
  13 are available for DOS, OS/2, and possibly other systems as well.  The
  14 extension module has not been tested with all available versions of
  15 curses.
  16
  17 \begin{seealso}
  18   \seetext{Tutorial material on using curses with Python is available
  19            on the Python Web site as Andrew Kuchling's
  20 \citetitle[http://www.python.org/doc/howto/curses/curses.html]{Curses
  21            Programming with Python}, at
  22            \url{http://www.python.org/doc/howto/curses/curses.html}.}
  23 \end{seealso}
  24
  25
  26 \subsection{Constants and Functions \label{curses-functions}}
  27
  28 The \module{curses} module defines the following data members:
  29
  30 \begin{datadesc}{version}
  31 A string representing the current version of the module.
  32 \end{datadesc}
  33
  34 \begin{datadesc}{A_NORMAL}
  35 Normal attribute.
  36 \end{datadesc}
  37
  38 \begin{datadesc}{A_STANDOUT}
  39 Standout mode.
  40 \end{datadesc}
  41
  42 \begin{datadesc}{A_UNDERLINE}
  43 Underline mode.
  44 \end{datadesc}
  45
  46 \begin{datadesc}{A_BLINK}
  47 Blink mode.
  48 \end{datadesc}
  49
  50 \begin{datadesc}{A_DIM}
  51 Dim mode.
  52 \end{datadesc}
  53
  54 \begin{datadesc}{A_BOLD}
  55 Bold mode.
  56 \end{datadesc}
  57
  58 \begin{datadesc}{A_ALTCHARSET}
  59 Alternate character set mode.
  60 \end{datadesc}
  61
  62 \begin{datadesc}{KEY_*}
  63 Names for various keys. The exact names available are system dependant.
  64 \end{datadesc}
  65
  66 \begin{datadesc}{ACS_*}
  67 Names for various characters:
  68 \constant{ACS_ULCORNER}, \constant{ACS_LLCORNER},
  69 \constant{ACS_URCORNER}, \constant{ACS_LRCORNER}, \constant{ACS_RTEE},
  70 \constant{ACS_LTEE}, \constant{ACS_BTEE}, \constant{ACS_TTEE},
  71 \constant{ACS_HLINE}, \constant{ACS_VLINE}, \constant{ACS_PLUS},
  72 \constant{ACS_S1}, \constant{ACS_S9}, \constant{ACS_DIAMOND},
  73 \constant{ACS_CKBOARD}, \constant{ACS_DEGREE}, \constant{ACS_PLMINUS},
  74 \constant{ACS_BULLET}, \constant{ACS_LARROW}, \constant{ACS_RARROW},
  75 \constant{ACS_DARROW}.
  76
  77 \strong{Note:} These are available only after \function{initscr()} has
  78 been called.
  79 \end{datadesc}
  80
  81 The module \module{curses} defines the following exception:
  82 \begin{excdesc}{error}
  83 Curses function returned an error status.
  84 \end{excdesc}
  85
  86 \strong{Note:} Whenever \var{x} or \var{y} arguments to a function
  87 or a method are optional, they default to the current cursor location.
  88 Whenever \var{attr} is optional, it defaults to \constant{A_NORMAL}.
  89
  90 The module \module{curses} defines the following functions:
  91
  92 \begin{funcdesc}{initscr}{}
  93 Initialize the library. Returns a \class{WindowObject} which represents
  94 the whole screen.
  95 \end{funcdesc}
  96
  97 \begin{funcdesc}{endwin}{}
  98 De-initialize the library, and return terminal to normal status.
  99 \end{funcdesc}
 100
 101 \begin{funcdesc}{isendwin}{}
 102 Returns true if \function{endwin()} has been called.
 103 \end{funcdesc}
 104
 105 \begin{funcdesc}{doupdate}{}
 106 Update the screen.
 107 \end{funcdesc}
 108
 109 \begin{funcdesc}{newwin}{\optional{nlines, ncols,} begin_y, begin_x}
 110 Return a new window, whose left-upper corner is at
 111 \code{(\var{begin_y}, \var{begin_x})}, and whose height/width is
 112 \var{nlines}/\var{ncols}.
 113
 114 By default, the window will extend from the
 115 specified position to the lower right corner of the screen.
 116 \end{funcdesc}
 117
 118 \begin{funcdesc}{beep}{}
 119 Emit a short sound.
 120 \end{funcdesc}
 121
 122 \begin{funcdesc}{flash}{}
 123 Flash the screen.
 124 \end{funcdesc}
 125
 126 \begin{funcdesc}{ungetch}{ch}
 127 Push \var{ch} so the next \method{getch()} will return it; \var{ch} is
 128 an integer specifying the character to be pushed.
 129 \strong{Note:} only one \var{ch} can be pushed before \method{getch()}
 130 is called.
 131 \end{funcdesc}
 132
 133 \begin{funcdesc}{flushinp}{}
 134 Flush all input buffers.
 135 \end{funcdesc}
 136
 137 \begin{funcdesc}{cbreak}{}
 138 Enter cbreak mode.
 139 \end{funcdesc}
 140
 141 \begin{funcdesc}{nocbreak}{}
 142 Leave cbreak mode.
 143 \end{funcdesc}
 144
 145 \begin{funcdesc}{echo}{}
 146 Enter echo mode.
 147 \end{funcdesc}
 148
 149 \begin{funcdesc}{noecho}{}
 150 Leave echo mode.
 151 \end{funcdesc}
 152
 153 \begin{funcdesc}{nl}{}
 154 Enter nl mode.
 155 \end{funcdesc}
 156
 157 \begin{funcdesc}{nonl}{}
 158 Leave nl mode.
 159 \end{funcdesc}
 160
 161 \begin{funcdesc}{raw}{}
 162 Enter raw mode.
 163 \end{funcdesc}
 164
 165 \begin{funcdesc}{noraw}{}
 166 Leave raw mode.
 167 \end{funcdesc}
 168
 169 \begin{funcdesc}{meta}{yes}
 170 If \var{yes} is 1, allow 8-bit characters. If \var{yes} is 0,
 171 allow only 7-bit chars.
 172 \end{funcdesc}
 173
 174 \begin{funcdesc}{keyname}{k}
 175 Return the name of the key numbered \var{k}.
 176 \end{funcdesc}
 177
 178
 179 \subsection{Window Objects \label{curses-window-objects}}
 180
 181 Window objects, as returned by \function{initscr()} and
 182 \function{newwin()} above, have the
 183 following methods:
 184
 185 \begin{methoddesc}{refresh}{}
 186 Update the display immediately (sync actual screen with previous
 187 drawing/deleting methods).
 188 \end{methoddesc}
 189
 190 \begin{methoddesc}{nooutrefresh}{}
 191 Mark for refresh but wait.
 192 \end{methoddesc}
 193
 194 \begin{methoddesc}{mvwin}{new_y, new_x}
 195 Move the window so its upper-left corner is at \code{(\var{new_y}, \var{new_x})}.
 196 \end{methoddesc}
 197
 198 \begin{methoddesc}{move}{new_y, new_x}
 199 Move cursor to \code{(\var{new_y}, \var{new_x})}.
 200 \end{methoddesc}
 201
 202 \begin{methoddesc}{subwin}{\optional{nlines, ncols,} begin_y, begin_y}
 203 Return a sub-window, whose upper-left corner is at
 204 \code{(\var{begin_y}, \var{begin_x})}, and whose width/height is
 205 \var{ncols}/\var{nlines}.
 206
 207 By default, the sub-window will extend from the
 208 specified position to the lower right corner of the window.
 209 \end{methoddesc}
 210
 211 \begin{methoddesc}{addch}{\optional{y, x,} ch\optional{, attr}}
 212 \strong{Note:} A \emph{character} means a C character (i.e., an
 213 \ASCII{} code), rather then a Python character (a string of length 1).
 214 (This note is true whenever the documentation mentions a character.)
 215
 216 Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes
 217 \var{attr}, overwriting any character previously painter at that
 218 location.  By default, the character position and attributes are the
 219 current settings for the window object.
 220 \end{methoddesc}
 221
 222 \begin{methoddesc}{insch}{\optional{y, x,} ch\optional{, attr}}
 223 Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes
 224 \var{attr}, moving the line from position \var{x} right by one
 225 character.
 226 \end{methoddesc}
 227
 228 \begin{methoddesc}{delch}{\optional{x, y}}
 229 Delete any character at \code{(\var{y}, \var{x})}.
 230 \end{methoddesc}
 231
 232 \begin{methoddesc}{echochar}{ch\optional{, attr}}
 233 Add character \var{ch} with attribute \var{attr}, and immediately
 234 call \method{refresh}.
 235 \end{methoddesc}
 236
 237 \begin{methoddesc}{addstr}{\optional{y, x,} str\optional{, attr}}
 238 Paint string \var{str} at \code{(\var{y}, \var{x})} with attributes
 239 \var{attr}, overwriting anything previously on the display.
 240 \end{methoddesc}
 241
 242 \begin{methoddesc}{attron}{attr}
 243 Turn on attribute \var{attr}.
 244 \end{methoddesc}
 245
 246 \begin{methoddesc}{attroff}{attr}
 247 Turn off attribute \var{attr}.
 248 \end{methoddesc}
 249
 250 \begin{methoddesc}{setattr}{attr}
 251 Set the current attributes to \var{attr}.
 252 \end{methoddesc}
 253
 254 \begin{methoddesc}{standend}{}
 255 Turn off all attributes.
 256 \end{methoddesc}
 257
 258 \begin{methoddesc}{standout}{}
 259 Turn on attribute \var{A_STANDOUT}.
 260 \end{methoddesc}
 261
 262 \begin{methoddesc}{border}{\optional{ls\optional{, rs\optional{, ts\optional{,
 263                            bs\optional{, tl\optional{, tr\optional{,
 264                            bl\optional{, br}}}}}}}}}
 265 Draw a border around the edges of the window. Each parameter specifies
 266 the character to use for a specific part of the border; see the table
 267 below for more details.  The characters must be specified as integers;
 268 using one-character strings will cause \exception{TypeError} to be
 269 raised.
 270
 271 \strong{Note:} A \code{0} value for any parameter will cause the
 272 default character to be used for that parameter.  Keyword parameters
 273 can \emph{not} be used.  The defaults are listed in this table:
 274
 275 \begin{tableiii}{l|l|l}{var}{Parameter}{Description}{Default value}
 276   \lineiii{ls}{Left side}{\constant{ACS_VLINE}}
 277   \lineiii{rs}{Right side}{\constant{ACS_VLINE}}
 278   \lineiii{ts}{Top}{\constant{ACS_HLINE}}
 279   \lineiii{bs}{Bottom}{\constant{ACS_HLINE}}
 280   \lineiii{tl}{Upper-left corner}{\constant{ACS_ULCORNER}}
 281   \lineiii{tr}{Upper-right corner}{\constant{ACS_URCORNER}}
 282   \lineiii{bl}{Bottom-left corner}{\constant{ACS_BLCORNER}}
 283   \lineiii{br}{Bottom-right corner}{\constant{ACS_BRCORNER}}
 284 \end{tableiii}
 285 \end{methoddesc}
 286
 287 \begin{methoddesc}{box}{\optional{vertch, horch}}
 288 Similar to \method{border()}, but both \var{ls} and \var{rs} are
 289 \var{vertch} and both \var{ts} and {bs} are \var{horch}.  The default
 290 corner characters are always used by this function.
 291 \end{methoddesc}
 292
 293 \begin{methoddesc}{hline}{\optional{y, x,} ch, n}
 294 Display a horizontal line starting at \code{(\var{y}, \var{x})} with
 295 length \var{n} consisting of the character \var{ch}.
 296 \end{methoddesc}
 297
 298 \begin{methoddesc}{vline}{\optional{y, x,} ch, n}
 299 Display a vertical line starting at \code{(\var{y}, \var{x})} with
 300 length \var{n} consisting of the character \var{ch}.
 301 \end{methoddesc}
 302
 303 \begin{methoddesc}{erase}{}
 304 Clear the screen.
 305 \end{methoddesc}
 306
 307 \begin{methoddesc}{deletln}{}
 308 Delete the line under the cursor. All following lines are moved up
 309 by 1 line.
 310 \end{methoddesc}
 311
 312 \begin{methoddesc}{insertln}{}
 313 Insert a blank line under the cursor. All following lines are moved
 314 down by 1 line.
 315 \end{methoddesc}
 316
 317 \begin{methoddesc}{getyx}{}
 318 Return a tuple \code{(\var{y}, \var{x})} of current cursor position.
 319 \end{methoddesc}
 320
 321 \begin{methoddesc}{getbegyx}{}
 322 Return a tuple \code{(\var{y}, \var{x})} of co-ordinates of upper-left
 323 corner.
 324 \end{methoddesc}
 325
 326 \begin{methoddesc}{getmaxyx}{}
 327 Return a tuple \code{(\var{y}, \var{x})} of the height and width of
 328 the window.
 329 \end{methoddesc}
 330
 331 \begin{methoddesc}{clear}{}
 332 Like \method{erase()}, but also causes the whole screen to be repainted
 333 upon next call to \method{refresh()}.
 334 \end{methoddesc}
 335
 336 \begin{methoddesc}{clrtobot}{}
 337 Erase from cursor to the end of the screen: all lines below the cursor
 338 are deleted, and then the equivalent of \method{clrtoeol()} is performed.
 339 \end{methoddesc}
 340
 341 \begin{methoddesc}{clrtoeol}{}
 342 Erase from cursor to the end of the line.
 343 \end{methoddesc}
 344
 345 \begin{methoddesc}{scroll}{\optional{lines\code{ = 1}}}
 346 Scroll the screen upward by \var{lines} lines.
 347 \end{methoddesc}
 348
 349 \begin{methoddesc}{touchwin}{}
 350 Pretend the whole window has been changed, for purposes of drawing
 351 optimizations.
 352 \end{methoddesc}
 353
 354 \begin{methoddesc}{touchline}{start, count}
 355 Pretend \var{count} lines have been changed, starting with line
 356 \var{start}.
 357 \end{methoddesc}
 358
 359 \begin{methoddesc}{getch}{\optional{x, y}}
 360 Get a character. Note that the integer returned does \emph{not} have to
 361 be in \ASCII{} range: function keys, keypad keys and so on return numbers
 362 higher then 256. In no-delay mode, an exception is raised if there is
 363 no input.
 364 \end{methoddesc}
 365
 366 \begin{methoddesc}{getstr}{\optional{x, y}}
 367 Read a string from the user, with primitive line editing capacity.
 368 \end{methoddesc}
 369
 370 \begin{methoddesc}{inch}{\optional{x, y}}
 371 Return the character at the given position in the window. The bottom
 372 8 bits are the character proper, and upper bits are the attributes.
 373 \end{methoddesc}
 374
 375 \begin{methoddesc}{clearok}{yes}
 376 If \var{yes} is 1, the next call to \method{refresh()}
 377 will clear the screen completely.
 378 \end{methoddesc}
 379
 380 \begin{methoddesc}{idlok}{yes}
 381 If called with \var{yes} equal to 1, \module{curses} will try and use
 382 hardware line editing facilities. Otherwise, line insertion/deletion
 383 are disabled.
 384 \end{methoddesc}
 385
 386 \begin{methoddesc}{leaveok}{yes}
 387 If \var{yes} is 1,
 388 cursor is left where it is, instead of being at ``cursor position.''
 389 This reduces cursor movement where possible. If possible it will be made
 390 invisible.
 391
 392 If \var{yes} is 0, cursor will always be at
 393 ``cursor position'' after an update.
 394 \end{methoddesc}
 395
 396 \begin{methoddesc}{setscrreg}{top, bottom}
 397 Set the scrolling region from line \var{top} to line \var{bottom}. All
 398 scrolling actions will take place in this region.
 399 \end{methoddesc}
 400
 401 \begin{methoddesc}{keypad}{yes}
 402 If \var{yes} is 1, escape sequences generated by some keys (keypad,
 403 function keys) will be interpreted by \module{curses}.
 404
 405 If \var{yes} is 0, escape sequences will be left as is in the input
 406 stream.
 407 \end{methoddesc}
 408
 409 \begin{methoddesc}{nodelay}{yes}
 410 If \var{yes} is 1, \method{getch()} will be non-blocking.
 411 \end{methoddesc}
 412
 413 \begin{methoddesc}{notimeout}{yes}
 414 If \var{yes} is 1, escape sequences will not be timed out.
 415
 416 If \var{yes} is 0, after a few milliseconds, an escape sequence will
 417 not be interpreted, and will be left in the input stream as is.
 418 \end{methoddesc}