Debian Codegraph @

upstream/debian-unstable/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.106 2025/11/12 00:52:57 tom Exp $
31 .TH outopts 3NCURSES 2025-11-11 "ncurses 6.6" "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 functions configure properties of
73 .I curses
74 windows that affect their manner of output.
75 Boolean-valued properties are initially
76 .B FALSE
77 except where noted.
78 \fBendwin\fP(3NCURSES) resets any terminal modes corresponding to these
79 properties;
80 an application need not restore their initial values.
81 .SS clearok
82 Setting
83 .IR win 's
84 .B \%clearok
85 property to
86 .B TRUE
87 causes the next
88 .B \%wrefresh
89 call on it to clear the terminal screen and redraw it entirely.
90 This property is useful to restore the contents of the screen
91 (perhaps because another process has written to the terminal),
92 or in some cases to achieve a more pleasing visual effect.
93 If
94 .I \%win
95 is
96 .B \%curscr
97 (see \fBcurses_variables\fP(3NCURSES)),
98 the next
99 .B \%wrefresh
100 call on
101 .I any
102 window causes the terminal screen to clear and redraw as above.
103 .B \%wrefresh
104 resets this property to
105 .BR FALSE "."
106 .SS idcok
107 (This property defaults
108 .BR TRUE ".)"
109 Setting
110 .IR win 's
111 .B \%idcok
112 property to
113 .B FALSE
114 prevents
115 .I curses
116 from using the insert/delete character capabilities of terminal types
117 possessing them according to the
118 .I \%term\%info
119 database.
120 .SS idlok
121 Setting
122 .IR win 's
123 .B \%idlok
124 property to
125 .B TRUE
126 causes
127 .I curses
128 to consider
129 using the insert/delete line capabilities of terminal types
130 possessing them according to the
131 .I \%term\%info
132 database.
133 Enable this option
134 if the application explicitly requires these operations,
135 as a full-screen text editor might;
136 otherwise the results may be visually annoying to the user.
137 .\" TODO: Substantiate that claim.
138 .SS immedok
139 If
140 .B \%immedok
141 is called with
142 .B TRUE
143 as second argument,
144 changes to the window image,
145 such as those caused by
146 .BR \%waddch ","
147 .BR \%wclrtobot ","
148 or
149 .BR \%wscrl ","
150 automatically cause a call to
151 .BR wrefresh "."
152 Setting a window's
153 .B \%immedok
154 property may degrade performance considerably
155 if writes are frequent.
156 Calling
157 .B \%immedok
158 with
159 .B FALSE
160 as second argument
161 restores the default behavior,
162 deferring screen updates until a refresh is needed
163 or explicitly directed by the application.
164 .SS leaveok
165 Normally,
166 .I curses
167 leaves the hardware cursor at the library's cursor location
168 of the window being refreshed.
169 The
170 .B \%leaveok
171 option allows the cursor to be left
172 wherever the update happens to leave it.
173 It is useful for applications that do not employ a visible cursor,
174 since it reduces the need for cursor motions.
175 .SS scrollok
176 The
177 .B \%scrollok
178 option controls what happens when a window's cursor
179 moves off the edge of the window or scrolling region,
180 as a result of either
181 (1) writing a newline anywhere on its bottom line,
182 or
183 (2) writing a character that advances the cursor to the last position
184 on its bottom line.
185 If disabled
186 .RI ( bf
187 is
188 .BR FALSE "),"
189 .I curses
190 leaves the cursor on the bottom line of the window.
191 If enabled
192 .RI ( bf
193 is
194 .BR TRUE "),"
195 .I curses
196 scrolls the window up one line.
197 (To get the physical scrolling effect on the terminal,
198 the application must also enable
199 .BR idlok ")."
200 .SS "setscrreg, wsetscrreg"
201 The
202 .B \%wsetscrreg
203 and
204 .B \%setscrreg
205 functions allow the application
206 to set a software scrolling region in the specified window or
207 .BR \%stdscr ","
208 respectively.
209 The
210 .I top
211 and
212 .I bot
213 parameters
214 are the line numbers of the top and bottom margin of the scrolling
215 region.
216 If this option and
217 .B scrollok
218 are enabled,
219 an attempt to move off the bottom margin line
220 causes all lines in the scrolling region
221 to scroll one line in the direction of the first line.
222 Only the text of the window is scrolled.
223 (This process has nothing to do
224 with the scrolling region capability of the terminal,
225 as found in the DEC VT100.)
226 If
227 .B \%idlok
228 is enabled and the terminal
229 has either a scrolling region or insert/delete line capability,
230 they will probably be used by the output routines.
231 .SH RETURN VALUE
232 The functions
233 .B \%setscrreg
234 and
235 .B \%wsetscrreg
236 return
237 .B OK
238 upon success
239 and
240 .B ERR
241 upon failure.
242 All other routines that return an integer always
243 return
244 .BR OK "."
245 .PP
246 In
247 .IR \%ncurses ","
248 these functions fail if
249 .bP
250 the
251 .I curses
252 screen has not been initialized,
253 .bP
254 (for functions taking a
255 .I \%WINDOW
256 pointer argument)
257 .I win
258 is a null pointer,
259 or
260 .bP
261 (for
262 .B \%setscrreg
263 and
264 .BR \%wsetscrreg ")"
265 the function is passed arguments describing a scrolling region
266 with limits that extend outside the window boundaries.
267 .SH NOTES
268 .BR \%clearok ","
269 .BR \%leaveok ","
270 .BR \%scrollok ","
271 .BR \%idcok ","
272 and
273 .B \%setscrreg
274 may be implemented as macros.
275 .PP
276 Unlike the other functions described by this page,
277 .B \%setscrreg
278 does not accept a
279 .RI pointer-to- WINDOW
280 parameter,
281 but operates on
282 .BR stdscr "."
283 Use
284 .B \%wsetscrreg
285 to configure the scrolling region of a selected window.
286 .PP
287 Historically,
288 applications used
289 .B \%idcok(FALSE)
290 to accommodate the \*(``magic cookie\*('' feature
291 of some terminal types;
292 see subsection \*(``Highlighting, Underlining, and Visible Bells\*(''
293 of \fB\%terminfo\fP(5).
294 When updating a line,
295 the presence of character cells with magic cookies in them
296 made the
297 .I curses
298 library's computations of characters to be rewritten inaccurate.
299 A better solution is to indicate the
300 .B \%magic_cookie_glitch
301 .RB ( xmc )
302 capability in the terminal's type description.
303 .PP
304 .B \%immedok
305 is useful for windows that are used as terminal emulators.
306 .SH PORTABILITY
307 X/Open Curses Issue\ 4 describes these functions.
308 It specifies no error conditions for them.
309 .PP
310 Some historic
311 .I curses
312 implementations,
313 as an undocumented feature,
314 did the equivalent of
315 .RB \*(`` \%clearok( .\|.\|. ", 1)" \*(''
316 when
317 .B \%touchwin(stdstr)
318 or
319 .B \%clear(stdstr)
320 were used.
321 This trick does not work with
322 .IR \%ncurses .
323 .PP
324 Early System\ V
325 .I curses
326 implementations specified that with
327 .I \%scrollok
328 enabled,
329 any window modification triggering a scroll
330 also forced a physical refresh.
331 X/Open Curses does not require this,
332 and
333 .I \%ncurses
334 avoids doing so to better optimize vertical motions upon a
335 .IR \%wrefresh "."
336 .PP
337 X/Open Curses does not mention that the cursor should be
338 made invisible as a side effect of
339 .IR \%leaveok "."
340 SVr4
341 .I curses
342 documentation notes this behavior,
343 but the code neglects to implement it.
344 Use \fB\%curs_set\fP(3NCURSES) to make the cursor invisible.
345 .SH HISTORY
346 4BSD (1980)
347 introduced
348 .IR \%clearok ","
349 .IR \%leaveok ","
350 and
351 .IR \%scrollok "."
352 .PP
353 SVr2 (1984)
354 supplied
355 .IR \%idlok ","
356 .IR \%setscrreg ","
357 and
358 .IR \%wsetscrreg "."
359 .PP
360 SVr3.1 (1987)
361 implemented
362 .I \%idcok
363 and
364 .IR \%immedok "."
365 .PP
366 .I \%ncurses
367 formerly treated
368 .I nl
369 and
370 .I nonl
371 as both input
372 .I and
373 output options,
374 but no longer;
375 see \fB\%inopts\fP(3NCURSES).
376 .SH SEE ALSO
377 \fB\%ncurses\fP(3NCURSES),
378 \fB\%addch\fP(3NCURSES),
379 \fB\%clear\fP(3NCURSES),
380 \fB\%initscr\fP(3NCURSES),
381 \fB\%refresh\fP(3NCURSES),
382 \fB\%scroll\fP(3NCURSES),
383 \fB\%curses_variables\fP(3NCURSES)