outopts(3NCURSES)

💖 outopts — bestie, it's the ncurses output-options glow-up ✨

okay so this one's from the 3NCURSES library calls section and it's literally the control panel for how your curses windows look when they write stuff. eight little functions, one big vibe. let's get into it 🫶

---

🌸 NAME 🌸

clearok, idcok, idlok, immedok, leaveok, scrollok, setscrreg, wsetscrreg — setting the output options for curses, periodt 💅

---

✨ SYNOPSIS ✨

#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 are the ones that configure properties of curses windows that change how they output stuff. the boolean-valued properties all start out as FALSE unless I say otherwise, and endwin(3NCURSES) resets any terminal modes that correspond to these properties — so bestie, your app does not need to restore the initial values itself. slay, less work for you 💖

🎀 clearok

setting win's clearok property to TRUE makes the next wrefresh call on it clear the whole terminal screen and redraw it entirely. super useful when you need to restore what's on screen (like, say, some other process wrote all over your terminal, rude 😭), or sometimes just to get a nicer visual effect. if win is curscr (peep curses_variables(3NCURSES) for that one), then the next wrefresh call on any window makes the terminal screen clear and redraw like that. wrefresh resets this property back to FALSE when it's done.

🍓 idcok

(this property defaults to TRUE, bestie, it's the special one 💅) setting win's idcok property to FALSE stops curses from using the insert/delete character capabilities of terminal types that have them, according to the terminfo database.

🌈 idlok

setting win's idlok property to TRUE makes curses consider using the insert/delete line capabilities of terminal types that have them, per the terminfo database. turn this on if your app explicitly needs those operations — like a full-screen text editor would — otherwise the results might be visually annoying to the user, and we do not want that energy 🙈

🧚 immedok

if you call immedok with TRUE as the second argument, then changes to the window image — the kind caused by waddch, wclrtobot, or wscrl — automatically trigger a call to wrefresh. heads up though: setting a window's immedok property can degrade performance considerably if writes are frequent 💀. calling immedok with FALSE as the second argument restores the default behavior, which defers screen updates until a refresh is needed or the app explicitly directs one.

⭐ leaveok

normally curses leaves the hardware cursor at the library's cursor location of the window being refreshed. the leaveok option lets the cursor be left wherever the update happens to leave it. this is useful for apps that don't have a visible cursor at all, since it cuts down on the need for cursor motions. iconic honestly.

👑 scrollok

the scrollok option controls what happens when a window's cursor moves off the edge of the window or the scrolling region — and it can happen two ways: (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 it's disabled (bf is FALSE), curses leaves the cursor sitting on the bottom line of the window. if it's enabled (bf is TRUE), curses scrolls the window up one line. (and psst — to get the physical scrolling effect on the terminal, the app also has to enable idlok.)

🎀 setscrreg, wsetscrreg

the wsetscrreg and setscrreg functions let the app 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 margins of the scrolling region. if this option and scrollok are both enabled, then an attempt to move off the bottom margin line causes all the lines in the scrolling region to scroll one line in the direction of the first line. only the text of the window is scrolled, no cap. (and this process has nothing to do with the scrolling region capability of the terminal itself, like the one found in the DEC VT100.) if idlok is enabled and the terminal has either a scrolling region or insert/delete line capability, the output routines will probably use them.

---

💜 RETURN VALUE 💜

setscrreg and wsetscrreg return OK on success and ERR on failure. every other routine here that returns an integer always returns OK. simple as that 💅

in ncurses, these functions fail if:

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

---

🌸 NOTES 🌸

clearok, leaveok, scrollok, idcok, and setscrreg may be implemented as macros, just so you know 👀

unlike the other functions on this page, setscrreg does not take a pointer-to-WINDOW parameter — it operates on stdscr. use wsetscrreg if you wanna configure the scrolling region of a specific window you picked.

historically, apps used idcok(FALSE) to accommodate the "magic cookie" feature of some terminal types; see the subsection "Highlighting, Underlining, and Visible Bells" of terminfo(5). when updating a line, having character cells with magic cookies in them made the curses library's computations of which characters needed rewriting inaccurate. a better solution is to indicate the magic_cookie_glitch (xmc) capability in the terminal's type description. do that instead bestie, fr fr.

also immedok is useful for windows that are being used as terminal emulators. good to know 🫶

---

🔥 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, so don't try it 💀

early System V curses implementations specified that with scrollok enabled, any window modification that triggered a scroll also forced a physical refresh. X/Open Curses does not require this, and ncurses avoids doing it so it can 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. so if you want an invisible cursor, use curs_set(3NCURSES) yourself. no shortcuts, sorry 🎀

---

🌈 HISTORY 🌈

• 4BSD (1980) introduced clearok, leaveok, and scrollok.
• SVr2 (1984) supplied idlok, setscrreg, and wsetscrreg.
• SVr3.1 (1987) implemented idcok and immedok.

and a lil fun fact: ncurses formerly treated nl and nonl as both input and output options, but no longer — see inopts(3NCURSES) for that lore. the more you know ✨

---

👑 SEE ALSO 👑

ncurses(3NCURSES), addch(3NCURSES), clear(3NCURSES), initscr(3NCURSES), refresh(3NCURSES), scroll(3NCURSES), curses_variables(3NCURSES)

---

and that's the whole page bestie, you ate it 💅 this was ncurses 6.6, dated 2025-11-11 — mwah, go configure some windows, you've got this 🦋💖