1.\" $NetBSD: curses_window.3,v 1.16 2013/10/15 22:15:17 roy 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 October 15, 2013 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 . 146If 147.Fa win 148is 149.Dv NULL , 150then no action occurs. 151.Pp 152A window can be moved to a new position by calling the 153.Fn mvwin 154function. 155The 156.Fa y 157and 158.Fa x 159positions are the new origin of the window on the screen. 160If the new position would cause the any part of the window to lie outside 161the screen, it is an error and the window is not moved. 162.Pp 163A mapping of a region relative to the parent window may be created by 164calling the 165.Fn mvderwin 166function, the 167.Fa y 168and 169.Fa x 170positions are relative to the origin of the parent window. 171The screen offset of 172.Fa win 173is not updated, the characters beginning at 174.Fa y , 175.Fa x 176for the area the size of 177.Fa win 178will be displayed at the screen offset of 179.Fa win . 180If the given window in 181.Fa win 182is not a subwindow then an error will be returned. 183If the new position would cause the any part of the window to lie outside 184the parent window, it is an error and the mapping is not updated. 185.Pp 186The 187.Fn newwin 188function creates a new window of size 189.Fa lines , 190.Fa cols 191with an origin at 192.Fa begin_y , 193.Fa begin_x . 194If 195.Fa lines 196is less than or equal to zero then the number of rows 197for the window is set to 198.Dv LINES - 199.Fa begin_x 200+ 201.Fa lines . 202Similarly if 203.Fa cols 204is less than or equal to zero then the number of columns 205for the window is set to 206.Dv COLS - 207.Fa begin_y 208+ 209.Fa cols . 210.Pp 211.Fn subwin 212is similar to 213.Fn newwin 214excepting that the size of the subwindow is bounded by the parent 215window 216.Fa win . 217The subwindow shares internal data structures with the parent window 218and will be refreshed when the parent window is refreshed. 219The subwindow inherits the background character and attributes of the 220parent window. 221.Pp 222The 223.Fn overlay 224function copies the contents of the source window 225.Fa source 226to the destination window 227.Fa dest , 228only the characters that are not the background character in the 229source window are copied to the destination. 230The windows need not be the same size, only the overlapping portion of both 231windows will be copied. 232The 233.Fn overwrite 234function performs the same functions as 235.Fn overlay 236excepting that characters from the source window are copied to the 237destination without exception. 238.Pp 239.Fn wresize 240resizes the specified window to the new number of lines and columns 241given, all internal curses structures are resized. 242Any subwindows of the specified window will also be resized if any part 243of them falls outside the new parent window size. 244The application must redraw the window after it has been resized. 245Note that 246.Dv curscr 247and 248.Dv stdscr 249can not be resized to be larger than the size of the screen. 250.Sh RETURN VALUES 251Functions returning pointers will return 252.Dv NULL 253if an error is detected. 254The functions that return an int will return one of the following 255values: 256.Pp 257.Bl -tag -width ERR -compact 258.It Er OK 259The function completed successfully. 260.It Er ERR 261An error occurred in the function. 262.El 263.Sh SEE ALSO 264.Xr curses_fileio 3 , 265.Xr curses_pad 3 , 266.Xr curses_screen 3 267.Sh STANDARDS 268The 269.Nx 270Curses library complies with the X/Open Curses specification, part of the 271Single Unix Specification. 272.Sh HISTORY 273The Curses package appeared in 274.Bx 4.0 . 275