lib/libcurses/curses_window.3

   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
  87 These functions create, modify and delete windows on the current screen.
  88 .Pp
  89 The contents of a window may be copied to another window by using the
  90 .Fn copywin
  91 function, a section of the destination window
  92 .Fa dest
  93 bounded by
  94 .Fa (dminrow ,
  95 .Fa dmincol )
  96 and
  97 .Fa (dmaxrow ,
  98 .Fa dmaxcol )
  99 will be overwritten with the contents of the window
 100 .Fa source
 101 starting at the coordinates
 102 .Fa (sminrow ,
 103 .Fa smincol ) .
 104 If the
 105 .Fa overlay
 106 flag is
 107 .Dv TRUE
 108 then only non-blank characters from
 109 .Fa source
 110 will be copied to
 111 .Fa dest ,
 112 if
 113 .Fa overlay
 114 is
 115 .Dv FALSE
 116 then all characters from
 117 .Fa source
 118 will be copied to
 119 .Fa dest .
 120 If the bounding rectangles of either the source or the destination
 121 windows lay outside the maximum size of the respective windows then
 122 the size of the window copied will be adjusted to be within the bounds
 123 of both the source and destination windows.
 124 .Pp
 125 The
 126 .Fn dupwin
 127 function creates an exact duplicate of
 128 .Fa win
 129 and returns a pointer to it.
 130 .Pp
 131 Calling
 132 .Fn derwin
 133 will create a subwindow of
 134 .Fa win
 135 in the same manner as
 136 .Fn subwin
 137 excepting that the starting column and row
 138 .Fa y ,
 139 .Fa x
 140 are relative to the parent window origin.
 141 .Pp
 142 A window may deleted and all resources freed by calling the
 143 .Fn delwin
 144 function with the pointer to the window to be deleted in
 145 .Fa win .
 146 If
 147 .Fa win
 148 is
 149 .Dv NULL ,
 150 then no action occurs.
 151 .Pp
 152 A window can be moved to a new position by calling the
 153 .Fn mvwin
 154 function.
 155 The
 156 .Fa y
 157 and
 158 .Fa x
 159 positions are the new origin of the window on the screen.
 160 If the new position would cause the any part of the window to lie outside
 161 the screen, it is an error and the window is not moved.
 162 .Pp
 163 A mapping of a region relative to the parent window may be created by
 164 calling the
 165 .Fn mvderwin
 166 function, the
 167 .Fa y
 168 and
 169 .Fa x
 170 positions are relative to the origin of the parent window.
 171 The screen offset of
 172 .Fa win
 173 is not updated, the characters beginning at
 174 .Fa y ,
 175 .Fa x
 176 for the area the size of
 177 .Fa win
 178 will be displayed at the screen offset of
 179 .Fa win .
 180 If the given window in
 181 .Fa win
 182 is not a subwindow then an error will be returned.
 183 If the new position would cause the any part of the window to lie outside
 184 the parent window, it is an error and the mapping is not updated.
 185 .Pp
 186 The
 187 .Fn newwin
 188 function creates a new window of size
 189 .Fa lines ,
 190 .Fa cols
 191 with an origin at
 192 .Fa begin_y ,
 193 .Fa begin_x .
 194 If
 195 .Fa lines
 196 is less than or equal to zero then the number of rows
 197 for the window is set to
 198 .Dv LINES -
 199 .Fa begin_x
 200 +
 201 .Fa lines .
 202 Similarly if
 203 .Fa cols
 204 is less than or equal to zero then the number of columns
 205 for the window is set to
 206 .Dv COLS -
 207 .Fa begin_y
 208 +
 209 .Fa cols .
 210 .Pp
 211 .Fn subwin
 212 is similar to
 213 .Fn newwin
 214 excepting that the size of the subwindow is bounded by the parent
 215 window
 216 .Fa win .
 217 The subwindow shares internal data structures with the parent window
 218 and will be refreshed when the parent window is refreshed.
 219 The subwindow inherits the background character and attributes of the
 220 parent window.
 221 .Pp
 222 The
 223 .Fn overlay
 224 function copies the contents of the source window
 225 .Fa source
 226 to the destination window
 227 .Fa dest ,
 228 only the characters that are not the background character in the
 229 source window are copied to the destination.
 230 The windows need not be the same size, only the overlapping portion of both
 231 windows will be copied.
 232 The
 233 .Fn overwrite
 234 function performs the same functions as
 235 .Fn overlay
 236 excepting that characters from the source window are copied to the
 237 destination without exception.
 238 .Pp
 239 .Fn wresize
 240 resizes the specified window to the new number of lines and columns
 241 given, all internal curses structures are resized.
 242 Any subwindows of the specified window will also be resized if any part
 243 of them falls outside the new parent window size.
 244 The application must redraw the window after it has been resized.
 245 Note that
 246 .Dv curscr
 247 and
 248 .Dv stdscr
 249 can not be resized to be larger than the size of the screen.
 250 .Sh RETURN VALUES
 251 Functions returning pointers will return
 252 .Dv NULL
 253 if an error is detected.
 254 The functions that return an int will return one of the following
 255 values:
 256 .Pp
 257 .Bl -tag -width ERR -compact
 258 .It Er OK
 259 The function completed successfully.
 260 .It Er ERR
 261 An 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
 268 The
 269 .Nx
 270 Curses library complies with the X/Open Curses specification, part of the
 271 Single Unix Specification.
 272 .Sh HISTORY
 273 The Curses package appeared in
 274 .Bx 4.0 .