.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_outopts.3x,v 1.50 2023/11/11 11:46:54 tom Exp $
-.TH curs_outopts 3X 2023-11-11 "ncurses 6.4" "Library calls"
+.\" $Id: curs_outopts.3x,v 1.65 2024/05/11 20:39:53 tom Exp $
+.TH curs_outopts 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
.SH NAME
\fB\%clearok\fP,
-\fB\%idlok\fP,
\fB\%idcok\fP,
+\fB\%idlok\fP,
\fB\%immedok\fP,
\fB\%leaveok\fP,
+\fB\%scrollok\fP,
\fB\%setscrreg\fP,
-\fB\%wsetscrreg\fP,
-\fB\%scrollok\fP \-
+\fB\%wsetscrreg\fP \-
set \fIcurses\fR output options
.SH SYNOPSIS
.nf
\fB#include <curses.h>
.PP
\fBint clearok(WINDOW *\fIwin\fP, bool \fIbf\fP);
-\fBint idlok(WINDOW *\fIwin\fP, bool \fIbf\fP);
\fBvoid idcok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint idlok(WINDOW *\fIwin\fP, bool \fIbf\fP);
\fBvoid immedok(WINDOW *\fIwin\fP, bool \fIbf\fP);
\fBint leaveok(WINDOW *\fIwin\fP, bool \fIbf\fP);
\fBint scrollok(WINDOW *\fIwin\fP, bool \fIbf\fP);
the \fIwin\fP argument to \fBclearok\fP is the global variable \fBcurscr\fP,
the next call to \fBwrefresh\fP with any window causes the screen to be cleared
and repainted from scratch.
+.SS idcok
+If \fBidcok\fP is called with \fBFALSE\fP as second argument, \fBcurses\fP
+no longer considers using the hardware insert/delete character feature of
+terminals so equipped.
+Use of character insert/delete is enabled by default.
+Calling \fBidcok\fP with \fBTRUE\fP as second argument re-enables use
+of character insertion and deletion.
.SS idlok
If \fBidlok\fP is called with \fBTRUE\fP as second argument, \fBcurses\fP
considers using the hardware insert/delete line feature of terminals so
when used in applications where it is not really needed.
If insert/delete line
cannot be used, \fBcurses\fP redraws the changed portions of all lines.
-.SS idcok
-If \fBidcok\fP is called with \fBFALSE\fP as second argument, \fBcurses\fP
-no longer considers using the hardware insert/delete character feature of
-terminals so equipped.
-Use of character insert/delete is enabled by default.
-Calling \fBidcok\fP with \fBTRUE\fP as second argument re-enables use
-of character insertion and deletion.
.SS immedok
If \fBimmedok\fP is called with \fBTRUE\fP as second argument,
any change in the window image,
If enabled, (\fIbf\fP is \fBTRUE\fP), the window is scrolled up one line
(Note that to get the physical scrolling effect on the terminal, it is
also necessary to call \fBidlok\fP).
-.SS setscrreg/wsetscrreg
+.SS "setscrreg, wsetscrreg"
The \fBsetscrreg\fP and \fBwsetscrreg\fP routines allow the application
programmer to set a software scrolling region in a window.
The \fItop\fP and
All other routines that return an integer always
return \fBOK\fP.
.PP
-X/Open Curses does not define any error conditions.
+X/Open Curses does not specify any error conditions.
.PP
In this implementation,
.bP
will return an error if the window pointer is null
.bP
\fBwsetscrreg\fP
-returns an error if the scrolling region limits extend outside the window.
+returns an error if the scrolling region limits extend outside the
+window boundaries.
+.SH NOTES
+Note that
+\fBclearok\fP,
+\fBleaveok\fP,
+\fBscrollok\fP,
+\fBidcok\fP, and
+\fBsetscrreg\fP may be macros.
.PP
-X/Open does not define any error conditions.
-This implementation returns an error
-if the window pointer is null.
+The \fBimmedok\fP routine is useful for windows that are used as terminal
+emulators.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-.PP
-From the outset, ncurses used \fBnl\fP/\fBnonl\fP 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 \fIpcurses\fP source
-(which used \fBioctl\fP calls with the \fBsgttyb\fP structure)
-to termios (i.e., the POSIX terminal interface).
-In the former, both input and output were controlled via a single
-option \fBCRMOD\fP,
-while the latter separates these features.
-Because that conversion interferes with output optimization,
-\fBnl\fP/\fBnonl\fP were amended after ncurses 6.2
-to eliminate their effect on output.
+These functions are described in X/Open Curses, Issue 4.
.PP
Some historic curses implementations had, as an undocumented feature, the
ability to do the equivalent of \fBclearok(..., 1)\fP by saying
\fBtouchwin(stdscr)\fP or \fBclear(stdscr)\fP.
-This will not work under ncurses.
+This will not work under \fI\%ncurses\fP.
.PP
Earlier System V curses implementations specified that with \fBscrollok\fP
enabled, any window modification triggering a scroll also forced a physical
refresh.
-XSI Curses does not require this, and \fBncurses\fP avoids doing
+X/Open Curses does not require this, and \fI\%ncurses\fP avoids doing
it to perform better vertical-motion optimization at \fBwrefresh\fP
time.
.PP
-The XSI Curses standard does not mention that the cursor should be
+X/Open Curses does not mention that the cursor should be
made invisible as a side-effect of \fBleaveok\fP.
SVr4 curses documentation does this, but the code does not.
Use \fBcurs_set\fP to make the cursor invisible.
-.SH NOTES
-Note that
-\fBclearok\fP,
-\fBleaveok\fP,
-\fBscrollok\fP,
-\fBidcok\fP, and
-\fBsetscrreg\fP may be macros.
-.PP
-The \fBimmedok\fP routine is useful for windows that are used as terminal
-emulators.
+.SH HISTORY
+.I \%ncurses
+formerly treated \fBnl\fP(3X) and \fBnonl\fP(3X) as both input
+.I and
+output options,
+but no longer;
+see \fB\%curs_inopts\fP(3X).
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_addch\fP(3X),