X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=inline;f=doc%2Fhtml%2Fman%2Fcurs_inopts.3x.html;h=d2d5b6b03f250e1dfd0cc6763301108f021c7ded;hb=c6cfd97b8beaf0f6deafbf8aac7281cf6aa7f012;hp=13ec59ce0164616796278096c68e17602394f451;hpb=b1f61d9f3aa244512045a6b02e759825d7049d34;p=ncurses.git diff --git a/doc/html/man/curs_inopts.3x.html b/doc/html/man/curs_inopts.3x.html index 13ec59ce..d2d5b6b0 100644 --- a/doc/html/man/curs_inopts.3x.html +++ b/doc/html/man/curs_inopts.3x.html @@ -1,171 +1,223 @@ + + +
+ + +- +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 +NAME
+ cbreak, nocbreak, echo, noecho, halfdelay, intrflush, + keypad, meta, nodelay, notimeout, raw, noraw, noqiflush, + qiflush, timeout, wtimeout, typeahead - curses input options-SYNOPSIS
- #include <curses.h> - - int cbreak(void); - int nocbreak(void); - int echo(void); - int noecho(void); - int halfdelay(int tenths); - int intrflush(WINDOW *win, bool bf); - int keypad(WINDOW *win, bool bf); - int meta(WINDOW *win, bool bf); - int nodelay(WINDOW *win, bool bf); - int raw(void); - int noraw(void); - void noqiflush(void); - void qiflush(void); - int notimeout(WINDOW *win, bool bf); - void timeout(int delay); - void wtimeout(WINDOW *win, int delay); - int typeahead(int fd); +SYNOPSIS
+ #include <curses.h> + + int cbreak(void); + int nocbreak(void); + int echo(void); + int noecho(void); + int halfdelay(int tenths); + int intrflush(WINDOW *win, bool bf); + int keypad(WINDOW *win, bool bf); + int meta(WINDOW *win, bool bf); + int nodelay(WINDOW *win, bool bf); + int raw(void); + int noraw(void); + void noqiflush(void); + void qiflush(void); + int notimeout(WINDOW *win, bool bf); + void timeout(int delay); + void wtimeout(WINDOW *win, int delay); + int typeahead(int fd);-DESCRIPTION
+DESCRIPTION
Normally, the tty driver buffers typed characters until a - newline or carriage return is typed. The cbreak routine + 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 - available to the program. The nocbreak routine returns + 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, + 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.] - - 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 - 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 + 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.] + + 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 initial- + ly 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 - must be a number between 1 and 255. Use nocbreak to leave + 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), 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 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. - - 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 + 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 (bf is FALSE), the option + prevents the flush. The default for the option is inher- + ited 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 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. + turned on (made to transmit) and off (made to work local- + ly), turning on this option causes the terminal keypad to + be turned on when wgetch 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 CS8 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 - 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 + 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 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 + 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. + 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 + 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 + 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 - 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). - - The curses library does ``line-breakout optimization'' by + 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 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 + 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 + 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.-RETURN VALUE
- All routines that return an integer return ERR upon fail- +RETURN VALUE
+ 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 + 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. +-PORTABILITY
+PORTABILITY
These functions are described in the XSI Curses standard, Issue 4. @@ -173,70 +225,78 @@ 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 portabil- - ity, set echo or noecho explicitly just after initializa- + 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. +-NOTES
- Note that echo, noecho, halfdelay, intrflush, meta, node- - lay, notimeout, noqiflush, qiflush, timeout, and wtimeout +NOTES
+ 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 + 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.-SEE ALSO
- curses(3x), curs_getch(3x), curs_initscr(3x), termio(7) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +SEE ALSO
+ curses(3x), curs_getch(3x), curs_initscr(3x), + curs_util(3x), define_key(3x), termio(7) + curs_inopts(3x)-
- -Man(1) output converted with -man2html - +