diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/curses.rst | 174 |
1 files changed, 87 insertions, 87 deletions
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 73b957e..b88dc1a 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -72,7 +72,7 @@ The module :mod:`curses` defines the following functions: .. function:: baudrate() - Returns the output speed of the terminal in bits per second. On software + Return the output speed of the terminal in bits per second. On software terminal emulators it will have a fixed high value. Included for historical reasons; in former times, it was used to write output loops for time delays and occasionally to change interfaces depending on the line speed. @@ -85,7 +85,7 @@ The module :mod:`curses` defines the following functions: .. function:: can_change_color() - Returns true or false, depending on whether the programmer can change the colors + Return ``True`` or ``False``, depending on whether the programmer can change the colors displayed by the terminal. @@ -100,7 +100,7 @@ The module :mod:`curses` defines the following functions: .. function:: color_content(color_number) - Returns the intensity of the red, green, and blue (RGB) components in the color + Return the intensity of the red, green, and blue (RGB) components in the color *color_number*, which must be between ``0`` and :const:`COLORS`. A 3-tuple is returned, containing the R,G,B values for the given color, which will be between ``0`` (no component) and ``1000`` (maximum amount of component). @@ -108,7 +108,7 @@ The module :mod:`curses` defines the following functions: .. function:: color_pair(color_number) - Returns the attribute value for displaying text in the specified color. This + Return the attribute value for displaying text in the specified color. This attribute value can be combined with :const:`A_STANDOUT`, :const:`A_REVERSE`, and the other :const:`A_\*` attributes. :func:`pair_number` is the counterpart to this function. @@ -116,7 +116,7 @@ The module :mod:`curses` defines the following functions: .. function:: curs_set(visibility) - Sets the cursor state. *visibility* can be set to 0, 1, or 2, for invisible, + Set the cursor state. *visibility* can be set to 0, 1, or 2, for invisible, normal, or very visible. If the terminal supports the visibility requested, the previous cursor state is returned; otherwise, an exception is raised. On many terminals, the "visible" mode is an underline cursor and the "very visible" mode @@ -125,7 +125,7 @@ The module :mod:`curses` defines the following functions: .. function:: def_prog_mode() - Saves the current terminal mode as the "program" mode, the mode when the running + Save the current terminal mode as the "program" mode, the mode when the running program is using curses. (Its counterpart is the "shell" mode, for when the program is not in curses.) Subsequent calls to :func:`reset_prog_mode` will restore this mode. @@ -133,7 +133,7 @@ The module :mod:`curses` defines the following functions: .. function:: def_shell_mode() - Saves the current terminal mode as the "shell" mode, the mode when the running + Save the current terminal mode as the "shell" mode, the mode when the running program is not using curses. (Its counterpart is the "program" mode, when the program is using curses capabilities.) Subsequent calls to :func:`reset_shell_mode` will restore this mode. @@ -141,7 +141,7 @@ The module :mod:`curses` defines the following functions: .. function:: delay_output(ms) - Inserts an *ms* millisecond pause in output. + Insert an *ms* millisecond pause in output. .. function:: doupdate() @@ -172,7 +172,7 @@ The module :mod:`curses` defines the following functions: .. function:: erasechar() - Returns the user's current erase character. Under Unix operating systems this + Return the user's current erase character. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself. @@ -180,7 +180,7 @@ The module :mod:`curses` defines the following functions: .. function:: filter() The :func:`.filter` routine, if used, must be called before :func:`initscr` is - called. The effect is that, during those calls, LINES is set to 1; the + called. The effect is that, during those calls, :envvar:`LINES` is set to 1; the capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home string is set to the value of cr. The effect is that the cursor is confined to the current line, and so are screen updates. This may be used for enabling @@ -206,7 +206,7 @@ The module :mod:`curses` defines the following functions: method should be call to retrieve the queued mouse event, represented as a 5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish multiple devices, and *x*, *y*, *z* are the event's coordinates. (*z* is - currently unused.). *bstate* is an integer value whose bits will be set to + currently unused.) *bstate* is an integer value whose bits will be set to indicate the type of event, and will be the bitwise OR of one or more of the following constants, where *n* is the button number from 1 to 4: :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`, @@ -216,32 +216,32 @@ The module :mod:`curses` defines the following functions: .. function:: getsyx() - Returns the current coordinates of the virtual screen cursor in y and x. If + Return the current coordinates of the virtual screen cursor in y and x. If leaveok is currently true, then -1,-1 is returned. .. function:: getwin(file) - Reads window related data stored in the file by an earlier :func:`putwin` call. + Read window related data stored in the file by an earlier :func:`putwin` call. The routine then creates and initializes a new window using that data, returning the new window object. .. function:: has_colors() - Returns true if the terminal can display colors; otherwise, it returns false. + Return ``True`` if the terminal can display colors; otherwise, return ``False``. .. function:: has_ic() - Returns true if the terminal has insert- and delete- character capabilities. + Return ``True`` if the terminal has insert- and delete-character capabilities. This function is included for historical reasons only, as all modern software terminal emulators have such capabilities. .. function:: has_il() - Returns true if the terminal has insert- and delete-line capabilities, or can + Return ``True`` if the terminal has insert- and delete-line capabilities, or can simulate them using scrolling regions. This function is included for historical reasons only, as all modern software terminal emulators have such capabilities. @@ -249,7 +249,7 @@ The module :mod:`curses` defines the following functions: .. function:: has_key(ch) - Takes a key value *ch*, and returns true if the current terminal type recognizes + Take a key value *ch*, and return ``True`` if the current terminal type recognizes a key with that value. @@ -258,13 +258,13 @@ The module :mod:`curses` defines the following functions: Used for half-delay mode, which is similar to cbreak mode in that characters typed by the user are immediately available to the program. However, after blocking for *tenths* tenths of seconds, an exception is raised if nothing has - been typed. The value of *tenths* must be a number between 1 and 255. Use + been typed. The value of *tenths* must be a number between ``1`` and ``255``. Use :func:`nocbreak` to leave half-delay mode. .. function:: init_color(color_number, r, g, b) - Changes the definition of a color, taking the number of the color to be changed + Change the definition of a color, taking the number of the color to be changed followed by three RGB values (for the amounts of red, green, and blue components). The value of *color_number* must be between ``0`` and :const:`COLORS`. Each of *r*, *g*, *b*, must be a value between ``0`` and @@ -275,7 +275,7 @@ The module :mod:`curses` defines the following functions: .. function:: init_pair(pair_number, fg, bg) - Changes the definition of a color-pair. It takes three arguments: the number of + Change the definition of a color-pair. It takes three arguments: the number of the color-pair to be changed, the foreground color number, and the background color number. The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cannot @@ -287,7 +287,7 @@ The module :mod:`curses` defines the following functions: .. function:: initscr() - Initialize the library. Returns a :class:`WindowObject` which represents the + Initialize the library. Return a :class:`WindowObject` which represents the whole screen. .. note:: @@ -298,7 +298,7 @@ The module :mod:`curses` defines the following functions: .. function:: isendwin() - Returns true if :func:`endwin` has been called (that is, the curses library has + Return ``True`` if :func:`endwin` has been called (that is, the curses library has been deinitialized). @@ -314,14 +314,14 @@ The module :mod:`curses` defines the following functions: .. function:: killchar() - Returns the user's current line kill character. Under Unix operating systems + Return the user's current line kill character. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself. .. function:: longname() - Returns a string containing the terminfo long name field describing the current + Return a string containing the terminfo long name field describing the current terminal. The maximum length of a verbose description is 128 characters. It is defined only after the call to :func:`initscr`. @@ -334,14 +334,14 @@ The module :mod:`curses` defines the following functions: .. function:: mouseinterval(interval) - Sets the maximum time in milliseconds that can elapse between press and release - events in order for them to be recognized as a click, and returns the previous + Set the maximum time in milliseconds that can elapse between press and release + events in order for them to be recognized as a click, and return the previous interval value. The default value is 200 msec, or one fifth of a second. .. function:: mousemask(mousemask) - Sets the mouse events to be reported, and returns a tuple ``(availmask, + Set the mouse events to be reported, and return a tuple ``(availmask, oldmask)``. *availmask* indicates which of the specified mouse events can be reported; on complete failure it returns 0. *oldmask* is the previous value of the given window's mouse event mask. If this function is never called, no mouse @@ -355,7 +355,7 @@ The module :mod:`curses` defines the following functions: .. function:: newpad(nlines, ncols) - Creates and returns a pointer to a new pad data structure with the given number + Create and return a pointer to a new pad data structure with the given number of lines and columns. A pad is returned as a window object. A pad is like a window, except that it is not restricted by the screen size, and @@ -365,9 +365,9 @@ The module :mod:`curses` defines the following functions: echoing of input) do not occur. The :meth:`refresh` and :meth:`noutrefresh` methods of a pad require 6 arguments to specify the part of the pad to be displayed and the location on the screen to be used for the display. The - arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p + arguments are *pminrow*, *pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p* arguments refer to the upper left corner of the pad region to be displayed and - the s arguments define a clipping box on the screen within which the pad region + the *s* arguments define a clipping box on the screen within which the pad region is to be displayed. @@ -409,7 +409,7 @@ The module :mod:`curses` defines the following functions: .. function:: noqiflush() - When the noqiflush routine is used, normal flush of input and output queues + When the :func:`noqiflush` routine is used, normal flush of input and output queues associated with the INTR, QUIT and SUSP characters will not be done. You may want to call :func:`noqiflush` in a signal handler if you want output to continue as though the interrupt had not occurred, after the handler exits. @@ -422,27 +422,27 @@ The module :mod:`curses` defines the following functions: .. function:: pair_content(pair_number) - Returns a tuple ``(fg, bg)`` containing the colors for the requested color pair. + Return a tuple ``(fg, bg)`` containing the colors for the requested color pair. The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1``. .. function:: pair_number(attr) - Returns the number of the color-pair set by the attribute value *attr*. + Return the number of the color-pair set by the attribute value *attr*. :func:`color_pair` is the counterpart to this function. .. function:: putp(string) - Equivalent to ``tputs(str, 1, putchar)``; emits the value of a specified - terminfo capability for the current terminal. Note that the output of putp + Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified + terminfo capability for the current terminal. Note that the output of :func:`putp` always goes to standard output. .. function:: qiflush( [flag] ) - If *flag* is false, the effect is the same as calling :func:`noqiflush`. If - *flag* is true, or no argument is provided, the queues will be flushed when + If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If + *flag* is ``True``, or no argument is provided, the queues will be flushed when these control characters are read. @@ -455,26 +455,26 @@ The module :mod:`curses` defines the following functions: .. function:: reset_prog_mode() - Restores the terminal to "program" mode, as previously saved by + Restore the terminal to "program" mode, as previously saved by :func:`def_prog_mode`. .. function:: reset_shell_mode() - Restores the terminal to "shell" mode, as previously saved by + Restore the terminal to "shell" mode, as previously saved by :func:`def_shell_mode`. .. function:: setsyx(y, x) - Sets the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then + Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then leaveok is set. .. function:: setupterm([termstr, fd]) - Initializes the terminal. *termstr* is a string giving the terminal name; if - omitted, the value of the TERM environment variable will be used. *fd* is the + Initialize the terminal. *termstr* is a string giving the terminal name; if + omitted, the value of the :envvar:`TERM` environment variable will be used. *fd* is the file descriptor to which any initialization sequences will be sent; if not supplied, the file descriptor for ``sys.stdout`` will be used. @@ -494,19 +494,19 @@ The module :mod:`curses` defines the following functions: .. function:: termattrs() - Returns a logical OR of all video attributes supported by the terminal. This + Return a logical OR of all video attributes supported by the terminal. This information is useful when a curses program needs complete control over the appearance of the screen. .. function:: termname() - Returns the value of the environment variable TERM, truncated to 14 characters. + Return the value of the environment variable :envvar:`TERM`, truncated to 14 characters. .. function:: tigetflag(capname) - Returns the value of the Boolean capability corresponding to the terminfo + Return the value of the Boolean capability corresponding to the terminfo capability name *capname*. The value ``-1`` is returned if *capname* is not a Boolean capability, or ``0`` if it is canceled or absent from the terminal description. @@ -514,7 +514,7 @@ The module :mod:`curses` defines the following functions: .. function:: tigetnum(capname) - Returns the value of the numeric capability corresponding to the terminfo + Return the value of the numeric capability corresponding to the terminfo capability name *capname*. The value ``-2`` is returned if *capname* is not a numeric capability, or ``-1`` if it is canceled or absent from the terminal description. @@ -522,22 +522,22 @@ The module :mod:`curses` defines the following functions: .. function:: tigetstr(capname) - Returns the value of the string capability corresponding to the terminfo + Return the value of the string capability corresponding to the terminfo capability name *capname*. ``None`` is returned if *capname* is not a string capability, or is canceled or absent from the terminal description. .. function:: tparm(str[, ...]) - Instantiates the string *str* with the supplied parameters, where *str* should - be a parameterized string obtained from the terminfo database. E.g. - ``tparm(tigetstr("cup"), 5, 3)`` could result in ``'\033[6;4H'``, the exact + Instantiate the string *str* with the supplied parameters, where *str* should + be a parameterized string obtained from the terminfo database. E.g. + ``tparm(tigetstr("cup"), 5, 3)`` could result in x``'\033[6;4H'``, the exact result depending on terminal type. .. function:: typeahead(fd) - Specifies that the file descriptor *fd* be used for typeahead checking. If *fd* + Specify that the file descriptor *fd* be used for typeahead checking. If *fd* is ``-1``, then no typeahead checking is done. The curses library does "line-breakout optimization" by looking for typeahead @@ -549,7 +549,7 @@ The module :mod:`curses` defines the following functions: .. function:: unctrl(ch) - Returns a string which is a printable representation of the character *ch*. + Return a string which is a printable representation of the character *ch*. Control characters are displayed as a caret followed by the character, for example as ``^C``. Printing characters are left as they are. @@ -572,7 +572,7 @@ The module :mod:`curses` defines the following functions: .. function:: use_env(flag) If used, this function should be called before :func:`initscr` or newterm are - called. When *flag* is false, the values of lines and columns specified in the + called. When *flag* is ``False``, the values of lines and columns specified in the terminfo database will be used, even if environment variables :envvar:`LINES` and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a window (in which case default behavior would be to use the window size if @@ -656,7 +656,7 @@ the following methods: .. method:: window.bkgd(ch[, attr]) - Sets the background property of the window to the character *ch*, with + Set the background property of the window to the character *ch*, with attributes *attr*. The change is then applied to every character position in that window: @@ -669,7 +669,7 @@ the following methods: .. method:: window.bkgdset(ch[, attr]) - Sets the window's background. A window's background consists of a character and + Set the window's background. A window's background consists of a character and any combination of attributes. The attribute part of the background is combined (OR'ed) with all non-blank characters that are written into the window. Both the character and attribute parts of the background are combined with the blank @@ -714,12 +714,12 @@ the following methods: .. method:: window.box([vertch, horch]) Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and - bs are *horch*. The default corner characters are always used by this function. + *bs* are *horch*. The default corner characters are always used by this function. .. method:: window.chgat([y, x, ] [num,] attr) - Sets the attributes of *num* characters at the current cursor position, or at + Set the attributes of *num* characters at the current cursor position, or at position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1, the attribute will be set on all the characters to the end of the line. This function does not move the cursor. The changed line will be touched using the @@ -729,7 +729,7 @@ the following methods: .. method:: window.clear() - Like :meth:`erase`, but also causes the whole window to be repainted upon next + Like :meth:`erase`, but also cause the whole window to be repainted upon next call to :meth:`refresh`. @@ -752,7 +752,7 @@ the following methods: .. method:: window.cursyncup() - Updates the current cursor position of all the ancestors of the window to + Update the current cursor position of all the ancestors of the window to reflect the current cursor position of the window. @@ -763,14 +763,14 @@ the following methods: .. method:: window.deleteln() - Delete the line under the cursor. All following lines are moved up by 1 line. + Delete the line under the cursor. All following lines are moved up by one line. .. method:: window.derwin([nlines, ncols,] begin_y, begin_x) An abbreviation for "derive window", :meth:`derwin` is the same as calling :meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin - of the window, rather than relative to the entire screen. Returns a window + of the window, rather than relative to the entire screen. Return a window object for the derived window. @@ -782,8 +782,8 @@ the following methods: .. method:: window.enclose(y, x) - Tests whether the given pair of screen-relative character-cell coordinates are - enclosed by the given window, returning true or false. It is useful for + Test whether the given pair of screen-relative character-cell coordinates are + enclosed by the given window, returning ``True`` or ``False``. It is useful for determining what subset of the screen windows enclose the location of a mouse event. @@ -820,8 +820,8 @@ the following methods: .. method:: window.getparyx() - Returns the beginning coordinates of this window relative to its parent window - into two integer variables y and x. Returns ``-1,-1`` if this window has no + Return the beginning coordinates of this window relative to its parent window + into two integer variables y and x. Return ``-1, -1`` if this window has no parent. @@ -844,8 +844,8 @@ the following methods: .. method:: window.idcok(flag) - If *flag* is false, curses no longer considers using the hardware insert/delete - character feature of the terminal; if *flag* is true, use of character insertion + If *flag* is ``False``, curses no longer considers using the hardware insert/delete + character feature of the terminal; if *flag* is ``True``, use of character insertion and deletion is enabled. When curses is first initialized, use of character insert/delete is enabled by default. @@ -858,7 +858,7 @@ the following methods: .. method:: window.immedok(flag) - If *flag* is true, any change in the window image automatically causes the + If *flag* is ``True``, any change in the window image automatically causes the window to be refreshed; you no longer have to call :meth:`refresh` yourself. However, it may degrade performance considerably, due to repeated calls to wrefresh. This option is disabled by default. @@ -878,7 +878,7 @@ the following methods: .. method:: window.insdelln(nlines) - Inserts *nlines* lines into the specified window above the current line. The + Insert *nlines* lines into the specified window above the current line. The *nlines* bottom lines are lost. For negative *nlines*, delete *nlines* lines starting with the one under the cursor, and move the remaining lines up. The bottom *nlines* lines are cleared. The current cursor position remains the @@ -887,7 +887,7 @@ the following methods: .. method:: window.insertln() - Insert a blank line under the cursor. All following lines are moved down by 1 + Insert a blank line under the cursor. All following lines are moved down by one line. @@ -910,23 +910,23 @@ the following methods: .. method:: window.instr([y, x] [, n]) - Returns a string of characters, extracted from the window starting at the + Return a string of characters, extracted from the window starting at the current cursor position, or at *y*, *x* if specified. Attributes are stripped - from the characters. If *n* is specified, :meth:`instr` returns return a string + from the characters. If *n* is specified, :meth:`instr` returns a string at most *n* characters long (exclusive of the trailing NUL). .. method:: window.is_linetouched(line) - Returns true if the specified line was modified since the last call to - :meth:`refresh`; otherwise returns false. Raises a :exc:`curses.error` + Return ``True`` if the specified line was modified since the last call to + :meth:`refresh`; otherwise return ``False``. Raise a :exc:`curses.error` exception if *line* is not valid for the given window. .. method:: window.is_wintouched() - Returns true if the specified window was modified since the last call to - :meth:`refresh`; otherwise returns false. + Return ``True`` if the specified window was modified since the last call to + :meth:`refresh`; otherwise return ``False``. .. method:: window.keypad(yes) @@ -952,7 +952,7 @@ the following methods: .. method:: window.mvderwin(y, x) - Moves the window inside its parent window. The screen-relative parameters of + Move the window inside its parent window. The screen-relative parameters of the window are not changed. This routine is used to display different parts of the parent window at the same physical position on the screen. @@ -1010,19 +1010,19 @@ the following methods: .. method:: window.putwin(file) - Writes all data associated with the window into the provided file object. This + Write all data associated with the window into the provided file object. This information can be later retrieved using the :func:`getwin` function. .. method:: window.redrawln(beg, num) - Indicates that the *num* screen lines, starting at line *beg*, are corrupted and + Indicate that the *num* screen lines, starting at line *beg*, are corrupted and should be completely redrawn on the next :meth:`refresh` call. .. method:: window.redrawwin() - Touches the entire window, causing it to be completely redrawn on the next + Touch the entire window, causing it to be completely redrawn on the next :meth:`refresh` call. @@ -1050,7 +1050,7 @@ the following methods: .. method:: window.scrollok(flag) - Controls what happens when the cursor of a window is moved off the edge of the + Control what happens when the cursor of a window is moved off the edge of the window or scrolling region, either as a result of a newline action on the bottom line, or typing the last character of the last line. If *flag* is false, the cursor is left on the bottom line. If *flag* is true, the window is scrolled up @@ -1092,26 +1092,26 @@ the following methods: .. method:: window.syncdown() - Touches each location in the window that has been touched in any of its ancestor + Touch each location in the window that has been touched in any of its ancestor windows. This routine is called by :meth:`refresh`, so it should almost never be necessary to call it manually. .. method:: window.syncok(flag) - If called with *flag* set to true, then :meth:`syncup` is called automatically + If called with *flag* set to ``True``, then :meth:`syncup` is called automatically whenever there is a change in the window. .. method:: window.syncup() - Touches all locations in ancestors of the window that have been changed in the + Touch all locations in ancestors of the window that have been changed in the window. .. method:: window.timeout(delay) - Sets blocking or non-blocking read behavior for the window. If *delay* is + Set blocking or non-blocking read behavior for the window. If *delay* is negative, blocking read is used (which will wait indefinitely for input). If *delay* is zero, then non-blocking read is used, and -1 will be returned by :meth:`getch` if no input is waiting. If *delay* is positive, then @@ -1134,7 +1134,7 @@ the following methods: .. method:: window.untouchwin() - Marks all lines in the window as unchanged since the last call to + Mark all lines in the window as unchanged since the last call to :meth:`refresh`. @@ -1657,7 +1657,7 @@ You can instantiate a :class:`Textbox` object as follows: .. method:: gather() - This method returns the window contents as a string; whether blanks in the + Return the window contents as a string; whether blanks in the window are included is affected by the :attr:`stripspaces` member. |