X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_outopts.3x;h=0e20a801f8405e75380fa4a2f44037834bd3a619;hb=75a9c36c205ebefe07580acd0b1053a2abbd44b9;hp=3f0bfdaee8c35cbb29209af3741c51a4122fee78;hpb=7e062bb2764a87d98073a90ee65a234a2679f9c1;p=ncurses.git diff --git a/man/curs_outopts.3x b/man/curs_outopts.3x index 3f0bfdae..0e20a801 100644 --- a/man/curs_outopts.3x +++ b/man/curs_outopts.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" 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 * @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_outopts.3x,v 1.46 2023/09/30 21:38:11 tom Exp $ -.TH curs_outopts 3X 2023-09-30 "ncurses 6.4" "Library calls" +.\" $Id: curs_outopts.3x,v 1.60 2024/04/13 22:23:57 tom Exp $ +.TH curs_outopts 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 @@ -44,23 +44,19 @@ \fB\%scrollok\fP \- set \fIcurses\fR output options .SH SYNOPSIS -\fB#include \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 +.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. @@ -97,12 +93,15 @@ 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 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. @@ -120,7 +119,7 @@ line. 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 @@ -144,7 +143,7 @@ and \fBERR\fP upon failure. 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 @@ -153,35 +152,28 @@ 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. +.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. -.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 @@ -189,21 +181,18 @@ The XSI Curses standard 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), \fB\%curs_clear\fP(3X), \fB\%curs_initscr\fP(3X), -\fB\%curs_scroll\fP(3X), \fB\%curs_refresh\fP(3X), +\fB\%curs_scroll\fP(3X), \fB\%curs_variables\fP(3X)