# curs_outopts 3x 2025-03-08 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, the hardware cursor is left at the  location  of  the  window
           cursor  being  refreshed.   The  leaveok option allows the cursor to be
           left wherever the update  happens  to  leave  it.   It  is  useful  for
           applications  where  the  cursor is not used, since it reduces the need
           for cursor motions.

### scrollok

           The scrollok option controls what happens when the cursor of  a  window
           is  moved  off  the edge of the window or scrolling region, either as a
           result of a newline action on the  bottom  line,  or  typing  the  last
           character  of the last line.  If disabled, (bf is FALSE), the cursor is
           left on the bottom line.  If enabled,  (bf  is  TRUE),  the  window  is
           scrolled up one line (Note that to get the physical scrolling effect on
           the terminal, it is also necessary to call idlok).

### setscrreg, wsetscrreg

           The setscrreg and wsetscrreg routines allow the application  programmer
           to  set  a  software  scrolling  region  in  a window.  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.  (Note that this has nothing to do with the use of a physical
           scrolling region capability in the terminal, like that  in  the  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 this implementation,

           o   those  functions  that have a window pointer will return ERR if the
               window pointer is null

           o   wsetscrreg returns  ERR  if  the  scrolling  region  limits  extend
               outside the window boundaries.

## NOTES

           clearok,  leaveok, scrollok, idcok, and setscrreg may be implemented as
           macros.

           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, but
           the code neglects 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-03-08                  curs_outopts(3x)