Debian Codegraph @

upstream/debian-unstable/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.59 2025/04/05 22:20:39 tom Exp $
31 .TH scroll 3NCURSES 2025-04-05 "ncurses 6.6" "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 (for functions taking a
126 .I \%WINDOW
127 pointer argument)
128 .I win
129 is a null pointer,
130 or
131 .bP
132 scrolling is not enabled in the window
133 (as by \fB\%scrollok\fP(3NCURSES)).
134 .SH NOTES
135 .B \%scroll
136 and
137 .B \%scrl
138 may be implemented as macros.
139 .PP
140 Unusually,
141 there is no
142 .B \%wscroll
143 function;
144 .B scroll
145 behaves as one would expect
146 .B \%wscroll
147 to,
148 accepting a
149 .I \%WINDOW
150 pointer argument.
151 .SH PORTABILITY
152 X/Open Curses Issue\ 4 describes these functions.
153 It specifies no error conditions for them.
154 .PP
155 SVr4 describes a successful return value only as
156 \*(``an integer value other than
157 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 531
158 .PP
159 SVr4 indicates that the optimization of physically scrolling immediately
160 if the scroll region is the entire screen \*(``is\*('' performed,
161 not \*(``may be\*('' performed.
162 .I \%ncurses
163 deliberately does not guarantee that this occurs,
164 to leave open the possibility of better optimization of multiple scroll
165 actions on the next update.
166 .PP
167 Neither SVr4
168 .I curses
169 nor X/Open Curses specify whether these functions zero the attributes or
170 color pair identifier of the background character.
171 In
172 .IR \%ncurses ","
173 they do not.
174 .SH HISTORY
175 4BSD (1980)
176 introduced
177 .IR scroll ","
178 defining it as a function.
179 .PP
180 SVr3.1 (1987)
181 added
182 .I \%scrl
183 and
184 .IR \%wscrl ","
185 redefining
186 .I \%scroll
187 as a macro wrapping the latter.
188 .SH SEE ALSO
189 \fB\%ncurses\fP(3NCURSES),
190 \fB\%outopts\fP(3NCURSES)