curs_outopts(3X)

💅 curs_outopts — setting your window's whole output vibe ✨

okay bestie, so this is a library calls page from the curses(3X) manual, and it's literally all about the little switches that decide how your window puts stuff on the screen. no cap, these are the personality settings for your WINDOW. 🫶

---

🌸 NAME 🌸

clearok, idcok, idlok, immedok, leaveok, scrollok, setscrreg, wsetscrreg — literally just "set curses output options," that's the whole gig ✨

---

🎀 SYNOPSIS 🎀

okay here's the lineup, copy-paste ready:

#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);

---

💖 DESCRIPTION 💖

so these functions configure properties of curses windows that affect their manner of output. the boolean-valued properties start out FALSE unless it says otherwise down there. and like, endwin(3X) resets any terminal modes that correspond to these properties, so an application does not need to restore their initial values. slay, one less thing to worry about 💅

✨ clearok

setting win's clearok property to TRUE makes the next wrefresh call on it clear the terminal screen and redraw it entirely. this property is useful to restore the contents of the screen (maybe because another process wrote to the terminal, rude 😭), or in some cases to achieve a more pleasing visual effect. if win is curscr (see curs_variables(3X)), then the next wrefresh call on any window causes the terminal screen to clear and redraw as above. wrefresh resets this property to FALSE. it's giving "start over, fresh face" ✨

🦋 idcok

(this property defaults TRUE, bestie, so it's already on 💅) setting win's idcok property to FALSE prevents curses from using the insert/delete character capabilities of terminal types that possess them according to the terminfo database.

🌸 idlok

setting win's idlok property to TRUE causes curses to consider using the insert/delete line capabilities of terminal types that possess them according to the terminfo database. enable this option if the application explicitly requires these operations, like a full-screen text editor might. otherwise the results may be visually annoying to the user 🙈. so like, don't just turn it on for fun, okay?

💜 immedok

if immedok is called with TRUE as the second argument, changes to the window image — like 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 the second argument restores the default behavior, deferring screen updates until a refresh is needed or explicitly directed by the application. no cap, it's convenient but it's expensive, so use it with intention.

🌈 leaveok

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's useful for applications that do not employ a visible cursor, since it reduces the need for cursor motions. main character energy: no cursor needed 💅

⭐ scrollok

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. two switches, one vibe.)

🍓 setscrreg, wsetscrreg

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. like, different thing entirely, don't get it twisted 🫶) 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.

---

👑 RETURN VALUE 👑

the functions setscrreg and wsetscrreg return OK upon success and ERR upon failure. all other routines that return an integer always return OK. periodt.

in ncurses, these functions fail if:

• the curses screen has not been initialized,
• (for functions taking a WINDOW pointer argument) win is a null pointer, or
• (for setscrreg and wsetscrreg) the function is passed arguments describing a scrolling region with limits that extend outside the window boundaries.

---

🧚 NOTES 🧚

clearok, leaveok, scrollok, idcok, and setscrreg may be implemented as macros. iykyk, so don't go taking their addresses or anything weird.

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. the way that magic cookies messed up the math... 💀

immedok is useful for windows that are used as terminal emulators.

---

🌟 PORTABILITY 🌟

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. fr fr, do it yourself.

---

💀 HISTORY 💀

• 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).

---

🔥 SEE ALSO 🔥

curses(3X), curs_addch(3X), curs_clear(3X), curs_initscr(3X), curs_refresh(3X), curs_scroll(3X), curs_variables(3X)

---

and that's the whole page bestie 💖 this was ncurses 6.6, dated 2025-11-11, from the curs_outopts(3X) manual. go forth and configure your windows, you absolute icon 👑✨