1.\" $NetBSD: curses_window.3,v 1.13 2009/05/18 09:30:31 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 March 31, 2008 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 . 195.Pp 196.Fn subwin 197is similar to 198.Fn newwin 199excepting that the size of the subwindow is bounded by the parent 200window 201.Fa win . 202The subwindow shares internal data structures with the parent window 203and will be refreshed when the parent window is refreshed. 204The subwindow inherits the background character and attributes of the 205parent window. 206.Pp 207The 208.Fn overlay 209function copies the contents of the source window 210.Fa source 211to the destination window 212.Fa dest , 213only the characters that are not the background character in the 214source window are copied to the destination. 215The windows need not be the same size, only the overlapping portion of both 216windows will be copied. 217The 218.Fn overwrite 219function performs the same functions as 220.Fn overlay 221excepting that characters from the source window are copied to the 222destination without exception. 223.Pp 224.Fn wresize 225resizes the specified window to the new number of lines and columns 226given, all internal curses structures are resized. 227Any subwindows of the specified window will also be resized if any part 228of them falls outside the new parent window size. 229The application must redraw the window after it has been resized. 230Note that 231.Dv curscr 232and 233.Dv stdscr 234can not be resized to be larger than the size of the screen. 235.Sh RETURN VALUES 236Functions returning pointers will return 237.Dv NULL 238if an error is detected. 239The functions that return an int will return one of the following 240values: 241.Pp 242.Bl -tag -width ERR -compact 243.It Er OK 244The function completed successfully. 245.It Er ERR 246An error occurred in the function. 247.El 248.Sh SEE ALSO 249.Xr curses_fileio 3 , 250.Xr curses_pad 3 , 251.Xr curses_screen 3 252.Sh STANDARDS 253The 254.Nx 255Curses library complies with the X/Open Curses specification, part of the 256Single Unix Specification. 257.Sh HISTORY 258The Curses package appeared in 259.Bx 4.0 . 260