curs_outopts(3x) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | PORTABILITY | NOTES | SEE ALSO | COLOPHON

curs_outopts(3X)                                         curs_outopts(3X)

NAME         top

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

SYNOPSIS         top

       #include <curses.h>

       int clearok(WINDOW *win, bool bf);
       int idlok(WINDOW *win, bool bf);
       void idcok(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         top

       These  routines set options that change the style of output within
       curses.  All options are initially FALSE, unless otherwise stated.
       It is not necessary to turn these options off before calling  end‐
       win(3X).

   clearok
       If  clearok is called with TRUE as argument, the next call to wre‐
       fresh with this window will clear the screen completely and redraw
       the entire screen from scratch.  This is useful when the  contents
       of  the screen are uncertain, or in some cases for a more pleasing
       visual effect.  If the win argument to clearok is the global vari‐
       able curscr, the next call to wrefresh with any window causes  the
       screen to be cleared and repainted from scratch.

   idlok
       If  idlok is called with TRUE as second argument, curses considers
       using the hardware insert/delete  line  feature  of  terminals  so
       equipped.   Calling  idlok  with FALSE as second argument disables
       use of line insertion and deletion.  This option should be enabled
       only if the application needs insert/delete line, for example, for
       a screen editor.  It is disabled by default because  insert/delete
       line tends to be visually annoying when used in applications where
       it  is  not  really needed.  If insert/delete line cannot be used,
       curses redraws the changed portions of all lines.

   idcok
       If idcok is called with FALSE as second argument, curses no longer
       considers using the hardware insert/delete  character  feature  of
       terminals  so equipped.  Use of character insert/delete is enabled
       by default.  Calling idcok with TRUE as second argument re-enables
       use of character insertion and deletion.

   immedok
       If immedok is called with TRUE as argument, any change in the win‐
       dow image, such as the ones caused by  waddch,  wclrtobot,  wscrl,
       etc., automatically cause a call to wrefresh.  However, it may de‐
       grade performance considerably, due to repeated calls to wrefresh.
       It is disabled by default.

   leaveok
       Normally,  the hardware cursor is left at the location of the win‐
       dow 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 typ‐
       ing  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 pro‐
       grammer to set a software scrolling region in a window.   The  top
       and bot parameters are the line numbers of the top and bottom mar‐
       gin  of the scrolling region.  (Line 0 is the top line of the win‐
       dow.)  If this option and scrollok are enabled, an attempt to move
       off the bottom margin line causes all lines in the  scrolling  re‐
       gion  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 capa‐
       bility, they will probably be used by the output routines.)

RETURN VALUE         top

       The functions setscrreg and wsetscrreg return OK upon success  and
       ERR  upon  failure.  All other routines that return an integer al‐
       ways return OK.

       X/Open Curses does not define any error conditions.

       In this implementation,

       •   those functions that have a window pointer will return an er‐
           ror if the window pointer is null

       •   wsetscrreg returns an error if the scrolling region limits ex‐
           tend outside the window.

       X/Open does not define any error conditions.  This implementation
       returns an error if the window pointer is null.

PORTABILITY         top

       These functions are described in the XSI Curses standard, Issue 4.

       From the outset, ncurses used nl/nonl to control the conversion of
       newlines to carriage return/line-feed on output as well as input.
       XSI Curses documents only the use of these functions for input.
       This difference arose from converting the pcurses source (which
       used ioctl calls with the sgttyb structure) to termios (i.e., the
       POSIX terminal interface).  In the former, both input and output
       were controlled via a single option CRMOD, while the latter sepa‐
       rates these features.  Because that conversion interferes with
       output optimization, nl/nonl were amended after ncurses 6.2 to
       eliminate their effect on output.

       Some historic curses implementations had, as an undocumented fea‐
       ture, the ability to do the equivalent of clearok(..., 1) by say‐
       ing touchwin(stdscr) or clear(stdscr).  This will not work under
       ncurses.

       Earlier System V curses implementations specified that with scrol‐
       lok enabled, any window modification triggering a scroll also
       forced a physical refresh.  XSI Curses does not require this, and
       ncurses avoids doing it to perform better vertical-motion opti‐
       mization at wrefresh time.

       The XSI Curses standard does not mention that the cursor should be
       made invisible as a side-effect of leaveok.  SVr4 curses documen‐
       tation does this, but the code does not.  Use curs_set to make the
       cursor invisible.

NOTES         top

       Note that clearok, leaveok, scrollok, idcok, and setscrreg may be
       macros.

       The immedok routine is useful for windows that are used as termi‐
       nal emulators.

SEE ALSO         top

       curses(3X), curs_addch(3X), curs_clear(3X), curs_initscr(3X),
       curs_scroll(3X), curs_refresh(3X), curs_variables(3X).

COLOPHON         top

       This page is part of the ncurses (new curses) project.  Informa‐
       tion about the project can be found at 
       ⟨https://www.gnu.org/software/ncurses/ncurses.html⟩.  If you have a
       bug report for this manual page, send it to
       bug-ncurses-request@gnu.org.  This page was obtained from the
       project's upstream Git mirror of the CVS repository
       ⟨https://github.com/mirror/ncurses.git⟩ on 2025-02-02.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2023-03-12.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there is
       a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

                                                         curs_outopts(3X)