diff options
Diffstat (limited to 'man/curs_scroll.3x')
| -rw-r--r-- | man/curs_scroll.3x | 143 |
1 files changed, 98 insertions, 45 deletions
diff --git a/man/curs_scroll.3x b/man/curs_scroll.3x index 16d5a501094f..aa9fdb8e4f54 100644 --- a/man/curs_scroll.3x +++ b/man/curs_scroll.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 2018-2024,2025 Thomas E. Dickey * .\" Copyright 1998-2006,2010 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_scroll.3x,v 1.43 2024/04/20 18:54:36 tom Exp $ -.TH curs_scroll 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.\" $Id: curs_scroll.3x,v 1.59 2025/04/05 22:20:39 tom Exp $ +.TH curs_scroll 3X 2025-04-05 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -48,43 +48,59 @@ \fB\%scroll\fP, \fB\%scrl\fP, \fB\%wscrl\fP \- -scroll a \fIcurses\fR window +scroll a \fIcurses\fP window .SH SYNOPSIS .nf \fB#include <curses.h> .PP -\fBint scroll(WINDOW *\fIwin\fP); +\fBint scroll(WINDOW * \fIwin\fP); .PP \fBint scrl(int \fIn\fP); -\fBint wscrl(WINDOW *\fIwin\fP, int \fIn\fP); +\fBint wscrl(WINDOW * \fIwin\fP, int \fIn\fP); .fi .SH DESCRIPTION -\fBscroll\fP scrolls the given window up one line. +.B scroll +scrolls the given window up one line. That is, every visible line we might number .I i becomes line .IR i "\-1." -The text of the top line in the window disappears and the bottom line -is populated with blank characters; -see \fB\%bkgd\fP(3X) or \fB\%bkgrnd\fP(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 \fB\%curscr\fP(3X). -.PP -\fB\%scrl\fP and \fB\%wscrl\fP scroll -.B \%stdscr -or the specified window up or down depending on the sign of -.IR n . +.B \%wscrl +and +.B \%scrl +scroll the specified window or +.BR \%stdscr "," +respectively, +up or down per the sign of +.IR n "." .bP For positive -.IR n , -line \fIi\fP+\fIn\fP becomes \fIi\fP (scrolling up); +.IR n "," +line +.IR i + n +becomes +.I i +(scrolling up); .bP for negative -.IR n , -line \fIi\fP-\fIn\fP becomes \fIi\fP (scrolling down). +.IR n "," +line +.IR i \- n +becomes +.I i +(scrolling down). +.PP +A line that scrolls beyond the window boundaries disappears; +.I curses +populates a new one emerging at the opposite boundary +with the background character; +see \fB\%bkgd\fP(3X) +(wide-character API users: \fB\%bkgrnd\fP(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 \fB\%curscr\fP(3X). .PP The cursor does not move. These functions perform no operation unless scrolling is enabled for the @@ -96,42 +112,79 @@ upon failure and .B OK upon success. .PP -.I \%ncurses -returns \fBERR\fP if scrolling is not enabled in the window, -for example with \fB\%scrollok\fP(3X), -or if the +In +.IR \%ncurses "," +they return +.B ERR +if +.bP +the +.I curses +screen has not been initialized, +.bP +(for functions taking a .I \%WINDOW -pointer is null. +pointer argument) +.I win +is a null pointer, +or +.bP +scrolling is not enabled in the window +(as by \fB\%scrollok\fP(3X)). .SH NOTES -Unusually, -there is no \fB\%wscroll\fP function; -\fBscroll\fP behaves as one would expect \fB\%wscroll\fP to, -accepting a \fI\%WINDOW\fP pointer argument. +.B \%scroll +and +.B \%scrl +may be implemented as macros. .PP -\fB\%scrl\fP and \fB\%scroll\fP may be implemented as macros. +Unusually, +there is no +.B \%wscroll +function; +.B scroll +behaves as one would expect +.B \%wscroll +to, +accepting a +.I \%WINDOW +pointer argument. .SH PORTABILITY -X/Open Curses, -Issue 4 describes these functions. -It defines no error conditions. +X/Open Curses Issue\ 4 describes these functions. +It specifies no error conditions for them. .PP -SVr4 specifies only -\*(``an integer value other than \fBERR\fP\*('' as a successful return -value. +SVr4 describes a successful return value only as +\*(``an integer value other than +.IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 531 .PP SVr4 indicates that the optimization of physically scrolling immediately if the scroll region is the entire screen \*(``is\*('' performed, not \*(``may be\*('' performed. .I \%ncurses -deliberately does not guarantee that this will occur, -to leave open the possibility of smarter optimization of multiple scroll +deliberately does not guarantee that this occurs, +to leave open the possibility of better optimization of multiple scroll actions on the next update. .PP Neither SVr4 .I curses -nor X/Open Curses specify whether the current attribute or current color -pair of blanks generated by the scroll function are zeroed. -.I \%ncurses -does so. +nor X/Open Curses specify whether these functions zero the attributes or +color pair identifier of the background character. +In +.IR \%ncurses "," +they do not. +.SH HISTORY +4BSD (1980) +introduced +.IR scroll "," +defining it as a function. +.PP +SVr3.1 (1987) +added +.I \%scrl +and +.IR \%wscrl "," +redefining +.I \%scroll +as a macro wrapping the latter. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_outopts\fP(3X) |