# curs_outopts 3x 2025-11-11 ncurses 6.6 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.  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.

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

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

           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.

## 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.6                       2025-11-11                  curs_outopts(3x)