Debian Codegraph @

upstream/debian-trixie/man3/scroll.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2006,2010 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_scroll.3x,v 1.57 2025/02/02 00:02:49 tom Exp $
31 .TH scroll 3NCURSES 2025-02-01 "ncurses 6.5" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%scroll\fP,
49 \fB\%scrl\fP,
50 \fB\%wscrl\fP \-
51 scroll a \fIcurses\fP window
52 .SH SYNOPSIS
53 .nf
54 \fB#include <curses.h>
55 .PP
56 \fBint scroll(WINDOW * \fIwin\fP);
57 .PP
58 \fBint scrl(int \fIn\fP);
59 \fBint wscrl(WINDOW * \fIwin\fP, int \fIn\fP);
60 .fi
61 .SH DESCRIPTION
62 .B scroll
63 scrolls the given window up one line.
64 That is,
65 every visible line we might number
66 .I i
67 becomes line
68 .IR i "\-1."
69 .B \%wscrl
70 and
71 .B \%scrl
72 scroll the specified window or
73 .BR \%stdscr ","
74 respectively,
75 up or down per the sign of
76 .IR n "."
77 .bP
78 For positive
79 .IR n ","
80 line
81 .IR i + n
82 becomes
83 .I i
84 (scrolling up);
85 .bP
86 for negative
87 .IR n ","
88 line
89 .IR i \- n
90 becomes
91 .I i
92 (scrolling down).
93 .PP
94 A line that scrolls beyond the window boundaries disappears;
95 .I curses
96 populates a new one emerging at the opposite boundary
97 with the background character;
98 see \fB\%bkgd\fP(3NCURSES)
99 (wide-character API users: \fB\%bkgrnd\fP(3NCURSES)).
100 As an optimization,
101 if the scrolling region of the window is the entire screen,
102 the physical screen may be scrolled at the same time;
103 see \fB\%curscr\fP(3NCURSES).
104 .PP
105 The cursor does not move.
106 These functions perform no operation unless scrolling is enabled for the
107 window via \fB\%scrollok\fP(3NCURSES).
108 .SH "RETURN VALUE"
109 These functions return
110 .B ERR
111 upon failure and
112 .B OK
113 upon success.
114 .PP
115 In
116 .IR \%ncurses ","
117 they return
118 .B ERR
119 if
120 .bP
121 the
122 .I curses
123 screen has not been initialized,
124 .bP
125 .I win
126 is a null pointer,
127 or
128 .bP
129 scrolling is not enabled in the window
130 (as by \fB\%scrollok\fP(3NCURSES)).
131 .SH NOTES
132 .B \%scroll
133 and
134 .B \%scrl
135 may be implemented as macros.
136 .PP
137 Unusually,
138 there is no
139 .B \%wscroll
140 function;
141 .B scroll
142 behaves as one would expect
143 .B \%wscroll
144 to,
145 accepting a
146 .I \%WINDOW
147 pointer argument.
148 .SH PORTABILITY
149 X/Open Curses Issue\ 4 describes these functions.
150 It specifies no error conditions for them.
151 .PP
152 SVr4 describes a successful return value only as
153 \*(``an integer value other than
154 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 531
155 .PP
156 SVr4 indicates that the optimization of physically scrolling immediately
157 if the scroll region is the entire screen \*(``is\*('' performed,
158 not \*(``may be\*('' performed.
159 .I \%ncurses
160 deliberately does not guarantee that this occurs,
161 to leave open the possibility of better optimization of multiple scroll
162 actions on the next update.
163 .PP
164 Neither SVr4
165 .I curses
166 nor X/Open Curses specify whether these functions zero the attributes or
167 color pair identifier of the background character.
168 In
169 .IR \%ncurses ","
170 they do not.
171 .SH HISTORY
172 4BSD (1980)
173 introduced
174 .IR scroll ","
175 defining it as a function.
176 .PP
177 SVr3.1 (1987)
178 added
179 .I \%scrl
180 and
181 .IR \%wscrl ","
182 redefining
183 .I \%scroll
184 as a macro wrapping the latter.
185 .SH SEE ALSO
186 \fB\%ncurses\fP(3NCURSES),
187 \fB\%outopts\fP(3NCURSES)