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