Debian Codegraph @

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

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2007,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_border.3x,v 1.63 2025/02/02 00:00:33 tom Exp $
31 .TH border 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\%border\fP,
49 \fB\%wborder\fP,
50 \fB\%box\fP,
51 \fB\%hline\fP,
52 \fB\%whline\fP,
53 \fB\%vline\fP,
54 \fB\%wvline\fP,
55 \fB\%mvhline\fP,
56 \fB\%mvwhline\fP,
57 \fB\%mvvline\fP,
58 \fB\%mvwvline\fP \-
59 draw borders and lines in a \fIcurses\fR window of characters
60 .SH SYNOPSIS
61 .nf
62 \fB#include <curses.h>
63 .PP
64 \fBint border(chtype \fIls\fP, chtype \fIrs\fP, chtype \fIts\fP, chtype \fIbs\fP,
65 \fBchtype \fItl\fB, chtype \fItr\fB, chtype \fIbl\fB, chtype \fIbr\fB);\fR
66 \fBint wborder(WINDOW *\fIwin\fB, chtype \fIls\fB, chtype \fIrs\fB,\fR
67 \fBchtype \fIts\fB, chtype \fIbs\fB, chtype \fItl\fB, chtype \fItr\fB,\fR
68 \fBchtype \fIbl\fB, chtype \fIbr\fB);\fR
69 .PP
70 \fBint box(WINDOW *\fIwin\fB, chtype \fIverch\fB, chtype \fIhorch\fB);\fR
71 .PP
72 \fBint hline(chtype \fIch\fB, int \fIn\fB);\fR
73 \fBint whline(WINDOW *\fIwin\fB, chtype \fIch\fB, int \fIn\fB);\fR
74 \fBint mvhline(int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR
75 \fBint mvwhline(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR
76 .PP
77 \fBint vline(chtype \fIch\fB, int \fIn\fB);\fR
78 \fBint wvline(WINDOW *\fIwin\fB, chtype \fIch\fB, int \fIn\fB);\fR
79 \fBint mvvline(int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR
80 \fBint mvwvline(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR
81 .fi
82 .SH DESCRIPTION
83 .B \%wborder
84 and
85 .B \%border
86 draw a box at the edges of the specified window or
87 .BR \%stdscr ","
88 respectively.
89 Each
90 .I \%chtype
91 argument corresponds to a geometric component of the border as follows:
92 .RS
93 .I ls
94 \- left side,
95 .br
96 .I rs
97 \- right side,
98 .br
99 .I ts
100 \- top side,
101 .br
102 .I bs
103 \- bottom side,
104 .br
105 .I tl
106 \- top left-hand corner,
107 .br
108 .I tr
109 \- top right-hand corner,
110 .br
111 .I bl
112 \- bottom left-hand corner, and
113 .br
114 .I br
115 \- bottom right-hand corner.
116 .RE
117 .PP
118 If any
119 .I \%chtype
120 argument is
121 .BR 0 ","
122 then
123 .I curses
124 uses forms-drawing characters
125 (see \fB\%addch\fP(3NCURSES))
126 in the following correspondence:
127 .RS
128 .BR \%ACS_VLINE ","
129 .br
130 .BR \%ACS_VLINE ","
131 .br
132 .BR \%ACS_HLINE ","
133 .br
134 .BR \%ACS_HLINE ","
135 .br
136 .BR \%ACS_ULCORNER ","
137 .br
138 .BR \%ACS_URCORNER ","
139 .br
140 .BR \%ACS_LLCORNER ","
141 and
142 .br
143 .BR \%ACS_LRCORNER "."
144 .RE
145 .PP
146 .BI \%box( win ","
147 .IB verch ,
148 .IB horch )
149 is shorthand for
150 .RB \%\*(`` wborder(\c
151 .IB win ,
152 .IB verch ,
153 .IB horch ,
154 .BR "0, 0, 0, 0)" "\*(''."
155 .PP
156 .B \%whline
157 draws a horizontal line of
158 .I ch
159 from left to right,
160 and
161 .B \%wvline
162 a vertical one from top to bottom,
163 stopping once
164 .I n
165 characters have been drawn or upon reaching the boundary of
166 .IR win "."
167 These functions do not update the cursor position
168 (beyond any motion directed by their \*(``mv\*('' variants).
169 \fB\%ncurses\fP(3NCURSES) describes the variants of these functions.
170 .SH RETURN VALUE
171 These functions return
172 .B OK
173 on success and
174 .B ERR
175 on failure.
176 .PP
177 In
178 .IR \%ncurses ","
179 .bP
180 these functions fail if the screen is not initialized;
181 and
182 .bP
183 functions taking a
184 .I \%WINDOW
185 pointer argument fail if
186 .I win
187 is a null pointer.
188 .PP
189 Functions prefixed with \*(``mv\*('' first perform cursor movement and
190 fail if the position
191 .RI ( y ,
192 .IR x )
193 is outside the window boundaries.
194 .SH NOTES
195 Unusually,
196 there is no
197 .B \%wbox
198 function;
199 .B \%box
200 behaves as one would expect
201 .B \%wbox
202 to,
203 accepting a
204 .I \%WINDOW
205 pointer argument.
206 .PP
207 .BR \%border ","
208 .BR \%box ","
209 .BR \%hline ","
210 .BR \%mvhline ","
211 .BR \%mvwhline ","
212 .BR \%vline ","
213 .BR \%mvvline ","
214 and
215 .B \%mvwvline
216 may be implemented as macros.
217 .PP
218 Borders drawn by these functions are
219 .I interior
220 borders.
221 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/libcurses/box.c
222 .SH PORTABILITY
223 These functions are described in X/Open Curses Issue\ 4.
224 It specifies no error conditions for them.
225 .PP
226 SVr4 documentation
227 .\" SVID 4, vol. 3, p. 483
228 says that these functions return
229 .I OK
230 \*(``or a non-negative integer if
231 .I \%immedok() \" Courier roman in source
232 is set\*('',
233 referring to the return value from
234 .IR \%wrefresh ","
235 which in SVr4 returns a count of characters
236 written to the window if its
237 .I \%immedok
238 property is set;
239 .\" ...though its wrefresh() man page says nothing about immedok()...
240 in
241 .IR \%ncurses ","
242 it does not.
243 .PP
244 BSD
245 .I curses
246 drew boxes with
247 .I horch
248 in
249 .I every
250 character cell of the top and bottom lines of the window,
251 whereas SVr3.1 and later
252 .IR curses ","
253 because its
254 .I box
255 wrapped
256 .IR wborder ","
257 used the default corner characters.
258 .\" https://github.com/ryanwoodsmall/oldsysv/blob/master/sysvr3/31/\
259 .\" usr/src/lib/libcurses/screen/curses.ed#L454
260 .SH HISTORY
261 4BSD (1980)
262 introduced
263 .IR box ","
264 defining it as a function.
265 .PP
266 SVr3.1 (1987)
267 added
268 .I \%whline
269 and
270 .I \%wvline
271 and their variants,
272 as well as
273 .I \%border
274 and
275 .IR \%wborder ","
276 redefining
277 .I \%box
278 as a macro wrapping the latter.
279 .SH SEE ALSO
280 \fB\%ncurses\fP(3NCURSES),
281 \fB\%outopts\fP(3NCURSES)