diff options
Diffstat (limited to 'contrib/ncurses/man/curs_inopts.3x')
| -rw-r--r-- | contrib/ncurses/man/curs_inopts.3x | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/contrib/ncurses/man/curs_inopts.3x b/contrib/ncurses/man/curs_inopts.3x new file mode 100644 index 000000000000..1fc6a820a603 --- /dev/null +++ b/contrib/ncurses/man/curs_inopts.3x @@ -0,0 +1,214 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inopts.3x,v 1.8 1998/03/11 21:12:53 juergen Exp $ +.TH curs_inopts 3X "" +.SH NAME +\fBcbreak\fR, \fBnocbreak\fR, \fBecho\fR, +\fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR, \fBkeypad\fR, +\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBraw\fR, \fBnoraw\fR, +\fBnoqiflush\fR, \fBqiflush\fR, \fBtimeout\fR, \fBwtimeout\fR, +\fBtypeahead\fR - \fBcurses\fR input options +.SH SYNOPSIS +\fB#include <curses.h>\fR + +\fBint cbreak(void);\fR +.br +\fBint nocbreak(void);\fR +.br +\fBint echo(void);\fR +.br +\fBint noecho(void);\fR +.br +\fBint halfdelay(int tenths);\fR +.br +\fBint intrflush(WINDOW *win, bool bf);\fR +.br +\fBint keypad(WINDOW *win, bool bf);\fR +.br +\fBint meta(WINDOW *win, bool bf);\fR +.br +\fBint nodelay(WINDOW *win, bool bf);\fR +.br +\fBint raw(void);\fR +.br +\fBint noraw(void);\fR +.br +\fBvoid noqiflush(void);\fR +.br +\fBvoid qiflush(void);\fR +.br +\fBint notimeout(WINDOW *win, bool bf);\fR +.br +\fBvoid timeout(int delay);\fR +.br +\fBvoid wtimeout(WINDOW *win, int delay);\fR +.br +\fBint typeahead(int fd);\fR +.br +.SH DESCRIPTION +Normally, the tty driver buffers typed characters until a newline or carriage +return is typed. The \fBcbreak\fR routine disables line buffering and +erase/kill character-processing (interrupt and flow control characters are +unaffected), making characters typed by the user immediately available to the +program. The \fBnocbreak\fR routine returns the terminal to normal (cooked) +mode. + +Initially the terminal may or may not be in \fBcbreak\fR mode, as the mode is +inherited; therefore, a program should call \fBcbreak\fR or \fBnocbreak\fR +explicitly. Most interactive programs using \fBcurses\fR set the \fBcbreak\fR +mode. Note that \fBcbreak\fR overrides \fBraw\fR. +[See \fBcurs_getch\fR(3X) for a +discussion of how these routines interact with \fBecho\fR and \fBnoecho\fR.] + +The \fBecho\fR and \fBnoecho\fR routines control whether characters typed by +the user are echoed by \fBgetch\fR as they are typed. Echoing by the tty +driver is always disabled, but initially \fBgetch\fR is in echo mode, so +characters typed are echoed. Authors of most interactive programs prefer to do +their own echoing in a controlled area of the screen, or not to echo at all, so +they disable echoing by calling \fBnoecho\fR. +[See \fBcurs_getch\fR(3X) for a +discussion of how these routines interact with \fBcbreak\fR and +\fBnocbreak\fR.] + +The \fBhalfdelay\fR routine is used for half-delay mode, which is similar to +\fBcbreak\fR mode in that characters typed by the user are immediately +available to the program. However, after blocking for \fItenths\fR tenths of +seconds, ERR is returned if nothing has been typed. The value of \fBtenths\fR +must be a number between 1 and 255. Use \fBnocbreak\fR to leave half-delay +mode. + +If the \fBintrflush\fR option is enabled, (\fIbf\fR is \fBTRUE\fR), when an +interrupt key is pressed on the keyboard (interrupt, break, quit) all output in +the tty driver queue will be flushed, giving the effect of faster response to +the interrupt, but causing \fBcurses\fR to have the wrong idea of what is on +the screen. Disabling (\fIbf\fR is \fBFALSE\fR), the option prevents the +flush. The default for the option is inherited from the tty driver settings. +The window argument is ignored. + +The \fBkeypad\fR option enables the keypad of the user's terminal. If +enabled (\fIbf\fR is \fBTRUE\fR), the user can press a function key +(such as an arrow key) and \fBwgetch\fR returns a single value +representing the function key, as in \fBKEY_LEFT\fR. If disabled +(\fIbf\fR is \fBFALSE\fR), \fBcurses\fR does not treat function keys +specially and the program has to interpret the escape sequences +itself. If the keypad in the terminal can be turned on (made to +transmit) and off (made to work locally), turning on this option +causes the terminal keypad to be turned on when \fBwgetch\fR is +called. The default value for keypad is false. + +Initially, whether the terminal returns 7 or 8 significant bits on +input depends on the control mode of the tty driver [see termio(7)]. +To force 8 bits to be returned, invoke \fBmeta\fR(\fIwin\fR, +\fBTRUE\fR); this is equivalent, under POSIX, to setting the CS8 flag +on the terminal. To force 7 bits to be returned, invoke +\fBmeta\fR(\fIwin\fR, \fBFALSE\fR); this is equivalent, under POSIX, +to setting the CS8 flag on the terminal. The window argument, +\fIwin\fR, is always ignored. If the terminfo capabilities \fBsmm\fR +(meta_on) and \fBrmm\fR (meta_off) are defined for the terminal, +\fBsmm\fR is sent to the terminal when \fBmeta\fR(\fIwin\fR, +\fBTRUE\fR) is called and \fBrmm\fR is sent when \fBmeta\fR(\fIwin\fR, +\fBFALSE\fR) is called. + +The \fBnodelay\fR option causes \fBgetch\fR to be a non-blocking call. +If no input is ready, \fBgetch\fR returns \fBERR\fR. If disabled +(\fIbf\fR is \fBFALSE\fR), \fBgetch\fR waits until a key is pressed. + +While interpreting an input escape sequence, \fBwgetch\fR sets a timer +while waiting for the next character. If \fBnotimeout(\fR\fIwin\fR, +\fBTRUE\fR) is called, then \fBwgetch\fR does not set a timer. The +purpose of the timeout is to differentiate between sequences received +from a function key and those typed by a user. + +The \fBraw\fR and \fBnoraw\fR routines place the terminal into or out of raw +mode. Raw mode is similar to \fBcbreak\fR mode, in that characters typed are +immediately passed through to the user program. The differences are that in +raw mode, the interrupt, quit, suspend, and flow control characters are all +passed through uninterpreted, instead of generating a signal. The behavior of +the BREAK key depends on other bits in the tty driver that are not set by +\fBcurses\fR. + +When the \fBnoqiflush\fR routine is used, normal flush of input and +output queues associated with the \fBINTR\fR, \fBQUIT\fR and +\fBSUSP\fR characters will not be done [see termio(7)]. When +\fBqiflush\fR is called, the queues will be flushed when these control +characters are read. You may want to call \fBnoqiflush()\fR in a signal +handler if you want output to continue as though the interrupt +had not occurred, after the handler exits. + +The \fBtimeout\fR and \fBwtimeout\fR routines set blocking or +non-blocking read for a given window. If \fIdelay\fR is negative, +blocking read is used (\fIi\fR.\fIe\fR., waits indefinitely for +input). If \fIdelay\fR is zero, then non-blocking read is used +(\fIi\fR.\fIe\fR., read returns \fBERR\fR if no input is waiting). If +\fIdelay\fR is positive, then read blocks for \fIdelay\fR +milliseconds, and returns \fBERR\fR if there is still no input. +Hence, these routines provide the same functionality as \fBnodelay\fR, +plus the additional capability of being able to block for only +\fIdelay\fR milliseconds (where \fIdelay\fR is positive). + +The \fBcurses\fR library does ``line-breakout optimization'' by looking for +typeahead periodically while updating the screen. If input is found, +and it is coming from a tty, the current update is postponed until +\fBrefresh\fR or \fBdoupdate\fR is called again. This allows faster +response to commands typed in advance. Normally, the input FILE +pointer passed to \fBnewterm\fR, or \fBstdin\fR in the case that +\fBinitscr\fR was used, will be used to do this typeahead checking. +The \fBtypeahead\fR routine specifies that the file descriptor +\fIfd\fR is to be used to check for typeahead instead. If \fIfd\fR is +-1, then no typeahead checking is done. +.SH RETURN VALUE +All routines that return an integer return \fBERR\fR upon failure and OK (SVr4 +specifies only "an integer value other than \fBERR\fR") upon successful +completion, unless otherwise noted in the preceding routine descriptions. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. + +The ncurses library obeys the XPG4 standard and the historical practice of the +AT&T curses implementations, in that the echo bit is cleared when curses +initializes the terminal state. BSD curses differed from this slightly; it +left the echo bit on at initialization, but the BSD \fBraw\fR call turned it +off as a side-effect. For best portability, set echo or noecho explicitly +just after initialization, even if your program remains in cooked mode. +.SH NOTES +Note that \fBecho\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR, +\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBnoqiflush\fR, +\fBqiflush\fR, \fBtimeout\fR, and \fBwtimeout\fR may be macros. + +The \fBnoraw\fR and \fBnocbreak\fR calls follow historical practice in that +they attempt to restore to normal (`cooked') mode from raw and cbreak modes +respectively. Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver +control states that are hard to predict or understand; it is not recommended. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_getch\fR(3X), \fBcurs_initscr\fR(3X), \fBtermio\fR(7) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: |