.\"***************************************************************************
-.\" 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.40 2023/07/01 15:43:20 tom Exp $
-.TH curs_outopts 3X 2023-07-01 "ncurses 6.4" "Library calls"
-.na
-.hy 0
+.\" $Id: curs_outopts.3x,v 1.56 2024/01/05 21:46:58 tom Exp $
+.TH curs_outopts 3X 2024-01-05 "ncurses 6.4" "Library calls"
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
.SH NAME
-\fBclearok\fP,
-\fBidlok\fP,
-\fBidcok\fP,
-\fBimmedok\fP,
-\fBleaveok\fP,
-\fBsetscrreg\fP,
-\fBwsetscrreg\fP,
-\fBscrollok\fP \- \fBcurses\fP output options
-.ad
-.hy
+\fB\%clearok\fP,
+\fB\%idlok\fP,
+\fB\%idcok\fP,
+\fB\%immedok\fP,
+\fB\%leaveok\fP,
+\fB\%setscrreg\fP,
+\fB\%wsetscrreg\fP,
+\fB\%scrollok\fP \-
+set \fIcurses\fR output options
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint clearok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
-\fBint idlok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
-\fBvoid idcok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
-\fBvoid immedok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
-\fBint leaveok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
-\fBint scrollok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.sp
-\fBint setscrreg(int \fItop\fB, int \fIbot\fB);\fR
-.br
-\fBint wsetscrreg(WINDOW *\fIwin\fB, int \fItop\fB, int \fIbot\fB);\fR
+.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);
+\fBvoid immedok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint leaveok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint scrollok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+.PP
+\fBint setscrreg(int \fItop\fP, int \fIbot\fP);
+\fBint wsetscrreg(WINDOW *\fIwin\fP, int \fItop\fP, int \fIbot\fP);
+.fi
.SH DESCRIPTION
These routines set options that change the style of output within
\fBcurses\fP.
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 as argument\fP, any change
-in the window image, such as the ones caused by \fBwaddch, wclrtobot, wscrl\fP,
-etc., automatically cause a call to \fBwrefresh\fP.
-However, it may
-degrade performance considerably, due to repeated calls to \fBwrefresh\fP.
-It is disabled by default.
+If \fBimmedok\fP is called with \fBTRUE\fP as second argument,
+any change in the window image,
+such as the ones caused by \fBwaddch, wclrtobot, wscrl\fP,
+etc., automatically causes a call to \fBwrefresh\fP.
+However, it may degrade performance considerably,
+due to repeated calls to \fBwrefresh\fP.
+Calling \fBimmedok\fP with \fBFALSE\fP as second argument
+restores the default behavior,
+i.e., deferring screen updates until a refresh is needed.
.SS leaveok
Normally, the hardware cursor is left at the location of the window cursor
being refreshed.
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
X/Open does not define any error conditions.
This implementation returns an error
if the window pointer is null.
+.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 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.
+From the outset,
+\fI\%ncurses\fP 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)
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
+\fBnl\fP/\fBnonl\fP were amended after \fI\%ncurses\fP 6.2
to eliminate their effect on output.
.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
+XSI Curses does not require this, and \fI\%ncurses\fP avoids doing
it to perform better vertical-motion optimization at \fBwrefresh\fP
time.
.PP
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 SEE ALSO
-.na
-\fBcurses\fP(3X),
-\fBcurs_addch\fP(3X),
-\fBcurs_clear\fP(3X),
-\fBcurs_initscr\fP(3X),
-\fBcurs_scroll\fP(3X),
-\fBcurs_refresh\fP(3X),
-\fBcurs_variables\fP(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_clear\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_scroll\fP(3X),
+\fB\%curs_variables\fP(3X)
projects / ncurses.git / blobdiff