https://invisible-island.net/ncurses/man/


curs_outopts 3x 2025-07-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.   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.5                       2025-07-05                  curs_outopts(3x)