# curs_outopts 3x 2025-04-05 ncurses 6.5 Library calls

    curs_outopts(3x)                 Library calls                curs_outopts(3x)

## NAME

           clearok,   idcok,   idlok,   immedok,   leaveok,  scrollok,  setscrreg,
           wsetscrreg - set curses output options

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

           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.

### clearok

           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.

### idcok

           (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.

### idlok

           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.

### immedok

           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.  However, doing so may  degrade
           performance  considerably  when many such calls occur.  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.

### 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  is
           useful  for  applications that do not employ a visible cursor, since it
           reduces the need for cursor motions.

### scrollok

           The scrollok option controls what happens when a window's cursor  moves
           off the edge of the window or scrolling region, either as a result of a
           newline occurring on the bottom line, or writing to the last  character
           of  the last 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).

### 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.  (Line 0 is the top line
           of the window.)  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.)

## 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.

           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.

## NOTES

           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.

           The  immedok  routine  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.

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

    ncurses 6.5                       2025-04-05                  curs_outopts(3x)