1.\" $NetBSD: curses_scroll.3,v 1.6 2025/01/01 00:29:18 jnemeth Exp $ 2.\" 3.\" Copyright (c) 2002 4.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) 5.\" 6.\" This code is donated to the NetBSD Foundation by the Author. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of the Author may not be used to endorse or promote 17.\" products derived from this software without specific prior written 18.\" permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" 33.Dd December 31, 2024 34.Dt CURSES_SCROLL 3 35.Os 36.Sh NAME 37.Nm curses_scroll , 38.Nm getscrreg , 39.Nm scrl , 40.Nm wscrl 41.Nm scroll , 42.Nm scrollok , 43.Nm setscrreg , 44.Nm wgetscrreg 45.Nm wsetscrreg 46.Nd curses window scrolling routines 47.Sh LIBRARY 48.Lb libcurses 49.Sh SYNOPSIS 50.In curses.h 51.Ft int 52.Fn getscrreg "int *top" "int *bottom" 53.Ft int 54.Fn scrl "int n" 55.Ft int 56.Fn wscrl "WINDOW *win" "int n" 57.Ft int 58.Fn scroll "WINDOW *win" 59.Ft int 60.Fn scrollok "WINDOW *win" "boolf flag" 61.Ft int 62.Fn setscrreg "int top" "int bottom" 63.Ft int 64.Fn wgetscrreg "WINDOW *win" "int *top" "int *bottom" 65.Ft int 66.Fn wsetscrreg "WINDOW *win" "int top" "int bottom" 67.Sh DESCRIPTION 68The 69.Fn getscrreg 70function gets the software scrolling region lines on 71.Dv stdscr 72which defines a region of the screen that will be scrolled. 73.Pp 74These functions scroll areas on 75.Dv stdscr 76or on the specified window. 77.Pp 78The 79.Fn scrl 80function scrolls 81.Dv stdscr 82by 83.Fa n 84lines. 85If 86.Fa n 87is positive then then 88.Dv stdscr 89is scrolled up. 90.Fa n 91lines are lost from the top of 92.Dv stdscr 93and 94.Fa n 95blank lines are inserted at the bottom. 96If 97.Fa n 98is negative then 99.Dv stdscr 100is scrolled down. 101.Fa n 102blank lines are inserted at the top of 103.Dv stdscr 104and 105.Fa n 106lines are lost from the bottom. 107.Pp 108The 109.Fn wscrl 110function is the same as the 111.Fn scrl 112function, excepting that it scrolls the window specified by 113.Fa win . 114.Pp 115The 116.Fn scroll 117function scrolls the window 118.Fa win 119up by one line. 120.Pp 121The scrolling behaviour of a window can be controlled by using the 122.Fn scrollok 123function. 124If the 125.Fa flag 126argument is 127.Dv TRUE 128then a line wrap at the bottom of the window will cause the window to 129be scrolled up one line, if 130.Fa flag 131is 132.Dv FALSE 133then lines that would force a scroll will be truncated. 134.Pp 135The 136.Fn setscrreg 137function sets up a software scrolling region on 138.Dv stdscr 139which will define a region of the screen that will be scrolled. 140The scrolling of this region is also controlled by the 141.Fn scrollok 142function. 143.Pp 144The 145.Fn wgetscrreg 146function does the same as the 147.Fn getscrreg 148function, except that the scrolling region is retrieved from the window 149specified by 150.Fa win . 151.Pp 152The 153.Fn wsetscrreg 154function does the same as the 155.Fn setscrreg 156function, except that the scrolling region is set on the window specified by 157.Fa win . 158.Pp 159If a scrolling region has been set with the 160.Fn setscrreg 161or 162.Fn wsetscrreg 163functions and the current cursor position is inside the scrolling region, 164then only the area inside the scrolling region is scrolled. 165.Sh RETURN VALUES 166Functions returning pointers will return 167.Dv NULL 168if an error is detected. 169The functions that return an int will return one of the following 170values: 171.Pp 172.Bl -tag -width ERR -compact 173.It Er OK 174The function completed successfully. 175.It Er ERR 176An error occurred in the function. 177.El 178.Sh SEE ALSO 179.Xr curses_deleteln 3 , 180.Xr curses_insdelln 3 , 181.Xr curses_insertln 3 182.Sh STANDARDS 183The 184.Nx 185Curses library complies with the X/Open Curses specification, part of the 186Single Unix Specification. 187.Sh HISTORY 188The Curses package appeared in 189.Bx 4.0 . 190