Debian Codegraph @

upstream/debian-unstable/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.65 2025/10/20 23:42:24 tom Exp $
31 .TH border 3NCURSES 2025-10-20 "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\%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 \fBaddch\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 verch ,
154 .IB horch ,
155 .IB horch ,
156 .BR "0, 0, 0, 0)" "\*(''."
157 .PP
158 .B \%whline
159 draws a horizontal line of
160 .I ch
161 from left to right,
162 and
163 .B \%wvline
164 a vertical one from top to bottom,
165 stopping once
166 .I n
167 characters have been drawn or upon reaching the boundary of
168 .IR win "."
169 These functions do not update the cursor position
170 (beyond any motion directed by their \*(``mv\*('' variants).
171 \fB\%ncurses\fP(3NCURSES) describes the variants of these functions.
172 .SH RETURN VALUE
173 These functions return
174 .B OK
175 on success and
176 .B ERR
177 on failure.
178 .PP
179 In
180 .IR \%ncurses ","
181 .bP
182 these functions fail if the screen is not initialized;
183 and
184 .bP
185 functions taking a
186 .I \%WINDOW
187 pointer argument fail if
188 .I win
189 is a null pointer.
190 .PP
191 Functions prefixed with \*(``mv\*('' first perform cursor movement and
192 fail if the position
193 .RI ( y ,
194 .IR x )
195 is outside the window boundaries.
196 .SH NOTES
197 Unusually,
198 there is no
199 .B \%wbox
200 function;
201 .B \%box
202 behaves as one would expect
203 .B \%wbox
204 to,
205 accepting a
206 .I \%WINDOW
207 pointer argument.
208 .PP
209 .BR \%border ","
210 .BR \%box ","
211 .BR \%hline ","
212 .BR \%mvhline ","
213 .BR \%mvwhline ","
214 .BR \%vline ","
215 .BR \%mvvline ","
216 and
217 .B \%mvwvline
218 may be implemented as macros.
219 .PP
220 Borders drawn by these functions are
221 .I interior
222 borders.
223 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/libcurses/box.c
224 .SH PORTABILITY
225 These functions are described in X/Open Curses Issue\ 4.
226 It specifies no error conditions for them.
227 .PP
228 SVr4 documentation
229 .\" SVID 4, vol. 3, p. 483
230 says that these functions return
231 .I OK
232 \*(``or a non-negative integer if
233 .I \%immedok() \" Courier roman in source
234 is set\*('',
235 referring to the return value from
236 .IR \%wrefresh ","
237 which in SVr4 returns a count of characters
238 written to the window if its
239 .I \%immedok
240 property is set;
241 .\" ...though its wrefresh() man page says nothing about immedok()...
242 in
243 .IR \%ncurses ","
244 it does not.
245 .PP
246 BSD
247 .I curses
248 drew boxes with
249 .I horch
250 in
251 .I every
252 character cell of the top and bottom lines of the window,
253 whereas SVr3.1 and later
254 .IR curses ","
255 because its
256 .I box
257 wrapped
258 .IR wborder ","
259 used the default corner characters.
260 .\" https://github.com/ryanwoodsmall/oldsysv/blob/master/sysvr3/31/\
261 .\" usr/src/lib/libcurses/screen/curses.ed#L454
262 .SH HISTORY
263 4BSD (1980)
264 introduced
265 .IR box ","
266 defining it as a function.
267 .PP
268 SVr3.1 (1987)
269 added
270 .I \%whline
271 and
272 .I \%wvline
273 and their variants,
274 as well as
275 .I \%border
276 and
277 .IR \%wborder ","
278 redefining
279 .I \%box
280 as a macro wrapping the latter.
281 .SH SEE ALSO
282 \fB\%ncurses\fP(3NCURSES),
283 \fB\%outopts\fP(3NCURSES)