1.\" $NetBSD: curses_window.3,v 1.8 2003/04/16 13:35:02 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 April 7, 2003 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. The 150.Fa y 151and 152.Fa x 153positions are the new origin of the window on the screen. 154If the new position would cause the any part of the window to lie outside 155the screen, it is an error and the window is not moved. 156.Pp 157A subwindow can be moved relative to the parent window by calling the 158.Fn mvderwin 159function, the 160.Fa y 161and 162.Fa x 163positions are relative to the origin of the parent window. 164If the given window in 165.Fa win 166is not a subwindow then an error will be returned. 167If the new position would cause the any part of the window to lie outside 168the parent window, it is an error and the window is not moved. 169.Pp 170The 171.Fn newwin 172function creates a new window of size 173.Fa lines , 174.Fa cols 175with an origin at 176.Fa begin_y , 177.Fa begin_x . 178If 179.Fa lines 180is less than or equal to zero then the number of rows 181for the window is set to 182.Dv LINES - 183.Fa begin_x 184+ 185.Fa lines . 186Similarly if 187.Fa cols 188is less than or equal to zero then the number of columns 189for the window is set to 190.Dv COLS - 191.Fa begin_y 192+ 193.Fa cols . 194If the terminal, or in the case of a subwindow the enclosing window, 195is resized then the window size will be recalculated so that the window 196ends the same number of columns from the far edge. 197.Pp 198.Fn subwin 199is similar to 200.Fn newwin 201excepting that the size of the subwindow is bounded by the parent 202window 203.Fa win . 204The subwindow shares internal data structures with the parent window 205and will be refreshed when the parent window is refreshed. 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. 227The application must redraw the window after it has been resized. 228.Sh RETURN VALUES 229Functions returning pointers will return 230.Dv NULL 231if an error is detected. 232The functions that return an int will return one of the following 233values: 234.Pp 235.Bl -tag -width ERR -compact 236.It Er OK 237The function completed successfully. 238.It Er ERR 239An error occurred in the function. 240.El 241.Sh SEE ALSO 242.Xr curses_pad 3 , 243.Xr curses_screen 3 244.Sh STANDARDS 245The 246.Nx 247Curses library complies with the X/Open Curses specification, part of the 248Single Unix Specification. 249.Sh HISTORY 250The Curses package appeared in 251.Bx 4.0 . 252