1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
3 ****************************************************************************
4 * Copyright (c) 1998,2000 Free Software Foundation, Inc. *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
29 ****************************************************************************
30 * @Id: curs_window.3x,v 1.9 2000/07/01 20:08:37 tom Exp @
34 <TITLE>curs_window 3x</TITLE>
35 <link rev=made href="mailto:bug-ncurses@gnu.org">
36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
39 <H1>curs_window 3x</H1>
42 <!-- Manpage converted by man2html 3.0.1 -->
46 <STRONG>newwin</STRONG>, <STRONG>delwin</STRONG>, <STRONG>mvwin</STRONG>, <STRONG>subwin</STRONG>, <STRONG>derwin</STRONG>, <STRONG>mvderwin</STRONG>, <STRONG>dupwin</STRONG>,
47 <STRONG>wsyncup</STRONG>, <STRONG>syncok</STRONG>, <STRONG>wcursyncup</STRONG>, <STRONG>wsyncdown</STRONG> - create <STRONG>curses</STRONG>
52 <H2>SYNOPSIS</H2><PRE>
53 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
55 <STRONG>WINDOW</STRONG> <STRONG>*newwin(int</STRONG> <STRONG>nlines,</STRONG> <STRONG>int</STRONG> <STRONG>ncols,</STRONG> <STRONG>int</STRONG> <STRONG>begin_y,</STRONG>
56 <STRONG>int</STRONG> <STRONG>begin_x);</STRONG>
57 <STRONG>int</STRONG> <STRONG>delwin(WINDOW</STRONG> <STRONG>*win);</STRONG>
58 <STRONG>int</STRONG> <STRONG>mvwin(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
59 <STRONG>WINDOW</STRONG> <STRONG>*subwin(WINDOW</STRONG> <STRONG>*orig,</STRONG> <STRONG>int</STRONG> <STRONG>nlines,</STRONG> <STRONG>int</STRONG> <STRONG>ncols,</STRONG>
60 <STRONG>int</STRONG> <STRONG>begin_y,</STRONG> <STRONG>int</STRONG> <STRONG>begin_x);</STRONG>
61 <STRONG>WINDOW</STRONG> <STRONG>*derwin(WINDOW</STRONG> <STRONG>*orig,</STRONG> <STRONG>int</STRONG> <STRONG>nlines,</STRONG> <STRONG>int</STRONG> <STRONG>ncols,</STRONG>
62 <STRONG>int</STRONG> <STRONG>begin_y,</STRONG> <STRONG>int</STRONG> <STRONG>begin_x);</STRONG>
63 <STRONG>int</STRONG> <STRONG>mvderwin(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>par_y,</STRONG> <STRONG>int</STRONG> <STRONG>par_x);</STRONG>
64 <STRONG>WINDOW</STRONG> <STRONG>*dupwin(WINDOW</STRONG> <STRONG>*win);</STRONG>
65 <STRONG>void</STRONG> <STRONG>wsyncup(WINDOW</STRONG> <STRONG>*win);</STRONG>
66 <STRONG>int</STRONG> <STRONG>syncok(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
67 <STRONG>void</STRONG> <STRONG>wcursyncup(WINDOW</STRONG> <STRONG>*win);</STRONG>
68 <STRONG>void</STRONG> <STRONG>wsyncdown(WINDOW</STRONG> <STRONG>*win);</STRONG>
72 <H2>DESCRIPTION</H2><PRE>
73 Calling <STRONG>newwin</STRONG> creates and returns a pointer to a new win-
74 dow with the given number of lines and columns. The upper
75 left-hand corner of the window is at line <EM>begin</EM>_<EM>y</EM>, column
76 <EM>begin</EM>_<EM>x</EM>. If either <EM>nlines</EM> or <EM>ncols</EM> is zero, they default
77 to <STRONG>LINES</STRONG> <STRONG>-</STRONG> <EM>begin</EM>_<EM>y</EM> and <STRONG>COLS</STRONG> <STRONG>-</STRONG> <EM>begin</EM>_<EM>x</EM>. A new full-screen
78 window is created by calling <STRONG>newwin(0,0,0,0)</STRONG>.
80 Calling <STRONG>delwin</STRONG> deletes the named window, freeing all mem-
81 ory associated with it (it does not actually erase the
82 window's screen image). Subwindows must be deleted before
83 the main window can be deleted.
85 Calling <STRONG>mvwin</STRONG> moves the window so that the upper left-hand
86 corner is at position (<EM>x</EM>, <EM>y</EM>). If the move would cause the
87 window to be off the screen, it is an error and the window
88 is not moved. Moving subwindows is allowed, but should be
91 Calling <STRONG>subwin</STRONG> creates and returns a pointer to a new win-
92 dow with the given number of lines, <EM>nlines</EM>, and columns,
93 <EM>ncols</EM>. The window is at position (<EM>begin</EM>_<EM>y</EM>, <EM>begin</EM>_<EM>x</EM>) on
94 the screen. (This position is relative to the screen, and
95 not to the window <EM>orig</EM>.) The window is made in the middle
96 of the window <EM>orig</EM>, so that changes made to one window
97 will affect both windows. The subwindow shares memory
98 with the window <EM>orig</EM>. When using this routine, it is nec-
99 essary to call <STRONG>touchwin</STRONG> or <STRONG>touchline</STRONG> on <EM>orig</EM> before call-
100 ing <STRONG>wrefresh</STRONG> on the subwindow.
102 Calling <STRONG>derwin</STRONG> is the same as calling <STRONG>subwin,</STRONG> except that
103 <EM>begin</EM>_<EM>y</EM> and <EM>begin</EM>_<EM>x</EM> are relative to the origin of the win-
104 dow <EM>orig</EM> rather than the screen. There is no difference
105 between the subwindows and the derived windows.
107 Calling <STRONG>mvderwin</STRONG> moves a derived window (or subwindow)
108 inside its parent window. The screen-relative parameters
109 of the window are not changed. This routine is used to
110 display different parts of the parent window at the same
111 physical position on the screen.
113 Calling <STRONG>dupwin</STRONG> creates an exact duplicate of the window
116 Calling <STRONG>wsyncup</STRONG> touches all locations in ancestors of <EM>win</EM>
117 that are changed in <EM>win</EM>. If <STRONG>syncok</STRONG> is called with second
118 argument <STRONG>TRUE</STRONG> then <STRONG>wsyncup</STRONG> is called automatically when-
119 ever there is a change in the window.
121 The <STRONG>wsyncdown</STRONG> routine touches each location in <EM>win</EM> that
122 has been touched in any of its ancestor windows. This
123 routine is called by <STRONG>wrefresh</STRONG>, so it should almost never
124 be necessary to call it manually.
126 The routine <STRONG>wcursyncup</STRONG> updates the current cursor position
127 of all the ancestors of the window to reflect the current
128 cursor position of the window.
132 <H2>RETURN VALUE</H2><PRE>
133 Routines that return an integer return the integer <STRONG>ERR</STRONG>
134 upon failure and <STRONG>OK</STRONG> (SVr4 only specifies "an integer value
135 other than <STRONG>ERR</STRONG>") upon successful completion.
137 <STRONG>delwin</STRONG> returns the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon
138 successful completion.
140 Routines that return pointers return <STRONG>NULL</STRONG> on error.
145 If many small changes are made to the window, the <STRONG>wsyncup</STRONG>
146 option could degrade performance.
148 Note that <STRONG>syncok</STRONG> may be a macro.
153 The subwindow functions (<EM>subwin</EM>, <EM>derwin</EM>, <EM>mvderwin</EM>, <STRONG>wsyn-</STRONG>
154 <STRONG>cup</STRONG>, <STRONG>wsyncdown</STRONG>, <STRONG>wcursyncup</STRONG>, <STRONG>syncok</STRONG>) are flaky, incom-
155 pletely implemented, and not well tested.
157 The System V curses documentation is very unclear about
158 what <STRONG>wsyncup</STRONG> and <STRONG>wsyncdown</STRONG> actually do. It seems to imply
159 that they are only supposed to touch exactly those lines
160 that are affected by ancestor changes. The language here,
161 and the behavior of the <STRONG>curses</STRONG> implementation, is pat-
162 terned on the XPG4 curses standard. The weaker XPG4 spec
163 may result in slower updates.
167 <H2>PORTABILITY</H2><PRE>
168 The XSI Curses standard, Issue 4 describes these func-
173 <H2>SEE ALSO</H2><PRE>
174 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>
224 Man(1) output converted with
225 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>