xref: /minix3/lib/libcurses/curses_pad.3 (revision 51ffecc181005cb45a40108612ee28d1daaeeb86)
1.\"	$NetBSD: curses_pad.3,v 1.4 2008/04/30 13:10:51 martin Exp $
2.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
3.\" All rights reserved.
4.\"
5.\" This code is derived from software contributed to The NetBSD Foundation
6.\" by Julian Coleman.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
17.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
18.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26.\" POSSIBILITY OF SUCH DAMAGE.
27.\"
28.Dd December 4, 2002
29.Dt CURSES_PAD 3
30.Os
31.Sh NAME
32.Nm curses_pad ,
33.Nm newpad ,
34.Nm subpad ,
35.Nm prefresh ,
36.Nm pnoutrefresh
37.Nd curses pad routines
38.Sh LIBRARY
39.Lb libcurses
40.Sh SYNOPSIS
41.In curses.h
42.Ft WINDOW *
43.Fn newpad "int lines" "int cols"
44.Ft WINDOW *
45.Fn subpad "WINDOW *pad" "int lines" "int cols" "int begin_y" "int begin_x"
46.Ft int
47.Fn prefresh "WINDOW *pad" "int pbeg_y" "int pbeg_x" "int sbeg_y" "int sbeg_x" "int smax_y" "int smax_x"
48.Ft int
49.Fn pnoutrefresh "WINDOW *pad" "int pbeg_y" "int pbeg_x" "int sbeg_y" "int sbeg_x" "int smax_y" "int smax_x"
50.Sh DESCRIPTION
51These functions create and display pads on the current screen.
52.Pp
53The
54.Fn newpad
55function creates a new pad of size
56.Fa lines ,
57.Fa cols .
58.Pp
59.Fn subpad
60is similar to
61.Fn newpad
62excepting that the size of the subpad is bounded by the parent
63pad
64.Fa pad .
65The subpad shares internal data structures with the parent pad
66and will be refreshed when the parent pad is refreshed.
67The starting column and row
68.Fa begin_y ,
69.Fa begin_x
70are relative to the parent pad origin.
71.Pp
72The
73.Fn pnoutrefresh
74function performs the internal processing required by curses to determine
75what changes need to be made to synchronise the internal screen buffer
76and the terminal but does not modify the terminal display.
77A rectangular area of the pad starting at column and row
78.Fa pbeg_y ,
79.Fa pbeg_x
80is copied to the corresponding rectangular area of the screen buffer starting
81at column and row
82.Fa sbeg_y ,
83.Fa sbeg_x
84and extending to
85.Fa smax_y ,
86.Fa smax_x .
87.Pp
88The
89.Fn prefresh
90function causes curses to propagate changes made to the pad specified by
91.Fa pad
92to the terminal display.
93A rectangular area of the pad starting at column and row
94.Fa pbeg_y ,
95.Fa pbeg_x
96is copied to the corresponding rectangular area of the terminal starting
97at column and row
98.Fa sbeg_y ,
99.Fa sbeg_x
100and extending to
101.Fa smax_y ,
102.Fa smax_x .
103.Pp
104The
105.Fn pnoutrefresh
106and
107.Fn doupdate
108functions can be used together to speed up terminal redraws by
109deferring the actual terminal updates until after a batch of updates
110to multiple pads has been done.
111.Sh RETURN VALUES
112Functions returning pointers will return
113.Dv NULL
114if an error is detected.
115The functions that return an int will return one of the following
116values:
117.Pp
118.Bl -tag -width ERR -compact
119.It Er OK
120The function completed successfully.
121.It Er ERR
122An error occurred in the function.
123.El
124.Sh SEE ALSO
125.Xr curses_refresh 3 ,
126.Xr curses_window 3
127.Sh NOTES
128The
129.Fn subpad
130function is similar to the
131.Xr derwin 3
132function, and not the
133.Xr subwin 3
134function.
135.Sh STANDARDS
136The
137.Nx
138Curses library complies with the X/Open Curses specification, part of the
139Single Unix Specification.
140.Sh HISTORY
141The Curses package appeared in
142.Bx 4.0 .
143