1.\" $NetBSD: curses_window.3,v 1.10 2006/01/15 16:57:45 jdc 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 January 15, 2006 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 mvwin , 43.Nm mvderwin , 44.Nm newwin , 45.Nm overlay , 46.Nm overwrite , 47.Nm subwin , 48.Nm wresize 49.Nd curses window routines 50.Sh LIBRARY 51.Lb libcurses 52.Sh SYNOPSIS 53.In curses.h 54.Ft int 55.Fo copywin 56.Fa "WINDOW *source" 57.Fa "WINDOW *dest" 58.Fa "int sminrow" 59.Fa "int smincol" 60.Fa "int dminrow" 61.Fa "int dmincol" 62.Fa "int dmaxrow" 63.Fa "int dmaxcol" 64.Fa "int overlay" 65.Fc 66.Ft WINDOW * 67.Fn dupwin "WINDOW *win" 68.Ft WINDOW * 69.Fn derwin "WINDOW *win" "int lines" "int cols" "int y" "int x" 70.Ft int 71.Fn delwin "WINDOW *win" 72.Ft int 73.Fn mvwin "WINDOW *win" "int y" "int x" 74.Ft int 75.Fn mvderwin "WINDOW *win" "int y" "int x" 76.Ft WINDOW * 77.Fn newwin "int lines" "int cols" "int begin_y" "int begin_x" 78.Ft WINDOW * 79.Fn subwin "WINDOW *win" "int lines" "int cols" "int begin_y" "int begin_x" 80.Ft int 81.Fn overlay "WINDOW *source" "WINDOW *dest" 82.Ft int 83.Fn overwrite "WINDOW *source" "WINDOW *dest" 84.Ft int 85.Fn wresize "WINDOW *win" "int lines" "int cols" 86.Sh DESCRIPTION 87These functions create, modify and delete windows on the current screen. 88.Pp 89The contents of a window may be copied to another window by using the 90.Fn copywin 91function, a section of the destination window 92.Fa dest 93bounded by 94.Fa (dminrow , 95.Fa dmincol ) 96and 97.Fa (dmaxrow , 98.Fa dmaxcol ) 99will be overwritten with the contents of the window 100.Fa source 101starting at the coordinates 102.Fa (sminrow , 103.Fa smincol ) . 104If the 105.Fa overlay 106flag is 107.Dv TRUE 108then only non-blank characters from 109.Fa source 110will be copied to 111.Fa dest , 112if 113.Fa overlay 114is 115.Dv FALSE 116then all characters from 117.Fa source 118will be copied to 119.Fa dest . 120If the bounding rectangles of either the source or the destination 121windows lay outside the maximum size of the respective windows then 122the size of the window copied will be adjusted to be within the bounds 123of both the source and destination windows. 124.Pp 125The 126.Fn dupwin 127function creates an exact duplicate of 128.Fa win 129and returns a pointer to it. 130.Pp 131Calling 132.Fn derwin 133will create a subwindow of 134.Fa win 135in the same manner as 136.Fn subwin 137excepting that the starting column and row 138.Fa y , 139.Fa x 140are relative to the parent window origin. 141.Pp 142A window may deleted and all resources freed by calling the 143.Fn delwin 144function with the pointer to the window to be deleted in 145.Fa win . 146.Pp 147A window can be moved to a new position by calling the 148.Fn mvwin 149function. 150The 151.Fa y 152and 153.Fa x 154positions are the new origin of the window on the screen. 155If the new position would cause the any part of the window to lie outside 156the screen, it is an error and the window is not moved. 157.Pp 158A subwindow can be moved relative to the parent window by calling the 159.Fn mvderwin 160function, the 161.Fa y 162and 163.Fa x 164positions are relative to the origin of the parent window. 165If the given window in 166.Fa win 167is not a subwindow then an error will be returned. 168If the new position would cause the any part of the window to lie outside 169the parent window, it is an error and the window is not moved. 170.Pp 171The 172.Fn newwin 173function creates a new window of size 174.Fa lines , 175.Fa cols 176with an origin at 177.Fa begin_y , 178.Fa begin_x . 179If 180.Fa lines 181is less than or equal to zero then the number of rows 182for the window is set to 183.Dv LINES - 184.Fa begin_x 185+ 186.Fa lines . 187Similarly if 188.Fa cols 189is less than or equal to zero then the number of columns 190for the window is set to 191.Dv COLS - 192.Fa begin_y 193+ 194.Fa cols . 195If the terminal, or in the case of a subwindow the enclosing window, 196is resized then the window size will be recalculated so that the window 197ends the same number of columns from the far edge. 198.Pp 199.Fn subwin 200is similar to 201.Fn newwin 202excepting that the size of the subwindow is bounded by the parent 203window 204.Fa win . 205The subwindow shares internal data structures with the parent window 206and will be refreshed when the parent window is refreshed. 207The subwindow inherits the background character and attributes of the 208parent window. 209.Pp 210The 211.Fn overlay 212function copies the contents of the source window 213.Fa source 214to the destination window 215.Fa dest , 216only the characters that are not the background character in the 217source window are copied to the destination. 218The windows need not be the same size, only the overlapping portion of both 219windows will be copied. 220The 221.Fn overwrite 222function performs the same functions as 223.Fn overlay 224excepting that characters from the source window are copied to the 225destination without exception. 226.Pp 227.Fn wresize 228resizes the specified window to the new number of lines and columns 229given, all internal curses structures are resized. 230The application must redraw the window after it has been resized. 231.Sh RETURN VALUES 232Functions returning pointers will return 233.Dv NULL 234if an error is detected. 235The functions that return an int will return one of the following 236values: 237.Pp 238.Bl -tag -width ERR -compact 239.It Er OK 240The function completed successfully. 241.It Er ERR 242An error occurred in the function. 243.El 244.Sh SEE ALSO 245.Xr curses_pad 3 , 246.Xr curses_screen 3 247.Sh STANDARDS 248The 249.Nx 250Curses library complies with the X/Open Curses specification, part of the 251Single Unix Specification. 252.Sh HISTORY 253The Curses package appeared in 254.Bx 4.0 . 255