1.\" $NetBSD: curses_window.3,v 1.2 2002/10/21 14:17:54 wiz Exp $ 2.\" 3.\" Copyright (c) 2002 4.\" Brett Lymn (blymn@netbsd.org, brett_lymn@yahoo.com.au) 5.\" 6.\" This code is donated to the NetBSD Foundation by the Author. 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. The name of the Author may not be used to endorse or promote 17.\" products derived from this software without specific prior written 18.\" permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" 33.Dd August 12, 2002 34.Dt CURSES_WINDOW 3 35.Os 36.Sh NAME 37.Nm curses_window , 38.Nm copywin , 39.Nm dupwin , 40.Nm delwin , 41.Nm derwin , 42.Nm mvderwin , 43.Nm newwin , 44.Nm overlay , 45.Nm overwrite , 46.Nm subwin , 47.Nm wresize 48.Nd curses window routines 49.Sh LIBRARY 50.Lb libcurses 51.Sh SYNOPSIS 52.Fd #include \*[Lt]curses.h\*[Gt] 53.Ft int 54.Fo copywin 55.Fa "WINDOW *source" 56.Fa "WINDOW *dest" 57.Fa "int sminrow" 58.Fa "int smincol" 59.Fa "int dminrow" 60.Fa "int dmincol" 61.Fa "int dmaxrow" 62.Fa "int dmaxcol" 63.Fa "int overlay" 64.Fc 65.Ft WINDOW * 66.Fn dupwin "WINDOW *win" 67.Ft WINDOW * 68.Fn derwin "WINDOW *win" "int lines" "int cols" "int y" "int x" 69.Ft int 70.Fn delwin "WINDOW *win" 71.Ft int 72.Fn mvderwin "WINDOW *win" "int y" "int x" 73.Ft WINDOW * 74.Fn newwin "int lines" "int cols" "int begin_y" "int begin_x" 75.Ft WINDOW * 76.Fn subwin "WINDOW *win" "int lines" "int cols" "int begin_y" "int begin_x" 77.Ft int 78.Fn overlay "WINDOW *source" "WINDOW *dest" 79.Ft int 80.Fn overwrite "WINDOW *source" "WINDOW *dest" 81.Ft int 82.Fn wresize "WINDOW *win" "int lines" "int cols" 83.Sh DESCRIPTION 84These functions create, modify and delete windows on the current screen. 85.Pp 86The contents of a window may be copied to another window by using the 87.Fn copywin 88function, a section of the destination window 89.Fa dest 90bounded by 91.Fa (dminrow , 92.Fa dmincol ) 93and 94.Fa (dmaxrow , 95.Fa dmaxcol ) 96will be overwritten with the contents of the window 97.Fa source 98starting at the coordinates 99.Fa (sminrow , 100.Fa smincol ) . 101If the 102.Fa overlay 103flag is 104.Dv TRUE 105then only non-blank characters from 106.Fa source 107will be copied to 108.Fa dest , 109if 110.Fa overlay 111is 112.Dv FALSE 113then all characters from 114.Fa source 115will be copied to 116.Fa dest . 117If the bounding rectangles of either the source or the destination 118windows lay outside the maximum size of the respective windows then 119the size of the window copied will be adjusted to be within the bounds 120of both the source and destination windows. 121.Pp 122The 123.Fn dupwin 124function creates an exact duplicate of 125.Fa win 126and returns a pointer to it. 127.Pp 128Calling 129.Fn derwin 130will create a subwindow of 131.Fa win 132in the same manner as 133.Fn subwin 134excepting that the starting column and row 135.Fa y , 136.Fa x 137are relative to the parent window origin. 138.Pp 139A window may deleted and all resources freed by calling the 140.Fn delwin 141function with the pointer to the window to be deleted in 142.Fa win . 143.Pp 144A subwindow can be moved relative to the parent window by calling the 145.Fn mvderwin 146function, the 147.Fa y 148and 149.Fa x 150positions are relative to the origin of the parent window. 151If the given window in 152.Fa win 153is not a subwindow then an error will be returned. 154.Pp 155The 156.Fn newwin 157function creates a new window of size 158.Fa lines , 159.Fa cols 160with an origin at 161.Fa begin_y , 162.Fa begin_x . 163If 164.Fa lines 165is zero then the number of rows for the window defaults to 166.Dv LINES - 167.Fa begin_x . 168If 169.Fa cols 170is zero then the number of columns for the window defaults to 171.Dv COLS 172\- 173.Fa begin_y . 174.Pp 175.Fn subwin 176is similar to 177.Fn newwin 178excepting that the size of the subwindow is bounded by the parent 179window 180.Fa win . 181The subwindow shares internal data structures with the parent window 182and will be refreshed when the parent window is refreshed. 183.Pp 184The 185.Fn overlay 186function copies the contents of the source window 187.Fa source 188to the destination window 189.Fa dest , 190only the characters that are not the background character in the 191source window are copied to the destination. 192The windows need not be the same size, only the overlapping portion of both 193windows will be copied. 194The 195.Fn overwrite 196function performs the same functions as 197.Fn overlay 198excepting that characters from the source window are copied to the 199destination without exception. 200.Pp 201.Fn wresize 202resizes the specified window to the new number of lines and columns 203given, all internal curses structures are resized. 204The application must redraw the window after it has been resized. 205.Sh RETURN VALUES 206Functions returning pointers will return 207.Dv NULL 208if an error is detected. 209The functions that return an int will return one of the following 210values: 211.Pp 212.Bl -tag -width ERR -compact 213.It Er OK 214The function completed successfully. 215.It Er ERR 216An error occurred in the function. 217.El 218.Sh SEE ALSO 219.Xr curses_screen 3 220.Sh STANDARDS 221The 222.Nx 223Curses library complies with the X/Open Curses specification, part of the 224Single Unix Specification. 225.Sh HISTORY 226The Curses package appeared in 227.Bx 4.0 . 228