Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`curses` --- Terminal handling for character-cell displays |
| 2 | =============================================================== |
| 3 | |
| 4 | .. module:: curses |
Georg Brandl | 71515ca | 2009-05-17 12:29:12 +0000 | [diff] [blame] | 5 | :synopsis: An interface to the curses library, providing portable |
| 6 | terminal handling. |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 7 | :platform: Unix |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
| 9 | .. sectionauthor:: Eric Raymond <esr@thyrsus.com> |
| 10 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | The :mod:`curses` module provides an interface to the curses library, the |
| 12 | de-facto standard for portable advanced terminal handling. |
| 13 | |
| 14 | While curses is most widely used in the Unix environment, versions are available |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 15 | for Windows, DOS, and possibly other systems as well. This extension module is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | designed to match the API of ncurses, an open-source curses library hosted on |
| 17 | Linux and the BSD variants of Unix. |
| 18 | |
Christian Heimes | 587c2bf | 2008-01-19 16:21:02 +0000 | [diff] [blame] | 19 | .. note:: |
| 20 | |
| 21 | Since version 5.4, the ncurses library decides how to interpret non-ASCII data |
| 22 | using the ``nl_langinfo`` function. That means that you have to call |
| 23 | :func:`locale.setlocale` in the application and encode Unicode strings |
| 24 | using one of the system's available encodings. This example uses the |
| 25 | system's default encoding:: |
| 26 | |
| 27 | import locale |
| 28 | locale.setlocale(locale.LC_ALL, '') |
| 29 | code = locale.getpreferredencoding() |
| 30 | |
| 31 | Then use *code* as the encoding for :meth:`str.encode` calls. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 32 | |
| 33 | .. seealso:: |
| 34 | |
| 35 | Module :mod:`curses.ascii` |
| 36 | Utilities for working with ASCII characters, regardless of your locale settings. |
| 37 | |
| 38 | Module :mod:`curses.panel` |
| 39 | A panel stack extension that adds depth to curses windows. |
| 40 | |
| 41 | Module :mod:`curses.textpad` |
| 42 | Editable text widget for curses supporting :program:`Emacs`\ -like bindings. |
| 43 | |
Christian Heimes | 2202f87 | 2008-02-06 14:31:34 +0000 | [diff] [blame] | 44 | :ref:`curses-howto` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 45 | Tutorial material on using curses with Python, by Andrew Kuchling and Eric |
Christian Heimes | 2202f87 | 2008-02-06 14:31:34 +0000 | [diff] [blame] | 46 | Raymond. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | |
Ezio Melotti | c6641db | 2013-02-28 18:02:28 +0200 | [diff] [blame] | 48 | The :source:`Tools/demo/` directory in the Python source distribution contains |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 49 | some example programs using the curses bindings provided by this module. |
| 50 | |
| 51 | |
| 52 | .. _curses-functions: |
| 53 | |
| 54 | Functions |
| 55 | --------- |
| 56 | |
| 57 | The module :mod:`curses` defines the following exception: |
| 58 | |
| 59 | |
| 60 | .. exception:: error |
| 61 | |
| 62 | Exception raised when a curses library function returns an error. |
| 63 | |
| 64 | .. note:: |
| 65 | |
| 66 | Whenever *x* or *y* arguments to a function or a method are optional, they |
| 67 | default to the current cursor location. Whenever *attr* is optional, it defaults |
| 68 | to :const:`A_NORMAL`. |
| 69 | |
| 70 | The module :mod:`curses` defines the following functions: |
| 71 | |
| 72 | |
| 73 | .. function:: baudrate() |
| 74 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 75 | Return the output speed of the terminal in bits per second. On software |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | terminal emulators it will have a fixed high value. Included for historical |
| 77 | reasons; in former times, it was used to write output loops for time delays and |
| 78 | occasionally to change interfaces depending on the line speed. |
| 79 | |
| 80 | |
| 81 | .. function:: beep() |
| 82 | |
| 83 | Emit a short attention sound. |
| 84 | |
| 85 | |
| 86 | .. function:: can_change_color() |
| 87 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 88 | Return ``True`` or ``False``, depending on whether the programmer can change the colors |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | displayed by the terminal. |
| 90 | |
| 91 | |
| 92 | .. function:: cbreak() |
| 93 | |
| 94 | Enter cbreak mode. In cbreak mode (sometimes called "rare" mode) normal tty |
| 95 | line buffering is turned off and characters are available to be read one by one. |
| 96 | However, unlike raw mode, special characters (interrupt, quit, suspend, and flow |
| 97 | control) retain their effects on the tty driver and calling program. Calling |
| 98 | first :func:`raw` then :func:`cbreak` leaves the terminal in cbreak mode. |
| 99 | |
| 100 | |
| 101 | .. function:: color_content(color_number) |
| 102 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 103 | Return the intensity of the red, green, and blue (RGB) components in the color |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 104 | *color_number*, which must be between ``0`` and :const:`COLORS`. A 3-tuple is |
| 105 | returned, containing the R,G,B values for the given color, which will be between |
| 106 | ``0`` (no component) and ``1000`` (maximum amount of component). |
| 107 | |
| 108 | |
| 109 | .. function:: color_pair(color_number) |
| 110 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 111 | Return the attribute value for displaying text in the specified color. This |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 112 | attribute value can be combined with :const:`A_STANDOUT`, :const:`A_REVERSE`, |
| 113 | and the other :const:`A_\*` attributes. :func:`pair_number` is the counterpart |
| 114 | to this function. |
| 115 | |
| 116 | |
| 117 | .. function:: curs_set(visibility) |
| 118 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 119 | Set the cursor state. *visibility* can be set to 0, 1, or 2, for invisible, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | normal, or very visible. If the terminal supports the visibility requested, the |
| 121 | previous cursor state is returned; otherwise, an exception is raised. On many |
| 122 | terminals, the "visible" mode is an underline cursor and the "very visible" mode |
| 123 | is a block cursor. |
| 124 | |
| 125 | |
| 126 | .. function:: def_prog_mode() |
| 127 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 128 | Save the current terminal mode as the "program" mode, the mode when the running |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 129 | program is using curses. (Its counterpart is the "shell" mode, for when the |
| 130 | program is not in curses.) Subsequent calls to :func:`reset_prog_mode` will |
| 131 | restore this mode. |
| 132 | |
| 133 | |
| 134 | .. function:: def_shell_mode() |
| 135 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 136 | Save the current terminal mode as the "shell" mode, the mode when the running |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 137 | program is not using curses. (Its counterpart is the "program" mode, when the |
| 138 | program is using curses capabilities.) Subsequent calls to |
| 139 | :func:`reset_shell_mode` will restore this mode. |
| 140 | |
| 141 | |
| 142 | .. function:: delay_output(ms) |
| 143 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 144 | Insert an *ms* millisecond pause in output. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | |
| 146 | |
| 147 | .. function:: doupdate() |
| 148 | |
| 149 | Update the physical screen. The curses library keeps two data structures, one |
| 150 | representing the current physical screen contents and a virtual screen |
| 151 | representing the desired next state. The :func:`doupdate` ground updates the |
| 152 | physical screen to match the virtual screen. |
| 153 | |
| 154 | The virtual screen may be updated by a :meth:`noutrefresh` call after write |
| 155 | operations such as :meth:`addstr` have been performed on a window. The normal |
| 156 | :meth:`refresh` call is simply :meth:`noutrefresh` followed by :func:`doupdate`; |
| 157 | if you have to update multiple windows, you can speed performance and perhaps |
| 158 | reduce screen flicker by issuing :meth:`noutrefresh` calls on all windows, |
| 159 | followed by a single :func:`doupdate`. |
| 160 | |
| 161 | |
| 162 | .. function:: echo() |
| 163 | |
| 164 | Enter echo mode. In echo mode, each character input is echoed to the screen as |
| 165 | it is entered. |
| 166 | |
| 167 | |
| 168 | .. function:: endwin() |
| 169 | |
| 170 | De-initialize the library, and return terminal to normal status. |
| 171 | |
| 172 | |
| 173 | .. function:: erasechar() |
| 174 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 175 | Return the user's current erase character. Under Unix operating systems this |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 176 | is a property of the controlling tty of the curses program, and is not set by |
| 177 | the curses library itself. |
| 178 | |
| 179 | |
| 180 | .. function:: filter() |
| 181 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 182 | The :func:`.filter` routine, if used, must be called before :func:`initscr` is |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 183 | called. The effect is that, during those calls, :envvar:`LINES` is set to 1; the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 184 | capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home |
| 185 | string is set to the value of cr. The effect is that the cursor is confined to |
| 186 | the current line, and so are screen updates. This may be used for enabling |
| 187 | character-at-a-time line editing without touching the rest of the screen. |
| 188 | |
| 189 | |
| 190 | .. function:: flash() |
| 191 | |
| 192 | Flash the screen. That is, change it to reverse-video and then change it back |
| 193 | in a short interval. Some people prefer such as 'visible bell' to the audible |
| 194 | attention signal produced by :func:`beep`. |
| 195 | |
| 196 | |
| 197 | .. function:: flushinp() |
| 198 | |
| 199 | Flush all input buffers. This throws away any typeahead that has been typed |
| 200 | by the user and has not yet been processed by the program. |
| 201 | |
| 202 | |
| 203 | .. function:: getmouse() |
| 204 | |
| 205 | After :meth:`getch` returns :const:`KEY_MOUSE` to signal a mouse event, this |
| 206 | method should be call to retrieve the queued mouse event, represented as a |
| 207 | 5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish |
| 208 | multiple devices, and *x*, *y*, *z* are the event's coordinates. (*z* is |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 209 | currently unused.) *bstate* is an integer value whose bits will be set to |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 210 | indicate the type of event, and will be the bitwise OR of one or more of the |
| 211 | following constants, where *n* is the button number from 1 to 4: |
| 212 | :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`, |
| 213 | :const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`, |
| 214 | :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`. |
| 215 | |
| 216 | |
| 217 | .. function:: getsyx() |
| 218 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 219 | Return the current coordinates of the virtual screen cursor in y and x. If |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 220 | leaveok is currently true, then -1,-1 is returned. |
| 221 | |
| 222 | |
| 223 | .. function:: getwin(file) |
| 224 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 225 | Read window related data stored in the file by an earlier :func:`putwin` call. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 226 | The routine then creates and initializes a new window using that data, returning |
| 227 | the new window object. |
| 228 | |
| 229 | |
| 230 | .. function:: has_colors() |
| 231 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 232 | Return ``True`` if the terminal can display colors; otherwise, return ``False``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 233 | |
| 234 | |
| 235 | .. function:: has_ic() |
| 236 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 237 | Return ``True`` if the terminal has insert- and delete-character capabilities. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 238 | This function is included for historical reasons only, as all modern software |
| 239 | terminal emulators have such capabilities. |
| 240 | |
| 241 | |
| 242 | .. function:: has_il() |
| 243 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 244 | Return ``True`` if the terminal has insert- and delete-line capabilities, or can |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 245 | simulate them using scrolling regions. This function is included for |
| 246 | historical reasons only, as all modern software terminal emulators have such |
| 247 | capabilities. |
| 248 | |
| 249 | |
| 250 | .. function:: has_key(ch) |
| 251 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 252 | Take a key value *ch*, and return ``True`` if the current terminal type recognizes |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 253 | a key with that value. |
| 254 | |
| 255 | |
| 256 | .. function:: halfdelay(tenths) |
| 257 | |
| 258 | Used for half-delay mode, which is similar to cbreak mode in that characters |
| 259 | typed by the user are immediately available to the program. However, after |
| 260 | blocking for *tenths* tenths of seconds, an exception is raised if nothing has |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 261 | been typed. The value of *tenths* must be a number between ``1`` and ``255``. Use |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 262 | :func:`nocbreak` to leave half-delay mode. |
| 263 | |
| 264 | |
| 265 | .. function:: init_color(color_number, r, g, b) |
| 266 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 267 | Change the definition of a color, taking the number of the color to be changed |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 268 | followed by three RGB values (for the amounts of red, green, and blue |
| 269 | components). The value of *color_number* must be between ``0`` and |
| 270 | :const:`COLORS`. Each of *r*, *g*, *b*, must be a value between ``0`` and |
| 271 | ``1000``. When :func:`init_color` is used, all occurrences of that color on the |
| 272 | screen immediately change to the new definition. This function is a no-op on |
| 273 | most terminals; it is active only if :func:`can_change_color` returns ``1``. |
| 274 | |
| 275 | |
| 276 | .. function:: init_pair(pair_number, fg, bg) |
| 277 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 278 | Change the definition of a color-pair. It takes three arguments: the number of |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 279 | the color-pair to be changed, the foreground color number, and the background |
| 280 | color number. The value of *pair_number* must be between ``1`` and |
| 281 | ``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cannot |
| 282 | be changed). The value of *fg* and *bg* arguments must be between ``0`` and |
| 283 | :const:`COLORS`. If the color-pair was previously initialized, the screen is |
| 284 | refreshed and all occurrences of that color-pair are changed to the new |
| 285 | definition. |
| 286 | |
| 287 | |
| 288 | .. function:: initscr() |
| 289 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 290 | Initialize the library. Return a :class:`WindowObject` which represents the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 291 | whole screen. |
| 292 | |
| 293 | .. note:: |
| 294 | |
| 295 | If there is an error opening the terminal, the underlying curses library may |
| 296 | cause the interpreter to exit. |
| 297 | |
| 298 | |
Ezio Melotti | 4850d52 | 2011-06-26 13:34:56 +0300 | [diff] [blame] | 299 | .. function:: is_term_resized(nlines, ncols) |
| 300 | |
| 301 | Return ``True`` if :func:`resize_term` would modify the window structure, |
| 302 | ``False`` otherwise. |
| 303 | |
| 304 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 305 | .. function:: isendwin() |
| 306 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 307 | Return ``True`` if :func:`endwin` has been called (that is, the curses library has |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 308 | been deinitialized). |
| 309 | |
| 310 | |
| 311 | .. function:: keyname(k) |
| 312 | |
| 313 | Return the name of the key numbered *k*. The name of a key generating printable |
| 314 | ASCII character is the key's character. The name of a control-key combination |
| 315 | is a two-character string consisting of a caret followed by the corresponding |
| 316 | printable ASCII character. The name of an alt-key combination (128-255) is a |
| 317 | string consisting of the prefix 'M-' followed by the name of the corresponding |
| 318 | ASCII character. |
| 319 | |
| 320 | |
| 321 | .. function:: killchar() |
| 322 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 323 | Return the user's current line kill character. Under Unix operating systems |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 324 | this is a property of the controlling tty of the curses program, and is not set |
| 325 | by the curses library itself. |
| 326 | |
| 327 | |
| 328 | .. function:: longname() |
| 329 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 330 | Return a string containing the terminfo long name field describing the current |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 331 | terminal. The maximum length of a verbose description is 128 characters. It is |
| 332 | defined only after the call to :func:`initscr`. |
| 333 | |
| 334 | |
| 335 | .. function:: meta(yes) |
| 336 | |
| 337 | If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0, allow only |
| 338 | 7-bit chars. |
| 339 | |
| 340 | |
| 341 | .. function:: mouseinterval(interval) |
| 342 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 343 | Set the maximum time in milliseconds that can elapse between press and release |
| 344 | events in order for them to be recognized as a click, and return the previous |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 345 | interval value. The default value is 200 msec, or one fifth of a second. |
| 346 | |
| 347 | |
| 348 | .. function:: mousemask(mousemask) |
| 349 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 350 | Set the mouse events to be reported, and return a tuple ``(availmask, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 351 | oldmask)``. *availmask* indicates which of the specified mouse events can be |
| 352 | reported; on complete failure it returns 0. *oldmask* is the previous value of |
| 353 | the given window's mouse event mask. If this function is never called, no mouse |
| 354 | events are ever reported. |
| 355 | |
| 356 | |
| 357 | .. function:: napms(ms) |
| 358 | |
| 359 | Sleep for *ms* milliseconds. |
| 360 | |
| 361 | |
| 362 | .. function:: newpad(nlines, ncols) |
| 363 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 364 | Create and return a pointer to a new pad data structure with the given number |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 365 | of lines and columns. A pad is returned as a window object. |
| 366 | |
| 367 | A pad is like a window, except that it is not restricted by the screen size, and |
| 368 | is not necessarily associated with a particular part of the screen. Pads can be |
| 369 | used when a large window is needed, and only a part of the window will be on the |
| 370 | screen at one time. Automatic refreshes of pads (such as from scrolling or |
| 371 | echoing of input) do not occur. The :meth:`refresh` and :meth:`noutrefresh` |
| 372 | methods of a pad require 6 arguments to specify the part of the pad to be |
| 373 | displayed and the location on the screen to be used for the display. The |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 374 | arguments are *pminrow*, *pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p* |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 375 | arguments refer to the upper left corner of the pad region to be displayed and |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 376 | the *s* arguments define a clipping box on the screen within which the pad region |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 377 | is to be displayed. |
| 378 | |
| 379 | |
Georg Brandl | 1ed80b0 | 2013-10-29 08:10:36 +0100 | [diff] [blame] | 380 | .. function:: newwin(nlines, ncols) |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 381 | newwin(nlines, ncols, begin_y, begin_x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 382 | |
| 383 | Return a new window, whose left-upper corner is at ``(begin_y, begin_x)``, and |
| 384 | whose height/width is *nlines*/*ncols*. |
| 385 | |
| 386 | By default, the window will extend from the specified position to the lower |
| 387 | right corner of the screen. |
| 388 | |
| 389 | |
| 390 | .. function:: nl() |
| 391 | |
| 392 | Enter newline mode. This mode translates the return key into newline on input, |
| 393 | and translates newline into return and line-feed on output. Newline mode is |
| 394 | initially on. |
| 395 | |
| 396 | |
| 397 | .. function:: nocbreak() |
| 398 | |
| 399 | Leave cbreak mode. Return to normal "cooked" mode with line buffering. |
| 400 | |
| 401 | |
| 402 | .. function:: noecho() |
| 403 | |
| 404 | Leave echo mode. Echoing of input characters is turned off. |
| 405 | |
| 406 | |
| 407 | .. function:: nonl() |
| 408 | |
| 409 | Leave newline mode. Disable translation of return into newline on input, and |
| 410 | disable low-level translation of newline into newline/return on output (but this |
| 411 | does not change the behavior of ``addch('\n')``, which always does the |
| 412 | equivalent of return and line feed on the virtual screen). With translation |
| 413 | off, curses can sometimes speed up vertical motion a little; also, it will be |
| 414 | able to detect the return key on input. |
| 415 | |
| 416 | |
| 417 | .. function:: noqiflush() |
| 418 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 419 | When the :func:`noqiflush` routine is used, normal flush of input and output queues |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 420 | associated with the INTR, QUIT and SUSP characters will not be done. You may |
| 421 | want to call :func:`noqiflush` in a signal handler if you want output to |
| 422 | continue as though the interrupt had not occurred, after the handler exits. |
| 423 | |
| 424 | |
| 425 | .. function:: noraw() |
| 426 | |
| 427 | Leave raw mode. Return to normal "cooked" mode with line buffering. |
| 428 | |
| 429 | |
| 430 | .. function:: pair_content(pair_number) |
| 431 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 432 | Return a tuple ``(fg, bg)`` containing the colors for the requested color pair. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 433 | The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1``. |
| 434 | |
| 435 | |
| 436 | .. function:: pair_number(attr) |
| 437 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 438 | Return the number of the color-pair set by the attribute value *attr*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 439 | :func:`color_pair` is the counterpart to this function. |
| 440 | |
| 441 | |
| 442 | .. function:: putp(string) |
| 443 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 444 | Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified |
| 445 | terminfo capability for the current terminal. Note that the output of :func:`putp` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 446 | always goes to standard output. |
| 447 | |
| 448 | |
| 449 | .. function:: qiflush( [flag] ) |
| 450 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 451 | If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If |
| 452 | *flag* is ``True``, or no argument is provided, the queues will be flushed when |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 453 | these control characters are read. |
| 454 | |
| 455 | |
| 456 | .. function:: raw() |
| 457 | |
| 458 | Enter raw mode. In raw mode, normal line buffering and processing of |
| 459 | interrupt, quit, suspend, and flow control keys are turned off; characters are |
| 460 | presented to curses input functions one by one. |
| 461 | |
| 462 | |
| 463 | .. function:: reset_prog_mode() |
| 464 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 465 | Restore the terminal to "program" mode, as previously saved by |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 466 | :func:`def_prog_mode`. |
| 467 | |
| 468 | |
| 469 | .. function:: reset_shell_mode() |
| 470 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 471 | Restore the terminal to "shell" mode, as previously saved by |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 472 | :func:`def_shell_mode`. |
| 473 | |
| 474 | |
Ezio Melotti | 4850d52 | 2011-06-26 13:34:56 +0300 | [diff] [blame] | 475 | .. function:: resetty() |
| 476 | |
| 477 | Restore the state of the terminal modes to what it was at the last call to |
| 478 | :func:`savetty`. |
| 479 | |
| 480 | |
| 481 | .. function:: resize_term(nlines, ncols) |
| 482 | |
| 483 | Backend function used by :func:`resizeterm`, performing most of the work; |
| 484 | when resizing the windows, :func:`resize_term` blank-fills the areas that are |
| 485 | extended. The calling application should fill in these areas with |
| 486 | appropriate data. The :func:`resize_term` function attempts to resize all |
| 487 | windows. However, due to the calling convention of pads, it is not possible |
| 488 | to resize these without additional interaction with the application. |
| 489 | |
| 490 | |
| 491 | .. function:: resizeterm(nlines, ncols) |
| 492 | |
| 493 | Resize the standard and current windows to the specified dimensions, and |
| 494 | adjusts other bookkeeping data used by the curses library that record the |
| 495 | window dimensions (in particular the SIGWINCH handler). |
| 496 | |
| 497 | |
| 498 | .. function:: savetty() |
| 499 | |
| 500 | Save the current state of the terminal modes in a buffer, usable by |
| 501 | :func:`resetty`. |
| 502 | |
| 503 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 504 | .. function:: setsyx(y, x) |
| 505 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 506 | Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 507 | leaveok is set. |
| 508 | |
| 509 | |
| 510 | .. function:: setupterm([termstr, fd]) |
| 511 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 512 | Initialize the terminal. *termstr* is a string giving the terminal name; if |
| 513 | omitted, the value of the :envvar:`TERM` environment variable will be used. *fd* is the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 514 | file descriptor to which any initialization sequences will be sent; if not |
| 515 | supplied, the file descriptor for ``sys.stdout`` will be used. |
| 516 | |
| 517 | |
| 518 | .. function:: start_color() |
| 519 | |
| 520 | Must be called if the programmer wants to use colors, and before any other color |
| 521 | manipulation routine is called. It is good practice to call this routine right |
| 522 | after :func:`initscr`. |
| 523 | |
| 524 | :func:`start_color` initializes eight basic colors (black, red, green, yellow, |
| 525 | blue, magenta, cyan, and white), and two global variables in the :mod:`curses` |
| 526 | module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing the maximum number |
| 527 | of colors and color-pairs the terminal can support. It also restores the colors |
| 528 | on the terminal to the values they had when the terminal was just turned on. |
| 529 | |
| 530 | |
| 531 | .. function:: termattrs() |
| 532 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 533 | Return a logical OR of all video attributes supported by the terminal. This |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 534 | information is useful when a curses program needs complete control over the |
| 535 | appearance of the screen. |
| 536 | |
| 537 | |
| 538 | .. function:: termname() |
| 539 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 540 | Return the value of the environment variable :envvar:`TERM`, truncated to 14 characters. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 541 | |
| 542 | |
| 543 | .. function:: tigetflag(capname) |
| 544 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 545 | Return the value of the Boolean capability corresponding to the terminfo |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 546 | capability name *capname*. The value ``-1`` is returned if *capname* is not a |
| 547 | Boolean capability, or ``0`` if it is canceled or absent from the terminal |
| 548 | description. |
| 549 | |
| 550 | |
| 551 | .. function:: tigetnum(capname) |
| 552 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 553 | Return the value of the numeric capability corresponding to the terminfo |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 554 | capability name *capname*. The value ``-2`` is returned if *capname* is not a |
| 555 | numeric capability, or ``-1`` if it is canceled or absent from the terminal |
| 556 | description. |
| 557 | |
| 558 | |
| 559 | .. function:: tigetstr(capname) |
| 560 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 561 | Return the value of the string capability corresponding to the terminfo |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 562 | capability name *capname*. ``None`` is returned if *capname* is not a string |
| 563 | capability, or is canceled or absent from the terminal description. |
| 564 | |
| 565 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 566 | .. function:: tparm(str[, ...]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 567 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 568 | Instantiate the string *str* with the supplied parameters, where *str* should |
| 569 | be a parameterized string obtained from the terminfo database. E.g. |
Victor Stinner | 2662133 | 2011-11-02 23:45:29 +0100 | [diff] [blame] | 570 | ``tparm(tigetstr("cup"), 5, 3)`` could result in ``b'\033[6;4H'``, the exact |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 571 | result depending on terminal type. |
| 572 | |
| 573 | |
| 574 | .. function:: typeahead(fd) |
| 575 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 576 | Specify that the file descriptor *fd* be used for typeahead checking. If *fd* |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 577 | is ``-1``, then no typeahead checking is done. |
| 578 | |
| 579 | The curses library does "line-breakout optimization" by looking for typeahead |
| 580 | periodically while updating the screen. If input is found, and it is coming |
| 581 | from a tty, the current update is postponed until refresh or doupdate is called |
| 582 | again, allowing faster response to commands typed in advance. This function |
| 583 | allows specifying a different file descriptor for typeahead checking. |
| 584 | |
| 585 | |
| 586 | .. function:: unctrl(ch) |
| 587 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 588 | Return a string which is a printable representation of the character *ch*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 589 | Control characters are displayed as a caret followed by the character, for |
| 590 | example as ``^C``. Printing characters are left as they are. |
| 591 | |
| 592 | |
| 593 | .. function:: ungetch(ch) |
| 594 | |
| 595 | Push *ch* so the next :meth:`getch` will return it. |
| 596 | |
| 597 | .. note:: |
| 598 | |
| 599 | Only one *ch* can be pushed before :meth:`getch` is called. |
| 600 | |
| 601 | |
Victor Stinner | 71e44cb | 2011-09-06 01:53:03 +0200 | [diff] [blame] | 602 | .. function:: unget_wch(ch) |
| 603 | |
| 604 | Push *ch* so the next :meth:`get_wch` will return it. |
| 605 | |
| 606 | .. note:: |
| 607 | |
| 608 | Only one *ch* can be pushed before :meth:`get_wch` is called. |
| 609 | |
| 610 | .. versionadded:: 3.3 |
| 611 | |
| 612 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 613 | .. function:: ungetmouse(id, x, y, z, bstate) |
| 614 | |
| 615 | Push a :const:`KEY_MOUSE` event onto the input queue, associating the given |
| 616 | state data with it. |
| 617 | |
| 618 | |
| 619 | .. function:: use_env(flag) |
| 620 | |
| 621 | If used, this function should be called before :func:`initscr` or newterm are |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 622 | called. When *flag* is ``False``, the values of lines and columns specified in the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 623 | terminfo database will be used, even if environment variables :envvar:`LINES` |
| 624 | and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a |
| 625 | window (in which case default behavior would be to use the window size if |
| 626 | :envvar:`LINES` and :envvar:`COLUMNS` are not set). |
| 627 | |
| 628 | |
| 629 | .. function:: use_default_colors() |
| 630 | |
| 631 | Allow use of default values for colors on terminals supporting this feature. Use |
| 632 | this to support transparency in your application. The default color is assigned |
| 633 | to the color number -1. After calling this function, ``init_pair(x, |
| 634 | curses.COLOR_RED, -1)`` initializes, for instance, color pair *x* to a red |
| 635 | foreground color on the default background. |
| 636 | |
| 637 | |
R David Murray | 409c32f | 2011-06-18 19:34:12 -0400 | [diff] [blame] | 638 | .. function:: wrapper(func, ...) |
| 639 | |
| 640 | Initialize curses and call another callable object, *func*, which should be the |
| 641 | rest of your curses-using application. If the application raises an exception, |
| 642 | this function will restore the terminal to a sane state before re-raising the |
| 643 | exception and generating a traceback. The callable object *func* is then passed |
| 644 | the main window 'stdscr' as its first argument, followed by any other arguments |
| 645 | passed to :func:`wrapper`. Before calling *func*, :func:`wrapper` turns on |
| 646 | cbreak mode, turns off echo, enables the terminal keypad, and initializes colors |
| 647 | if the terminal has color support. On exit (whether normally or by exception) |
| 648 | it restores cooked mode, turns on echo, and disables the terminal keypad. |
| 649 | |
| 650 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 651 | .. _curses-window-objects: |
| 652 | |
| 653 | Window Objects |
| 654 | -------------- |
| 655 | |
| 656 | Window objects, as returned by :func:`initscr` and :func:`newwin` above, have |
Victor Stinner | 0fdfceb | 2011-11-25 22:10:02 +0100 | [diff] [blame] | 657 | the following methods and attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 658 | |
| 659 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 660 | .. method:: window.addch(ch[, attr]) |
| 661 | window.addch(y, x, ch[, attr]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 662 | |
| 663 | .. note:: |
| 664 | |
Sandro Tosi | 8a3b657 | 2011-08-12 19:31:32 +0200 | [diff] [blame] | 665 | A *character* means a C character (an ASCII code), rather than a Python |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 666 | character (a string of length 1). (This note is true whenever the |
| 667 | documentation mentions a character.) The built-in :func:`ord` is handy for |
| 668 | conveying strings to codes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 669 | |
| 670 | Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any |
| 671 | character previously painter at that location. By default, the character |
| 672 | position and attributes are the current settings for the window object. |
| 673 | |
| 674 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 675 | .. method:: window.addnstr(str, n[, attr]) |
| 676 | window.addnstr(y, x, str, n[, attr]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 677 | |
| 678 | Paint at most *n* characters of the string *str* at ``(y, x)`` with attributes |
| 679 | *attr*, overwriting anything previously on the display. |
| 680 | |
| 681 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 682 | .. method:: window.addstr(str[, attr]) |
| 683 | window.addstr(y, x, str[, attr]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 684 | |
| 685 | Paint the string *str* at ``(y, x)`` with attributes *attr*, overwriting |
| 686 | anything previously on the display. |
| 687 | |
| 688 | |
| 689 | .. method:: window.attroff(attr) |
| 690 | |
| 691 | Remove attribute *attr* from the "background" set applied to all writes to the |
| 692 | current window. |
| 693 | |
| 694 | |
| 695 | .. method:: window.attron(attr) |
| 696 | |
| 697 | Add attribute *attr* from the "background" set applied to all writes to the |
| 698 | current window. |
| 699 | |
| 700 | |
| 701 | .. method:: window.attrset(attr) |
| 702 | |
| 703 | Set the "background" set of attributes to *attr*. This set is initially 0 (no |
| 704 | attributes). |
| 705 | |
| 706 | |
| 707 | .. method:: window.bkgd(ch[, attr]) |
| 708 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 709 | Set the background property of the window to the character *ch*, with |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 710 | attributes *attr*. The change is then applied to every character position in |
| 711 | that window: |
| 712 | |
| 713 | * The attribute of every character in the window is changed to the new |
| 714 | background attribute. |
| 715 | |
| 716 | * Wherever the former background character appears, it is changed to the new |
| 717 | background character. |
| 718 | |
| 719 | |
| 720 | .. method:: window.bkgdset(ch[, attr]) |
| 721 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 722 | Set the window's background. A window's background consists of a character and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 723 | any combination of attributes. The attribute part of the background is combined |
| 724 | (OR'ed) with all non-blank characters that are written into the window. Both |
| 725 | the character and attribute parts of the background are combined with the blank |
| 726 | characters. The background becomes a property of the character and moves with |
| 727 | the character through any scrolling and insert/delete line/character operations. |
| 728 | |
| 729 | |
| 730 | .. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]]) |
| 731 | |
| 732 | Draw a border around the edges of the window. Each parameter specifies the |
| 733 | character to use for a specific part of the border; see the table below for more |
| 734 | details. The characters can be specified as integers or as one-character |
| 735 | strings. |
| 736 | |
| 737 | .. note:: |
| 738 | |
| 739 | A ``0`` value for any parameter will cause the default character to be used for |
| 740 | that parameter. Keyword parameters can *not* be used. The defaults are listed |
| 741 | in this table: |
| 742 | |
| 743 | +-----------+---------------------+-----------------------+ |
| 744 | | Parameter | Description | Default value | |
| 745 | +===========+=====================+=======================+ |
| 746 | | *ls* | Left side | :const:`ACS_VLINE` | |
| 747 | +-----------+---------------------+-----------------------+ |
| 748 | | *rs* | Right side | :const:`ACS_VLINE` | |
| 749 | +-----------+---------------------+-----------------------+ |
| 750 | | *ts* | Top | :const:`ACS_HLINE` | |
| 751 | +-----------+---------------------+-----------------------+ |
| 752 | | *bs* | Bottom | :const:`ACS_HLINE` | |
| 753 | +-----------+---------------------+-----------------------+ |
| 754 | | *tl* | Upper-left corner | :const:`ACS_ULCORNER` | |
| 755 | +-----------+---------------------+-----------------------+ |
| 756 | | *tr* | Upper-right corner | :const:`ACS_URCORNER` | |
| 757 | +-----------+---------------------+-----------------------+ |
| 758 | | *bl* | Bottom-left corner | :const:`ACS_LLCORNER` | |
| 759 | +-----------+---------------------+-----------------------+ |
| 760 | | *br* | Bottom-right corner | :const:`ACS_LRCORNER` | |
| 761 | +-----------+---------------------+-----------------------+ |
| 762 | |
| 763 | |
| 764 | .. method:: window.box([vertch, horch]) |
| 765 | |
| 766 | Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 767 | *bs* are *horch*. The default corner characters are always used by this function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 768 | |
| 769 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 770 | .. method:: window.chgat(attr) |
| 771 | window.chgat(num, attr) |
| 772 | window.chgat(y, x, attr) |
| 773 | window.chgat(y, x, num, attr) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 774 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 775 | Set the attributes of *num* characters at the current cursor position, or at |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 776 | position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1, |
| 777 | the attribute will be set on all the characters to the end of the line. This |
| 778 | function does not move the cursor. The changed line will be touched using the |
| 779 | :meth:`touchline` method so that the contents will be redisplayed by the next |
| 780 | window refresh. |
| 781 | |
| 782 | |
| 783 | .. method:: window.clear() |
| 784 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 785 | Like :meth:`erase`, but also cause the whole window to be repainted upon next |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 786 | call to :meth:`refresh`. |
| 787 | |
| 788 | |
| 789 | .. method:: window.clearok(yes) |
| 790 | |
| 791 | If *yes* is 1, the next call to :meth:`refresh` will clear the window |
| 792 | completely. |
| 793 | |
| 794 | |
| 795 | .. method:: window.clrtobot() |
| 796 | |
| 797 | Erase from cursor to the end of the window: all lines below the cursor are |
| 798 | deleted, and then the equivalent of :meth:`clrtoeol` is performed. |
| 799 | |
| 800 | |
| 801 | .. method:: window.clrtoeol() |
| 802 | |
| 803 | Erase from cursor to the end of the line. |
| 804 | |
| 805 | |
| 806 | .. method:: window.cursyncup() |
| 807 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 808 | Update the current cursor position of all the ancestors of the window to |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 809 | reflect the current cursor position of the window. |
| 810 | |
| 811 | |
| 812 | .. method:: window.delch([y, x]) |
| 813 | |
| 814 | Delete any character at ``(y, x)``. |
| 815 | |
| 816 | |
| 817 | .. method:: window.deleteln() |
| 818 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 819 | Delete the line under the cursor. All following lines are moved up by one line. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 820 | |
| 821 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 822 | .. method:: window.derwin(begin_y, begin_x) |
| 823 | window.derwin(nlines, ncols, begin_y, begin_x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 824 | |
| 825 | An abbreviation for "derive window", :meth:`derwin` is the same as calling |
| 826 | :meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 827 | of the window, rather than relative to the entire screen. Return a window |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 828 | object for the derived window. |
| 829 | |
| 830 | |
| 831 | .. method:: window.echochar(ch[, attr]) |
| 832 | |
| 833 | Add character *ch* with attribute *attr*, and immediately call :meth:`refresh` |
| 834 | on the window. |
| 835 | |
| 836 | |
| 837 | .. method:: window.enclose(y, x) |
| 838 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 839 | Test whether the given pair of screen-relative character-cell coordinates are |
| 840 | enclosed by the given window, returning ``True`` or ``False``. It is useful for |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 841 | determining what subset of the screen windows enclose the location of a mouse |
| 842 | event. |
| 843 | |
| 844 | |
Victor Stinner | 0fdfceb | 2011-11-25 22:10:02 +0100 | [diff] [blame] | 845 | .. attribute:: window.encoding |
| 846 | |
| 847 | Encoding used to encode method arguments (Unicode strings and characters). |
Ross Lagerwall | ce66a3e | 2012-09-06 18:58:43 +0200 | [diff] [blame] | 848 | The encoding attribute is inherited from the parent window when a subwindow |
Victor Stinner | 0fdfceb | 2011-11-25 22:10:02 +0100 | [diff] [blame] | 849 | is created, for example with :meth:`window.subwin`. By default, the locale |
| 850 | encoding is used (see :func:`locale.getpreferredencoding`). |
| 851 | |
| 852 | .. versionadded:: 3.3 |
| 853 | |
| 854 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 855 | .. method:: window.erase() |
| 856 | |
| 857 | Clear the window. |
| 858 | |
| 859 | |
| 860 | .. method:: window.getbegyx() |
| 861 | |
| 862 | Return a tuple ``(y, x)`` of co-ordinates of upper-left corner. |
| 863 | |
| 864 | |
Ezio Melotti | 4850d52 | 2011-06-26 13:34:56 +0300 | [diff] [blame] | 865 | .. method:: window.getbkgd() |
| 866 | |
| 867 | Return the given window's current background character/attribute pair. |
| 868 | |
| 869 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 870 | .. method:: window.getch([y, x]) |
| 871 | |
| 872 | Get a character. Note that the integer returned does *not* have to be in ASCII |
| 873 | range: function keys, keypad keys and so on return numbers higher than 256. In |
Georg Brandl | e810e5a | 2009-06-17 10:03:58 +0000 | [diff] [blame] | 874 | no-delay mode, -1 is returned if there is no input, else :func:`getch` waits |
| 875 | until a key is pressed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 876 | |
| 877 | |
Victor Stinner | a7878b7 | 2011-07-14 23:07:44 +0200 | [diff] [blame] | 878 | .. method:: window.get_wch([y, x]) |
| 879 | |
Victor Stinner | 1d39cde | 2012-08-29 01:40:57 +0200 | [diff] [blame] | 880 | Get a wide character. Return a character for most keys, or an integer for |
| 881 | function keys, keypad keys, and other special keys. |
Victor Stinner | a7878b7 | 2011-07-14 23:07:44 +0200 | [diff] [blame] | 882 | |
| 883 | .. versionadded:: 3.3 |
| 884 | |
| 885 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 886 | .. method:: window.getkey([y, x]) |
| 887 | |
| 888 | Get a character, returning a string instead of an integer, as :meth:`getch` |
Victor Stinner | 1d39cde | 2012-08-29 01:40:57 +0200 | [diff] [blame] | 889 | does. Function keys, keypad keys and other special keys return a multibyte |
| 890 | string containing the key name. In no-delay mode, an exception is raised if |
| 891 | there is no input. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 892 | |
| 893 | |
| 894 | .. method:: window.getmaxyx() |
| 895 | |
| 896 | Return a tuple ``(y, x)`` of the height and width of the window. |
| 897 | |
| 898 | |
| 899 | .. method:: window.getparyx() |
| 900 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 901 | Return the beginning coordinates of this window relative to its parent window |
| 902 | into two integer variables y and x. Return ``-1, -1`` if this window has no |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 903 | parent. |
| 904 | |
| 905 | |
| 906 | .. method:: window.getstr([y, x]) |
| 907 | |
| 908 | Read a string from the user, with primitive line editing capacity. |
| 909 | |
| 910 | |
| 911 | .. method:: window.getyx() |
| 912 | |
| 913 | Return a tuple ``(y, x)`` of current cursor position relative to the window's |
| 914 | upper-left corner. |
| 915 | |
| 916 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 917 | .. method:: window.hline(ch, n) |
| 918 | window.hline(y, x, ch, n) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 919 | |
| 920 | Display a horizontal line starting at ``(y, x)`` with length *n* consisting of |
| 921 | the character *ch*. |
| 922 | |
| 923 | |
| 924 | .. method:: window.idcok(flag) |
| 925 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 926 | If *flag* is ``False``, curses no longer considers using the hardware insert/delete |
| 927 | character feature of the terminal; if *flag* is ``True``, use of character insertion |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 928 | and deletion is enabled. When curses is first initialized, use of character |
| 929 | insert/delete is enabled by default. |
| 930 | |
| 931 | |
| 932 | .. method:: window.idlok(yes) |
| 933 | |
| 934 | If called with *yes* equal to 1, :mod:`curses` will try and use hardware line |
| 935 | editing facilities. Otherwise, line insertion/deletion are disabled. |
| 936 | |
| 937 | |
| 938 | .. method:: window.immedok(flag) |
| 939 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 940 | If *flag* is ``True``, any change in the window image automatically causes the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 941 | window to be refreshed; you no longer have to call :meth:`refresh` yourself. |
| 942 | However, it may degrade performance considerably, due to repeated calls to |
| 943 | wrefresh. This option is disabled by default. |
| 944 | |
| 945 | |
| 946 | .. method:: window.inch([y, x]) |
| 947 | |
| 948 | Return the character at the given position in the window. The bottom 8 bits are |
| 949 | the character proper, and upper bits are the attributes. |
| 950 | |
| 951 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 952 | .. method:: window.insch(ch[, attr]) |
| 953 | window.insch(y, x, ch[, attr]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 954 | |
| 955 | Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line from |
| 956 | position *x* right by one character. |
| 957 | |
| 958 | |
| 959 | .. method:: window.insdelln(nlines) |
| 960 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 961 | Insert *nlines* lines into the specified window above the current line. The |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 962 | *nlines* bottom lines are lost. For negative *nlines*, delete *nlines* lines |
| 963 | starting with the one under the cursor, and move the remaining lines up. The |
| 964 | bottom *nlines* lines are cleared. The current cursor position remains the |
| 965 | same. |
| 966 | |
| 967 | |
| 968 | .. method:: window.insertln() |
| 969 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 970 | Insert a blank line under the cursor. All following lines are moved down by one |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 971 | line. |
| 972 | |
| 973 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 974 | .. method:: window.insnstr(str, n[, attr]) |
| 975 | window.insnstr(y, x, str, n[, attr]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 976 | |
| 977 | Insert a character string (as many characters as will fit on the line) before |
| 978 | the character under the cursor, up to *n* characters. If *n* is zero or |
| 979 | negative, the entire string is inserted. All characters to the right of the |
| 980 | cursor are shifted right, with the rightmost characters on the line being lost. |
| 981 | The cursor position does not change (after moving to *y*, *x*, if specified). |
| 982 | |
| 983 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 984 | .. method:: window.insstr(str[, attr]) |
| 985 | window.insstr(y, x, str[, attr]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 986 | |
| 987 | Insert a character string (as many characters as will fit on the line) before |
| 988 | the character under the cursor. All characters to the right of the cursor are |
| 989 | shifted right, with the rightmost characters on the line being lost. The cursor |
| 990 | position does not change (after moving to *y*, *x*, if specified). |
| 991 | |
| 992 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 993 | .. method:: window.instr([n]) |
| 994 | window.instr(y, x[, n]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 995 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 996 | Return a string of characters, extracted from the window starting at the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 997 | current cursor position, or at *y*, *x* if specified. Attributes are stripped |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 998 | from the characters. If *n* is specified, :meth:`instr` returns a string |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 999 | at most *n* characters long (exclusive of the trailing NUL). |
| 1000 | |
| 1001 | |
| 1002 | .. method:: window.is_linetouched(line) |
| 1003 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1004 | Return ``True`` if the specified line was modified since the last call to |
| 1005 | :meth:`refresh`; otherwise return ``False``. Raise a :exc:`curses.error` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1006 | exception if *line* is not valid for the given window. |
| 1007 | |
| 1008 | |
| 1009 | .. method:: window.is_wintouched() |
| 1010 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1011 | Return ``True`` if the specified window was modified since the last call to |
| 1012 | :meth:`refresh`; otherwise return ``False``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1013 | |
| 1014 | |
| 1015 | .. method:: window.keypad(yes) |
| 1016 | |
| 1017 | If *yes* is 1, escape sequences generated by some keys (keypad, function keys) |
| 1018 | will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be |
| 1019 | left as is in the input stream. |
| 1020 | |
| 1021 | |
| 1022 | .. method:: window.leaveok(yes) |
| 1023 | |
| 1024 | If *yes* is 1, cursor is left where it is on update, instead of being at "cursor |
| 1025 | position." This reduces cursor movement where possible. If possible the cursor |
| 1026 | will be made invisible. |
| 1027 | |
| 1028 | If *yes* is 0, cursor will always be at "cursor position" after an update. |
| 1029 | |
| 1030 | |
| 1031 | .. method:: window.move(new_y, new_x) |
| 1032 | |
| 1033 | Move cursor to ``(new_y, new_x)``. |
| 1034 | |
| 1035 | |
| 1036 | .. method:: window.mvderwin(y, x) |
| 1037 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1038 | Move the window inside its parent window. The screen-relative parameters of |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1039 | the window are not changed. This routine is used to display different parts of |
| 1040 | the parent window at the same physical position on the screen. |
| 1041 | |
| 1042 | |
| 1043 | .. method:: window.mvwin(new_y, new_x) |
| 1044 | |
| 1045 | Move the window so its upper-left corner is at ``(new_y, new_x)``. |
| 1046 | |
| 1047 | |
| 1048 | .. method:: window.nodelay(yes) |
| 1049 | |
| 1050 | If *yes* is ``1``, :meth:`getch` will be non-blocking. |
| 1051 | |
| 1052 | |
| 1053 | .. method:: window.notimeout(yes) |
| 1054 | |
| 1055 | If *yes* is ``1``, escape sequences will not be timed out. |
| 1056 | |
| 1057 | If *yes* is ``0``, after a few milliseconds, an escape sequence will not be |
| 1058 | interpreted, and will be left in the input stream as is. |
| 1059 | |
| 1060 | |
| 1061 | .. method:: window.noutrefresh() |
| 1062 | |
| 1063 | Mark for refresh but wait. This function updates the data structure |
| 1064 | representing the desired state of the window, but does not force an update of |
| 1065 | the physical screen. To accomplish that, call :func:`doupdate`. |
| 1066 | |
| 1067 | |
| 1068 | .. method:: window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol]) |
| 1069 | |
| 1070 | Overlay the window on top of *destwin*. The windows need not be the same size, |
| 1071 | only the overlapping region is copied. This copy is non-destructive, which means |
| 1072 | that the current background character does not overwrite the old contents of |
| 1073 | *destwin*. |
| 1074 | |
| 1075 | To get fine-grained control over the copied region, the second form of |
| 1076 | :meth:`overlay` can be used. *sminrow* and *smincol* are the upper-left |
| 1077 | coordinates of the source window, and the other variables mark a rectangle in |
| 1078 | the destination window. |
| 1079 | |
| 1080 | |
| 1081 | .. method:: window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol]) |
| 1082 | |
| 1083 | Overwrite the window on top of *destwin*. The windows need not be the same size, |
| 1084 | in which case only the overlapping region is copied. This copy is destructive, |
| 1085 | which means that the current background character overwrites the old contents of |
| 1086 | *destwin*. |
| 1087 | |
| 1088 | To get fine-grained control over the copied region, the second form of |
| 1089 | :meth:`overwrite` can be used. *sminrow* and *smincol* are the upper-left |
| 1090 | coordinates of the source window, the other variables mark a rectangle in the |
| 1091 | destination window. |
| 1092 | |
| 1093 | |
| 1094 | .. method:: window.putwin(file) |
| 1095 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1096 | Write all data associated with the window into the provided file object. This |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1097 | information can be later retrieved using the :func:`getwin` function. |
| 1098 | |
| 1099 | |
| 1100 | .. method:: window.redrawln(beg, num) |
| 1101 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1102 | Indicate that the *num* screen lines, starting at line *beg*, are corrupted and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1103 | should be completely redrawn on the next :meth:`refresh` call. |
| 1104 | |
| 1105 | |
| 1106 | .. method:: window.redrawwin() |
| 1107 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1108 | Touch the entire window, causing it to be completely redrawn on the next |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1109 | :meth:`refresh` call. |
| 1110 | |
| 1111 | |
| 1112 | .. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol]) |
| 1113 | |
| 1114 | Update the display immediately (sync actual screen with previous |
| 1115 | drawing/deleting methods). |
| 1116 | |
| 1117 | The 6 optional arguments can only be specified when the window is a pad created |
| 1118 | with :func:`newpad`. The additional parameters are needed to indicate what part |
| 1119 | of the pad and screen are involved. *pminrow* and *pmincol* specify the upper |
| 1120 | left-hand corner of the rectangle to be displayed in the pad. *sminrow*, |
| 1121 | *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be |
| 1122 | displayed on the screen. The lower right-hand corner of the rectangle to be |
| 1123 | displayed in the pad is calculated from the screen coordinates, since the |
| 1124 | rectangles must be the same size. Both rectangles must be entirely contained |
| 1125 | within their respective structures. Negative values of *pminrow*, *pmincol*, |
| 1126 | *sminrow*, or *smincol* are treated as if they were zero. |
| 1127 | |
| 1128 | |
Ezio Melotti | 4850d52 | 2011-06-26 13:34:56 +0300 | [diff] [blame] | 1129 | .. method:: window.resize(nlines, ncols) |
| 1130 | |
| 1131 | Reallocate storage for a curses window to adjust its dimensions to the |
| 1132 | specified values. If either dimension is larger than the current values, the |
| 1133 | window's data is filled with blanks that have the current background |
| 1134 | rendition (as set by :meth:`bkgdset`) merged into them. |
| 1135 | |
| 1136 | |
Hynek Schlawack | 979f37a | 2012-05-22 16:12:18 +0200 | [diff] [blame] | 1137 | .. method:: window.scroll([lines=1]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1138 | |
| 1139 | Scroll the screen or scrolling region upward by *lines* lines. |
| 1140 | |
| 1141 | |
| 1142 | .. method:: window.scrollok(flag) |
| 1143 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1144 | Control what happens when the cursor of a window is moved off the edge of the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1145 | window or scrolling region, either as a result of a newline action on the bottom |
| 1146 | line, or typing the last character of the last line. If *flag* is false, the |
| 1147 | cursor is left on the bottom line. If *flag* is true, the window is scrolled up |
| 1148 | one line. Note that in order to get the physical scrolling effect on the |
| 1149 | terminal, it is also necessary to call :meth:`idlok`. |
| 1150 | |
| 1151 | |
| 1152 | .. method:: window.setscrreg(top, bottom) |
| 1153 | |
| 1154 | Set the scrolling region from line *top* to line *bottom*. All scrolling actions |
| 1155 | will take place in this region. |
| 1156 | |
| 1157 | |
| 1158 | .. method:: window.standend() |
| 1159 | |
| 1160 | Turn off the standout attribute. On some terminals this has the side effect of |
| 1161 | turning off all attributes. |
| 1162 | |
| 1163 | |
| 1164 | .. method:: window.standout() |
| 1165 | |
| 1166 | Turn on attribute *A_STANDOUT*. |
| 1167 | |
| 1168 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 1169 | .. method:: window.subpad(begin_y, begin_x) |
| 1170 | window.subpad(nlines, ncols, begin_y, begin_x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1171 | |
| 1172 | Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and |
| 1173 | whose width/height is *ncols*/*nlines*. |
| 1174 | |
| 1175 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 1176 | .. method:: window.subwin(begin_y, begin_x) |
| 1177 | window.subwin(nlines, ncols, begin_y, begin_x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1178 | |
| 1179 | Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and |
| 1180 | whose width/height is *ncols*/*nlines*. |
| 1181 | |
| 1182 | By default, the sub-window will extend from the specified position to the lower |
| 1183 | right corner of the window. |
| 1184 | |
| 1185 | |
| 1186 | .. method:: window.syncdown() |
| 1187 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1188 | Touch each location in the window that has been touched in any of its ancestor |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1189 | windows. This routine is called by :meth:`refresh`, so it should almost never |
| 1190 | be necessary to call it manually. |
| 1191 | |
| 1192 | |
| 1193 | .. method:: window.syncok(flag) |
| 1194 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1195 | If called with *flag* set to ``True``, then :meth:`syncup` is called automatically |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1196 | whenever there is a change in the window. |
| 1197 | |
| 1198 | |
| 1199 | .. method:: window.syncup() |
| 1200 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1201 | Touch all locations in ancestors of the window that have been changed in the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1202 | window. |
| 1203 | |
| 1204 | |
| 1205 | .. method:: window.timeout(delay) |
| 1206 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1207 | Set blocking or non-blocking read behavior for the window. If *delay* is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1208 | negative, blocking read is used (which will wait indefinitely for input). If |
| 1209 | *delay* is zero, then non-blocking read is used, and -1 will be returned by |
| 1210 | :meth:`getch` if no input is waiting. If *delay* is positive, then |
| 1211 | :meth:`getch` will block for *delay* milliseconds, and return -1 if there is |
| 1212 | still no input at the end of that time. |
| 1213 | |
| 1214 | |
| 1215 | .. method:: window.touchline(start, count[, changed]) |
| 1216 | |
| 1217 | Pretend *count* lines have been changed, starting with line *start*. If |
| 1218 | *changed* is supplied, it specifies whether the affected lines are marked as |
| 1219 | having been changed (*changed*\ =1) or unchanged (*changed*\ =0). |
| 1220 | |
| 1221 | |
| 1222 | .. method:: window.touchwin() |
| 1223 | |
| 1224 | Pretend the whole window has been changed, for purposes of drawing |
| 1225 | optimizations. |
| 1226 | |
| 1227 | |
| 1228 | .. method:: window.untouchwin() |
| 1229 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1230 | Mark all lines in the window as unchanged since the last call to |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1231 | :meth:`refresh`. |
| 1232 | |
| 1233 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 1234 | .. method:: window.vline(ch, n) |
| 1235 | window.vline(y, x, ch, n) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1236 | |
| 1237 | Display a vertical line starting at ``(y, x)`` with length *n* consisting of the |
| 1238 | character *ch*. |
| 1239 | |
| 1240 | |
| 1241 | Constants |
| 1242 | --------- |
| 1243 | |
| 1244 | The :mod:`curses` module defines the following data members: |
| 1245 | |
| 1246 | |
| 1247 | .. data:: ERR |
| 1248 | |
| 1249 | Some curses routines that return an integer, such as :func:`getch`, return |
| 1250 | :const:`ERR` upon failure. |
| 1251 | |
| 1252 | |
| 1253 | .. data:: OK |
| 1254 | |
| 1255 | Some curses routines that return an integer, such as :func:`napms`, return |
| 1256 | :const:`OK` upon success. |
| 1257 | |
| 1258 | |
| 1259 | .. data:: version |
| 1260 | |
| 1261 | A string representing the current version of the module. Also available as |
| 1262 | :const:`__version__`. |
| 1263 | |
| 1264 | Several constants are available to specify character cell attributes: |
| 1265 | |
| 1266 | +------------------+-------------------------------+ |
| 1267 | | Attribute | Meaning | |
| 1268 | +==================+===============================+ |
| 1269 | | ``A_ALTCHARSET`` | Alternate character set mode. | |
| 1270 | +------------------+-------------------------------+ |
| 1271 | | ``A_BLINK`` | Blink mode. | |
| 1272 | +------------------+-------------------------------+ |
| 1273 | | ``A_BOLD`` | Bold mode. | |
| 1274 | +------------------+-------------------------------+ |
| 1275 | | ``A_DIM`` | Dim mode. | |
| 1276 | +------------------+-------------------------------+ |
| 1277 | | ``A_NORMAL`` | Normal attribute. | |
| 1278 | +------------------+-------------------------------+ |
Georg Brandl | 931e5c1 | 2011-03-06 11:08:35 +0100 | [diff] [blame] | 1279 | | ``A_REVERSE`` | Reverse background and | |
| 1280 | | | foreground colors. | |
| 1281 | +------------------+-------------------------------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1282 | | ``A_STANDOUT`` | Standout mode. | |
| 1283 | +------------------+-------------------------------+ |
| 1284 | | ``A_UNDERLINE`` | Underline mode. | |
| 1285 | +------------------+-------------------------------+ |
| 1286 | |
| 1287 | Keys are referred to by integer constants with names starting with ``KEY_``. |
| 1288 | The exact keycaps available are system dependent. |
| 1289 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 1290 | .. XXX this table is far too large! should it be alphabetized? |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1291 | |
| 1292 | +-------------------+--------------------------------------------+ |
| 1293 | | Key constant | Key | |
| 1294 | +===================+============================================+ |
| 1295 | | ``KEY_MIN`` | Minimum key value | |
| 1296 | +-------------------+--------------------------------------------+ |
| 1297 | | ``KEY_BREAK`` | Break key (unreliable) | |
| 1298 | +-------------------+--------------------------------------------+ |
| 1299 | | ``KEY_DOWN`` | Down-arrow | |
| 1300 | +-------------------+--------------------------------------------+ |
| 1301 | | ``KEY_UP`` | Up-arrow | |
| 1302 | +-------------------+--------------------------------------------+ |
| 1303 | | ``KEY_LEFT`` | Left-arrow | |
| 1304 | +-------------------+--------------------------------------------+ |
| 1305 | | ``KEY_RIGHT`` | Right-arrow | |
| 1306 | +-------------------+--------------------------------------------+ |
| 1307 | | ``KEY_HOME`` | Home key (upward+left arrow) | |
| 1308 | +-------------------+--------------------------------------------+ |
| 1309 | | ``KEY_BACKSPACE`` | Backspace (unreliable) | |
| 1310 | +-------------------+--------------------------------------------+ |
| 1311 | | ``KEY_F0`` | Function keys. Up to 64 function keys are | |
| 1312 | | | supported. | |
| 1313 | +-------------------+--------------------------------------------+ |
| 1314 | | ``KEY_Fn`` | Value of function key *n* | |
| 1315 | +-------------------+--------------------------------------------+ |
| 1316 | | ``KEY_DL`` | Delete line | |
| 1317 | +-------------------+--------------------------------------------+ |
| 1318 | | ``KEY_IL`` | Insert line | |
| 1319 | +-------------------+--------------------------------------------+ |
| 1320 | | ``KEY_DC`` | Delete character | |
| 1321 | +-------------------+--------------------------------------------+ |
| 1322 | | ``KEY_IC`` | Insert char or enter insert mode | |
| 1323 | +-------------------+--------------------------------------------+ |
| 1324 | | ``KEY_EIC`` | Exit insert char mode | |
| 1325 | +-------------------+--------------------------------------------+ |
| 1326 | | ``KEY_CLEAR`` | Clear screen | |
| 1327 | +-------------------+--------------------------------------------+ |
| 1328 | | ``KEY_EOS`` | Clear to end of screen | |
| 1329 | +-------------------+--------------------------------------------+ |
| 1330 | | ``KEY_EOL`` | Clear to end of line | |
| 1331 | +-------------------+--------------------------------------------+ |
| 1332 | | ``KEY_SF`` | Scroll 1 line forward | |
| 1333 | +-------------------+--------------------------------------------+ |
| 1334 | | ``KEY_SR`` | Scroll 1 line backward (reverse) | |
| 1335 | +-------------------+--------------------------------------------+ |
| 1336 | | ``KEY_NPAGE`` | Next page | |
| 1337 | +-------------------+--------------------------------------------+ |
| 1338 | | ``KEY_PPAGE`` | Previous page | |
| 1339 | +-------------------+--------------------------------------------+ |
| 1340 | | ``KEY_STAB`` | Set tab | |
| 1341 | +-------------------+--------------------------------------------+ |
| 1342 | | ``KEY_CTAB`` | Clear tab | |
| 1343 | +-------------------+--------------------------------------------+ |
| 1344 | | ``KEY_CATAB`` | Clear all tabs | |
| 1345 | +-------------------+--------------------------------------------+ |
| 1346 | | ``KEY_ENTER`` | Enter or send (unreliable) | |
| 1347 | +-------------------+--------------------------------------------+ |
| 1348 | | ``KEY_SRESET`` | Soft (partial) reset (unreliable) | |
| 1349 | +-------------------+--------------------------------------------+ |
| 1350 | | ``KEY_RESET`` | Reset or hard reset (unreliable) | |
| 1351 | +-------------------+--------------------------------------------+ |
| 1352 | | ``KEY_PRINT`` | Print | |
| 1353 | +-------------------+--------------------------------------------+ |
| 1354 | | ``KEY_LL`` | Home down or bottom (lower left) | |
| 1355 | +-------------------+--------------------------------------------+ |
| 1356 | | ``KEY_A1`` | Upper left of keypad | |
| 1357 | +-------------------+--------------------------------------------+ |
| 1358 | | ``KEY_A3`` | Upper right of keypad | |
| 1359 | +-------------------+--------------------------------------------+ |
| 1360 | | ``KEY_B2`` | Center of keypad | |
| 1361 | +-------------------+--------------------------------------------+ |
| 1362 | | ``KEY_C1`` | Lower left of keypad | |
| 1363 | +-------------------+--------------------------------------------+ |
| 1364 | | ``KEY_C3`` | Lower right of keypad | |
| 1365 | +-------------------+--------------------------------------------+ |
| 1366 | | ``KEY_BTAB`` | Back tab | |
| 1367 | +-------------------+--------------------------------------------+ |
| 1368 | | ``KEY_BEG`` | Beg (beginning) | |
| 1369 | +-------------------+--------------------------------------------+ |
| 1370 | | ``KEY_CANCEL`` | Cancel | |
| 1371 | +-------------------+--------------------------------------------+ |
| 1372 | | ``KEY_CLOSE`` | Close | |
| 1373 | +-------------------+--------------------------------------------+ |
| 1374 | | ``KEY_COMMAND`` | Cmd (command) | |
| 1375 | +-------------------+--------------------------------------------+ |
| 1376 | | ``KEY_COPY`` | Copy | |
| 1377 | +-------------------+--------------------------------------------+ |
| 1378 | | ``KEY_CREATE`` | Create | |
| 1379 | +-------------------+--------------------------------------------+ |
| 1380 | | ``KEY_END`` | End | |
| 1381 | +-------------------+--------------------------------------------+ |
| 1382 | | ``KEY_EXIT`` | Exit | |
| 1383 | +-------------------+--------------------------------------------+ |
| 1384 | | ``KEY_FIND`` | Find | |
| 1385 | +-------------------+--------------------------------------------+ |
| 1386 | | ``KEY_HELP`` | Help | |
| 1387 | +-------------------+--------------------------------------------+ |
| 1388 | | ``KEY_MARK`` | Mark | |
| 1389 | +-------------------+--------------------------------------------+ |
| 1390 | | ``KEY_MESSAGE`` | Message | |
| 1391 | +-------------------+--------------------------------------------+ |
| 1392 | | ``KEY_MOVE`` | Move | |
| 1393 | +-------------------+--------------------------------------------+ |
| 1394 | | ``KEY_NEXT`` | Next | |
| 1395 | +-------------------+--------------------------------------------+ |
| 1396 | | ``KEY_OPEN`` | Open | |
| 1397 | +-------------------+--------------------------------------------+ |
| 1398 | | ``KEY_OPTIONS`` | Options | |
| 1399 | +-------------------+--------------------------------------------+ |
| 1400 | | ``KEY_PREVIOUS`` | Prev (previous) | |
| 1401 | +-------------------+--------------------------------------------+ |
| 1402 | | ``KEY_REDO`` | Redo | |
| 1403 | +-------------------+--------------------------------------------+ |
| 1404 | | ``KEY_REFERENCE`` | Ref (reference) | |
| 1405 | +-------------------+--------------------------------------------+ |
| 1406 | | ``KEY_REFRESH`` | Refresh | |
| 1407 | +-------------------+--------------------------------------------+ |
| 1408 | | ``KEY_REPLACE`` | Replace | |
| 1409 | +-------------------+--------------------------------------------+ |
| 1410 | | ``KEY_RESTART`` | Restart | |
| 1411 | +-------------------+--------------------------------------------+ |
| 1412 | | ``KEY_RESUME`` | Resume | |
| 1413 | +-------------------+--------------------------------------------+ |
| 1414 | | ``KEY_SAVE`` | Save | |
| 1415 | +-------------------+--------------------------------------------+ |
| 1416 | | ``KEY_SBEG`` | Shifted Beg (beginning) | |
| 1417 | +-------------------+--------------------------------------------+ |
| 1418 | | ``KEY_SCANCEL`` | Shifted Cancel | |
| 1419 | +-------------------+--------------------------------------------+ |
| 1420 | | ``KEY_SCOMMAND`` | Shifted Command | |
| 1421 | +-------------------+--------------------------------------------+ |
| 1422 | | ``KEY_SCOPY`` | Shifted Copy | |
| 1423 | +-------------------+--------------------------------------------+ |
| 1424 | | ``KEY_SCREATE`` | Shifted Create | |
| 1425 | +-------------------+--------------------------------------------+ |
| 1426 | | ``KEY_SDC`` | Shifted Delete char | |
| 1427 | +-------------------+--------------------------------------------+ |
| 1428 | | ``KEY_SDL`` | Shifted Delete line | |
| 1429 | +-------------------+--------------------------------------------+ |
| 1430 | | ``KEY_SELECT`` | Select | |
| 1431 | +-------------------+--------------------------------------------+ |
| 1432 | | ``KEY_SEND`` | Shifted End | |
| 1433 | +-------------------+--------------------------------------------+ |
| 1434 | | ``KEY_SEOL`` | Shifted Clear line | |
| 1435 | +-------------------+--------------------------------------------+ |
| 1436 | | ``KEY_SEXIT`` | Shifted Dxit | |
| 1437 | +-------------------+--------------------------------------------+ |
| 1438 | | ``KEY_SFIND`` | Shifted Find | |
| 1439 | +-------------------+--------------------------------------------+ |
| 1440 | | ``KEY_SHELP`` | Shifted Help | |
| 1441 | +-------------------+--------------------------------------------+ |
| 1442 | | ``KEY_SHOME`` | Shifted Home | |
| 1443 | +-------------------+--------------------------------------------+ |
| 1444 | | ``KEY_SIC`` | Shifted Input | |
| 1445 | +-------------------+--------------------------------------------+ |
| 1446 | | ``KEY_SLEFT`` | Shifted Left arrow | |
| 1447 | +-------------------+--------------------------------------------+ |
| 1448 | | ``KEY_SMESSAGE`` | Shifted Message | |
| 1449 | +-------------------+--------------------------------------------+ |
| 1450 | | ``KEY_SMOVE`` | Shifted Move | |
| 1451 | +-------------------+--------------------------------------------+ |
| 1452 | | ``KEY_SNEXT`` | Shifted Next | |
| 1453 | +-------------------+--------------------------------------------+ |
| 1454 | | ``KEY_SOPTIONS`` | Shifted Options | |
| 1455 | +-------------------+--------------------------------------------+ |
| 1456 | | ``KEY_SPREVIOUS`` | Shifted Prev | |
| 1457 | +-------------------+--------------------------------------------+ |
| 1458 | | ``KEY_SPRINT`` | Shifted Print | |
| 1459 | +-------------------+--------------------------------------------+ |
| 1460 | | ``KEY_SREDO`` | Shifted Redo | |
| 1461 | +-------------------+--------------------------------------------+ |
| 1462 | | ``KEY_SREPLACE`` | Shifted Replace | |
| 1463 | +-------------------+--------------------------------------------+ |
| 1464 | | ``KEY_SRIGHT`` | Shifted Right arrow | |
| 1465 | +-------------------+--------------------------------------------+ |
| 1466 | | ``KEY_SRSUME`` | Shifted Resume | |
| 1467 | +-------------------+--------------------------------------------+ |
| 1468 | | ``KEY_SSAVE`` | Shifted Save | |
| 1469 | +-------------------+--------------------------------------------+ |
| 1470 | | ``KEY_SSUSPEND`` | Shifted Suspend | |
| 1471 | +-------------------+--------------------------------------------+ |
| 1472 | | ``KEY_SUNDO`` | Shifted Undo | |
| 1473 | +-------------------+--------------------------------------------+ |
| 1474 | | ``KEY_SUSPEND`` | Suspend | |
| 1475 | +-------------------+--------------------------------------------+ |
| 1476 | | ``KEY_UNDO`` | Undo | |
| 1477 | +-------------------+--------------------------------------------+ |
| 1478 | | ``KEY_MOUSE`` | Mouse event has occurred | |
| 1479 | +-------------------+--------------------------------------------+ |
| 1480 | | ``KEY_RESIZE`` | Terminal resize event | |
| 1481 | +-------------------+--------------------------------------------+ |
| 1482 | | ``KEY_MAX`` | Maximum key value | |
| 1483 | +-------------------+--------------------------------------------+ |
| 1484 | |
| 1485 | On VT100s and their software emulations, such as X terminal emulators, there are |
| 1486 | normally at least four function keys (:const:`KEY_F1`, :const:`KEY_F2`, |
| 1487 | :const:`KEY_F3`, :const:`KEY_F4`) available, and the arrow keys mapped to |
| 1488 | :const:`KEY_UP`, :const:`KEY_DOWN`, :const:`KEY_LEFT` and :const:`KEY_RIGHT` in |
| 1489 | the obvious way. If your machine has a PC keyboard, it is safe to expect arrow |
| 1490 | keys and twelve function keys (older PC keyboards may have only ten function |
| 1491 | keys); also, the following keypad mappings are standard: |
| 1492 | |
| 1493 | +------------------+-----------+ |
| 1494 | | Keycap | Constant | |
| 1495 | +==================+===========+ |
| 1496 | | :kbd:`Insert` | KEY_IC | |
| 1497 | +------------------+-----------+ |
| 1498 | | :kbd:`Delete` | KEY_DC | |
| 1499 | +------------------+-----------+ |
| 1500 | | :kbd:`Home` | KEY_HOME | |
| 1501 | +------------------+-----------+ |
| 1502 | | :kbd:`End` | KEY_END | |
| 1503 | +------------------+-----------+ |
| 1504 | | :kbd:`Page Up` | KEY_NPAGE | |
| 1505 | +------------------+-----------+ |
| 1506 | | :kbd:`Page Down` | KEY_PPAGE | |
| 1507 | +------------------+-----------+ |
| 1508 | |
| 1509 | The following table lists characters from the alternate character set. These are |
| 1510 | inherited from the VT100 terminal, and will generally be available on software |
| 1511 | emulations such as X terminals. When there is no graphic available, curses |
| 1512 | falls back on a crude printable ASCII approximation. |
| 1513 | |
| 1514 | .. note:: |
| 1515 | |
| 1516 | These are available only after :func:`initscr` has been called. |
| 1517 | |
| 1518 | +------------------+------------------------------------------+ |
| 1519 | | ACS code | Meaning | |
| 1520 | +==================+==========================================+ |
| 1521 | | ``ACS_BBSS`` | alternate name for upper right corner | |
| 1522 | +------------------+------------------------------------------+ |
| 1523 | | ``ACS_BLOCK`` | solid square block | |
| 1524 | +------------------+------------------------------------------+ |
| 1525 | | ``ACS_BOARD`` | board of squares | |
| 1526 | +------------------+------------------------------------------+ |
| 1527 | | ``ACS_BSBS`` | alternate name for horizontal line | |
| 1528 | +------------------+------------------------------------------+ |
| 1529 | | ``ACS_BSSB`` | alternate name for upper left corner | |
| 1530 | +------------------+------------------------------------------+ |
| 1531 | | ``ACS_BSSS`` | alternate name for top tee | |
| 1532 | +------------------+------------------------------------------+ |
| 1533 | | ``ACS_BTEE`` | bottom tee | |
| 1534 | +------------------+------------------------------------------+ |
| 1535 | | ``ACS_BULLET`` | bullet | |
| 1536 | +------------------+------------------------------------------+ |
| 1537 | | ``ACS_CKBOARD`` | checker board (stipple) | |
| 1538 | +------------------+------------------------------------------+ |
| 1539 | | ``ACS_DARROW`` | arrow pointing down | |
| 1540 | +------------------+------------------------------------------+ |
| 1541 | | ``ACS_DEGREE`` | degree symbol | |
| 1542 | +------------------+------------------------------------------+ |
| 1543 | | ``ACS_DIAMOND`` | diamond | |
| 1544 | +------------------+------------------------------------------+ |
| 1545 | | ``ACS_GEQUAL`` | greater-than-or-equal-to | |
| 1546 | +------------------+------------------------------------------+ |
| 1547 | | ``ACS_HLINE`` | horizontal line | |
| 1548 | +------------------+------------------------------------------+ |
| 1549 | | ``ACS_LANTERN`` | lantern symbol | |
| 1550 | +------------------+------------------------------------------+ |
| 1551 | | ``ACS_LARROW`` | left arrow | |
| 1552 | +------------------+------------------------------------------+ |
| 1553 | | ``ACS_LEQUAL`` | less-than-or-equal-to | |
| 1554 | +------------------+------------------------------------------+ |
| 1555 | | ``ACS_LLCORNER`` | lower left-hand corner | |
| 1556 | +------------------+------------------------------------------+ |
| 1557 | | ``ACS_LRCORNER`` | lower right-hand corner | |
| 1558 | +------------------+------------------------------------------+ |
| 1559 | | ``ACS_LTEE`` | left tee | |
| 1560 | +------------------+------------------------------------------+ |
| 1561 | | ``ACS_NEQUAL`` | not-equal sign | |
| 1562 | +------------------+------------------------------------------+ |
| 1563 | | ``ACS_PI`` | letter pi | |
| 1564 | +------------------+------------------------------------------+ |
| 1565 | | ``ACS_PLMINUS`` | plus-or-minus sign | |
| 1566 | +------------------+------------------------------------------+ |
| 1567 | | ``ACS_PLUS`` | big plus sign | |
| 1568 | +------------------+------------------------------------------+ |
| 1569 | | ``ACS_RARROW`` | right arrow | |
| 1570 | +------------------+------------------------------------------+ |
| 1571 | | ``ACS_RTEE`` | right tee | |
| 1572 | +------------------+------------------------------------------+ |
| 1573 | | ``ACS_S1`` | scan line 1 | |
| 1574 | +------------------+------------------------------------------+ |
| 1575 | | ``ACS_S3`` | scan line 3 | |
| 1576 | +------------------+------------------------------------------+ |
| 1577 | | ``ACS_S7`` | scan line 7 | |
| 1578 | +------------------+------------------------------------------+ |
| 1579 | | ``ACS_S9`` | scan line 9 | |
| 1580 | +------------------+------------------------------------------+ |
| 1581 | | ``ACS_SBBS`` | alternate name for lower right corner | |
| 1582 | +------------------+------------------------------------------+ |
| 1583 | | ``ACS_SBSB`` | alternate name for vertical line | |
| 1584 | +------------------+------------------------------------------+ |
| 1585 | | ``ACS_SBSS`` | alternate name for right tee | |
| 1586 | +------------------+------------------------------------------+ |
| 1587 | | ``ACS_SSBB`` | alternate name for lower left corner | |
| 1588 | +------------------+------------------------------------------+ |
| 1589 | | ``ACS_SSBS`` | alternate name for bottom tee | |
| 1590 | +------------------+------------------------------------------+ |
| 1591 | | ``ACS_SSSB`` | alternate name for left tee | |
| 1592 | +------------------+------------------------------------------+ |
| 1593 | | ``ACS_SSSS`` | alternate name for crossover or big plus | |
| 1594 | +------------------+------------------------------------------+ |
| 1595 | | ``ACS_STERLING`` | pound sterling | |
| 1596 | +------------------+------------------------------------------+ |
| 1597 | | ``ACS_TTEE`` | top tee | |
| 1598 | +------------------+------------------------------------------+ |
| 1599 | | ``ACS_UARROW`` | up arrow | |
| 1600 | +------------------+------------------------------------------+ |
| 1601 | | ``ACS_ULCORNER`` | upper left corner | |
| 1602 | +------------------+------------------------------------------+ |
| 1603 | | ``ACS_URCORNER`` | upper right corner | |
| 1604 | +------------------+------------------------------------------+ |
| 1605 | | ``ACS_VLINE`` | vertical line | |
| 1606 | +------------------+------------------------------------------+ |
| 1607 | |
| 1608 | The following table lists the predefined colors: |
| 1609 | |
| 1610 | +-------------------+----------------------------+ |
| 1611 | | Constant | Color | |
| 1612 | +===================+============================+ |
| 1613 | | ``COLOR_BLACK`` | Black | |
| 1614 | +-------------------+----------------------------+ |
| 1615 | | ``COLOR_BLUE`` | Blue | |
| 1616 | +-------------------+----------------------------+ |
| 1617 | | ``COLOR_CYAN`` | Cyan (light greenish blue) | |
| 1618 | +-------------------+----------------------------+ |
| 1619 | | ``COLOR_GREEN`` | Green | |
| 1620 | +-------------------+----------------------------+ |
| 1621 | | ``COLOR_MAGENTA`` | Magenta (purplish red) | |
| 1622 | +-------------------+----------------------------+ |
| 1623 | | ``COLOR_RED`` | Red | |
| 1624 | +-------------------+----------------------------+ |
| 1625 | | ``COLOR_WHITE`` | White | |
| 1626 | +-------------------+----------------------------+ |
| 1627 | | ``COLOR_YELLOW`` | Yellow | |
| 1628 | +-------------------+----------------------------+ |
| 1629 | |
| 1630 | |
| 1631 | :mod:`curses.textpad` --- Text input widget for curses programs |
| 1632 | =============================================================== |
| 1633 | |
| 1634 | .. module:: curses.textpad |
| 1635 | :synopsis: Emacs-like input editing in a curses window. |
| 1636 | .. moduleauthor:: Eric Raymond <esr@thyrsus.com> |
| 1637 | .. sectionauthor:: Eric Raymond <esr@thyrsus.com> |
| 1638 | |
| 1639 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1640 | The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles |
| 1641 | elementary text editing in a curses window, supporting a set of keybindings |
| 1642 | resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x, |
| 1643 | FrameMaker, and many other programs). The module also provides a |
| 1644 | rectangle-drawing function useful for framing text boxes or for other purposes. |
| 1645 | |
| 1646 | The module :mod:`curses.textpad` defines the following function: |
| 1647 | |
| 1648 | |
| 1649 | .. function:: rectangle(win, uly, ulx, lry, lrx) |
| 1650 | |
| 1651 | Draw a rectangle. The first argument must be a window object; the remaining |
| 1652 | arguments are coordinates relative to that window. The second and third |
| 1653 | arguments are the y and x coordinates of the upper left hand corner of the |
| 1654 | rectangle to be drawn; the fourth and fifth arguments are the y and x |
| 1655 | coordinates of the lower right hand corner. The rectangle will be drawn using |
| 1656 | VT100/IBM PC forms characters on terminals that make this possible (including |
| 1657 | xterm and most other software terminal emulators). Otherwise it will be drawn |
| 1658 | with ASCII dashes, vertical bars, and plus signs. |
| 1659 | |
| 1660 | |
| 1661 | .. _curses-textpad-objects: |
| 1662 | |
| 1663 | Textbox objects |
| 1664 | --------------- |
| 1665 | |
| 1666 | You can instantiate a :class:`Textbox` object as follows: |
| 1667 | |
| 1668 | |
| 1669 | .. class:: Textbox(win) |
| 1670 | |
| 1671 | Return a textbox widget object. The *win* argument should be a curses |
| 1672 | :class:`WindowObject` in which the textbox is to be contained. The edit cursor |
| 1673 | of the textbox is initially located at the upper left hand corner of the |
| 1674 | containing window, with coordinates ``(0, 0)``. The instance's |
| 1675 | :attr:`stripspaces` flag is initially on. |
| 1676 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1677 | :class:`Textbox` objects have the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1678 | |
| 1679 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1680 | .. method:: edit([validator]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1681 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1682 | This is the entry point you will normally use. It accepts editing |
| 1683 | keystrokes until one of the termination keystrokes is entered. If |
| 1684 | *validator* is supplied, it must be a function. It will be called for |
| 1685 | each keystroke entered with the keystroke as a parameter; command dispatch |
| 1686 | is done on the result. This method returns the window contents as a |
| 1687 | string; whether blanks in the window are included is affected by the |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1688 | :attr:`stripspaces` attribute. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1689 | |
| 1690 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1691 | .. method:: do_command(ch) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1692 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1693 | Process a single command keystroke. Here are the supported special |
| 1694 | keystrokes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1695 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1696 | +------------------+-------------------------------------------+ |
| 1697 | | Keystroke | Action | |
| 1698 | +==================+===========================================+ |
| 1699 | | :kbd:`Control-A` | Go to left edge of window. | |
| 1700 | +------------------+-------------------------------------------+ |
| 1701 | | :kbd:`Control-B` | Cursor left, wrapping to previous line if | |
| 1702 | | | appropriate. | |
| 1703 | +------------------+-------------------------------------------+ |
| 1704 | | :kbd:`Control-D` | Delete character under cursor. | |
| 1705 | +------------------+-------------------------------------------+ |
| 1706 | | :kbd:`Control-E` | Go to right edge (stripspaces off) or end | |
| 1707 | | | of line (stripspaces on). | |
| 1708 | +------------------+-------------------------------------------+ |
| 1709 | | :kbd:`Control-F` | Cursor right, wrapping to next line when | |
| 1710 | | | appropriate. | |
| 1711 | +------------------+-------------------------------------------+ |
| 1712 | | :kbd:`Control-G` | Terminate, returning the window contents. | |
| 1713 | +------------------+-------------------------------------------+ |
| 1714 | | :kbd:`Control-H` | Delete character backward. | |
| 1715 | +------------------+-------------------------------------------+ |
| 1716 | | :kbd:`Control-J` | Terminate if the window is 1 line, | |
| 1717 | | | otherwise insert newline. | |
| 1718 | +------------------+-------------------------------------------+ |
| 1719 | | :kbd:`Control-K` | If line is blank, delete it, otherwise | |
| 1720 | | | clear to end of line. | |
| 1721 | +------------------+-------------------------------------------+ |
| 1722 | | :kbd:`Control-L` | Refresh screen. | |
| 1723 | +------------------+-------------------------------------------+ |
| 1724 | | :kbd:`Control-N` | Cursor down; move down one line. | |
| 1725 | +------------------+-------------------------------------------+ |
| 1726 | | :kbd:`Control-O` | Insert a blank line at cursor location. | |
| 1727 | +------------------+-------------------------------------------+ |
| 1728 | | :kbd:`Control-P` | Cursor up; move up one line. | |
| 1729 | +------------------+-------------------------------------------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1730 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1731 | Move operations do nothing if the cursor is at an edge where the movement |
| 1732 | is not possible. The following synonyms are supported where possible: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1733 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1734 | +------------------------+------------------+ |
| 1735 | | Constant | Keystroke | |
| 1736 | +========================+==================+ |
| 1737 | | :const:`KEY_LEFT` | :kbd:`Control-B` | |
| 1738 | +------------------------+------------------+ |
| 1739 | | :const:`KEY_RIGHT` | :kbd:`Control-F` | |
| 1740 | +------------------------+------------------+ |
| 1741 | | :const:`KEY_UP` | :kbd:`Control-P` | |
| 1742 | +------------------------+------------------+ |
| 1743 | | :const:`KEY_DOWN` | :kbd:`Control-N` | |
| 1744 | +------------------------+------------------+ |
| 1745 | | :const:`KEY_BACKSPACE` | :kbd:`Control-h` | |
| 1746 | +------------------------+------------------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1747 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1748 | All other keystrokes are treated as a command to insert the given |
| 1749 | character and move right (with line wrapping). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1750 | |
| 1751 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1752 | .. method:: gather() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1753 | |
Ezio Melotti | b6b7371 | 2011-06-26 13:38:11 +0300 | [diff] [blame] | 1754 | Return the window contents as a string; whether blanks in the |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1755 | window are included is affected by the :attr:`stripspaces` member. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1756 | |
| 1757 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1758 | .. attribute:: stripspaces |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1759 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1760 | This attribute is a flag which controls the interpretation of blanks in |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1761 | the window. When it is on, trailing blanks on each line are ignored; any |
| 1762 | cursor motion that would land the cursor on a trailing blank goes to the |
| 1763 | end of that line instead, and trailing blanks are stripped when the window |
| 1764 | contents are gathered. |