X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_inopts.3x.html;h=211295e49ab1a11e5ebc2e160912565d9bb3fc75;hp=9e8ce06e96e074db36921cdde499f237dc41cd77;hb=58552e8c761a70f8f0bd591fecdf576fa8216e3e;hpb=46722468f47c2b77b3987729b4bcf2321cccfd01 diff --git a/doc/html/man/curs_inopts.3x.html b/doc/html/man/curs_inopts.3x.html index 9e8ce06e..211295e4 100644 --- a/doc/html/man/curs_inopts.3x.html +++ b/doc/html/man/curs_inopts.3x.html @@ -1,7 +1,6 @@ - +
+ +- +curs_inopts(3x) curs_inopts(3x) --
- cbreak, nocbreak, echo, noecho, halfdelay, intrflush, key- - pad, meta, nodelay, notimeout, raw, noraw, noqiflush, - qiflush, timeout, wtimeout, typeahead - curses input + + + +
+ cbreak, nocbreak, echo, noecho, halfdelay, intrflush, + keypad, meta, nodelay, notimeout, raw, noraw, noqiflush, + qiflush, timeout, wtimeout, typeahead - curses input options --
+
#include <curses.h> int cbreak(void); @@ -72,13 +74,22 @@ int typeahead(int fd); --
+
+ The ncurses library provides several functions which let + an application change the way input from the terminal is + handled. Some are global, applying to all windows. Oth- + ers apply only to a specific window. Window-specific set- + tings are not automatically applied to new or derived win- + dows. An application must apply these to each window, if + the same behavior is needed. + + +
Normally, the tty driver buffers typed characters until a newline or carriage return is typed. The cbreak routine disables line buffering and erase/kill character-process- - ing (interrupt and flow control characters are unaf- - fected), making characters typed by the user immediately + ing (interrupt and flow control characters are unaffect- + ed), making characters typed by the user immediately available to the program. The nocbreak routine returns the terminal to normal (cooked) mode. @@ -89,121 +100,148 @@ rides raw. [See curs_getch(3x) for a discussion of how these routines interact with echo and noecho.] + +
The echo and noecho routines control whether characters - typed by the user are echoed by getch as they are typed. - Echoing by the tty driver is always disabled, but ini- - tially getch is in echo mode, so characters typed are + typed by the user are echoed by getch(3x) as they are + typed. Echoing by the tty driver is always disabled, but + initially getch 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 noecho. [See curs_getch(3x) for a discussion of how these routines interact with cbreak and nocbreak.] + +
The halfdelay routine is 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, ERR is - returned if nothing has been typed. The value of tenths + after blocking for tenths tenths of seconds, ERR is re- + turned if nothing has been typed. The value of tenths must be a number between 1 and 255. Use nocbreak to leave half-delay mode. - If the intrflush option is enabled, (bf is TRUE), when an + +
+ If the intrflush option is enabled (bf is TRUE), and 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 curses to have the wrong idea of - what is on the screen. Disabling (bf is FALSE), the - option prevents the flush. The default for the option is - inherited from the tty driver settings. The window argu- - ment is ignored. + break, quit), all output in the tty driver queue will be + flushed, giving the effect of faster response to the in- + terrupt, but causing curses to have the wrong idea of what + is on the screen. Disabling the option (bf is FALSE) pre- + vents the flush. The default for the option is inherited + from the tty driver settings. The window argument is ig- + nored. + +
The keypad option enables the keypad of the user's termi- nal. If enabled (bf is TRUE), the user can press a func- - tion key (such as an arrow key) and wgetch returns a sin- - gle value representing the function key, as in KEY_LEFT. - If disabled (bf is FALSE), curses 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 key- - pad to be turned on when wgetch is called. The default - value for keypad is false. - + tion key (such as an arrow key) and wgetch(3x) returns a + single value representing the function key, as in + KEY_LEFT. If disabled (bf is FALSE), curses does not + treat function keys specially and the program has to in- + terpret 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 termi- + nal keypad to be turned on when wgetch(3x) 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 meta(win, TRUE); this is equivalent, under POSIX, - to setting the CS8 flag on the terminal. To force 7 bits - to be returned, invoke meta(win, FALSE); this is equiva- - lent, under POSIX, to setting the CS7 flag on the termi- - nal. The window argument, win, is always ignored. If the - terminfo capabilities smm (meta_on) and rmm (meta_off) are - defined for the terminal, smm is sent to the terminal when + bits on input depends on the control mode of the tty driv- + er [see termio(7)]. To force 8 bits to be returned, in- + voke meta(win, TRUE); this is equivalent, under POSIX, to + setting the CS8 flag on the terminal. To force 7 bits to + be returned, invoke meta(win, FALSE); this is equivalent, + under POSIX, to setting the CS7 flag on the terminal. The + window argument, win, is always ignored. If the terminfo + capabilities smm (meta_on) and rmm (meta_off) are defined + for the terminal, smm is sent to the terminal when meta(win, TRUE) is called and rmm is sent when meta(win, FALSE) is called. + +
The nodelay option causes getch to be a non-blocking call. If no input is ready, getch returns ERR. If disabled (bf is FALSE), getch waits until a key is pressed. - While interpreting an input escape sequence, wgetch sets a - timer while waiting for the next character. If notime- - out(win, TRUE) is called, then wgetch does not set a - timer. The purpose of the timeout is to differentiate - between sequences received from a function key and those + While interpreting an input escape sequence, wgetch(3x) + sets a timer while waiting for the next character. If no- + timeout(win, TRUE) is called, then wgetch does not set a + timer. The purpose of the timeout is to differentiate be- + tween sequences received from a function key and those typed by a user. + +
The raw and noraw routines place the terminal into or out of raw mode. Raw mode is similar to cbreak 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 + characters typed are immediately passed through to the us- + er program. The differences are that in raw mode, the in- + terrupt, 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 curses. + +
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 [see termio(7)]. When qiflush + characters will not be done [see termio(7)]. When qiflush is called, the queues will be flushed when these control - characters are read. You may want to call noqiflush() in - a signal handler if you want output to continue as though + characters are read. You may want to call noqiflush in a + signal handler if you want output to continue as though the interrupt had not occurred, after the handler exits. + +
The timeout and wtimeout routines set blocking or non- blocking read for a given window. If delay is negative, - blocking read is used (i.e., waits indefinitely for - input). If delay is zero, then non-blocking read is used - (i.e., read returns ERR if no input is waiting). If delay + blocking read is used (i.e., waits indefinitely for in- + put). If delay is zero, then non-blocking read is used + (i.e., read returns ERR if no input is waiting). If delay is positive, then read blocks for delay milliseconds, and returns ERR if there is still no input. Hence, these rou- tines provide the same functionality as nodelay, plus the - additional capability of being able to block for only - delay milliseconds (where delay is positive). + additional capability of being able to block for only de- + lay milliseconds (where delay is positive). - The curses library does ``line-breakout optimization'' by + +
+ The curses 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 refresh or doupdate - is called again. This allows faster response to commands - typed in advance. Normally, the input FILE pointer passed - to newterm, or stdin in the case that initscr was used, - will be used to do this typeahead checking. The typeahead - routine specifies that the file descriptor fd is to be - used to check for typeahead instead. If fd is -1, then no - typeahead checking is done. + the current update is postponed until refresh(3x) or doup- + date is called again. This allows faster response to com- + mands typed in advance. Normally, the input FILE pointer + passed to newterm, or stdin in the case that initscr was + used, will be used to do this typeahead checking. The ty- + peahead routine specifies that the file descriptor fd is + to be used to check for typeahead instead. If fd is -1, + then no typeahead checking is done. --
+
All routines that return an integer return ERR upon fail- ure and OK (SVr4 specifies only "an integer value other than ERR") upon successful completion, unless otherwise noted in the preceding routine descriptions. + X/Open does not define any error conditions. In this im- + plementation, functions with a window parameter will re- + turn an error if it is null. Any function will also re- + turn an error if the terminal was not initialized. Also, --
+ halfdelay + returns an error if its parameter is outside + the range 1..255. + + +
These functions are described in the XSI Curses standard, Issue 4. @@ -212,69 +250,89 @@ 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 raw - call turned it off as a side-effect. For best portabil- - ity, set echo or noecho explicitly just after initializa- + call turned it off as a side-effect. For best portabili- + ty, set echo or noecho explicitly just after initializa- tion, even if your program remains in cooked mode. - --
- Note that echo, noecho, halfdelay, intrflush, meta, node- - lay, notimeout, noqiflush, qiflush, timeout, and wtimeout + When keypad is first enabled, ncurses loads the key-defi- + nitions for the current terminal description. If the ter- + minal description includes extended string capabilities, + e.g., from using the -x option of tic, then ncurses also + defines keys for the capabilities whose names begin with + "k". The corresponding keycodes are generated and (de- + pending on previous loads of terminal descriptions) may + differ from one execution of a program to the next. The + generated keycodes are recognized by the keyname function + (which will then return a name beginning with "k" denoting + the terminfo capability name rather than "K", used for + curses key-names). On the other hand, an application can + use define_key to establish a specific keycode for a given + string. This makes it possible for an application to + check for an extended capability's presence with tigetstr, + and reassign the keycode to match its own needs. + + Low-level applications can use tigetstr to obtain the def- + inition of any particular string capability. Higher-level + applications which use the curses wgetch and similar func- + tions to return keycodes rely upon the order in which the + strings are loaded. If more than one key definition has + the same string value, then wgetch can return only one + keycode. Most curses implementations (including ncurses) + load key definitions in the order defined by the array of + string capability names. The last key to be loaded deter- + mines the keycode which will be returned. In ncurses, you + may also have extended capabilities interpreted as key + definitions. These are loaded after the predefined keys, + and if a capability's value is the same as a previously- + loaded key definition, the later definition is the one + used. + + +
+ Note that echo, noecho, halfdelay, intrflush, meta, node- + lay, notimeout, noqiflush, qiflush, timeout, and wtimeout may be macros. The noraw and nocbreak 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 + 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. --
- curses(3x), curs_getch(3x), curs_initscr(3x), termio(7) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
+ curses(3x), curs_getch(3x), curs_initscr(3x), + curs_util(3x), define_key(3x), termio(7) + curs_inopts(3x)-