***************************************************************************
Copyright 2018-2023,2024 Thomas E. Dickey *
Copyright 1998-2006,2010 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_scroll.3x,v 1.43 2024/04/20 18:54:36 tom Exp $
.\} .\} . .. \%scroll, \%scrl, \%wscrl - scroll a curses window

#include <curses.h>

int scroll(WINDOW *win);

int scrl(int n);
int wscrl(WINDOW *win, int n);

scroll scrolls the given window up one line. That is, every visible line we might number i becomes line i "-1." The text of the top line in the window disappears and the bottom line is populated with blank characters; see \%bkgd(3X) or \%bkgrnd(3X). As an optimization, if the scrolling region of the window is the entire screen, the physical screen may be scrolled at the same time; see \%curscr(3X).

\%scrl and \%wscrl scroll \%stdscr or the specified window up or down depending on the sign of n . .bP For positive n , line i+n becomes i (scrolling up); .bP for negative n , line i-n becomes i (scrolling down).

The cursor does not move. These functions perform no operation unless scrolling is enabled for the window via \%scrollok(3X).

These functions return ERR upon failure and OK upon success.

\%ncurses returns ERR if scrolling is not enabled in the window, for example with \%scrollok(3X), or if the \%WINDOW pointer is null.

Unusually, there is no \%wscroll function; scroll behaves as one would expect \%wscroll to, accepting a \%WINDOW pointer argument.

\%scrl and \%scroll may be implemented as macros.

X/Open Curses, Issue 4 describes these functions. It defines no error conditions.

SVr4 specifies only \*(``an integer value other than ERR\*('' as a successful return value.

SVr4 indicates that the optimization of physically scrolling immediately if the scroll region is the entire screen \*(``is\*('' performed, not \*(``may be\*('' performed. \%ncurses deliberately does not guarantee that this will occur, to leave open the possibility of smarter optimization of multiple scroll actions on the next update.

Neither SVr4 curses nor X/Open Curses specify whether the current attribute or current color pair of blanks generated by the scroll function are zeroed. \%ncurses does so.

\%curses(3X), \%curs_outopts(3X)