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