X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_outopts.3x;h=4f90611bbdcc63bba975ab3e722d50df7738f2da;hb=16fbf3f4f7d96b6ee6bf9159b22f26e05962aa3d;hp=30906151abc3f0e874e77ece3a19a628544b1578;hpb=661078ddbde3ce0f3b06e95642fbb9b5fef7dca1;p=ncurses.git diff --git a/man/curs_outopts.3x b/man/curs_outopts.3x index 30906151..4f90611b 100644 --- a/man/curs_outopts.3x +++ b/man/curs_outopts.3x @@ -1,140 +1,223 @@ -.\" $Id: curs_outopts.3x,v 1.10 1998/02/07 21:56:39 tom Exp $ +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_outopts.3x,v 1.36 2022/02/12 20:05:11 tom Exp $ .TH curs_outopts 3X "" +.na +.hy 0 +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .SH NAME -\fBclearok\fR, \fBidlok\fR, \fBidcok immedok\fR, -\fBleaveok\fR, \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBscrollok\fR, -\fBnl\fR, \fBnonl\fR - \fBcurses\fR output options +\fBclearok\fP, +\fBidlok\fP, +\fBidcok\fP, +\fBimmedok\fP, +\fBleaveok\fP, +\fBsetscrreg\fP, +\fBwsetscrreg\fP, +\fBscrollok\fP \- \fBcurses\fP output options +.ad +.hy .SH SYNOPSIS -\fB#include \fR - -\fBint clearok(WINDOW *win, bool bf);\fR +\fB#include \fP +.sp +\fBint clearok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR .br -\fBint idlok(WINDOW *win, bool bf);\fR +\fBint idlok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR .br -\fBvoid idcok(WINDOW *win, bool bf);\fR +\fBvoid idcok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR .br -\fBvoid immedok(WINDOW *win, bool bf);\fR +\fBvoid immedok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR .br -\fBint leaveok(WINDOW *win, bool bf);\fR +\fBint leaveok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR .br -\fBint setscrreg(int top, int bot);\fR +\fBint scrollok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.sp +\fBint setscrreg(int \fItop\fB, int \fIbot\fB);\fR .br -\fBint wsetscrreg(WINDOW *win, int top, int bot);\fR -.br -\fBint scrollok(WINDOW *win, bool bf);\fR -.br -\fBint nl(void);\fR -.br -\fBint nonl(void);\fR +\fBint wsetscrreg(WINDOW *\fIwin\fB, int \fItop\fB, int \fIbot\fB);\fR .br .SH DESCRIPTION +.PP These routines set options that change the style of output within -\fBcurses\fR. All options are initially \fBFALSE\fR, unless otherwise stated. -It is not necessary to turn these options off before calling \fBendwin\fR. - -If \fBclearok\fR is called with \fBTRUE\fR as argument, the next -call to \fBwrefresh\fR 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 \fIwin\fR argument to \fBclearok\fR is the global variable \fBcurscr\fR, -the next call to \fBwrefresh\fR with any window causes the screen to be cleared +\fBcurses\fP. +All options are initially \fBFALSE\fP, unless otherwise stated. +It is not necessary to turn these options off before calling \fBendwin\fP(3X). +.SS clearok +.PP +If \fBclearok\fP is called with \fBTRUE\fP as argument, the next +call to \fBwrefresh\fP 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 \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. - -If \fBidlok\fR is called with \fBTRUE\fR as second argument, \fBcurses\fR +.SS idlok +.PP +If \fBidlok\fP is called with \fBTRUE\fP as second argument, \fBcurses\fP considers using the hardware insert/delete line feature of terminals so -equipped. Calling \fBidlok\fR with \fBFALSE\fR 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 +equipped. +Calling \fBidlok\fP with \fBFALSE\fP 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 isn't really needed. If insert/delete line -cannot be used, \fBcurses\fR redraws the changed portions of all lines. - -If \fBidcok\fR is called with \fBFALSE\fR as second argument, \fBcurses\fR +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 +.PP +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\fR with \fBTRUE\fR as second argument re-enables use +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. - -If \fBimmedok\fR is called with \fBTRUE as argument\fR, any change -in the window image, such as the ones caused by \fBwaddch, wclrtobot, wscrl\fR, -\fIetc\fR., automatically cause a call to \fBwrefresh\fR. However, it may -degrade performance considerably, due to repeated calls to \fBwrefresh\fR. +.SS immedok +.PP +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. - +.SS leaveok +.PP Normally, the hardware cursor is left at the location of the window cursor -being refreshed. The \fBleaveok\fR 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. If -possible, the cursor is made invisible when this option is enabled. - -The \fBsetscrreg\fR and \fBwsetscrreg\fR routines allow the application -programmer to set a software scrolling region in a window. \fItop\fR and -\fIbot\fR are the line numbers of the top and bottom margin of the scrolling -region. (Line 0 is the top line of the window.) If this option and -\fBscrollok\fR are enabled, an attempt to move off the bottom margin line +being refreshed. +The \fBleaveok\fP 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. +.SS scrollok +.PP +The \fBscrollok\fP 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 typing the last character of the last +line. +If disabled, (\fIbf\fP is \fBFALSE\fP), the cursor is left on the bottom +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 +.PP +The \fBsetscrreg\fP and \fBwsetscrreg\fP routines allow the application +programmer to set a software scrolling region in a window. +The \fItop\fP and +\fIbot\fP parameters +are the line numbers of the top and bottom margin of the scrolling +region. +(Line 0 is the top line of the window.) If this option and +\fBscrollok\fP 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. (Note that this +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 \fBidlok\fR is enabled and the terminal +terminal, like that in the VT100. +If \fBidlok\fP is enabled and the terminal has either a scrolling region or insert/delete line capability, they will probably be used by the output routines.) - -The \fBscrollok\fR 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 typing the last character of the last -line. If disabled, (\fIbf\fR is \fBFALSE\fR), the cursor is left on the bottom -line. If enabled, (\fIbf\fR is \fBTRUE\fR), the window is scrolled up one line -(Note that in order to get the physical scrolling effect on the terminal, it is -also necessary to call \fBidlok\fR). - -The \fBnl\fR and \fBnonl\fR routines control whether the underlying display -device translates the return key into newline on input, and whether it -translates newline into return and line-feed on output (in either case, the -call \fBaddch('\n')\fR does the equivalent of return and line feed on the -virtual screen). Initially, these translations do occur. If you disable them -using \fBnonl\fR, \fBcurses\fR will be able to make better use of the line-feed -capability, resulting in faster cursor motion. Also, \fBcurses\fR will then be -able to detect the return key. .SH RETURN VALUE -The functions \fBsetscrreg\fR and \fBwsetscrreg\fR return \fBOK\fR upon success -and \fBERR\fR upon failure. All other routines that return an integer always -return \fBOK\fR. +The functions \fBsetscrreg\fP and \fBwsetscrreg\fP return \fBOK\fP upon success +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. +.PP +In this implementation, +.bP +those functions that have a window pointer +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. +.RE +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null. .SH PORTABILITY These functions are described in the XSI Curses standard, Issue 4. - -The XSI Curses standard is ambiguous on the question of whether \fBraw\fR() -should disable the CRLF translations controlled by \fBnl\fR() and \fBnonl\fR(). -BSD curses did turn off these translations; AT&T curses (at least as late as -SVr1) did not. We choose to do so, on the theory that a programmer requesting -raw input wants a clean (ideally 8-bit clean) connection that the operating -system does not mess with. - +.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)\fR by saying -\fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR. This will not work under -ncurses. - -Earlier System V curses implementations specified that with \fBscrollok\fR +ability to do the equivalent of \fBclearok(..., 1)\fP by saying +\fBtouchwin(stdscr)\fP or \fBclear(stdscr)\fP. +This will not work under ncurses. +.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\fR avoids doing -it in order to perform better vertical-motion optimization at \fBwrefresh\fR +refresh. +XSI Curses does not require this, and \fBncurses\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 -made invisible as a side-effect of \fBleaveok\fR. -SVr4 curses does this. +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\fR, \fBleaveok\fR, \fBscrollok\fR, \fBidcok\fR, \fBnl\fR, -\fBnonl\fR and \fBsetscrreg\fR may be macros. - -The \fBimmedok\fR routine is useful for windows that are used as terminal +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 -\fBcurses\fR(3X), \fBcurs_addch\fR(3X), \fBcurs_clear\fR(3X), -\fBcurs_initscr\fR(3X), \fBcurs_scroll\fR(3X), \fBcurs_refresh\fR(3X) -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +.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).