1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
<!--
****************************************************************************
* Copyright 2018-2024,2025 Thomas E. Dickey *
* Copyright 1998-2016,2017 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_outopts.3x,v 1.106 2025/11/12 00:52:57 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 2025-11-11 ncurses 6.6 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
<H1 class="no-header">curs_outopts 3x 2025-11-11 ncurses 6.6 Library calls</H1>
<PRE>
<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>idcok</STRONG>, <STRONG>idlok</STRONG>, <STRONG>immedok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>setscrreg</STRONG>,
<STRONG>wsetscrreg</STRONG> - set <EM>curses</EM> output options
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
<STRONG>int</STRONG> <STRONG>clearok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>void</STRONG> <STRONG>idcok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>idlok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>void</STRONG> <STRONG>immedok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>leaveok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>scrollok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>setscrreg(int</STRONG> <EM>top</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bot</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>wsetscrreg(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>top</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bot</EM><STRONG>);</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
These functions configure properties of <EM>curses</EM> windows that affect
their manner of output. Boolean-valued properties are initially <STRONG>FALSE</STRONG>
except where noted. <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> resets any terminal modes corresponding
to these properties; an application need not restore their initial
values.
</PRE><H3><a name="h3-clearok">clearok</a></H3><PRE>
Setting <EM>win</EM>'s <STRONG>clearok</STRONG> property to <STRONG>TRUE</STRONG> causes the next <STRONG>wrefresh</STRONG> call on
it to clear the terminal screen and redraw it entirely. This property
is useful to restore the contents of the screen (perhaps because
another process has written to the terminal), or in some cases to
achieve a more pleasing visual effect. If <EM>win</EM> is <STRONG>curscr</STRONG> (see
<STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>), the next <STRONG>wrefresh</STRONG> call on <EM>any</EM> window causes the
terminal screen to clear and redraw as above. <STRONG>wrefresh</STRONG> resets this
property to <STRONG>FALSE</STRONG>.
</PRE><H3><a name="h3-idcok">idcok</a></H3><PRE>
(This property defaults <STRONG>TRUE</STRONG>.) Setting <EM>win</EM>'s <STRONG>idcok</STRONG> property to <STRONG>FALSE</STRONG>
prevents <EM>curses</EM> from using the insert/delete character capabilities of
terminal types possessing them according to the <EM>terminfo</EM> database.
</PRE><H3><a name="h3-idlok">idlok</a></H3><PRE>
Setting <EM>win</EM>'s <STRONG>idlok</STRONG> property to <STRONG>TRUE</STRONG> causes <EM>curses</EM> to consider using
the insert/delete line capabilities of terminal types possessing them
according to the <EM>terminfo</EM> database. Enable this option if the
application explicitly requires these operations, as a full-screen text
editor might; otherwise the results may be visually annoying to the
user.
</PRE><H3><a name="h3-immedok">immedok</a></H3><PRE>
If <STRONG>immedok</STRONG> is called with <STRONG>TRUE</STRONG> as second argument, changes to the
window image, such as those caused by <STRONG>waddch</STRONG>, <STRONG>wclrtobot</STRONG>, or <STRONG>wscrl</STRONG>,
automatically cause a call to <STRONG>wrefresh</STRONG>. Setting a window's <STRONG>immedok</STRONG>
property may degrade performance considerably if writes are frequent.
Calling <STRONG>immedok</STRONG> with <STRONG>FALSE</STRONG> as second argument restores the default
behavior, deferring screen updates until a refresh is needed or
explicitly directed by the application.
</PRE><H3><a name="h3-leaveok">leaveok</a></H3><PRE>
Normally, <EM>curses</EM> leaves the hardware cursor at the library's cursor
location of the window 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 that do not employ a visible cursor, 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 a window's cursor moves
off the edge of the window or scrolling region, as a result of either
(1) writing a newline anywhere on its bottom line, or (2) writing a
character that advances the cursor to the last position on its bottom
line. If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <EM>curses</EM> leaves the cursor on the
bottom line of the window. If enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), <EM>curses</EM> scrolls the
window up one line. (To get the physical scrolling effect on the
terminal, the application must also enable <STRONG>idlok</STRONG>).
</PRE><H3><a name="h3-setscrreg_wsetscrreg">setscrreg, wsetscrreg</a></H3><PRE>
The <STRONG>wsetscrreg</STRONG> and <STRONG>setscrreg</STRONG> functions allow the application to set a
software scrolling region in the specified window or <STRONG>stdscr</STRONG>,
respectively. The <EM>top</EM> and <EM>bot</EM> parameters are the line numbers of the
top and bottom margin of the scrolling region. 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.
(This process has nothing to do with the scrolling region capability of
the terminal, as found in the DEC 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>
The functions <STRONG>setscrreg</STRONG> and <STRONG>wsetscrreg</STRONG> return <STRONG>OK</STRONG> upon success and <STRONG>ERR</STRONG>
upon failure. All other routines that return an integer always return
<STRONG>OK</STRONG>.
In <EM>ncurses</EM>, these functions fail if
<STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized,
<STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null
pointer, or
<STRONG>o</STRONG> (for <STRONG>setscrreg</STRONG> and <STRONG>wsetscrreg</STRONG>) the function is passed arguments
describing a scrolling region with limits that extend outside the
window boundaries.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
<STRONG>clearok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>idcok</STRONG>, and <STRONG>setscrreg</STRONG> may be implemented as
macros.
Unlike the other functions described by this page, <STRONG>setscrreg</STRONG> does not
accept a pointer-to-<EM>WINDOW</EM> parameter, but operates on <STRONG>stdscr</STRONG>. Use
<STRONG>wsetscrreg</STRONG> to configure the scrolling region of a selected window.
Historically, applications used <STRONG>idcok(FALSE)</STRONG> to accommodate the "magic
cookie" feature of some terminal types; see subsection "Highlighting,
Underlining, and Visible Bells" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. When updating a line,
the presence of character cells with magic cookies in them made the
<EM>curses</EM> library's computations of characters to be rewritten inaccurate.
A better solution is to indicate the <STRONG>magic_cookie_glitch</STRONG> (<STRONG>xmc</STRONG>)
capability in the terminal's type description.
<STRONG>immedok</STRONG> is useful for windows that are used as terminal emulators.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
X/Open Curses Issue 4 describes these functions. It specifies no error
conditions for them.
Some historic <EM>curses</EM> implementations, as an undocumented feature, did
the equivalent of "<STRONG>clearok(</STRONG>...<STRONG>,</STRONG> <STRONG>1)</STRONG>" when <STRONG>touchwin(stdstr)</STRONG> or
<STRONG>clear(stdstr)</STRONG> were used. This trick does not work with <EM>ncurses</EM>.
Early System V <EM>curses</EM> implementations specified that with <EM>scrollok</EM>
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 so to better optimize vertical motions upon a <EM>wrefresh</EM>.
X/Open Curses does not mention that the cursor should be made invisible
as a side effect of <EM>leaveok</EM>. SVr4 <EM>curses</EM> documentation notes this
behavior, but the code neglects to implement it. Use <STRONG><A HREF="curs_kernel.3x.html">curs_set(3x)</A></STRONG> to
make the cursor invisible.
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
4BSD (1980) introduced <EM>clearok</EM>, <EM>leaveok</EM>, and <EM>scrollok</EM>.
SVr2 (1984) supplied <EM>idlok</EM>, <EM>setscrreg</EM>, and <EM>wsetscrreg</EM>.
SVr3.1 (1987) implemented <EM>idcok</EM> and <EM>immedok</EM>.
<EM>ncurses</EM> formerly treated <EM>nl</EM> and <EM>nonl</EM> 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_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>
ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-clearok">clearok</a></li>
<li><a href="#h3-idcok">idcok</a></li>
<li><a href="#h3-idlok">idlok</a></li>
<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>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</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>
</BODY>
</HTML>
|
