diff options
Diffstat (limited to 'doc/html/man/curs_outopts.3x.html')
| -rw-r--r-- | doc/html/man/curs_outopts.3x.html | 184 |
1 files changed, 89 insertions, 95 deletions
diff --git a/doc/html/man/curs_outopts.3x.html b/doc/html/man/curs_outopts.3x.html index a860b1bb1291..7f04d92eabef 100644 --- a/doc/html/man/curs_outopts.3x.html +++ b/doc/html/man/curs_outopts.3x.html @@ -1,6 +1,6 @@ -<!-- +<!-- **************************************************************************** - * Copyright 2018,2020 Thomas E. Dickey * + * Copyright 2018-2023,2024 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,28 +27,28 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_outopts.3x,v 1.33 2020/10/03 22:04:09 tom Exp @ + * @Id: curs_outopts.3x,v 1.64 2024/04/20 21:24:19 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_outopts 3x</TITLE> +<TITLE>curs_outopts 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + </HEAD> <BODY> -<H1 class="no-header">curs_outopts 3x</H1> +<H1 class="no-header">curs_outopts 3x 2024-04-20 ncurses 6.5 Library calls</H1> <PRE> -<STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> +<STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>clearok</STRONG>, <STRONG>idlok</STRONG>, <STRONG>idcok</STRONG>, <STRONG>immedok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, - <STRONG>scrollok</STRONG> - <STRONG>curses</STRONG> output options + <STRONG>clearok</STRONG>, <STRONG>idlok</STRONG>, <STRONG>idcok</STRONG>, <STRONG>immedok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, + <STRONG>scrollok</STRONG> - set <EM>curses</EM> output options </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -66,9 +66,9 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These routines set options that change the style of output within <STRONG>curs-</STRONG> - <STRONG>es</STRONG>. All options are initially <STRONG>FALSE</STRONG>, unless otherwise stated. It is - not necessary to turn these options off before calling <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG>. + These routines set options that change the style of output within + <STRONG>curses</STRONG>. All options are initially <STRONG>FALSE</STRONG>, unless otherwise stated. It + is not necessary to turn these options off before calling <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG>. </PRE><H3><a name="h3-clearok">clearok</a></H3><PRE> @@ -84,61 +84,63 @@ </PRE><H3><a name="h3-idlok">idlok</a></H3><PRE> If <STRONG>idlok</STRONG> is called with <STRONG>TRUE</STRONG> as second argument, <STRONG>curses</STRONG> considers using the hardware insert/delete line feature of terminals so equipped. - Calling <STRONG>idlok</STRONG> with <STRONG>FALSE</STRONG> as second argument disables use of line inser- - tion and deletion. This option should be enabled only if the applica- - tion needs insert/delete line, for example, for a screen editor. It is - disabled by default because insert/delete line tends to be visually an- - noying when used in applications where it is not really needed. If in- - sert/delete line cannot be used, <STRONG>curses</STRONG> redraws the changed portions of - all lines. + Calling <STRONG>idlok</STRONG> with <STRONG>FALSE</STRONG> as second argument disables use of line + insertion and deletion. This option should be enabled only if the + application needs insert/delete line, for example, for a screen editor. + It is disabled by default because insert/delete line tends to be + visually annoying when used in applications where it is not really + needed. If insert/delete line cannot be used, <STRONG>curses</STRONG> redraws the + changed portions of all lines. </PRE><H3><a name="h3-idcok">idcok</a></H3><PRE> - If <STRONG>idcok</STRONG> is called with <STRONG>FALSE</STRONG> as second argument, <STRONG>curses</STRONG> no longer con- - siders using the hardware insert/delete character feature of terminals - so equipped. Use of character insert/delete is enabled by default. - Calling <STRONG>idcok</STRONG> with <STRONG>TRUE</STRONG> as second argument re-enables use of character - insertion and deletion. + If <STRONG>idcok</STRONG> is called with <STRONG>FALSE</STRONG> as second argument, <STRONG>curses</STRONG> no longer + considers using the hardware insert/delete character feature of + terminals so equipped. Use of character insert/delete is enabled by + default. Calling <STRONG>idcok</STRONG> with <STRONG>TRUE</STRONG> as second argument re-enables use of + character insertion and deletion. </PRE><H3><a name="h3-immedok">immedok</a></H3><PRE> - If <STRONG>immedok</STRONG> is called with <STRONG>TRUE</STRONG> <STRONG>as</STRONG> <STRONG>argument</STRONG>, any change in the window - image, such as the ones caused by <STRONG>waddch,</STRONG> <STRONG>wclrtobot,</STRONG> <STRONG>wscrl</STRONG>, etc., auto- - matically cause a call to <STRONG>wrefresh</STRONG>. However, it may degrade perfor- - mance considerably, due to repeated calls to <STRONG>wrefresh</STRONG>. It is disabled - by default. + If <STRONG>immedok</STRONG> is called with <STRONG>TRUE</STRONG> as second argument, any change in the + window image, such as the ones caused by <STRONG>waddch,</STRONG> <STRONG>wclrtobot,</STRONG> <STRONG>wscrl</STRONG>, + etc., automatically causes a call to <STRONG>wrefresh</STRONG>. However, it may degrade + performance considerably, due to repeated calls to <STRONG>wrefresh</STRONG>. Calling + <STRONG>immedok</STRONG> with <STRONG>FALSE</STRONG> as second argument restores the default behavior, + i.e., deferring screen updates until a refresh is needed. </PRE><H3><a name="h3-leaveok">leaveok</a></H3><PRE> - Normally, the hardware cursor is left at the location of the window - cursor being refreshed. The <STRONG>leaveok</STRONG> option allows the cursor to be - left wherever the update happens to leave it. It is useful for appli- - cations where the cursor is not used, since it reduces the need for - cursor motions. + Normally, the hardware cursor is left at the location of the window + cursor being refreshed. The <STRONG>leaveok</STRONG> option allows the cursor to be + left wherever the update happens to leave it. It is useful for + applications where the cursor is not used, since it reduces the need + for cursor motions. </PRE><H3><a name="h3-scrollok">scrollok</a></H3><PRE> - The <STRONG>scrollok</STRONG> option 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 char- - acter of the last line. If disabled, (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the cursor is left - on the bottom line. If enabled, (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the window is scrolled - up one line (Note that to get the physical scrolling effect on the ter- - minal, it is also necessary to call <STRONG>idlok</STRONG>). - - -</PRE><H3><a name="h3-setscrreg_wsetscrreg">setscrreg/wsetscrreg</a></H3><PRE> - The <STRONG>setscrreg</STRONG> and <STRONG>wsetscrreg</STRONG> routines allow the application programmer - to set a software scrolling region in a window. The <EM>top</EM> and <EM>bot</EM> param- - eters are the line numbers of the top and bottom margin of the - scrolling region. (Line 0 is the top line of the window.) If this op- - tion and <STRONG>scrollok</STRONG> are enabled, an attempt to move off the bottom margin - line causes all lines in the scrolling region to scroll one line in the - direction of the first line. Only the text of the window is scrolled. - (Note that this has nothing to do with the use of a physical scrolling - region capability in the terminal, like that in the VT100. If <STRONG>idlok</STRONG> is - enabled and the terminal has either a scrolling region or insert/delete - line capability, they will probably be used by the output routines.) + The <STRONG>scrollok</STRONG> option 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 disabled, (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the cursor is + left on the bottom line. If enabled, (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the window is + scrolled up one line (Note that to get the physical scrolling effect on + the terminal, it is also necessary to call <STRONG>idlok</STRONG>). + + +</PRE><H3><a name="h3-setscrreg_wsetscrreg">setscrreg, wsetscrreg</a></H3><PRE> + The <STRONG>setscrreg</STRONG> and <STRONG>wsetscrreg</STRONG> routines allow the application programmer + to set a software scrolling region in a window. The <EM>top</EM> and <EM>bot</EM> + parameters are the line numbers of the top and bottom margin of the + scrolling region. (Line 0 is the top line of the window.) If this + option and <STRONG>scrollok</STRONG> are enabled, an attempt to move off the bottom + margin line causes all lines in the scrolling region to scroll one line + in the direction of the first line. Only the text of the window is + scrolled. (Note that this has nothing to do with the use of a physical + scrolling region capability in the terminal, like that in the VT100. + If <STRONG>idlok</STRONG> is enabled and the terminal has either a scrolling region or + insert/delete line capability, they will probably be used by the output + routines.) </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> @@ -146,7 +148,7 @@ upon failure. All other routines that return an integer always return <STRONG>OK</STRONG>. - X/Open Curses does not define any error conditions. + X/Open Curses does not specify any error conditions. In this implementation, @@ -154,56 +156,47 @@ the window pointer is null <STRONG>o</STRONG> <STRONG>wsetscrreg</STRONG> returns an error if the scrolling region limits extend - outside the window. + outside the window boundaries. - X/Open does not define any error conditions. This implementation re- - turns an error if the window pointer is null. + +</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> + Note that <STRONG>clearok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>idcok</STRONG>, and <STRONG>setscrreg</STRONG> may be + macros. + + The <STRONG>immedok</STRONG> routine is useful for windows that are used as terminal + emulators. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in the XSI Curses standard, Issue 4. - - From the outset, ncurses used <STRONG>nl</STRONG>/<STRONG>nonl</STRONG> to control the conversion of new- - lines to carriage return/line-feed on output as well as input. XSI - Curses documents only the use of these functions for input. This dif- - ference arose from converting the <EM>pcurses</EM> source (which used <STRONG>ioctl</STRONG> - calls with the <STRONG>sgttyb</STRONG> structure) to termios (i.e., the POSIX terminal - interface). In the former, both input and output were controlled via a - single option <STRONG>CRMOD</STRONG>, while the latter separates these features. Be- - cause that conversion interferes with output optimization, <STRONG>nl</STRONG>/<STRONG>nonl</STRONG> were - amended after ncurses 6.2 to eliminate their effect on output. - - Some historic curses implementations had, as an undocumented feature, - the ability to do the equivalent of <STRONG>clearok(...,</STRONG> <STRONG>1)</STRONG> by saying <STRONG>touch-</STRONG> - <STRONG>win(stdscr)</STRONG> or <STRONG>clear(stdscr)</STRONG>. This will not work under ncurses. - - Earlier System V curses implementations specified that with <STRONG>scrollok</STRONG> - enabled, any window modification triggering a scroll also forced a - physical refresh. XSI Curses does not require this, and <STRONG>ncurses</STRONG> avoids - doing it to perform better vertical-motion optimization at <STRONG>wrefresh</STRONG> - time. - - The XSI Curses standard does not mention that the cursor should be made - invisible as a side-effect of <STRONG>leaveok</STRONG>. SVr4 curses documentation does - this, but the code does not. Use <STRONG>curs_set</STRONG> to make the cursor invisi- - ble. + These functions are described in X/Open Curses, Issue 4. + Some historic curses implementations had, as an undocumented feature, + the ability to do the equivalent of <STRONG>clearok(...,</STRONG> <STRONG>1)</STRONG> by saying + <STRONG>touchwin(stdscr)</STRONG> or <STRONG>clear(stdscr)</STRONG>. This will not work under <EM>ncurses</EM>. -</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that <STRONG>clearok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>idcok</STRONG>, and <STRONG>setscrreg</STRONG> may be - macros. + Earlier System V curses implementations specified that with <STRONG>scrollok</STRONG> + enabled, any window modification triggering a scroll also forced a + physical refresh. X/Open Curses does not require this, and <EM>ncurses</EM> + avoids doing it to perform better vertical-motion optimization at + <STRONG>wrefresh</STRONG> time. + + X/Open Curses does not mention that the cursor should be made invisible + as a side-effect of <STRONG>leaveok</STRONG>. SVr4 curses documentation does this, but + the code does not. Use <STRONG>curs_set</STRONG> to make the cursor invisible. - The <STRONG>immedok</STRONG> routine is useful for windows that are used as terminal em- - ulators. + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + <EM>ncurses</EM> formerly treated <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> and <STRONG><A HREF="curs_inopts.3x.html">nonl(3x)</A></STRONG> as both input <EM>and</EM> output + options, but no longer; see <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, - <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, + <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> +ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -217,12 +210,13 @@ <li><a href="#h3-immedok">immedok</a></li> <li><a href="#h3-leaveok">leaveok</a></li> <li><a href="#h3-scrollok">scrollok</a></li> -<li><a href="#h3-setscrreg_wsetscrreg">setscrreg/wsetscrreg</a></li> +<li><a href="#h3-setscrreg_wsetscrreg">setscrreg, wsetscrreg</a></li> </ul> </li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> -<li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> |