Debian Codegraph @

upstream/debian-trixie/man3/outopts.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_outopts.3x,v 1.81 2025/02/01 22:49:13 tom Exp $
31 .TH outopts 3NCURSES 2025-02-01 "ncurses 6.5" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%clearok\fP,
49 \fB\%idcok\fP,
50 \fB\%idlok\fP,
51 \fB\%immedok\fP,
52 \fB\%leaveok\fP,
53 \fB\%scrollok\fP,
54 \fB\%setscrreg\fP,
55 \fB\%wsetscrreg\fP \-
56 set \fIcurses\fR output options
57 .SH SYNOPSIS
58 .nf
59 \fB#include <curses.h>
60 .PP
61 \fBint clearok(WINDOW *\fIwin\fP, bool \fIbf\fP);
62 \fBvoid idcok(WINDOW *\fIwin\fP, bool \fIbf\fP);
63 \fBint idlok(WINDOW *\fIwin\fP, bool \fIbf\fP);
64 \fBvoid immedok(WINDOW *\fIwin\fP, bool \fIbf\fP);
65 \fBint leaveok(WINDOW *\fIwin\fP, bool \fIbf\fP);
66 \fBint scrollok(WINDOW *\fIwin\fP, bool \fIbf\fP);
67 .PP
68 \fBint setscrreg(int \fItop\fP, int \fIbot\fP);
69 \fBint wsetscrreg(WINDOW *\fIwin\fP, int \fItop\fP, int \fIbot\fP);
70 .fi
71 .SH DESCRIPTION
72 These routines set options that change the style of output within
73 \fBcurses\fP.
74 All options are initially \fBFALSE\fP, unless otherwise stated.
75 It is not necessary to turn these options off before calling \fB\%endwin\fP(3NCURSES).
76 .SS clearok
77 If \fBclearok\fP is called with \fBTRUE\fP as argument, the next
78 call to \fBwrefresh\fP with this window will clear the screen completely and
79 redraw the entire screen from scratch.
80 This is useful when the contents of the
81 screen are uncertain, or in some cases for a more pleasing visual effect.
82 If
83 the \fIwin\fP argument to \fBclearok\fP is the global variable \fBcurscr\fP,
84 the next call to \fBwrefresh\fP with any window causes the screen to be cleared
85 and repainted from scratch.
86 .SS idcok
87 If \fBidcok\fP is called with \fBFALSE\fP as second argument, \fBcurses\fP
88 no longer considers using the hardware insert/delete character feature of
89 terminals so equipped.
90 Use of character insert/delete is enabled by default.
91 Calling \fBidcok\fP with \fBTRUE\fP as second argument re-enables use
92 of character insertion and deletion.
93 .SS idlok
94 If \fBidlok\fP is called with \fBTRUE\fP as second argument, \fBcurses\fP
95 considers using the hardware insert/delete line feature of terminals so
96 equipped.
97 Calling \fBidlok\fP with \fBFALSE\fP as second argument disables use
98 of line insertion and deletion.
99 This option should be enabled only if the
100 application needs insert/delete line, for example, for a screen editor.
101 It is
102 disabled by default because insert/delete line tends to be visually annoying
103 when used in applications where it is not really needed.
104 If insert/delete line
105 cannot be used, \fBcurses\fP redraws the changed portions of all lines.
106 .SS immedok
107 If \fBimmedok\fP is called with \fBTRUE\fP as second argument,
108 any change in the window image,
109 such as the ones caused by \fBwaddch, wclrtobot, wscrl\fP,
110 etc., automatically causes a call to \fBwrefresh\fP.
111 However, it may degrade performance considerably,
112 due to repeated calls to \fBwrefresh\fP.
113 Calling \fBimmedok\fP with \fBFALSE\fP as second argument
114 restores the default behavior,
115 i.e., deferring screen updates until a refresh is needed.
116 .SS leaveok
117 Normally, the hardware cursor is left at the location of the window cursor
118 being refreshed.
119 The \fBleaveok\fP option allows the cursor to be left
120 wherever the update happens to leave it.
121 It is useful for applications where
122 the cursor is not used, since it reduces the need for cursor motions.
123 .SS scrollok
124 The \fBscrollok\fP option controls what happens when the cursor of a window is
125 moved off the edge of the window or scrolling region, either as a result of a
126 newline action on the bottom line, or typing the last character of the last
127 line.
128 If disabled, (\fIbf\fP is \fBFALSE\fP), the cursor is left on the bottom
129 line.
130 If enabled, (\fIbf\fP is \fBTRUE\fP), the window is scrolled up one line
131 (Note that to get the physical scrolling effect on the terminal, it is
132 also necessary to call \fBidlok\fP).
133 .SS "setscrreg, wsetscrreg"
134 The \fBsetscrreg\fP and \fBwsetscrreg\fP routines allow the application
135 programmer to set a software scrolling region in a window.
136 The \fItop\fP and
137 \fIbot\fP parameters
138 are the line numbers of the top and bottom margin of the scrolling
139 region.
140 (Line 0 is the top line of the window.) If this option and
141 \fBscrollok\fP are enabled, an attempt to move off the bottom margin line
142 causes all lines in the scrolling region to scroll one line in the direction
143 of the first line.
144 Only the text of the window is scrolled.
145 (Note that this
146 has nothing to do with the use of a physical scrolling region capability in the
147 terminal, like that in the VT100.
148 If \fBidlok\fP is enabled and the terminal
149 has either a scrolling region or insert/delete line capability, they will
150 probably be used by the output routines.)
151 .SH RETURN VALUE
152 The functions \fBsetscrreg\fP and \fBwsetscrreg\fP return \fBOK\fP upon success
153 and \fBERR\fP upon failure.
154 All other routines that return an integer always
155 return \fBOK\fP.
156 .PP
157 In this implementation,
158 .bP
159 those functions that have a window pointer
160 will return
161 .B ERR
162 if the window pointer is null
163 .bP
164 \fBwsetscrreg\fP
165 returns
166 .B ERR
167 if the scrolling region limits extend outside the
168 window boundaries.
169 .SH NOTES
170 .BR \%clearok ","
171 .BR \%leaveok ","
172 .BR \%scrollok ","
173 .BR \%idcok ","
174 and
175 .B \%setscrreg
176 may be implemented as macros.
177 .PP
178 The \fBimmedok\fP routine is useful for windows that are used as terminal
179 emulators.
180 .SH PORTABILITY
181 X/Open Curses Issue\ 4 describes these functions.
182 It specifies no error conditions for them.
183 .PP
184 Some historic
185 .I curses
186 implementations,
187 as an undocumented feature,
188 did the equivalent of
189 .RB \*(`` \%clearok( .\|.\|. ", 1)" \*(''
190 when
191 .B \%touchwin(stdstr)
192 or
193 .B \%clear(stdstr)
194 were used.
195 This trick does not work with
196 .IR \%ncurses .
197 .PP
198 Early System\ V
199 .I curses
200 implementations specified that with
201 .I \%scrollok
202 enabled,
203 any window modification triggering a scroll
204 also forced a physical refresh.
205 X/Open Curses does not require this,
206 and
207 .I \%ncurses
208 avoids doing so to better optimize vertical motions upon a
209 .IR \%wrefresh "."
210 .PP
211 X/Open Curses does not mention that the cursor should be
212 made invisible as a side-effect of
213 .IR \%leaveok "."
214 SVr4
215 .I curses
216 documentation notes this,
217 but the code neglects it.
218 Use \fB\%curs_set\fP(3NCURSES) to make the cursor invisible.
219 .SH HISTORY
220 4BSD (1980)
221 introduced
222 .IR \%clearok ","
223 .IR \%leaveok ","
224 and
225 .IR \%scrollok "."
226 .PP
227 SVr2 (1984)
228 supplied
229 .IR \%idlok ","
230 .IR \%setscrreg ","
231 and
232 .IR \%wsetscrreg "."
233 .PP
234 SVr3.1 (1987)
235 implemented
236 .I \%idcok
237 and
238 .IR \%immedok "."
239 .PP
240 .I \%ncurses
241 formerly treated
242 .I nl
243 and
244 .I nonl
245 as both input
246 .I and
247 output options,
248 but no longer;
249 see \fB\%inopts\fP(3NCURSES).
250 .SH SEE ALSO
251 \fB\%ncurses\fP(3NCURSES),
252 \fB\%addch\fP(3NCURSES),
253 \fB\%clear\fP(3NCURSES),
254 \fB\%initscr\fP(3NCURSES),
255 \fB\%refresh\fP(3NCURSES),
256 \fB\%scroll\fP(3NCURSES),
257 \fB\%curses_variables\fP(3NCURSES)