X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_inopts.3x.html;h=7aea80376f0d722b7dbb0e76788674b25d02c15c;hb=b793748293cd1a764b1a858455399ad899b5a8a1;hp=211295e49ab1a11e5ebc2e160912565d9bb3fc75;hpb=58552e8c761a70f8f0bd591fecdf576fa8216e3e;p=ncurses.git diff --git a/doc/html/man/curs_inopts.3x.html b/doc/html/man/curs_inopts.3x.html index 211295e4..7aea8037 100644 --- a/doc/html/man/curs_inopts.3x.html +++ b/doc/html/man/curs_inopts.3x.html @@ -26,7 +26,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_inopts.3x,v 1.24 2017/01/07 19:25:15 tom Exp @ + * @Id: curs_inopts.3x,v 1.25 2017/02/18 16:39:44 tom Exp @ --> @@ -40,16 +40,15 @@
-curs_inopts(3x) curs_inopts(3x) +curs_inopts(3x) curs_inopts(3x)
- cbreak, nocbreak, echo, noecho, halfdelay, intrflush, - keypad, meta, nodelay, notimeout, raw, noraw, noqiflush, - qiflush, timeout, wtimeout, typeahead - curses input - options + cbreak, nocbreak, echo, noecho, halfdelay, intrflush, keypad, meta, + nodelay, notimeout, raw, noraw, noqiflush, qiflush, timeout, wtimeout, + typeahead - curses input options
@@ -75,239 +74,211 @@
- 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. + 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. Others apply only to a specific window. Win- + dow-specific settings are not automatically applied to new or derived + windows. 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 unaffect- - ed), making characters typed by the user immediately - available to the program. The nocbreak routine returns - the terminal to normal (cooked) mode. - - Initially the terminal may or may not be in cbreak mode, - as the mode is inherited; therefore, a program should call - cbreak or nocbreak explicitly. Most interactive programs - using curses set the cbreak mode. Note that cbreak over- - rides raw. [See curs_getch(3x) for a discussion of how - these routines interact with echo and noecho.] + 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-processing (interrupt and flow control charac- + ters are unaffected), making characters typed by the user immediately + available to the program. The nocbreak routine returns the terminal to + normal (cooked) mode. + + Initially the terminal may or may not be in cbreak mode, as the mode is + inherited; therefore, a program should call cbreak or nocbreak explic- + itly. Most interactive programs using curses set the cbreak mode. + Note that cbreak overrides 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(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 echo and noecho routines control whether characters 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 pre- + fer 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 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. + The halfdelay routine is used for half-delay mode, which is similar to + cbreak mode in that characters typed by the user are immediately avail- + able to the program. However, after blocking for tenths tenths of sec- + onds, ERR is returned 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), 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 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. + 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 the option (bf is FALSE) prevents the flush. + The default for the option is inherited from the tty driver settings. + The window argument is ignored.
- 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(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. + The keypad option enables the keypad of the user's terminal. If en- + abled (bf is TRUE), the user can press a function 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 interpret the escape se- + quences 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 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 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, + Initially, whether the terminal returns 7 or 8 significant bits on in- + put 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 equiva- + lent, 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 termi- + nal 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. + 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(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. + While interpreting an input escape sequence, wgetch(3x) sets a timer + while waiting for the next character. If notimeout(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 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 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. + 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 imme- + diately 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 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 - 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 + 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 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 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 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 de- - lay milliseconds (where delay is positive). + 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 + is positive, then read blocks for delay milliseconds, and returns ERR + if there is still no input. Hence, these routines provide the same + functionality as nodelay, plus the additional capability of being able + to block for only delay milliseconds (where delay is positive).
- 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(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. + The curses library does "line-breakout optimization" by looking for ty- + peahead periodically while updating the screen. If input is found, and + it is coming from a tty, the current update is postponed until re- + fresh(3x) 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.
- 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. + All routines that return an integer return ERR upon failure and OK + (SVr4 specifies only "an integer value other than ERR") upon successful + completion, unless otherwise noted in the preceding routine descrip- + tions. - 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, + X/Open does not define any error conditions. In this implementation, + functions with a window parameter will return an error if it is null. + Any function will also return an error if the terminal was not initial- + ized. Also, halfdelay - returns an error if its parameter is outside - the range 1..255. + returns an error if its parameter is outside the range + 1..255.
- These functions are described in the XSI Curses standard, - Issue 4. - - The ncurses library obeys the XPG4 standard and the his- - torical 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 raw - 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. - - 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. + 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 + raw call turned it off as a side-effect. For best portability, set + echo or noecho explicitly just after initialization, even if your pro- + gram remains in cooked mode. + + When keypad is first enabled, ncurses loads the key-definitions for the + current terminal description. If the terminal description includes ex- + tended 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 (depending on previ- + ous loads of terminal descriptions) may differ from one execution of a + program to the next. The generated keycodes are recognized by the key- + name function (which will then return a name beginning with "k" denot- + ing the terminfo capability name rather than "K", used for curses key- + names). On the other hand, an application can use define_key to estab- + lish 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 definition of any + particular string capability. Higher-level applications which use the + curses wgetch and similar functions 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 determines 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 ca- + pability'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 + Note that echo, noecho, halfdelay, intrflush, meta, nodelay, 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 recommended.
- curses(3x), curs_getch(3x), curs_initscr(3x), - curs_util(3x), define_key(3x), termio(7) + curses(3x), curs_getch(3x), curs_initscr(3x), curs_util(3x), de- + fine_key(3x), termio(7) - curs_inopts(3x) + curs_inopts(3x)