https://invisible-island.net/ncurses/man/
curs_outopts(3x) Library calls curs_outopts(3x)
clearok, idcok, idlok, immedok, leaveok, scrollok, setscrreg,
wsetscrreg - set curses output options
#include <curses.h>
int clearok(WINDOW * win, bool bf);
void idcok(WINDOW * win, bool bf);
int idlok(WINDOW * win, bool bf);
void immedok(WINDOW * win, bool bf);
int leaveok(WINDOW * win, bool bf);
int scrollok(WINDOW * win, bool bf);
int setscrreg(int top, int bot);
int wsetscrreg(WINDOW * win, int top, int bot);
These functions configure properties of curses windows that affect
their manner of output. Boolean-valued properties are initially FALSE
except where noted. endwin(3x) resets any terminal modes corresponding
to these properties; an application need not restore their initial
values.
Setting win's clearok property to TRUE causes the next wrefresh 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 win is curscr (see
curs_variables(3x)), the next wrefresh call on any window causes the
terminal screen to clear and redraw as above. wrefresh resets this
property to FALSE.
(This property defaults TRUE.) Setting win's idcok property to FALSE
prevents curses from using the insert/delete character capabilities of
terminal types possessing them according to the terminfo database.
Setting win's idlok property to TRUE causes curses to consider using
the insert/delete line capabilities of terminal types possessing them
according to the terminfo 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.
If immedok is called with TRUE as second argument, changes to the
window image, such as those caused by waddch, wclrtobot, or wscrl,
automatically cause a call to wrefresh. Setting a window's immedok
property may degrade performance considerably if writes are frequent.
Calling immedok with FALSE as second argument restores the default
behavior, deferring screen updates until a refresh is needed or
explicitly directed by the application.
Normally, curses leaves the hardware cursor at the library's cursor
location of the window being refreshed. The leaveok 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.
The scrollok 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 (bf is FALSE), curses leaves the cursor on the
bottom line of the window. If enabled (bf is TRUE), curses scrolls the
window up one line. (To get the physical scrolling effect on the
terminal, the application must also enable idlok).
The wsetscrreg and setscrreg functions allow the application to set a
software scrolling region in the specified window or stdscr,
respectively. The top and bot parameters are the line numbers of the
top and bottom margin of the scrolling region. If this option and
scrollok 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 idlok 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 functions setscrreg and wsetscrreg return OK upon success and ERR
upon failure. All other routines that return an integer always return
OK.
In ncurses, these functions fail if
o the curses screen has not been initialized,
o (for functions taking a WINDOW pointer argument) win is a null
pointer, or
o (for setscrreg and wsetscrreg) the function is passed arguments
describing a scrolling region with limits that extend outside the
window boundaries.
clearok, leaveok, scrollok, idcok, and setscrreg may be implemented as
macros.
Unlike the other functions described by this page, setscrreg does not
accept a pointer-to-WINDOW parameter, but operates on stdscr. Use
wsetscrreg to configure the scrolling region of a selected window.
Historically, applications used idcok(FALSE) to accommodate the "magic
cookie" feature of some terminal types; see subsection "Highlighting,
Underlining, and Visible Bells" of terminfo(5). When updating a line,
the presence of character cells with magic cookies in them made the
curses library's computations of characters to be rewritten inaccurate.
A better solution is to indicate the magic_cookie_glitch (xmc)
capability in the terminal's type description.
immedok is useful for windows that are used as terminal emulators.
X/Open Curses Issue 4 describes these functions. It specifies no error
conditions for them.
Some historic curses implementations, as an undocumented feature, did
the equivalent of "clearok(..., 1)" when touchwin(stdstr) or
clear(stdstr) were used. This trick does not work with ncurses.
Early System V curses implementations specified that with scrollok
enabled, any window modification triggering a scroll also forced a
physical refresh. X/Open Curses does not require this, and ncurses
avoids doing so to better optimize vertical motions upon a wrefresh.
X/Open Curses does not mention that the cursor should be made invisible
as a side-effect of leaveok. SVr4 curses documentation notes this
behavior, but the code neglects to implement it. Use curs_set(3x) to
make the cursor invisible.
4BSD (1980) introduced clearok, leaveok, and scrollok.
SVr2 (1984) supplied idlok, setscrreg, and wsetscrreg.
SVr3.1 (1987) implemented idcok and immedok.
ncurses formerly treated nl and nonl as both input and output options,
but no longer; see curs_inopts(3x).
curses(3x), curs_addch(3x), curs_clear(3x), curs_initscr(3x),
curs_refresh(3x), curs_scroll(3x), curs_variables(3x)
ncurses 6.5 2025-07-05 curs_outopts(3x)