Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(9)

Side by Side Diff: Doc/library/curses.rst

Issue 10639: reindent.py converts newlines to platform default
Patch Set: Created 8 years, 8 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « Doc/library/collections.rst ('k') | Doc/library/datetime.rst » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`curses` --- Terminal handling for character-cell displays 1 :mod:`curses` --- Terminal handling for character-cell displays
2 =============================================================== 2 ===============================================================
3 3
4 .. module:: curses 4 .. module:: curses
5 :synopsis: An interface to the curses library, providing portable 5 :synopsis: An interface to the curses library, providing portable
6 terminal handling. 6 terminal handling.
7 :platform: Unix 7 :platform: Unix
8 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> 8 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
9 .. sectionauthor:: Eric Raymond <esr@thyrsus.com> 9 .. sectionauthor:: Eric Raymond <esr@thyrsus.com>
10 10
(...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after
65 65
66 Whenever *x* or *y* arguments to a function or a method are optional, they 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 defau lts 67 default to the current cursor location. Whenever *attr* is optional, it defau lts
68 to :const:`A_NORMAL`. 68 to :const:`A_NORMAL`.
69 69
70 The module :mod:`curses` defines the following functions: 70 The module :mod:`curses` defines the following functions:
71 71
72 72
73 .. function:: baudrate() 73 .. function:: baudrate()
74 74
75 Return the output speed of the terminal in bits per second. On software 75 Returns the output speed of the terminal in bits per second. On software
76 terminal emulators it will have a fixed high value. Included for historical 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 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. 78 occasionally to change interfaces depending on the line speed.
79 79
80 80
81 .. function:: beep() 81 .. function:: beep()
82 82
83 Emit a short attention sound. 83 Emit a short attention sound.
84 84
85 85
86 .. function:: can_change_color() 86 .. function:: can_change_color()
87 87
88 Return ``True`` or ``False``, depending on whether the programmer can change the colors 88 Returns true or false, depending on whether the programmer can change the col ors
89 displayed by the terminal. 89 displayed by the terminal.
90 90
91 91
92 .. function:: cbreak() 92 .. function:: cbreak()
93 93
94 Enter cbreak mode. In cbreak mode (sometimes called "rare" mode) normal tty 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 o ne. 95 line buffering is turned off and characters are available to be read one by o ne.
96 However, unlike raw mode, special characters (interrupt, quit, suspend, and f low 96 However, unlike raw mode, special characters (interrupt, quit, suspend, and f low
97 control) retain their effects on the tty driver and calling program. Calling 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. 98 first :func:`raw` then :func:`cbreak` leaves the terminal in cbreak mode.
99 99
100 100
101 .. function:: color_content(color_number) 101 .. function:: color_content(color_number)
102 102
103 Return the intensity of the red, green, and blue (RGB) components in the colo r 103 Returns the intensity of the red, green, and blue (RGB) components in the col or
104 *color_number*, which must be between ``0`` and :const:`COLORS`. A 3-tuple i s 104 *color_number*, which must be between ``0`` and :const:`COLORS`. A 3-tuple i s
105 returned, containing the R,G,B values for the given color, which will be betw een 105 returned, containing the R,G,B values for the given color, which will be betw een
106 ``0`` (no component) and ``1000`` (maximum amount of component). 106 ``0`` (no component) and ``1000`` (maximum amount of component).
107 107
108 108
109 .. function:: color_pair(color_number) 109 .. function:: color_pair(color_number)
110 110
111 Return the attribute value for displaying text in the specified color. This 111 Returns the attribute value for displaying text in the specified color. This
112 attribute value can be combined with :const:`A_STANDOUT`, :const:`A_REVERSE`, 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 counterpa rt 113 and the other :const:`A_\*` attributes. :func:`pair_number` is the counterpa rt
114 to this function. 114 to this function.
115 115
116 116
117 .. function:: curs_set(visibility) 117 .. function:: curs_set(visibility)
118 118
119 Set the cursor state. *visibility* can be set to 0, 1, or 2, for invisible, 119 Sets the cursor state. *visibility* can be set to 0, 1, or 2, for invisible,
120 normal, or very visible. If the terminal supports the visibility requested, the 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 man y 121 previous cursor state is returned; otherwise, an exception is raised. On man y
122 terminals, the "visible" mode is an underline cursor and the "very visible" m ode 122 terminals, the "visible" mode is an underline cursor and the "very visible" m ode
123 is a block cursor. 123 is a block cursor.
124 124
125 125
126 .. function:: def_prog_mode() 126 .. function:: def_prog_mode()
127 127
128 Save the current terminal mode as the "program" mode, the mode when the runni ng 128 Saves the current terminal mode as the "program" mode, the mode when the runn ing
129 program is using curses. (Its counterpart is the "shell" mode, for when the 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 130 program is not in curses.) Subsequent calls to :func:`reset_prog_mode` will
131 restore this mode. 131 restore this mode.
132 132
133 133
134 .. function:: def_shell_mode() 134 .. function:: def_shell_mode()
135 135
136 Save the current terminal mode as the "shell" mode, the mode when the running 136 Saves the current terminal mode as the "shell" mode, the mode when the runnin g
137 program is not using curses. (Its counterpart is the "program" mode, when th e 137 program is not using curses. (Its counterpart is the "program" mode, when th e
138 program is using curses capabilities.) Subsequent calls to 138 program is using curses capabilities.) Subsequent calls to
139 :func:`reset_shell_mode` will restore this mode. 139 :func:`reset_shell_mode` will restore this mode.
140 140
141 141
142 .. function:: delay_output(ms) 142 .. function:: delay_output(ms)
143 143
144 Insert an *ms* millisecond pause in output. 144 Inserts an *ms* millisecond pause in output.
145 145
146 146
147 .. function:: doupdate() 147 .. function:: doupdate()
148 148
149 Update the physical screen. The curses library keeps two data structures, on e 149 Update the physical screen. The curses library keeps two data structures, on e
150 representing the current physical screen contents and a virtual screen 150 representing the current physical screen contents and a virtual screen
151 representing the desired next state. The :func:`doupdate` ground updates the 151 representing the desired next state. The :func:`doupdate` ground updates the
152 physical screen to match the virtual screen. 152 physical screen to match the virtual screen.
153 153
154 The virtual screen may be updated by a :meth:`noutrefresh` call after write 154 The virtual screen may be updated by a :meth:`noutrefresh` call after write
(...skipping 10 matching lines...) Expand all
165 it is entered. 165 it is entered.
166 166
167 167
168 .. function:: endwin() 168 .. function:: endwin()
169 169
170 De-initialize the library, and return terminal to normal status. 170 De-initialize the library, and return terminal to normal status.
171 171
172 172
173 .. function:: erasechar() 173 .. function:: erasechar()
174 174
175 Return the user's current erase character. Under Unix operating systems this 175 Returns the user's current erase character. Under Unix operating systems thi s
176 is a property of the controlling tty of the curses program, and is not set by 176 is a property of the controlling tty of the curses program, and is not set by
177 the curses library itself. 177 the curses library itself.
178 178
179 179
180 .. function:: filter() 180 .. function:: filter()
181 181
182 The :func:`.filter` routine, if used, must be called before :func:`initscr` i s 182 The :func:`.filter` routine, if used, must be called before :func:`initscr` i s
183 called. The effect is that, during those calls, :envvar:`LINES` is set to 1; the 183 called. The effect is that, during those calls, LINES is set to 1; the
184 capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home 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 t o 185 string is set to the value of cr. The effect is that the cursor is confined t o
186 the current line, and so are screen updates. This may be used for enabling 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. 187 character-at-a-time line editing without touching the rest of the screen.
188 188
189 189
190 .. function:: flash() 190 .. function:: flash()
191 191
192 Flash the screen. That is, change it to reverse-video and then change it bac k 192 Flash the screen. That is, change it to reverse-video and then change it bac k
193 in a short interval. Some people prefer such as 'visible bell' to the audibl e 193 in a short interval. Some people prefer such as 'visible bell' to the audibl e
194 attention signal produced by :func:`beep`. 194 attention signal produced by :func:`beep`.
195 195
196 196
197 .. function:: flushinp() 197 .. function:: flushinp()
198 198
199 Flush all input buffers. This throws away any typeahead that has been typ ed 199 Flush all input buffers. This throws away any typeahead that has been typ ed
200 by the user and has not yet been processed by the program. 200 by the user and has not yet been processed by the program.
201 201
202 202
203 .. function:: getmouse() 203 .. function:: getmouse()
204 204
205 After :meth:`getch` returns :const:`KEY_MOUSE` to signal a mouse event, this 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 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 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 208 multiple devices, and *x*, *y*, *z* are the event's coordinates. (*z* is
209 currently unused.) *bstate* is an integer value whose bits will be set to 209 currently unused.). *bstate* is an integer value whose bits will be set to
210 indicate the type of event, and will be the bitwise OR of one or more of the 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: 211 following constants, where *n* is the button number from 1 to 4:
212 :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED` , 212 :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED` ,
213 :const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`, 213 :const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`,
214 :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`. 214 :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`.
215 215
216 216
217 .. function:: getsyx() 217 .. function:: getsyx()
218 218
219 Return the current coordinates of the virtual screen cursor in y and x. If 219 Returns the current coordinates of the virtual screen cursor in y and x. If
220 leaveok is currently true, then -1,-1 is returned. 220 leaveok is currently true, then -1,-1 is returned.
221 221
222 222
223 .. function:: getwin(file) 223 .. function:: getwin(file)
224 224
225 Read window related data stored in the file by an earlier :func:`putwin` call . 225 Reads window related data stored in the file by an earlier :func:`putwin` cal l.
226 The routine then creates and initializes a new window using that data, return ing 226 The routine then creates and initializes a new window using that data, return ing
227 the new window object. 227 the new window object.
228 228
229 229
230 .. function:: has_colors() 230 .. function:: has_colors()
231 231
232 Return ``True`` if the terminal can display colors; otherwise, return ``False ``. 232 Returns true if the terminal can display colors; otherwise, it returns false.
233 233
234 234
235 .. function:: has_ic() 235 .. function:: has_ic()
236 236
237 Return ``True`` if the terminal has insert- and delete-character capabilities . 237 Returns true if the terminal has insert- and delete- character capabilities.
238 This function is included for historical reasons only, as all modern software 238 This function is included for historical reasons only, as all modern software
239 terminal emulators have such capabilities. 239 terminal emulators have such capabilities.
240 240
241 241
242 .. function:: has_il() 242 .. function:: has_il()
243 243
244 Return ``True`` if the terminal has insert- and delete-line capabilities, or can 244 Returns true if the terminal has insert- and delete-line capabilities, or can
245 simulate them using scrolling regions. This function is included for 245 simulate them using scrolling regions. This function is included for
246 historical reasons only, as all modern software terminal emulators have such 246 historical reasons only, as all modern software terminal emulators have such
247 capabilities. 247 capabilities.
248 248
249 249
250 .. function:: has_key(ch) 250 .. function:: has_key(ch)
251 251
252 Take a key value *ch*, and return ``True`` if the current terminal type recog nizes 252 Takes a key value *ch*, and returns true if the current terminal type recogni zes
253 a key with that value. 253 a key with that value.
254 254
255 255
256 .. function:: halfdelay(tenths) 256 .. function:: halfdelay(tenths)
257 257
258 Used for half-delay mode, which is similar to cbreak mode in that characters 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 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 ha s 260 blocking for *tenths* tenths of seconds, an exception is raised if nothing ha s
261 been typed. The value of *tenths* must be a number between ``1`` and ``255`` . Use 261 been typed. The value of *tenths* must be a number between 1 and 255. Use
262 :func:`nocbreak` to leave half-delay mode. 262 :func:`nocbreak` to leave half-delay mode.
263 263
264 264
265 .. function:: init_color(color_number, r, g, b) 265 .. function:: init_color(color_number, r, g, b)
266 266
267 Change the definition of a color, taking the number of the color to be change d 267 Changes the definition of a color, taking the number of the color to be chang ed
268 followed by three RGB values (for the amounts of red, green, and blue 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 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 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 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 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``. 273 most terminals; it is active only if :func:`can_change_color` returns ``1``.
274 274
275 275
276 .. function:: init_pair(pair_number, fg, bg) 276 .. function:: init_pair(pair_number, fg, bg)
277 277
278 Change the definition of a color-pair. It takes three arguments: the number of 278 Changes the definition of a color-pair. It takes three arguments: the number of
279 the color-pair to be changed, the foreground color number, and the background 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 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 cann ot 281 ``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cann ot
282 be changed). The value of *fg* and *bg* arguments must be between ``0`` and 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 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 284 refreshed and all occurrences of that color-pair are changed to the new
285 definition. 285 definition.
286 286
287 287
288 .. function:: initscr() 288 .. function:: initscr()
289 289
290 Initialize the library. Return a :class:`WindowObject` which represents the 290 Initialize the library. Returns a :class:`WindowObject` which represents the
291 whole screen. 291 whole screen.
292 292
293 .. note:: 293 .. note::
294 294
295 If there is an error opening the terminal, the underlying curses library m ay 295 If there is an error opening the terminal, the underlying curses library m ay
296 cause the interpreter to exit. 296 cause the interpreter to exit.
297
298
299 .. function:: is_term_resized(nlines, ncols)
300
301 Return ``True`` if :func:`resize_term` would modify the window structure,
302 ``False`` otherwise.
303 297
304 298
305 .. function:: isendwin() 299 .. function:: isendwin()
306 300
307 Return ``True`` if :func:`endwin` has been called (that is, the curses libra ry has 301 Returns true if :func:`endwin` has been called (that is, the curses library has
308 been deinitialized). 302 been deinitialized).
309 303
310 304
311 .. function:: keyname(k) 305 .. function:: keyname(k)
312 306
313 Return the name of the key numbered *k*. The name of a key generating printa ble 307 Return the name of the key numbered *k*. The name of a key generating printa ble
314 ASCII character is the key's character. The name of a control-key combinatio n 308 ASCII character is the key's character. The name of a control-key combinatio n
315 is a two-character string consisting of a caret followed by the corresponding 309 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 310 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 correspondin g 311 string consisting of the prefix 'M-' followed by the name of the correspondin g
318 ASCII character. 312 ASCII character.
319 313
320 314
321 .. function:: killchar() 315 .. function:: killchar()
322 316
323 Return the user's current line kill character. Under Unix operating systems 317 Returns the user's current line kill character. Under Unix operating systems
324 this is a property of the controlling tty of the curses program, and is not s et 318 this is a property of the controlling tty of the curses program, and is not s et
325 by the curses library itself. 319 by the curses library itself.
326 320
327 321
328 .. function:: longname() 322 .. function:: longname()
329 323
330 Return a string containing the terminfo long name field describing the curren t 324 Returns a string containing the terminfo long name field describing the curre nt
331 terminal. The maximum length of a verbose description is 128 characters. It is 325 terminal. The maximum length of a verbose description is 128 characters. It is
332 defined only after the call to :func:`initscr`. 326 defined only after the call to :func:`initscr`.
333 327
334 328
335 .. function:: meta(yes) 329 .. function:: meta(yes)
336 330
337 If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0, allow only 331 If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0, allow only
338 7-bit chars. 332 7-bit chars.
339 333
340 334
341 .. function:: mouseinterval(interval) 335 .. function:: mouseinterval(interval)
342 336
343 Set the maximum time in milliseconds that can elapse between press and releas e 337 Sets the maximum time in milliseconds that can elapse between press and relea se
344 events in order for them to be recognized as a click, and return the previous 338 events in order for them to be recognized as a click, and returns the previou s
345 interval value. The default value is 200 msec, or one fifth of a second. 339 interval value. The default value is 200 msec, or one fifth of a second.
346 340
347 341
348 .. function:: mousemask(mousemask) 342 .. function:: mousemask(mousemask)
349 343
350 Set the mouse events to be reported, and return a tuple ``(availmask, 344 Sets the mouse events to be reported, and returns a tuple ``(availmask,
351 oldmask)``. *availmask* indicates which of the specified mouse events can b e 345 oldmask)``. *availmask* indicates which of the specified mouse events can b e
352 reported; on complete failure it returns 0. *oldmask* is the previous value of 346 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 mo use 347 the given window's mouse event mask. If this function is never called, no mo use
354 events are ever reported. 348 events are ever reported.
355 349
356 350
357 .. function:: napms(ms) 351 .. function:: napms(ms)
358 352
359 Sleep for *ms* milliseconds. 353 Sleep for *ms* milliseconds.
360 354
361 355
362 .. function:: newpad(nlines, ncols) 356 .. function:: newpad(nlines, ncols)
363 357
364 Create and return a pointer to a new pad data structure with the given number 358 Creates and returns a pointer to a new pad data structure with the given numb er
365 of lines and columns. A pad is returned as a window object. 359 of lines and columns. A pad is returned as a window object.
366 360
367 A pad is like a window, except that it is not restricted by the screen size, and 361 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 362 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 363 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 364 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` 365 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 366 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 367 displayed and the location on the screen to be used for the display. The
374 arguments are *pminrow*, *pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol *; the *p* 368 arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p
375 arguments refer to the upper left corner of the pad region to be displayed an d 369 arguments refer to the upper left corner of the pad region to be displayed an d
376 the *s* arguments define a clipping box on the screen within which the pad re gion 370 the s arguments define a clipping box on the screen within which the pad regi on
377 is to be displayed. 371 is to be displayed.
378 372
379 373
380 .. function:: newwin([nlines, ncols,] begin_y, begin_x) 374 .. function:: newwin([nlines, ncols,] begin_y, begin_x)
381 375
382 Return a new window, whose left-upper corner is at ``(begin_y, begin_x)``, a nd 376 Return a new window, whose left-upper corner is at ``(begin_y, begin_x)``, a nd
383 whose height/width is *nlines*/*ncols*. 377 whose height/width is *nlines*/*ncols*.
384 378
385 By default, the window will extend from the specified position to the lower 379 By default, the window will extend from the specified position to the lower
386 right corner of the screen. 380 right corner of the screen.
(...skipping 21 matching lines...) Expand all
408 Leave newline mode. Disable translation of return into newline on input, and 402 Leave newline mode. Disable translation of return into newline on input, and
409 disable low-level translation of newline into newline/return on output (but t his 403 disable low-level translation of newline into newline/return on output (but t his
410 does not change the behavior of ``addch('\n')``, which always does the 404 does not change the behavior of ``addch('\n')``, which always does the
411 equivalent of return and line feed on the virtual screen). With translation 405 equivalent of return and line feed on the virtual screen). With translation
412 off, curses can sometimes speed up vertical motion a little; also, it will be 406 off, curses can sometimes speed up vertical motion a little; also, it will be
413 able to detect the return key on input. 407 able to detect the return key on input.
414 408
415 409
416 .. function:: noqiflush() 410 .. function:: noqiflush()
417 411
418 When the :func:`noqiflush` routine is used, normal flush of input and output queues 412 When the noqiflush routine is used, normal flush of input and output queues
419 associated with the INTR, QUIT and SUSP characters will not be done. You may 413 associated with the INTR, QUIT and SUSP characters will not be done. You may
420 want to call :func:`noqiflush` in a signal handler if you want output to 414 want to call :func:`noqiflush` in a signal handler if you want output to
421 continue as though the interrupt had not occurred, after the handler exits. 415 continue as though the interrupt had not occurred, after the handler exits.
422 416
423 417
424 .. function:: noraw() 418 .. function:: noraw()
425 419
426 Leave raw mode. Return to normal "cooked" mode with line buffering. 420 Leave raw mode. Return to normal "cooked" mode with line buffering.
427 421
428 422
429 .. function:: pair_content(pair_number) 423 .. function:: pair_content(pair_number)
430 424
431 Return a tuple ``(fg, bg)`` containing the colors for the requested color pai r. 425 Returns a tuple ``(fg, bg)`` containing the colors for the requested color pa ir.
432 The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1``. 426 The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1``.
433 427
434 428
435 .. function:: pair_number(attr) 429 .. function:: pair_number(attr)
436 430
437 Return the number of the color-pair set by the attribute value *attr*. 431 Returns the number of the color-pair set by the attribute value *attr*.
438 :func:`color_pair` is the counterpart to this function. 432 :func:`color_pair` is the counterpart to this function.
439 433
440 434
441 .. function:: putp(string) 435 .. function:: putp(string)
442 436
443 Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified 437 Equivalent to ``tputs(str, 1, putchar)``; emits the value of a specified
444 terminfo capability for the current terminal. Note that the output of :func: `putp` 438 terminfo capability for the current terminal. Note that the output of putp
445 always goes to standard output. 439 always goes to standard output.
446 440
447 441
448 .. function:: qiflush( [flag] ) 442 .. function:: qiflush( [flag] )
449 443
450 If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If 444 If *flag* is false, the effect is the same as calling :func:`noqiflush`. If
451 *flag* is ``True``, or no argument is provided, the queues will be flushed wh en 445 *flag* is true, or no argument is provided, the queues will be flushed when
452 these control characters are read. 446 these control characters are read.
453 447
454 448
455 .. function:: raw() 449 .. function:: raw()
456 450
457 Enter raw mode. In raw mode, normal line buffering and processing of 451 Enter raw mode. In raw mode, normal line buffering and processing of
458 interrupt, quit, suspend, and flow control keys are turned off; characters ar e 452 interrupt, quit, suspend, and flow control keys are turned off; characters ar e
459 presented to curses input functions one by one. 453 presented to curses input functions one by one.
460 454
461 455
462 .. function:: reset_prog_mode() 456 .. function:: reset_prog_mode()
463 457
464 Restore the terminal to "program" mode, as previously saved by 458 Restores the terminal to "program" mode, as previously saved by
465 :func:`def_prog_mode`. 459 :func:`def_prog_mode`.
466 460
467 461
468 .. function:: reset_shell_mode() 462 .. function:: reset_shell_mode()
469 463
470 Restore the terminal to "shell" mode, as previously saved by 464 Restores the terminal to "shell" mode, as previously saved by
471 :func:`def_shell_mode`. 465 :func:`def_shell_mode`.
472
473
474 .. function:: resetty()
475
476 Restore the state of the terminal modes to what it was at the last call to
477 :func:`savetty`.
478
479
480 .. function:: resize_term(nlines, ncols)
481
482 Backend function used by :func:`resizeterm`, performing most of the work;
483 when resizing the windows, :func:`resize_term` blank-fills the areas that are
484 extended. The calling application should fill in these areas with
485 appropriate data. The :func:`resize_term` function attempts to resize all
486 windows. However, due to the calling convention of pads, it is not possible
487 to resize these without additional interaction with the application.
488
489
490 .. function:: resizeterm(nlines, ncols)
491
492 Resize the standard and current windows to the specified dimensions, and
493 adjusts other bookkeeping data used by the curses library that record the
494 window dimensions (in particular the SIGWINCH handler).
495
496
497 .. function:: savetty()
498
499 Save the current state of the terminal modes in a buffer, usable by
500 :func:`resetty`.
501 466
502 467
503 .. function:: setsyx(y, x) 468 .. function:: setsyx(y, x)
504 469
505 Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then 470 Sets the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then
506 leaveok is set. 471 leaveok is set.
507 472
508 473
509 .. function:: setupterm([termstr, fd]) 474 .. function:: setupterm([termstr, fd])
510 475
511 Initialize the terminal. *termstr* is a string giving the terminal name; if 476 Initializes the terminal. *termstr* is a string giving the terminal name; if
512 omitted, the value of the :envvar:`TERM` environment variable will be used. *fd* is the 477 omitted, the value of the TERM environment variable will be used. *fd* is th e
513 file descriptor to which any initialization sequences will be sent; if not 478 file descriptor to which any initialization sequences will be sent; if not
514 supplied, the file descriptor for ``sys.stdout`` will be used. 479 supplied, the file descriptor for ``sys.stdout`` will be used.
515 480
516 481
517 .. function:: start_color() 482 .. function:: start_color()
518 483
519 Must be called if the programmer wants to use colors, and before any other co lor 484 Must be called if the programmer wants to use colors, and before any other co lor
520 manipulation routine is called. It is good practice to call this routine rig ht 485 manipulation routine is called. It is good practice to call this routine rig ht
521 after :func:`initscr`. 486 after :func:`initscr`.
522 487
523 :func:`start_color` initializes eight basic colors (black, red, green, yello w, 488 :func:`start_color` initializes eight basic colors (black, red, green, yello w,
524 blue, magenta, cyan, and white), and two global variables in the :mod:`curses ` 489 blue, magenta, cyan, and white), and two global variables in the :mod:`curses `
525 module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing the maximum numb er 490 module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing the maximum numb er
526 of colors and color-pairs the terminal can support. It also restores the col ors 491 of colors and color-pairs the terminal can support. It also restores the col ors
527 on the terminal to the values they had when the terminal was just turned on. 492 on the terminal to the values they had when the terminal was just turned on.
528 493
529 494
530 .. function:: termattrs() 495 .. function:: termattrs()
531 496
532 Return a logical OR of all video attributes supported by the terminal. This 497 Returns a logical OR of all video attributes supported by the terminal. This
533 information is useful when a curses program needs complete control over the 498 information is useful when a curses program needs complete control over the
534 appearance of the screen. 499 appearance of the screen.
535 500
536 501
537 .. function:: termname() 502 .. function:: termname()
538 503
539 Return the value of the environment variable :envvar:`TERM`, truncated to 14 characters. 504 Returns the value of the environment variable TERM, truncated to 14 character s.
540 505
541 506
542 .. function:: tigetflag(capname) 507 .. function:: tigetflag(capname)
543 508
544 Return the value of the Boolean capability corresponding to the terminfo 509 Returns the value of the Boolean capability corresponding to the terminfo
545 capability name *capname*. The value ``-1`` is returned if *capname* is not a 510 capability name *capname*. The value ``-1`` is returned if *capname* is not a
546 Boolean capability, or ``0`` if it is canceled or absent from the terminal 511 Boolean capability, or ``0`` if it is canceled or absent from the terminal
547 description. 512 description.
548 513
549 514
550 .. function:: tigetnum(capname) 515 .. function:: tigetnum(capname)
551 516
552 Return the value of the numeric capability corresponding to the terminfo 517 Returns the value of the numeric capability corresponding to the terminfo
553 capability name *capname*. The value ``-2`` is returned if *capname* is not a 518 capability name *capname*. The value ``-2`` is returned if *capname* is not a
554 numeric capability, or ``-1`` if it is canceled or absent from the terminal 519 numeric capability, or ``-1`` if it is canceled or absent from the terminal
555 description. 520 description.
556 521
557 522
558 .. function:: tigetstr(capname) 523 .. function:: tigetstr(capname)
559 524
560 Return the value of the string capability corresponding to the terminfo 525 Returns the value of the string capability corresponding to the terminfo
561 capability name *capname*. ``None`` is returned if *capname* is not a string 526 capability name *capname*. ``None`` is returned if *capname* is not a string
562 capability, or is canceled or absent from the terminal description. 527 capability, or is canceled or absent from the terminal description.
563 528
564 529
565 .. function:: tparm(str[, ...]) 530 .. function:: tparm(str[, ...])
566 531
567 Instantiate the string *str* with the supplied parameters, where *str* should 532 Instantiates the string *str* with the supplied parameters, where *str* shou ld
568 be a parameterized string obtained from the terminfo database. E.g. 533 be a parameterized string obtained from the terminfo database. E.g.
569 ``tparm(tigetstr("cup"), 5, 3)`` could result in ``'\033[6;4H'``, the exact 534 ``tparm(tigetstr("cup"), 5, 3)`` could result in ``'\033[6;4H'``, the exact
570 result depending on terminal type. 535 result depending on terminal type.
571 536
572 537
573 .. function:: typeahead(fd) 538 .. function:: typeahead(fd)
574 539
575 Specify that the file descriptor *fd* be used for typeahead checking. If *fd * 540 Specifies that the file descriptor *fd* be used for typeahead checking. If * fd*
576 is ``-1``, then no typeahead checking is done. 541 is ``-1``, then no typeahead checking is done.
577 542
578 The curses library does "line-breakout optimization" by looking for typeahead 543 The curses library does "line-breakout optimization" by looking for typeahead
579 periodically while updating the screen. If input is found, and it is coming 544 periodically while updating the screen. If input is found, and it is coming
580 from a tty, the current update is postponed until refresh or doupdate is call ed 545 from a tty, the current update is postponed until refresh or doupdate is call ed
581 again, allowing faster response to commands typed in advance. This function 546 again, allowing faster response to commands typed in advance. This function
582 allows specifying a different file descriptor for typeahead checking. 547 allows specifying a different file descriptor for typeahead checking.
583 548
584 549
585 .. function:: unctrl(ch) 550 .. function:: unctrl(ch)
586 551
587 Return a string which is a printable representation of the character *ch*. 552 Returns a string which is a printable representation of the character *ch*.
588 Control characters are displayed as a caret followed by the character, for 553 Control characters are displayed as a caret followed by the character, for
589 example as ``^C``. Printing characters are left as they are. 554 example as ``^C``. Printing characters are left as they are.
590 555
591 556
592 .. function:: ungetch(ch) 557 .. function:: ungetch(ch)
593 558
594 Push *ch* so the next :meth:`getch` will return it. 559 Push *ch* so the next :meth:`getch` will return it.
595 560
596 .. note:: 561 .. note::
597 562
598 Only one *ch* can be pushed before :meth:`getch` is called. 563 Only one *ch* can be pushed before :meth:`getch` is called.
599 564
600 565
601 .. function:: ungetmouse(id, x, y, z, bstate) 566 .. function:: ungetmouse(id, x, y, z, bstate)
602 567
603 Push a :const:`KEY_MOUSE` event onto the input queue, associating the given 568 Push a :const:`KEY_MOUSE` event onto the input queue, associating the given
604 state data with it. 569 state data with it.
605 570
606 571
607 .. function:: use_env(flag) 572 .. function:: use_env(flag)
608 573
609 If used, this function should be called before :func:`initscr` or newterm are 574 If used, this function should be called before :func:`initscr` or newterm are
610 called. When *flag* is ``False``, the values of lines and columns specified in the 575 called. When *flag* is false, the values of lines and columns specified in t he
611 terminfo database will be used, even if environment variables :envvar:`LINES` 576 terminfo database will be used, even if environment variables :envvar:`LINES`
612 and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a 577 and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a
613 window (in which case default behavior would be to use the window size if 578 window (in which case default behavior would be to use the window size if
614 :envvar:`LINES` and :envvar:`COLUMNS` are not set). 579 :envvar:`LINES` and :envvar:`COLUMNS` are not set).
615 580
616 581
617 .. function:: use_default_colors() 582 .. function:: use_default_colors()
618 583
619 Allow use of default values for colors on terminals supporting this feature. Use 584 Allow use of default values for colors on terminals supporting this feature. Use
620 this to support transparency in your application. The default color is assig ned 585 this to support transparency in your application. The default color is assig ned
(...skipping 63 matching lines...) Expand 10 before | Expand all | Expand 10 after
684 649
685 650
686 .. method:: window.attrset(attr) 651 .. method:: window.attrset(attr)
687 652
688 Set the "background" set of attributes to *attr*. This set is initially 0 (n o 653 Set the "background" set of attributes to *attr*. This set is initially 0 (n o
689 attributes). 654 attributes).
690 655
691 656
692 .. method:: window.bkgd(ch[, attr]) 657 .. method:: window.bkgd(ch[, attr])
693 658
694 Set the background property of the window to the character *ch*, with 659 Sets the background property of the window to the character *ch*, with
695 attributes *attr*. The change is then applied to every character position in 660 attributes *attr*. The change is then applied to every character position in
696 that window: 661 that window:
697 662
698 * The attribute of every character in the window is changed to the new 663 * The attribute of every character in the window is changed to the new
699 background attribute. 664 background attribute.
700 665
701 * Wherever the former background character appears, it is changed to the ne w 666 * Wherever the former background character appears, it is changed to the ne w
702 background character. 667 background character.
703 668
704 669
705 .. method:: window.bkgdset(ch[, attr]) 670 .. method:: window.bkgdset(ch[, attr])
706 671
707 Set the window's background. A window's background consists of a character a nd 672 Sets the window's background. A window's background consists of a character and
708 any combination of attributes. The attribute part of the background is combi ned 673 any combination of attributes. The attribute part of the background is combi ned
709 (OR'ed) with all non-blank characters that are written into the window. Both 674 (OR'ed) with all non-blank characters that are written into the window. Both
710 the character and attribute parts of the background are combined with the bla nk 675 the character and attribute parts of the background are combined with the bla nk
711 characters. The background becomes a property of the character and moves wit h 676 characters. The background becomes a property of the character and moves wit h
712 the character through any scrolling and insert/delete line/character operatio ns. 677 the character through any scrolling and insert/delete line/character operatio ns.
713 678
714 679
715 .. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]]) 680 .. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])
716 681
717 Draw a border around the edges of the window. Each parameter specifies the 682 Draw a border around the edges of the window. Each parameter specifies the
(...skipping 24 matching lines...) Expand all
742 +-----------+---------------------+-----------------------+ 707 +-----------+---------------------+-----------------------+
743 | *bl* | Bottom-left corner | :const:`ACS_LLCORNER` | 708 | *bl* | Bottom-left corner | :const:`ACS_LLCORNER` |
744 +-----------+---------------------+-----------------------+ 709 +-----------+---------------------+-----------------------+
745 | *br* | Bottom-right corner | :const:`ACS_LRCORNER` | 710 | *br* | Bottom-right corner | :const:`ACS_LRCORNER` |
746 +-----------+---------------------+-----------------------+ 711 +-----------+---------------------+-----------------------+
747 712
748 713
749 .. method:: window.box([vertch, horch]) 714 .. method:: window.box([vertch, horch])
750 715
751 Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and 716 Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and
752 *bs* are *horch*. The default corner characters are always used by this func tion. 717 bs are *horch*. The default corner characters are always used by this functi on.
753 718
754 719
755 .. method:: window.chgat([y, x, ] [num,] attr) 720 .. method:: window.chgat([y, x, ] [num,] attr)
756 721
757 Set the attributes of *num* characters at the current cursor position, or at 722 Sets the attributes of *num* characters at the current cursor position, or at
758 position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1, 723 position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,
759 the attribute will be set on all the characters to the end of the line. Thi s 724 the attribute will be set on all the characters to the end of the line. Thi s
760 function does not move the cursor. The changed line will be touched using the 725 function does not move the cursor. The changed line will be touched using the
761 :meth:`touchline` method so that the contents will be redisplayed by the next 726 :meth:`touchline` method so that the contents will be redisplayed by the next
762 window refresh. 727 window refresh.
763 728
764 729
765 .. method:: window.clear() 730 .. method:: window.clear()
766 731
767 Like :meth:`erase`, but also cause the whole window to be repainted upon next 732 Like :meth:`erase`, but also causes the whole window to be repainted upon nex t
768 call to :meth:`refresh`. 733 call to :meth:`refresh`.
769 734
770 735
771 .. method:: window.clearok(yes) 736 .. method:: window.clearok(yes)
772 737
773 If *yes* is 1, the next call to :meth:`refresh` will clear the window 738 If *yes* is 1, the next call to :meth:`refresh` will clear the window
774 completely. 739 completely.
775 740
776 741
777 .. method:: window.clrtobot() 742 .. method:: window.clrtobot()
778 743
779 Erase from cursor to the end of the window: all lines below the cursor are 744 Erase from cursor to the end of the window: all lines below the cursor are
780 deleted, and then the equivalent of :meth:`clrtoeol` is performed. 745 deleted, and then the equivalent of :meth:`clrtoeol` is performed.
781 746
782 747
783 .. method:: window.clrtoeol() 748 .. method:: window.clrtoeol()
784 749
785 Erase from cursor to the end of the line. 750 Erase from cursor to the end of the line.
786 751
787 752
788 .. method:: window.cursyncup() 753 .. method:: window.cursyncup()
789 754
790 Update the current cursor position of all the ancestors of the window to 755 Updates the current cursor position of all the ancestors of the window to
791 reflect the current cursor position of the window. 756 reflect the current cursor position of the window.
792 757
793 758
794 .. method:: window.delch([y, x]) 759 .. method:: window.delch([y, x])
795 760
796 Delete any character at ``(y, x)``. 761 Delete any character at ``(y, x)``.
797 762
798 763
799 .. method:: window.deleteln() 764 .. method:: window.deleteln()
800 765
801 Delete the line under the cursor. All following lines are moved up by one lin e. 766 Delete the line under the cursor. All following lines are moved up by 1 line.
802 767
803 768
804 .. method:: window.derwin([nlines, ncols,] begin_y, begin_x) 769 .. method:: window.derwin([nlines, ncols,] begin_y, begin_x)
805 770
806 An abbreviation for "derive window", :meth:`derwin` is the same as calling 771 An abbreviation for "derive window", :meth:`derwin` is the same as calling
807 :meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origi n 772 :meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origi n
808 of the window, rather than relative to the entire screen. Return a window 773 of the window, rather than relative to the entire screen. Returns a window
809 object for the derived window. 774 object for the derived window.
810 775
811 776
812 .. method:: window.echochar(ch[, attr]) 777 .. method:: window.echochar(ch[, attr])
813 778
814 Add character *ch* with attribute *attr*, and immediately call :meth:`refres h` 779 Add character *ch* with attribute *attr*, and immediately call :meth:`refres h`
815 on the window. 780 on the window.
816 781
817 782
818 .. method:: window.enclose(y, x) 783 .. method:: window.enclose(y, x)
819 784
820 Test whether the given pair of screen-relative character-cell coordinates are 785 Tests whether the given pair of screen-relative character-cell coordinates ar e
821 enclosed by the given window, returning ``True`` or ``False``. It is useful for 786 enclosed by the given window, returning true or false. It is useful for
822 determining what subset of the screen windows enclose the location of a mouse 787 determining what subset of the screen windows enclose the location of a mouse
823 event. 788 event.
824 789
825 790
826 .. method:: window.erase() 791 .. method:: window.erase()
827 792
828 Clear the window. 793 Clear the window.
829 794
830 795
831 .. method:: window.getbegyx() 796 .. method:: window.getbegyx()
832 797
833 Return a tuple ``(y, x)`` of co-ordinates of upper-left corner. 798 Return a tuple ``(y, x)`` of co-ordinates of upper-left corner.
834
835
836 .. method:: window.getbkgd()
837
838 Return the given window's current background character/attribute pair.
839 799
840 800
841 .. method:: window.getch([y, x]) 801 .. method:: window.getch([y, x])
842 802
843 Get a character. Note that the integer returned does *not* have to be in ASCI I 803 Get a character. Note that the integer returned does *not* have to be in ASCI I
844 range: function keys, keypad keys and so on return numbers higher than 256. I n 804 range: function keys, keypad keys and so on return numbers higher than 256. I n
845 no-delay mode, -1 is returned if there is no input, else :func:`getch` waits 805 no-delay mode, -1 is returned if there is no input, else :func:`getch` waits
846 until a key is pressed. 806 until a key is pressed.
847
848
849 .. method:: window.get_wch([y, x])
850
851 Get a wide character. Like :meth:`getch`, but the integer returned is the
852 Unicode code point for the key pressed, so it can be passed to :func:`chr`.
853
854 .. versionadded:: 3.3
855 807
856 808
857 .. method:: window.getkey([y, x]) 809 .. method:: window.getkey([y, x])
858 810
859 Get a character, returning a string instead of an integer, as :meth:`getch` 811 Get a character, returning a string instead of an integer, as :meth:`getch`
860 does. Function keys, keypad keys and so on return a multibyte string containi ng 812 does. Function keys, keypad keys and so on return a multibyte string containi ng
861 the key name. In no-delay mode, an exception is raised if there is no input. 813 the key name. In no-delay mode, an exception is raised if there is no input.
862 814
863 815
864 .. method:: window.getmaxyx() 816 .. method:: window.getmaxyx()
865 817
866 Return a tuple ``(y, x)`` of the height and width of the window. 818 Return a tuple ``(y, x)`` of the height and width of the window.
867 819
868 820
869 .. method:: window.getparyx() 821 .. method:: window.getparyx()
870 822
871 Return the beginning coordinates of this window relative to its parent window 823 Returns the beginning coordinates of this window relative to its parent windo w
872 into two integer variables y and x. Return ``-1, -1`` if this window has no 824 into two integer variables y and x. Returns ``-1,-1`` if this window has no
873 parent. 825 parent.
874 826
875 827
876 .. method:: window.getstr([y, x]) 828 .. method:: window.getstr([y, x])
877 829
878 Read a string from the user, with primitive line editing capacity. 830 Read a string from the user, with primitive line editing capacity.
879 831
880 832
881 .. method:: window.getyx() 833 .. method:: window.getyx()
882 834
883 Return a tuple ``(y, x)`` of current cursor position relative to the window' s 835 Return a tuple ``(y, x)`` of current cursor position relative to the window' s
884 upper-left corner. 836 upper-left corner.
885 837
886 838
887 .. method:: window.hline([y, x,] ch, n) 839 .. method:: window.hline([y, x,] ch, n)
888 840
889 Display a horizontal line starting at ``(y, x)`` with length *n* consisting o f 841 Display a horizontal line starting at ``(y, x)`` with length *n* consisting o f
890 the character *ch*. 842 the character *ch*.
891 843
892 844
893 .. method:: window.idcok(flag) 845 .. method:: window.idcok(flag)
894 846
895 If *flag* is ``False``, curses no longer considers using the hardware insert/ delete 847 If *flag* is false, curses no longer considers using the hardware insert/dele te
896 character feature of the terminal; if *flag* is ``True``, use of character in sertion 848 character feature of the terminal; if *flag* is true, use of character insert ion
897 and deletion is enabled. When curses is first initialized, use of character 849 and deletion is enabled. When curses is first initialized, use of character
898 insert/delete is enabled by default. 850 insert/delete is enabled by default.
899 851
900 852
901 .. method:: window.idlok(yes) 853 .. method:: window.idlok(yes)
902 854
903 If called with *yes* equal to 1, :mod:`curses` will try and use hardware line 855 If called with *yes* equal to 1, :mod:`curses` will try and use hardware line
904 editing facilities. Otherwise, line insertion/deletion are disabled. 856 editing facilities. Otherwise, line insertion/deletion are disabled.
905 857
906 858
907 .. method:: window.immedok(flag) 859 .. method:: window.immedok(flag)
908 860
909 If *flag* is ``True``, any change in the window image automatically causes th e 861 If *flag* is true, any change in the window image automatically causes the
910 window to be refreshed; you no longer have to call :meth:`refresh` yourself. 862 window to be refreshed; you no longer have to call :meth:`refresh` yourself.
911 However, it may degrade performance considerably, due to repeated calls to 863 However, it may degrade performance considerably, due to repeated calls to
912 wrefresh. This option is disabled by default. 864 wrefresh. This option is disabled by default.
913 865
914 866
915 .. method:: window.inch([y, x]) 867 .. method:: window.inch([y, x])
916 868
917 Return the character at the given position in the window. The bottom 8 bits a re 869 Return the character at the given position in the window. The bottom 8 bits a re
918 the character proper, and upper bits are the attributes. 870 the character proper, and upper bits are the attributes.
919 871
920 872
921 .. method:: window.insch([y, x,] ch[, attr]) 873 .. method:: window.insch([y, x,] ch[, attr])
922 874
923 Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line fr om 875 Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line fr om
924 position *x* right by one character. 876 position *x* right by one character.
925 877
926 878
927 .. method:: window.insdelln(nlines) 879 .. method:: window.insdelln(nlines)
928 880
929 Insert *nlines* lines into the specified window above the current line. The 881 Inserts *nlines* lines into the specified window above the current line. The
930 *nlines* bottom lines are lost. For negative *nlines*, delete *nlines* lines 882 *nlines* bottom lines are lost. For negative *nlines*, delete *nlines* lines
931 starting with the one under the cursor, and move the remaining lines up. The 883 starting with the one under the cursor, and move the remaining lines up. The
932 bottom *nlines* lines are cleared. The current cursor position remains the 884 bottom *nlines* lines are cleared. The current cursor position remains the
933 same. 885 same.
934 886
935 887
936 .. method:: window.insertln() 888 .. method:: window.insertln()
937 889
938 Insert a blank line under the cursor. All following lines are moved down by o ne 890 Insert a blank line under the cursor. All following lines are moved down by 1
939 line. 891 line.
940 892
941 893
942 .. method:: window.insnstr([y, x,] str, n [, attr]) 894 .. method:: window.insnstr([y, x,] str, n [, attr])
943 895
944 Insert a character string (as many characters as will fit on the line) before 896 Insert a character string (as many characters as will fit on the line) before
945 the character under the cursor, up to *n* characters. If *n* is zero or 897 the character under the cursor, up to *n* characters. If *n* is zero or
946 negative, the entire string is inserted. All characters to the right of the 898 negative, the entire string is inserted. All characters to the right of the
947 cursor are shifted right, with the rightmost characters on the line being los t. 899 cursor are shifted right, with the rightmost characters on the line being los t.
948 The cursor position does not change (after moving to *y*, *x*, if specified). 900 The cursor position does not change (after moving to *y*, *x*, if specified).
949 901
950 902
951 .. method:: window.insstr([y, x, ] str [, attr]) 903 .. method:: window.insstr([y, x, ] str [, attr])
952 904
953 Insert a character string (as many characters as will fit on the line) before 905 Insert a character string (as many characters as will fit on the line) before
954 the character under the cursor. All characters to the right of the cursor ar e 906 the character under the cursor. All characters to the right of the cursor ar e
955 shifted right, with the rightmost characters on the line being lost. The cur sor 907 shifted right, with the rightmost characters on the line being lost. The cur sor
956 position does not change (after moving to *y*, *x*, if specified). 908 position does not change (after moving to *y*, *x*, if specified).
957 909
958 910
959 .. method:: window.instr([y, x] [, n]) 911 .. method:: window.instr([y, x] [, n])
960 912
961 Return a string of characters, extracted from the window starting at the 913 Returns a string of characters, extracted from the window starting at the
962 current cursor position, or at *y*, *x* if specified. Attributes are stripped 914 current cursor position, or at *y*, *x* if specified. Attributes are stripped
963 from the characters. If *n* is specified, :meth:`instr` returns a string 915 from the characters. If *n* is specified, :meth:`instr` returns return a str ing
964 at most *n* characters long (exclusive of the trailing NUL). 916 at most *n* characters long (exclusive of the trailing NUL).
965 917
966 918
967 .. method:: window.is_linetouched(line) 919 .. method:: window.is_linetouched(line)
968 920
969 Return ``True`` if the specified line was modified since the last call to 921 Returns true if the specified line was modified since the last call to
970 :meth:`refresh`; otherwise return ``False``. Raise a :exc:`curses.error` 922 :meth:`refresh`; otherwise returns false. Raises a :exc:`curses.error`
971 exception if *line* is not valid for the given window. 923 exception if *line* is not valid for the given window.
972 924
973 925
974 .. method:: window.is_wintouched() 926 .. method:: window.is_wintouched()
975 927
976 Return ``True`` if the specified window was modified since the last call to 928 Returns true if the specified window was modified since the last call to
977 :meth:`refresh`; otherwise return ``False``. 929 :meth:`refresh`; otherwise returns false.
978 930
979 931
980 .. method:: window.keypad(yes) 932 .. method:: window.keypad(yes)
981 933
982 If *yes* is 1, escape sequences generated by some keys (keypad, function key s) 934 If *yes* is 1, escape sequences generated by some keys (keypad, function key s)
983 will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be 935 will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be
984 left as is in the input stream. 936 left as is in the input stream.
985 937
986 938
987 .. method:: window.leaveok(yes) 939 .. method:: window.leaveok(yes)
988 940
989 If *yes* is 1, cursor is left where it is on update, instead of being at "cur sor 941 If *yes* is 1, cursor is left where it is on update, instead of being at "cur sor
990 position." This reduces cursor movement where possible. If possible the curs or 942 position." This reduces cursor movement where possible. If possible the curs or
991 will be made invisible. 943 will be made invisible.
992 944
993 If *yes* is 0, cursor will always be at "cursor position" after an update. 945 If *yes* is 0, cursor will always be at "cursor position" after an update.
994 946
995 947
996 .. method:: window.move(new_y, new_x) 948 .. method:: window.move(new_y, new_x)
997 949
998 Move cursor to ``(new_y, new_x)``. 950 Move cursor to ``(new_y, new_x)``.
999 951
1000 952
1001 .. method:: window.mvderwin(y, x) 953 .. method:: window.mvderwin(y, x)
1002 954
1003 Move the window inside its parent window. The screen-relative parameters of 955 Moves the window inside its parent window. The screen-relative parameters of
1004 the window are not changed. This routine is used to display different parts of 956 the window are not changed. This routine is used to display different parts of
1005 the parent window at the same physical position on the screen. 957 the parent window at the same physical position on the screen.
1006 958
1007 959
1008 .. method:: window.mvwin(new_y, new_x) 960 .. method:: window.mvwin(new_y, new_x)
1009 961
1010 Move the window so its upper-left corner is at ``(new_y, new_x)``. 962 Move the window so its upper-left corner is at ``(new_y, new_x)``.
1011 963
1012 964
1013 .. method:: window.nodelay(yes) 965 .. method:: window.nodelay(yes)
(...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after
1051 *destwin*. 1003 *destwin*.
1052 1004
1053 To get fine-grained control over the copied region, the second form of 1005 To get fine-grained control over the copied region, the second form of
1054 :meth:`overwrite` can be used. *sminrow* and *smincol* are the upper-left 1006 :meth:`overwrite` can be used. *sminrow* and *smincol* are the upper-left
1055 coordinates of the source window, the other variables mark a rectangle in the 1007 coordinates of the source window, the other variables mark a rectangle in the
1056 destination window. 1008 destination window.
1057 1009
1058 1010
1059 .. method:: window.putwin(file) 1011 .. method:: window.putwin(file)
1060 1012
1061 Write all data associated with the window into the provided file object. Thi s 1013 Writes all data associated with the window into the provided file object. Th is
1062 information can be later retrieved using the :func:`getwin` function. 1014 information can be later retrieved using the :func:`getwin` function.
1063 1015
1064 1016
1065 .. method:: window.redrawln(beg, num) 1017 .. method:: window.redrawln(beg, num)
1066 1018
1067 Indicate that the *num* screen lines, starting at line *beg*, are corrupted a nd 1019 Indicates that the *num* screen lines, starting at line *beg*, are corrupted and
1068 should be completely redrawn on the next :meth:`refresh` call. 1020 should be completely redrawn on the next :meth:`refresh` call.
1069 1021
1070 1022
1071 .. method:: window.redrawwin() 1023 .. method:: window.redrawwin()
1072 1024
1073 Touch the entire window, causing it to be completely redrawn on the next 1025 Touches the entire window, causing it to be completely redrawn on the next
1074 :meth:`refresh` call. 1026 :meth:`refresh` call.
1075 1027
1076 1028
1077 .. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol ]) 1029 .. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol ])
1078 1030
1079 Update the display immediately (sync actual screen with previous 1031 Update the display immediately (sync actual screen with previous
1080 drawing/deleting methods). 1032 drawing/deleting methods).
1081 1033
1082 The 6 optional arguments can only be specified when the window is a pad creat ed 1034 The 6 optional arguments can only be specified when the window is a pad creat ed
1083 with :func:`newpad`. The additional parameters are needed to indicate what p art 1035 with :func:`newpad`. The additional parameters are needed to indicate what p art
1084 of the pad and screen are involved. *pminrow* and *pmincol* specify the upper 1036 of the pad and screen are involved. *pminrow* and *pmincol* specify the upper
1085 left-hand corner of the rectangle to be displayed in the pad. *sminrow*, 1037 left-hand corner of the rectangle to be displayed in the pad. *sminrow*,
1086 *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be 1038 *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be
1087 displayed on the screen. The lower right-hand corner of the rectangle to be 1039 displayed on the screen. The lower right-hand corner of the rectangle to be
1088 displayed in the pad is calculated from the screen coordinates, since the 1040 displayed in the pad is calculated from the screen coordinates, since the
1089 rectangles must be the same size. Both rectangles must be entirely contained 1041 rectangles must be the same size. Both rectangles must be entirely contained
1090 within their respective structures. Negative values of *pminrow*, *pmincol*, 1042 within their respective structures. Negative values of *pminrow*, *pmincol*,
1091 *sminrow*, or *smincol* are treated as if they were zero. 1043 *sminrow*, or *smincol* are treated as if they were zero.
1092
1093
1094 .. method:: window.resize(nlines, ncols)
1095
1096 Reallocate storage for a curses window to adjust its dimensions to the
1097 specified values. If either dimension is larger than the current values, the
1098 window's data is filled with blanks that have the current background
1099 rendition (as set by :meth:`bkgdset`) merged into them.
1100 1044
1101 1045
1102 .. method:: window.scroll([lines=1]) 1046 .. method:: window.scroll([lines=1])
1103 1047
1104 Scroll the screen or scrolling region upward by *lines* lines. 1048 Scroll the screen or scrolling region upward by *lines* lines.
1105 1049
1106 1050
1107 .. method:: window.scrollok(flag) 1051 .. method:: window.scrollok(flag)
1108 1052
1109 Control what happens when the cursor of a window is moved off the edge of the 1053 Controls what happens when the cursor of a window is moved off the edge of th e
1110 window or scrolling region, either as a result of a newline action on the bot tom 1054 window or scrolling region, either as a result of a newline action on the bot tom
1111 line, or typing the last character of the last line. If *flag* is false, the 1055 line, or typing the last character of the last line. If *flag* is false, the
1112 cursor is left on the bottom line. If *flag* is true, the window is scrolled up 1056 cursor is left on the bottom line. If *flag* is true, the window is scrolled up
1113 one line. Note that in order to get the physical scrolling effect on the 1057 one line. Note that in order to get the physical scrolling effect on the
1114 terminal, it is also necessary to call :meth:`idlok`. 1058 terminal, it is also necessary to call :meth:`idlok`.
1115 1059
1116 1060
1117 .. method:: window.setscrreg(top, bottom) 1061 .. method:: window.setscrreg(top, bottom)
1118 1062
1119 Set the scrolling region from line *top* to line *bottom*. All scrolling acti ons 1063 Set the scrolling region from line *top* to line *bottom*. All scrolling acti ons
(...skipping 21 matching lines...) Expand all
1141 1085
1142 Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, an d 1086 Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, an d
1143 whose width/height is *ncols*/*nlines*. 1087 whose width/height is *ncols*/*nlines*.
1144 1088
1145 By default, the sub-window will extend from the specified position to the low er 1089 By default, the sub-window will extend from the specified position to the low er
1146 right corner of the window. 1090 right corner of the window.
1147 1091
1148 1092
1149 .. method:: window.syncdown() 1093 .. method:: window.syncdown()
1150 1094
1151 Touch each location in the window that has been touched in any of its ancesto r 1095 Touches each location in the window that has been touched in any of its ances tor
1152 windows. This routine is called by :meth:`refresh`, so it should almost neve r 1096 windows. This routine is called by :meth:`refresh`, so it should almost neve r
1153 be necessary to call it manually. 1097 be necessary to call it manually.
1154 1098
1155 1099
1156 .. method:: window.syncok(flag) 1100 .. method:: window.syncok(flag)
1157 1101
1158 If called with *flag* set to ``True``, then :meth:`syncup` is called automati cally 1102 If called with *flag* set to true, then :meth:`syncup` is called automaticall y
1159 whenever there is a change in the window. 1103 whenever there is a change in the window.
1160 1104
1161 1105
1162 .. method:: window.syncup() 1106 .. method:: window.syncup()
1163 1107
1164 Touch all locations in ancestors of the window that have been changed in the 1108 Touches all locations in ancestors of the window that have been changed in t he
1165 window. 1109 window.
1166 1110
1167 1111
1168 .. method:: window.timeout(delay) 1112 .. method:: window.timeout(delay)
1169 1113
1170 Set blocking or non-blocking read behavior for the window. If *delay* is 1114 Sets blocking or non-blocking read behavior for the window. If *delay* is
1171 negative, blocking read is used (which will wait indefinitely for input). If 1115 negative, blocking read is used (which will wait indefinitely for input). If
1172 *delay* is zero, then non-blocking read is used, and -1 will be returned by 1116 *delay* is zero, then non-blocking read is used, and -1 will be returned by
1173 :meth:`getch` if no input is waiting. If *delay* is positive, then 1117 :meth:`getch` if no input is waiting. If *delay* is positive, then
1174 :meth:`getch` will block for *delay* milliseconds, and return -1 if there is 1118 :meth:`getch` will block for *delay* milliseconds, and return -1 if there is
1175 still no input at the end of that time. 1119 still no input at the end of that time.
1176 1120
1177 1121
1178 .. method:: window.touchline(start, count[, changed]) 1122 .. method:: window.touchline(start, count[, changed])
1179 1123
1180 Pretend *count* lines have been changed, starting with line *start*. If 1124 Pretend *count* lines have been changed, starting with line *start*. If
1181 *changed* is supplied, it specifies whether the affected lines are marked as 1125 *changed* is supplied, it specifies whether the affected lines are marked as
1182 having been changed (*changed*\ =1) or unchanged (*changed*\ =0). 1126 having been changed (*changed*\ =1) or unchanged (*changed*\ =0).
1183 1127
1184 1128
1185 .. method:: window.touchwin() 1129 .. method:: window.touchwin()
1186 1130
1187 Pretend the whole window has been changed, for purposes of drawing 1131 Pretend the whole window has been changed, for purposes of drawing
1188 optimizations. 1132 optimizations.
1189 1133
1190 1134
1191 .. method:: window.untouchwin() 1135 .. method:: window.untouchwin()
1192 1136
1193 Mark all lines in the window as unchanged since the last call to 1137 Marks all lines in the window as unchanged since the last call to
1194 :meth:`refresh`. 1138 :meth:`refresh`.
1195 1139
1196 1140
1197 .. method:: window.vline([y, x,] ch, n) 1141 .. method:: window.vline([y, x,] ch, n)
1198 1142
1199 Display a vertical line starting at ``(y, x)`` with length *n* consisting of the 1143 Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
1200 character *ch*. 1144 character *ch*.
1201 1145
1202 1146
1203 Constants 1147 Constants
(...skipping 436 matching lines...) Expand 10 before | Expand all | Expand 10 after
1640 1584
1641 1585
1642 .. method:: edit([validator]) 1586 .. method:: edit([validator])
1643 1587
1644 This is the entry point you will normally use. It accepts editing 1588 This is the entry point you will normally use. It accepts editing
1645 keystrokes until one of the termination keystrokes is entered. If 1589 keystrokes until one of the termination keystrokes is entered. If
1646 *validator* is supplied, it must be a function. It will be called for 1590 *validator* is supplied, it must be a function. It will be called for
1647 each keystroke entered with the keystroke as a parameter; command dispatch 1591 each keystroke entered with the keystroke as a parameter; command dispatch
1648 is done on the result. This method returns the window contents as a 1592 is done on the result. This method returns the window contents as a
1649 string; whether blanks in the window are included is affected by the 1593 string; whether blanks in the window are included is affected by the
1650 :attr:`stripspaces` attribute. 1594 :attr:`stripspaces` member.
1651 1595
1652 1596
1653 .. method:: do_command(ch) 1597 .. method:: do_command(ch)
1654 1598
1655 Process a single command keystroke. Here are the supported special 1599 Process a single command keystroke. Here are the supported special
1656 keystrokes: 1600 keystrokes:
1657 1601
1658 +------------------+-------------------------------------------+ 1602 +------------------+-------------------------------------------+
1659 | Keystroke | Action | 1603 | Keystroke | Action |
1660 +==================+===========================================+ 1604 +==================+===========================================+
(...skipping 45 matching lines...) Expand 10 before | Expand all | Expand 10 after
1706 +------------------------+------------------+ 1650 +------------------------+------------------+
1707 | :const:`KEY_BACKSPACE` | :kbd:`Control-h` | 1651 | :const:`KEY_BACKSPACE` | :kbd:`Control-h` |
1708 +------------------------+------------------+ 1652 +------------------------+------------------+
1709 1653
1710 All other keystrokes are treated as a command to insert the given 1654 All other keystrokes are treated as a command to insert the given
1711 character and move right (with line wrapping). 1655 character and move right (with line wrapping).
1712 1656
1713 1657
1714 .. method:: gather() 1658 .. method:: gather()
1715 1659
1716 Return the window contents as a string; whether blanks in the 1660 This method returns the window contents as a string; whether blanks in the
1717 window are included is affected by the :attr:`stripspaces` member. 1661 window are included is affected by the :attr:`stripspaces` member.
1718 1662
1719 1663
1720 .. attribute:: stripspaces 1664 .. attribute:: stripspaces
1721 1665
1722 This attribute is a flag which controls the interpretation of blanks in 1666 This data member is a flag which controls the interpretation of blanks in
1723 the window. When it is on, trailing blanks on each line are ignored; any 1667 the window. When it is on, trailing blanks on each line are ignored; any
1724 cursor motion that would land the cursor on a trailing blank goes to the 1668 cursor motion that would land the cursor on a trailing blank goes to the
1725 end of that line instead, and trailing blanks are stripped when the window 1669 end of that line instead, and trailing blanks are stripped when the window
1726 contents are gathered. 1670 contents are gathered.
OLDNEW
« no previous file with comments | « Doc/library/collections.rst ('k') | Doc/library/datetime.rst » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+