From f1dc5fa2c8d97e3618a0a260e9f831e5e2fae554 Mon Sep 17 00:00:00 2001 From: "Andrew M. Kuchling" Date: Tue, 23 May 2000 16:46:04 +0000 Subject: Updated docs to list all the new methods and functions. The docs are now complete, but probably still not very helpful or friendly. Note: two very large tables (of key names, and of character names) were added; these tables format terribly, and need some reworking. --- Doc/lib/libcurses.tex | 945 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 757 insertions(+), 188 deletions(-) diff --git a/Doc/lib/libcurses.tex b/Doc/lib/libcurses.tex index a108002..e35c731 100644 --- a/Doc/lib/libcurses.tex +++ b/Doc/lib/libcurses.tex @@ -23,87 +23,219 @@ curses. \end{seealso} -\subsection{Constants and Functions \label{curses-functions}} +\subsection{Functions \label{curses-functions}} -The \module{curses} module defines the following data members: - -\begin{datadesc}{version} -A string representing the current version of the module. -\end{datadesc} +The module \module{curses} defines the following exception: +\begin{excdesc}{error} +Curses function returned an error status. +\end{excdesc} -\begin{datadesc}{A_NORMAL} -Normal attribute. -\end{datadesc} +\strong{Note:} Whenever \var{x} or \var{y} arguments to a function +or a method are optional, they default to the current cursor location. +Whenever \var{attr} is optional, it defaults to \constant{A_NORMAL}. -\begin{datadesc}{A_STANDOUT} -Standout mode. -\end{datadesc} +The module \module{curses} defines the following functions: -\begin{datadesc}{A_UNDERLINE} -Underline mode. -\end{datadesc} +\begin{funcdesc}{baudrate}{} +Returns the output speed of the terminal in bits per second. +\end{funcdesc} -\begin{datadesc}{A_BLINK} -Blink mode. -\end{datadesc} +\begin{funcdesc}{beep}{} +Emit a short sound. +\end{funcdesc} -\begin{datadesc}{A_DIM} -Dim mode. -\end{datadesc} +\begin{funcdesc}{can_change_color}{} +Returns true or false, depending on whether the programmer can change +the colors displayed by the terminal. +\end{funcdesc} -\begin{datadesc}{A_BOLD} -Bold mode. -\end{datadesc} +\begin{funcdesc}{cbreak}{} +Enter cbreak mode. +\end{funcdesc} -\begin{datadesc}{A_ALTCHARSET} -Alternate character set mode. -\end{datadesc} +\begin{funcdesc}{color_content}{color_number} +Returns the intensity of the red, green, and blue (RGB) components in +the color \var{color_number}, which must be between 0 and 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). +\end{funcdesc} -\begin{datadesc}{KEY_*} -Names for various keys. The exact names available are system dependant. -\end{datadesc} +\begin{funcdesc}{color_pair}{color_number} +Returns the attribute value for displaying text in the specified +color. This attribute value can be combined with +\constant{A_STANDOUT}, \constant{A_REVERSE}, and the other +\constant{A_*} attributes. \function{pair_number()} is the counterpart to this function. +\end{funcdesc} -\begin{datadesc}{ACS_*} -Names for various characters: -\constant{ACS_ULCORNER}, \constant{ACS_LLCORNER}, -\constant{ACS_URCORNER}, \constant{ACS_LRCORNER}, \constant{ACS_RTEE}, -\constant{ACS_LTEE}, \constant{ACS_BTEE}, \constant{ACS_TTEE}, -\constant{ACS_HLINE}, \constant{ACS_VLINE}, \constant{ACS_PLUS}, -\constant{ACS_S1}, \constant{ACS_S9}, \constant{ACS_DIAMOND}, -\constant{ACS_CKBOARD}, \constant{ACS_DEGREE}, \constant{ACS_PLMINUS}, -\constant{ACS_BULLET}, \constant{ACS_LARROW}, \constant{ACS_RARROW}, -\constant{ACS_DARROW}. +\begin{funcdesc}{curs_set}{visibility} +Sets the cursor state. \var{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. +\end{funcdesc} -\strong{Note:} These are available only after \function{initscr()} has -been called. -\end{datadesc} +\begin{funcdesc}{def_prog_mode}{} +Saves 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 \function{reset_prog_mode()} will restore this mode. +\end{funcdesc} -The module \module{curses} defines the following exception: -\begin{excdesc}{error} -Curses function returned an error status. -\end{excdesc} +\begin{funcdesc}{def_shell_mode}{} +Saves 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 \function{reset_shell_mode()} will restore this mode. +\end{funcdesc} -\strong{Note:} Whenever \var{x} or \var{y} arguments to a function -or a method are optional, they default to the current cursor location. -Whenever \var{attr} is optional, it defaults to \constant{A_NORMAL}. +\begin{funcdesc}{delay_output}{ms} +Inserts an \var{ms} millisecond pause in output. +\end{funcdesc} -The module \module{curses} defines the following functions: +\begin{funcdesc}{doupdate}{} +Update the screen. +\end{funcdesc} -\begin{funcdesc}{initscr}{} -Initialize the library. Returns a \class{WindowObject} which represents -the whole screen. +\begin{funcdesc}{echo}{} +Enter echo mode. \end{funcdesc} \begin{funcdesc}{endwin}{} De-initialize the library, and return terminal to normal status. \end{funcdesc} +\begin{funcdesc}{erasechar}{} +Returns the user's current erase character. +\end{funcdesc} + +\begin{funcdesc}{filter}{} +The \function{filter()} routine, if used, must be called before +\function{initscr()} is called. + +The effect is that, during those calls, 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. +\end{funcdesc} + +\begin{funcdesc}{flash}{} +Flash the screen. +\end{funcdesc} + +\begin{funcdesc}{flushinp}{} +Flush all input buffers. +\end{funcdesc} + +\begin{funcdesc}{getsyx}{} +Returns the current coordinates of the virtual screen cursor in y and +x. If leaveok is currently true, then -1,-1 is returned. +\end{funcdesc} + +\begin{funcdesc}{getwin}{file} +Reads window related data stored in the file by an earlier +\function{putwin()} call. The routine then creates and initializes a +new window using that data, returning the new window object. +\end{funcdesc} + +\begin{funcdesc}{has_colors}{} +Returns true if the terminal can manipulate colors; otherwise, it +returns false. +\end{funcdesc} + +\begin{funcdesc}{has_ic}{} +Returns true if the terminal has insert- and delete- character +capabilities. +\end{funcdesc} + +\begin{funcdesc}{has_il}{} +Returns true if the terminal has insert- and +delete-line capabilities, or can simulate them using +scrolling regions. +\end{funcdesc} + +\begin{funcdesc}{has_key}{ch} +Takes a key value \var{ch}, and returns true if the current terminal +type recognizes a key with that value. +\end{funcdesc} + +\begin{funcdesc}{halfdelay}{tenths} +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 \var{tenths} tenths of seconds, an +exception is raised if nothing has been typed. The value of +\var{tenths} must be a number between 1 and 255. Use nocbreak to +leave half-delay mode. +\end{funcdesc} + +\begin{funcdesc}{init_color}{color_number, r, g, b} +Changes 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 \var{color_number} must be +between 0 and COLORS. Each of \var{r}, \var{g}, \var{b}, must be a +value between 0 and 1000. When \function{init_color()} is used, all +occurrences of that color on the screen immediately change to the new +definition. +\end{funcdesc} + +\begin{funcdesc}{init_pair}{pair_number, fg, bg} +Changes 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 \var{pair_number} must +be between 1 and COLOR_PAIRS-1 (the 0 color pair is wired to white on +black and cannot be changed). The value of \var{fg} and \var{bg} +arguments must be between 0 and COLORS. If the color-pair was +previously initialized, the screen is refreshed and all occurrences of +that color-pair are changed to the new definition. +\end{funcdesc} + +\begin{funcdesc}{initscr}{} +Initialize the library. Returns a \class{WindowObject} which represents +the whole screen. +\end{funcdesc} + \begin{funcdesc}{isendwin}{} Returns true if \function{endwin()} has been called. \end{funcdesc} -\begin{funcdesc}{doupdate}{} -Update the screen. +\begin{funcdesc}{keyname}{k} +Return the name of the key numbered \var{k}. +\end{funcdesc} + +\begin{funcdesc}{killchar}{} +Returns the user's current line kill character. +\end{funcdesc} + +\begin{funcdesc}{longname}{} +Returns a string containing a verbose description of the current +terminal. The maximum length of a verbose description is 128 +characters. It is defined only after the call to +\function{initscr()}. +\end{funcdesc} + +\begin{funcdesc}{meta}{yes} +If \var{yes} is 1, allow 8-bit characters. If \var{yes} is 0, +allow only 7-bit chars. +\end{funcdesc} + +\begin{funcdesc}{newpad}{nlines, ncols} +Creates and returns 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 is not +necessarily associated with a particular part of the screen. +Pads can be used when a large window is needed, and only a part +of the window will be on the screen at one time. Automatic +refreshes of pads (e.g., from scrolling or echoing of + input) do not occur. It is not legal to call wrefresh + with a pad as an argument; the routines prefresh or + pnoutrefresh should be called instead. Note that these + routines require additional parameters to specify the part of + the pad to be displayed and the location on the screen to be + used for the display. + \end{funcdesc} \begin{funcdesc}{newwin}{\optional{nlines, ncols,} begin_y, begin_x} @@ -115,98 +247,129 @@ By default, the window will extend from the specified position to the lower right corner of the screen. \end{funcdesc} -\begin{funcdesc}{beep}{} -Emit a short sound. +\begin{funcdesc}{nl}{} +Enter nl mode. \end{funcdesc} -\begin{funcdesc}{flash}{} -Flash the screen. +\begin{funcdesc}{nocbreak}{} +Leave cbreak mode. \end{funcdesc} -\begin{funcdesc}{ungetch}{ch} -Push \var{ch} so the next \method{getch()} will return it; \var{ch} is -an integer specifying the character to be pushed. -\strong{Note:} only one \var{ch} can be pushed before \method{getch()} -is called. +\begin{funcdesc}{noecho}{} +Leave echo mode. \end{funcdesc} -\begin{funcdesc}{flushinp}{} -Flush all input buffers. +\begin{funcdesc}{nonl}{} +Leave nl mode. \end{funcdesc} -\begin{funcdesc}{cbreak}{} -Enter cbreak mode. +\begin{funcdesc}{noqiflush}{} + When the 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 + \function{noqiflush()} in a signal handler if you want output + to continue as though the interrupt had not occurred, after the + handler exits. \end{funcdesc} -\begin{funcdesc}{nocbreak}{} -Leave cbreak mode. +\begin{funcdesc}{noraw}{} +Leave raw mode. \end{funcdesc} -\begin{funcdesc}{echo}{} -Enter echo mode. +\begin{funcdesc}{pair_content}{pair_number} +Returns a tuple \var{(fg,bg)} containing the colors for the requested +color pair. The value of \var{pair_number} must be between 0 and +COLOR_PAIRS-1. \end{funcdesc} -\begin{funcdesc}{noecho}{} -Leave echo mode. +\begin{funcdesc}{pair_number}{attr} +Returns the number of the color-pair set by the attribute value \var{attr}. +\function{color_pair()} is the counterpart to this function. \end{funcdesc} -\begin{funcdesc}{nl}{} -Enter nl mode. +\begin{funcdesc}{putp}{string} +Equivalent to \code{tputs(str, 1, putchar)}. Note that the output of putp always +goes to standard output. \end{funcdesc} -\begin{funcdesc}{nonl}{} -Leave nl mode. +\begin{funcdesc}{qiflush}{ \optional{flag} } +If \var{flag} is false, the effect is the same as calling +\function{noqiflush()}. If \var{flag} is true, or no argument is +provided, the queues will be flushed when these control characters are +read. \end{funcdesc} \begin{funcdesc}{raw}{} Enter raw mode. \end{funcdesc} -\begin{funcdesc}{noraw}{} -Leave raw mode. +\begin{funcdesc}{reset_prog_mode}{} +Restores the terminal to ``program'' mode, as previously saved +by \function{def_prog_mode()}. \end{funcdesc} -\begin{funcdesc}{meta}{yes} -If \var{yes} is 1, allow 8-bit characters. If \var{yes} is 0, -allow only 7-bit chars. +\begin{funcdesc}{reset_shell_mode}{} +Restores the terminal to ``shell'' mode, as previously saved +by \function{def_shell_mode()}. \end{funcdesc} -\begin{funcdesc}{keyname}{k} -Return the name of the key numbered \var{k}. +\begin{funcdesc}{setsyx}{y, x} +Sets the virtual screen cursor to \var{y}, \var{x}. +If \var{y} and \var{x} are both -1, then leaveok is set. \end{funcdesc} +\begin{funcdesc}{start_color}{} +Must be called if the programmer wants to use colors, and before any +other color manipulation routine is called. It is good +practice to call this routine right after \function{initscr()}. + +\function{start_color()} initializes eight basic colors (black, red, +green, yellow, blue, magenta, cyan, and white), and two global +variables in the \module{curses} module, COLORS and COLOR_PAIRS, +containing the maximum number of colors and color-pairs the terminal +can support. It also restores the colors on the terminal to the +values they had when the terminal was just turned on. +\end{funcdesc} -\subsection{Window Objects \label{curses-window-objects}} - -Window objects, as returned by \function{initscr()} and -\function{newwin()} above, have the -following methods: +\begin{funcdesc}{termattrs}{} +Returns 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. +\end{funcdesc} -\begin{methoddesc}{refresh}{} -Update the display immediately (sync actual screen with previous -drawing/deleting methods). -\end{methoddesc} +\begin{funcdesc}{termname}{} +Returns the value of the environment variable TERM, truncated to 14 +characters. +\end{funcdesc} -\begin{methoddesc}{nooutrefresh}{} -Mark for refresh but wait. -\end{methoddesc} +\begin{funcdesc}{unctrl}{ch} +Returns a string which is a printable representation of the character +\var{ch}. Control characters are displayed as a caret followed by the +character, for example as \verb|^C|. Printing characters are left as they +are. +\end{funcdesc} -\begin{methoddesc}{mvwin}{new_y, new_x} -Move the window so its upper-left corner is at \code{(\var{new_y}, \var{new_x})}. -\end{methoddesc} +\begin{funcdesc}{ungetch}{ch} +Push \var{ch} so the next \method{getch()} will return it. +\strong{Note:} only one \var{ch} can be pushed before \method{getch()} +is called. +\end{funcdesc} -\begin{methoddesc}{move}{new_y, new_x} -Move cursor to \code{(\var{new_y}, \var{new_x})}. -\end{methoddesc} +\begin{funcdesc}{use_env}{flag} +If used, this function should be called before \function{initscr} or +newterm are called. When \var{flag} is false, the values of +lines and columns specified in the terminfo database will be +used, even if environment variables LINES and 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 LINES +and COLUMNS are not set). +\end{funcdesc} -\begin{methoddesc}{subwin}{\optional{nlines, ncols,} begin_y, begin_y} -Return a sub-window, whose upper-left corner is at -\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is -\var{ncols}/\var{nlines}. +\subsection{Window Objects \label{curses-window-objects}} -By default, the sub-window will extend from the -specified position to the lower right corner of the window. -\end{methoddesc} +Window objects, as returned by \function{initscr()} and +\function{newwin()} above, have the +following methods: \begin{methoddesc}{addch}{\optional{y, x,} ch\optional{, attr}} \strong{Note:} A \emph{character} means a C character (i.e., an @@ -219,44 +382,52 @@ location. By default, the character position and attributes are the current settings for the window object. \end{methoddesc} -\begin{methoddesc}{insch}{\optional{y, x,} ch\optional{, attr}} -Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes -\var{attr}, moving the line from position \var{x} right by one -character. -\end{methoddesc} - -\begin{methoddesc}{delch}{\optional{x, y}} -Delete any character at \code{(\var{y}, \var{x})}. -\end{methoddesc} - -\begin{methoddesc}{echochar}{ch\optional{, attr}} -Add character \var{ch} with attribute \var{attr}, and immediately -call \method{refresh}. +\begin{methoddesc}{addnstr}{\optional{y, x,} str, n\optional{, attr}} +Paint at most \var{n} characters of the +string \var{str} at \code{(\var{y}, \var{x})} with attributes +\var{attr}, overwriting anything previously on the display. \end{methoddesc} \begin{methoddesc}{addstr}{\optional{y, x,} str\optional{, attr}} -Paint string \var{str} at \code{(\var{y}, \var{x})} with attributes +Paint the string \var{str} at \code{(\var{y}, \var{x})} with attributes \var{attr}, overwriting anything previously on the display. \end{methoddesc} +\begin{methoddesc}{attroff}{attr} +Turn off attribute \var{attr}. +\end{methoddesc} + \begin{methoddesc}{attron}{attr} Turn on attribute \var{attr}. \end{methoddesc} -\begin{methoddesc}{attroff}{attr} -Turn off attribute \var{attr}. +\begin{methoddesc}{attrset}{attr} +Set the attributes to \var{attr}. \end{methoddesc} -\begin{methoddesc}{setattr}{attr} -Set the current attributes to \var{attr}. -\end{methoddesc} +\begin{methoddesc}{bkgd}{ch\optional{, attr}} +Sets the background property of the window to the character \var{ch}, +with attributes \var{attr}. The change is then applied to every +character position in that window: +\begin{itemize} +\item The attribute of every character in the window is + changed to the new background attribute. + +\item Wherever the former background character appears, +it is changed to the new background character. +\end{itemize} -\begin{methoddesc}{standend}{} -Turn off all attributes. \end{methoddesc} -\begin{methoddesc}{standout}{} -Turn on attribute \var{A_STANDOUT}. +\begin{methoddesc}{bkgdset}{ch\optional{, attr}} +Sets 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 characters. The +background becomes a property of the character and moves with the +character through any scrolling and insert/delete line/character +operations. \end{methoddesc} \begin{methoddesc}{border}{\optional{ls\optional{, rs\optional{, ts\optional{, @@ -290,32 +461,54 @@ Similar to \method{border()}, but both \var{ls} and \var{rs} are corner characters are always used by this function. \end{methoddesc} -\begin{methoddesc}{hline}{\optional{y, x,} ch, n} -Display a horizontal line starting at \code{(\var{y}, \var{x})} with -length \var{n} consisting of the character \var{ch}. +\begin{methoddesc}{clear}{} +Like \method{erase()}, but also causes the whole screen to be repainted +upon next call to \method{refresh()}. \end{methoddesc} -\begin{methoddesc}{vline}{\optional{y, x,} ch, n} -Display a vertical line starting at \code{(\var{y}, \var{x})} with -length \var{n} consisting of the character \var{ch}. +\begin{methoddesc}{clearok}{yes} +If \var{yes} is 1, the next call to \method{refresh()} +will clear the screen completely. \end{methoddesc} -\begin{methoddesc}{erase}{} -Clear the screen. +\begin{methoddesc}{clrtobot}{} +Erase from cursor to the end of the screen: all lines below the cursor +are deleted, and then the equivalent of \method{clrtoeol()} is performed. \end{methoddesc} -\begin{methoddesc}{deletln}{} +\begin{methoddesc}{clrtoeol}{} +Erase from cursor to the end of the line. +\end{methoddesc} + +\begin{methoddesc}{cursyncup}{} +Updates the current cursor position of all the ancestors of the window +to reflect the current cursor position of the window. +\end{methoddesc} + +\begin{methoddesc}{delch}{\optional{x, y}} +Delete any character at \code{(\var{y}, \var{x})}. +\end{methoddesc} + +\begin{methoddesc}{deleteln}{} Delete the line under the cursor. All following lines are moved up by 1 line. \end{methoddesc} -\begin{methoddesc}{insertln}{} -Insert a blank line under the cursor. All following lines are moved -down by 1 line. +\begin{methoddesc}{derwin}{\optional{nlines, ncols,} begin_y, begin_y} +An abbreviation for ``derive window'', \method{derwin()} is the same +as calling \method{subwin()}, except that \var{begin_y} and +\var{begin_x} are relative to the origin of the window, rather than +relative to the entire screen. Returns a window object for the +derived window. \end{methoddesc} -\begin{methoddesc}{getyx}{} -Return a tuple \code{(\var{y}, \var{x})} of current cursor position. +\begin{methoddesc}{echochar}{ch\optional{, attr}} +Add character \var{ch} with attribute \var{attr}, and immediately +call \method{refresh}. +\end{methoddesc} + +\begin{methoddesc}{erase}{} +Clear the window. \end{methoddesc} \begin{methoddesc}{getbegyx}{} @@ -323,48 +516,64 @@ Return a tuple \code{(\var{y}, \var{x})} of co-ordinates of upper-left corner. \end{methoddesc} +\begin{methoddesc}{getch}{\optional{x, y}} +Get a character. Note that the integer returned does \emph{not} have to +be in \ASCII{} range: function keys, keypad keys and so on return numbers +higher then 256. In no-delay mode, an exception is raised if there is +no input. +\end{methoddesc} + +\begin{methoddesc}{getkey}{\optional{x, y}} +Get a character, returning a string instead of an integer, as +\method{getch()} does. Function keys, keypad keys and so on return a +multibyte string containing the key name. In no-delay mode, an +exception is raised if there is no input. +\end{methoddesc} + \begin{methoddesc}{getmaxyx}{} Return a tuple \code{(\var{y}, \var{x})} of the height and width of the window. \end{methoddesc} -\begin{methoddesc}{clear}{} -Like \method{erase()}, but also causes the whole screen to be repainted -upon next call to \method{refresh()}. +\begin{methoddesc}{getparyx}{} +Returns the beginning coordinates of this window relative to its +parent window into two integer variables y and x. Returns +\code{-1,-1} if this window has no parent. \end{methoddesc} -\begin{methoddesc}{clrtobot}{} -Erase from cursor to the end of the screen: all lines below the cursor -are deleted, and then the equivalent of \method{clrtoeol()} is performed. -\end{methoddesc} - -\begin{methoddesc}{clrtoeol}{} -Erase from cursor to the end of the line. +\begin{methoddesc}{getstr}{\optional{x, y}} +Read a string from the user, with primitive line editing capacity. \end{methoddesc} -\begin{methoddesc}{scroll}{\optional{lines\code{ = 1}}} -Scroll the screen upward by \var{lines} lines. +\begin{methoddesc}{getyx}{} +Return a tuple \code{(\var{y}, \var{x})} of current cursor position. \end{methoddesc} -\begin{methoddesc}{touchwin}{} -Pretend the whole window has been changed, for purposes of drawing -optimizations. +\begin{methoddesc}{hline}{\optional{y, x,} ch, n} +Display a horizontal line starting at \code{(\var{y}, \var{x})} with +length \var{n} consisting of the character \var{ch}. \end{methoddesc} -\begin{methoddesc}{touchline}{start, count} -Pretend \var{count} lines have been changed, starting with line -\var{start}. +\begin{methoddesc}{idcok}{flag} +If \var{flag} is false, curses no longer considers using the hardware +insert/delete character feature of the terminal; if \var{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. \end{methoddesc} -\begin{methoddesc}{getch}{\optional{x, y}} -Get a character. Note that the integer returned does \emph{not} have to -be in \ASCII{} range: function keys, keypad keys and so on return numbers -higher then 256. In no-delay mode, an exception is raised if there is -no input. +\begin{methoddesc}{idlok}{yes} +If called with \var{yes} equal to 1, \module{curses} will try and use +hardware line editing facilities. Otherwise, line insertion/deletion +are disabled. \end{methoddesc} -\begin{methoddesc}{getstr}{\optional{x, y}} -Read a string from the user, with primitive line editing capacity. +\begin{methoddesc}{immedok}{flag} +If \var{flag} is true, any change in the window image +automatically causes the window to be refreshed; you no longer +have to call \method{refresh()} yourself. However, it may +degrade performance considerably, due to repeated calls to +wrefresh. This option is disabled by default. \end{methoddesc} \begin{methoddesc}{inch}{\optional{x, y}} @@ -372,15 +581,69 @@ Return the character at the given position in the window. The bottom 8 bits are the character proper, and upper bits are the attributes. \end{methoddesc} -\begin{methoddesc}{clearok}{yes} -If \var{yes} is 1, the next call to \method{refresh()} -will clear the screen completely. +\begin{methoddesc}{insch}{\optional{y, x,} ch\optional{, attr}} +Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes +\var{attr}, moving the line from position \var{x} right by one +character. \end{methoddesc} -\begin{methoddesc}{idlok}{yes} -If called with \var{yes} equal to 1, \module{curses} will try and use -hardware line editing facilities. Otherwise, line insertion/deletion -are disabled. +\begin{methoddesc}{insdelln}{nlines} +Inserts \var{nlines} lines into the specified window above the current +line. The \var{nlines} bottom lines are lost. For negative +\var{nlines}, delete \var{nlines} lines starting with the one under +the cursor, and move the remaining lines up. The bottom \var{nlines} +lines are cleared. The current cursor position remains the same. +\end{methoddesc} + +\begin{methoddesc}{insertln}{} +Insert a blank line under the cursor. All following lines are moved +down by 1 line. +\end{methoddesc} + +\begin{methoddesc}{insnstr}{\optional{y, x, } str, n \optional{, attr}} +Insert a character string (as many characters as will fit on the line) +before the character under the cursor, up to \var{n} characters. +If \var{n} is zero or negative, +the entire string is inserted. +All characters to the right of +the cursor are shifted right, with the the rightmost characters on the +line being lost. The cursor position does not change (after moving to +\var{y}, \var{x}, if specified). +\end{methoddesc} + +\begin{methoddesc}{insstr}{\optional{y, x, } str \optional{, attr}} +Insert a character string (as many characters as will fit on the line) +before the character under the cursor. All characters to the right of +the cursor are shifted right, with the the rightmost characters on the +line being lost. The cursor position does not change (after moving to +\var{y}, \var{x}, if specified). +\end{methoddesc} + +\begin{methoddesc}{instr}{\optional{y, x} \optional{, n}} +Returns a string of characters, extracted from the window starting at +the current cursor position, or at \var{y}, \var{x} if specified. +Attributes are stripped from the characters. If \var{n} is specified, +\method{instr()} returns return a string at most \var{n} characters +long (exclusive of the trailing NUL). +\end{methoddesc} + +\begin{methoddesc}{is_linetouched}{\var{line}} +Returns true if the specified line was modified since the last call to +\method{refresh()}; otherwise returns false. Raises a +\exception{curses.error} exception if \var{line} is not valid +for the given window. +\end{methoddesc} + +\begin{methoddesc}{is_wintouched}{} +Returns true if the specified window was modified since the last call to +\method{refresh()}; otherwise returns false. +\end{methoddesc} + +\begin{methoddesc}{keypad}{yes} +If \var{yes} is 1, escape sequences generated by some keys (keypad, +function keys) will be interpreted by \module{curses}. +If \var{yes} is 0, escape sequences will be left as is in the input +stream. \end{methoddesc} \begin{methoddesc}{leaveok}{yes} @@ -393,17 +656,19 @@ If \var{yes} is 0, cursor will always be at ``cursor position'' after an update. \end{methoddesc} -\begin{methoddesc}{setscrreg}{top, bottom} -Set the scrolling region from line \var{top} to line \var{bottom}. All -scrolling actions will take place in this region. +\begin{methoddesc}{move}{new_y, new_x} +Move cursor to \code{(\var{new_y}, \var{new_x})}. \end{methoddesc} -\begin{methoddesc}{keypad}{yes} -If \var{yes} is 1, escape sequences generated by some keys (keypad, -function keys) will be interpreted by \module{curses}. +\begin{methoddesc}{mvderwin}{y, x} +Moves 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. +\end{methoddesc} -If \var{yes} is 0, escape sequences will be left as is in the input -stream. +\begin{methoddesc}{mvwin}{new_y, new_x} +Move the window so its upper-left corner is at \code{(\var{new_y}, \var{new_x})}. \end{methoddesc} \begin{methoddesc}{nodelay}{yes} @@ -416,3 +681,307 @@ If \var{yes} is 1, escape sequences will not be timed out. If \var{yes} is 0, after a few milliseconds, an escape sequence will not be interpreted, and will be left in the input stream as is. \end{methoddesc} + +\begin{methoddesc}{noutrefresh}{} +Mark for refresh but wait. +\end{methoddesc} + +\begin{methoddesc}{putwin}{file} +Writes all data associated with the window into the provided file +object. This information can be later retrieved using the +\function{getwin()} function. + +\end{methoddesc} + +\begin{methoddesc}{redrawln}{beg, num} +Indicates that the \var{num} screen lines, starting at line \var{beg}, +are corrupted and should be completely redrawn on the next +\method{refresh()} call. +\end{methoddesc} + +\begin{methoddesc}{redrawwin}{} +Touches the entire window, causing it to be completely redrawn on the +next \method{refresh()} call. +\end{methoddesc} + +\begin{methoddesc}{refresh}{ \optional{pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol} } +Update the display immediately (sync actual screen with previous +drawing/deleting methods). + +The 6 optional arguments can only be specified when the window is a +pad created with \function{newpad()}. The additional parameters are +needed to indicate what part of the pad and screen are involved. +\var{pminrow} and \var{pmincol} specify the upper left-hand corner of the +rectangle to be displayed in the pad. \var{sminrow}, \var{smincol}, +\var{smaxrow}, and \var{smaxcol} specify the edges of the rectangle to be displayed on the screen. The lower right-hand corner of the +rectangle to be displayed in the pad is calculated from the screen +coordinates, since the rectangles must be the same size. Both +rectangles must be entirely contained within their respective +structures. Negative values of \var{pminrow}, \var{pmincol}, +\var{sminrow}, or \var{smincol} are treated as if they were zero. +\end{methoddesc} + +\begin{methoddesc}{scroll}{\optional{lines\code{ = 1}}} +Scroll the screen upward by \var{lines} lines. +\end{methoddesc} + +\begin{methoddesc}{scrollok}{flag} +Controls 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 \var{flag} is false, the cursor is left + on the bottom line. If \var{flag} is true, the window is + scrolled up one line. Note that in order to get the physical + scrolling effect on the terminal, it is also necessary to call + \method{idlok()}. +\end{methoddesc} + +\begin{methoddesc}{setscrreg}{top, bottom} +Set the scrolling region from line \var{top} to line \var{bottom}. All +scrolling actions will take place in this region. +\end{methoddesc} + +\begin{methoddesc}{standend}{} +Turn off all attributes. +\end{methoddesc} + +\begin{methoddesc}{standout}{} +Turn on attribute \var{A_STANDOUT}. +\end{methoddesc} + +\begin{methoddesc}{subpad}{\optional{nlines, ncols,} begin_y, begin_y} +Return a sub-window, whose upper-left corner is at +\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is +\var{ncols}/\var{nlines}. +\end{methoddesc} + +\begin{methoddesc}{subwin}{\optional{nlines, ncols,} begin_y, begin_y} +Return a sub-window, whose upper-left corner is at +\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is +\var{ncols}/\var{nlines}. + +By default, the sub-window will extend from the +specified position to the lower right corner of the window. +\end{methoddesc} + +\begin{methoddesc}{syncdown}{} +Touches each location in the window that has been touched in any of +its ancestor windows. This routine is called by \method{refresh()}, +so it should almost never be necessary to call it manually. +\end{methoddesc} + +\begin{methoddesc}{syncok}{flag} +If called with \var{flag} set to true, then \method{syncup()} is +called automatically whenever there is a change in the window. +\end{methoddesc} + +\begin{methoddesc}{syncup}{} +Touches all locations in ancestors of the window that have been changed in +the window. +\end{methoddesc} + +\begin{methoddesc}{touchline}{start, count} +Pretend \var{count} lines have been changed, starting with line +\var{start}. +\end{methoddesc} + +\begin{methoddesc}{touchwin}{} +Pretend the whole window has been changed, for purposes of drawing +optimizations. +\end{methoddesc} + +\begin{methoddesc}{untouchwin}{} +Marks all lines in the window as unchanged since the last call to +\method{refresh()}. +\end{methoddesc} + +\begin{methoddesc}{vline}{\optional{y, x,} ch, n} +Display a vertical line starting at \code{(\var{y}, \var{x})} with +length \var{n} consisting of the character \var{ch}. +\end{methoddesc} + +\subsection{Constants} + +The \module{curses} module defines the following data members: + +\begin{datadesc}{version} +A string representing the current version of the module. +Also available as \constant{__version__}. +\end{datadesc} + + +\begin{tableii}{c|l}{code}{Attribute}{Meaning} + \lineii{A_ALTCHARSET}{Alternate character set mode.} + \lineii{A_BLINK}{Blink mode.} + \lineii{A_BOLD}{Bold mode.} + \lineii{A_DIM}{Dim mode.} + \lineii{A_NORMAL}{Normal attribute.} + \lineii{A_STANDOUT}{Standout mode.} + \lineii{A_UNDERLINE}{Underline mode.} +\end{tableii} + +Keys are referred to by integer constants with names starting with +\code{KEY_}. The exact names available are system dependent. + +% XXX this table is far too large! +% XXX should this table be alphabetized? + +\begin{tableii}{c|l}{code}{Key constant}{Key} + \lineii{KEY_MIN}{Minimum key value} + \lineii{KEY_BREAK}{ Break key (unreliable) } + \lineii{KEY_DOWN}{ Down-arrow } + \lineii{KEY_UP}{ Up-arrow } + \lineii{KEY_LEFT}{ Left-arrow } + \lineii{KEY_RIGHT}{ Right-arrow } + \lineii{KEY_HOME}{ Home key (upward+left arrow) } + \lineii{KEY_BACKSPACE}{ Backspace (unreliable) } + \lineii{KEY_F0}{ Function keys. Up to 64 function keys are supported. } + \lineii{KEY_F\var{n}}{ Value of function key \var{n} } + \lineii{KEY_DL}{ Delete line } + \lineii{KEY_IL}{ Insert line } + \lineii{KEY_DC}{ Delete character } + \lineii{KEY_IC}{ Insert char or enter insert mode } + \lineii{KEY_EIC}{ Exit insert char mode } + \lineii{KEY_CLEAR}{ Clear screen } + \lineii{KEY_EOS}{ Clear to end of screen } + \lineii{KEY_EOL}{ Clear to end of line } + \lineii{KEY_SF}{ Scroll 1 line forward } + \lineii{KEY_SR}{ Scroll 1 line backward (reverse) } + \lineii{KEY_NPAGE}{ Next page } + \lineii{KEY_PPAGE}{ Previous page } + \lineii{KEY_STAB}{ Set tab } + \lineii{KEY_CTAB}{ Clear tab } + \lineii{KEY_CATAB}{ Clear all tabs } + \lineii{KEY_ENTER}{ Enter or send (unreliable) } + \lineii{KEY_SRESET}{ Soft (partial) reset (unreliable) } + \lineii{KEY_RESET}{ Reset or hard reset (unreliable) } + \lineii{KEY_PRINT}{ Print } + \lineii{KEY_LL}{ Home down or bottom (lower left) } + \lineii{KEY_A1}{ Upper left of keypad } + \lineii{KEY_A3}{ Upper right of keypad } + \lineii{KEY_B2}{ Center of keypad } + \lineii{KEY_C1}{ Lower left of keypad } + \lineii{KEY_C3}{ Lower right of keypad } + \lineii{KEY_BTAB}{ Back tab } + \lineii{KEY_BEG}{ Beg (beginning) } + \lineii{KEY_CANCEL}{ Cancel } + \lineii{KEY_CLOSE}{ Close } + \lineii{KEY_COMMAND}{ Cmd (command) } + \lineii{KEY_COPY}{ Copy } + \lineii{KEY_CREATE}{ Create } + \lineii{KEY_END}{ End } + \lineii{KEY_EXIT}{ Exit } + \lineii{KEY_FIND}{ Find } + \lineii{KEY_HELP}{ Help } + \lineii{KEY_MARK}{ Mark } + \lineii{KEY_MESSAGE}{ Message } + \lineii{KEY_MOVE}{ Move } + \lineii{KEY_NEXT}{ Next } + \lineii{KEY_OPEN}{ Open } + \lineii{KEY_OPTIONS}{ Options } + \lineii{KEY_PREVIOUS}{ Prev (previous) } + \lineii{KEY_REDO}{ Redo } + \lineii{KEY_REFERENCE}{ Ref (reference) } + \lineii{KEY_REFRESH}{ Refresh } + \lineii{KEY_REPLACE}{ Replace } + \lineii{KEY_RESTART}{ Restart } + \lineii{KEY_RESUME}{ Resume } + \lineii{KEY_SAVE}{ Save } + \lineii{KEY_SBEG}{ Shifted Beg (beginning) } + \lineii{KEY_SCANCEL}{ Shifted Cancel } + \lineii{KEY_SCOMMAND}{ Shifted Command } + \lineii{KEY_SCOPY}{ Shifted Copy } + \lineii{KEY_SCREATE}{ Shifted Create } + \lineii{KEY_SDC}{ Shifted Delete char } + \lineii{KEY_SDL}{ Shifted Delete line } + \lineii{KEY_SELECT}{ Select } + \lineii{KEY_SEND}{ Shifted End } + \lineii{KEY_SEOL}{ Shifted Clear line } + \lineii{KEY_SEXIT}{ Shifted Dxit } + \lineii{KEY_SFIND}{ Shifted Find } + \lineii{KEY_SHELP}{ Shifted Help } + \lineii{KEY_SHOME}{ Shifted Home } + \lineii{KEY_SIC}{ Shifted Input } + \lineii{KEY_SLEFT}{ Shifted Left arrow } + \lineii{KEY_SMESSAGE}{ Shifted Message } + \lineii{KEY_SMOVE}{ Shifted Move } + \lineii{KEY_SNEXT}{ Shifted Next } + \lineii{KEY_SOPTIONS}{ Shifted Options } + \lineii{KEY_SPREVIOUS}{ Shifted Prev } + \lineii{KEY_SPRINT}{ Shifted Print } + \lineii{KEY_SREDO}{ Shifted Redo } + \lineii{KEY_SREPLACE}{ Shifted Replace } + \lineii{KEY_SRIGHT}{ Shifted Right arrow } + \lineii{KEY_SRSUME}{ Shifted Resume } + \lineii{KEY_SSAVE}{ Shifted Save } + \lineii{KEY_SSUSPEND}{ Shifted Suspend } + \lineii{KEY_SUNDO}{ Shifted Undo } + \lineii{KEY_SUSPEND}{ Suspend } + \lineii{KEY_UNDO}{ Undo } + \lineii{KEY_MOUSE}{ Mouse event has occurred } + \lineii{KEY_RESIZE}{ Terminal resize event } + \lineii{KEY_MAX}{Maximum key value} +\end{tableii} + +The following table lists characters from the alternate character set. +\strong{Note:} These are available only after \function{initscr()} has +been called. + +\begin{tableii}{c|l}{code}{ACS code}{Meaning} + \lineii{ACS_BBSS}{} + \lineii{ACS_BLOCK}{} + \lineii{ACS_BOARD}{} + \lineii{ACS_BSBS}{} + \lineii{ACS_BSSB}{} + \lineii{ACS_BSSS}{} + \lineii{ACS_BTEE}{} + \lineii{ACS_BULLET}{} + \lineii{ACS_CKBOARD}{} + \lineii{ACS_DARROW}{} + \lineii{ACS_DEGREE}{} + \lineii{ACS_DIAMOND}{} + \lineii{ACS_GEQUAL}{ (Not available with SGI curses)} + \lineii{ACS_HLINE}{} + \lineii{ACS_LANTERN}{} + \lineii{ACS_LARROW}{} + \lineii{ACS_LEQUAL}{ (Not available with SGI curses)} + \lineii{ACS_LLCORNER}{} + \lineii{ACS_LRCORNER}{} + \lineii{ACS_LTEE}{} + \lineii{ACS_NEQUAL}{ (Not available with SGI curses)} + \lineii{ACS_PI}{ (Not available with SGI curses)} + \lineii{ACS_PLMINUS}{} + \lineii{ACS_PLUS}{} + \lineii{ACS_RARROW}{} + \lineii{ACS_RTEE}{} + \lineii{ACS_S1}{} + \lineii{ACS_S3}{ (Not available with SGI curses)} + \lineii{ACS_S9}{} + \lineii{ACS_SBBS}{} + \lineii{ACS_SBSB}{} + \lineii{ACS_SBSS}{} + \lineii{ACS_SSBB}{} + \lineii{ACS_SSBS}{} + \lineii{ACS_SSSB}{} + \lineii{ACS_SSSS}{} + \lineii{ACS_STERLING}{ (Not available with SGI curses)} + \lineii{ACS_TTEE}{} + \lineii{ACS_UARROW}{} + \lineii{ACS_ULCORNER}{} + \lineii{ACS_URCORNER}{} + \lineii{ACS_VLINE}{} +\end{tableii} + +The following table lists the predefined colors: + +\begin{tableii}{c|l}{code}{Constant}{Color} + \lineii{COLOR_BLACK}{Black} + \lineii{COLOR_BLUE}{Blue} + \lineii{COLOR_CYAN}{Cyan (light greenish blue)} + \lineii{COLOR_GREEN}{Green} + \lineii{COLOR_MAGENTA}{Magenta (purplish red)} + \lineii{COLOR_RED}{Red} + \lineii{COLOR_WHITE}{White} + \lineii{COLOR_YELLOW}{Yellow} +\end{tableii} + -- cgit v0.12