2002-10-13 11:35:53 +08:00
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<!--
****************************************************************************
2004-02-09 10:15:26 +08:00
* Copyright (c) 1998-2000,2003 Free Software Foundation, Inc. *
2002-10-13 11:35:53 +08:00
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
* copy of this software and associated documentation files (the *
* "Software"), to deal in the Software without restriction, including *
* without limitation the rights to use, copy, modify, merge, publish, *
* distribute, distribute with modifications, sublicense, and/or sell *
* copies of the Software, and to permit persons to whom the Software is *
* furnished to do so, subject to the following conditions: *
* *
* The above copyright notice and this permission notice shall be included *
* in all copies or substantial portions of the Software. *
* *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
* *
* Except as contained in this notice, the name(s) of the above copyright *
* holders shall not be used in advertising or otherwise to promote the *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
2004-02-09 10:15:26 +08:00
* @Id: curs_window.3x,v 1.10 2003/05/10 20:33:49 jmc Exp @
2002-10-13 11:35:53 +08:00
-->
2000-07-09 10:46:08 +08:00
< HTML >
2002-10-13 11:35:53 +08:00
< HEAD >
< TITLE > curs_window 3x< / TITLE >
< link rev = made href = "mailto:bug-ncurses@gnu.org" >
< meta http-equiv = "Content-Type" content = "text/html; charset=iso-8859-1" >
< / HEAD >
2000-07-09 10:46:08 +08:00
< BODY >
2002-10-13 11:35:53 +08:00
< H1 > curs_window 3x< / H1 >
< HR >
2000-07-09 10:46:08 +08:00
< PRE >
<!-- Manpage converted by man2html 3.0.1 -->
2004-02-09 10:15:26 +08:00
< STRONG > < A HREF = "curs_window.3x.html" > curs_window(3x)< / A > < / STRONG > < STRONG > < A HREF = "curs_window.3x.html" > curs_window(3x)< / A > < / STRONG >
2000-07-09 10:46:08 +08:00
< / PRE >
< H2 > NAME< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
< STRONG > newwin< / STRONG > , < STRONG > delwin< / STRONG > , < STRONG > mvwin< / STRONG > , < STRONG > subwin< / STRONG > , < STRONG > derwin< / STRONG > , < STRONG > mvderwin< / STRONG > , < STRONG > dupwin< / STRONG > ,
< STRONG > wsyncup< / STRONG > , < STRONG > syncok< / STRONG > , < STRONG > wcursyncup< / STRONG > , < STRONG > wsyncdown< / STRONG > - create < STRONG > curses< / STRONG >
2000-07-09 10:46:08 +08:00
windows
< / PRE >
< H2 > SYNOPSIS< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
< STRONG > #include< / STRONG > < STRONG > < curses.h> < / STRONG >
< STRONG > WINDOW< / STRONG > < STRONG > *newwin(int< / STRONG > < STRONG > nlines,< / STRONG > < STRONG > int< / STRONG > < STRONG > ncols,< / STRONG > < STRONG > int< / STRONG > < STRONG > begin_y,< / STRONG >
< STRONG > int< / STRONG > < STRONG > begin_x);< / STRONG >
< STRONG > int< / STRONG > < STRONG > delwin(WINDOW< / STRONG > < STRONG > *win);< / STRONG >
< STRONG > int< / STRONG > < STRONG > mvwin(WINDOW< / STRONG > < STRONG > *win,< / STRONG > < STRONG > int< / STRONG > < STRONG > y,< / STRONG > < STRONG > int< / STRONG > < STRONG > x);< / STRONG >
< STRONG > WINDOW< / STRONG > < STRONG > *subwin(WINDOW< / STRONG > < STRONG > *orig,< / STRONG > < STRONG > int< / STRONG > < STRONG > nlines,< / STRONG > < STRONG > int< / STRONG > < STRONG > ncols,< / STRONG >
< STRONG > int< / STRONG > < STRONG > begin_y,< / STRONG > < STRONG > int< / STRONG > < STRONG > begin_x);< / STRONG >
< STRONG > WINDOW< / STRONG > < STRONG > *derwin(WINDOW< / STRONG > < STRONG > *orig,< / STRONG > < STRONG > int< / STRONG > < STRONG > nlines,< / STRONG > < STRONG > int< / STRONG > < STRONG > ncols,< / STRONG >
< STRONG > int< / STRONG > < STRONG > begin_y,< / STRONG > < STRONG > int< / STRONG > < STRONG > begin_x);< / STRONG >
< STRONG > int< / STRONG > < STRONG > mvderwin(WINDOW< / STRONG > < STRONG > *win,< / STRONG > < STRONG > int< / STRONG > < STRONG > par_y,< / STRONG > < STRONG > int< / STRONG > < STRONG > par_x);< / STRONG >
< STRONG > WINDOW< / STRONG > < STRONG > *dupwin(WINDOW< / STRONG > < STRONG > *win);< / STRONG >
< STRONG > void< / STRONG > < STRONG > wsyncup(WINDOW< / STRONG > < STRONG > *win);< / STRONG >
< STRONG > int< / STRONG > < STRONG > syncok(WINDOW< / STRONG > < STRONG > *win,< / STRONG > < STRONG > bool< / STRONG > < STRONG > bf);< / STRONG >
< STRONG > void< / STRONG > < STRONG > wcursyncup(WINDOW< / STRONG > < STRONG > *win);< / STRONG >
< STRONG > void< / STRONG > < STRONG > wsyncdown(WINDOW< / STRONG > < STRONG > *win);< / STRONG >
2000-07-09 10:46:08 +08:00
< / PRE >
< H2 > DESCRIPTION< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
Calling < STRONG > newwin< / STRONG > creates and returns a pointer to a new win-
2000-07-09 10:46:08 +08:00
dow with the given number of lines and columns. The upper
2002-10-13 11:35:53 +08:00
left-hand corner of the window is at line < EM > begin< / EM > _< EM > y< / EM > , column
< EM > begin< / EM > _< EM > x< / EM > . If either < EM > nlines< / EM > or < EM > ncols< / EM > is zero, they default
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
window is created by calling < STRONG > newwin(0,0,0,0)< / STRONG > .
2000-07-09 10:46:08 +08:00
2002-10-13 11:35:53 +08:00
Calling < STRONG > delwin< / STRONG > deletes the named window, freeing all mem-
2000-07-09 10:46:08 +08:00
ory associated with it (it does not actually erase the
window's screen image). Subwindows must be deleted before
the main window can be deleted.
2002-10-13 11:35:53 +08:00
Calling < STRONG > mvwin< / STRONG > moves the window so that the upper left-hand
corner is at position (< EM > x< / EM > , < EM > y< / EM > ). If the move would cause the
2000-07-09 10:46:08 +08:00
window to be off the screen, it is an error and the window
is not moved. Moving subwindows is allowed, but should be
avoided.
2002-10-13 11:35:53 +08:00
Calling < STRONG > subwin< / STRONG > creates and returns a pointer to a new win-
dow with the given number of lines, < EM > nlines< / EM > , and columns,
< EM > ncols< / EM > . The window is at position (< EM > begin< / EM > _< EM > y< / EM > , < EM > begin< / EM > _< EM > x< / EM > ) on
2000-07-09 10:46:08 +08:00
the screen. (This position is relative to the screen, and
2002-10-13 11:35:53 +08:00
not to the window < EM > orig< / EM > .) The window is made in the middle
of the window < EM > orig< / EM > , so that changes made to one window
2000-07-09 10:46:08 +08:00
will affect both windows. The subwindow shares memory
2002-10-13 11:35:53 +08:00
with the window < EM > orig< / EM > . When using this routine, it is nec-
essary to call < STRONG > touchwin< / STRONG > or < STRONG > touchline< / STRONG > on < EM > orig< / EM > before call-
ing < STRONG > wrefresh< / STRONG > on the subwindow.
2000-07-09 10:46:08 +08:00
2002-10-13 11:35:53 +08:00
Calling < STRONG > derwin< / STRONG > is the same as calling < STRONG > subwin,< / STRONG > except that
< EM > begin< / EM > _< EM > y< / EM > and < EM > begin< / EM > _< EM > x< / EM > are relative to the origin of the win-
dow < EM > orig< / EM > rather than the screen. There is no difference
2000-07-09 10:46:08 +08:00
between the subwindows and the derived windows.
2002-10-13 11:35:53 +08:00
Calling < STRONG > mvderwin< / STRONG > moves a derived window (or subwindow)
2000-07-09 10:46:08 +08:00
inside its parent window. The screen-relative parameters
of the window are not changed. This routine is used to
display different parts of the parent window at the same
physical position on the screen.
2002-10-13 11:35:53 +08:00
Calling < STRONG > dupwin< / STRONG > creates an exact duplicate of the window
< EM > win< / EM > .
2000-07-09 10:46:08 +08:00
2002-10-13 11:35:53 +08:00
Calling < STRONG > wsyncup< / STRONG > touches all locations in ancestors of < EM > win< / EM >
that are changed in < EM > win< / EM > . If < STRONG > syncok< / STRONG > is called with second
argument < STRONG > TRUE< / STRONG > then < STRONG > wsyncup< / STRONG > is called automatically when-
2000-07-09 10:46:08 +08:00
ever there is a change in the window.
2002-10-13 11:35:53 +08:00
The < STRONG > wsyncdown< / STRONG > routine touches each location in < EM > win< / EM > that
2000-07-09 10:46:08 +08:00
has been touched in any of its ancestor windows. This
2002-10-13 11:35:53 +08:00
routine is called by < STRONG > wrefresh< / STRONG > , so it should almost never
2000-07-09 10:46:08 +08:00
be necessary to call it manually.
2002-10-13 11:35:53 +08:00
The routine < STRONG > wcursyncup< / STRONG > updates the current cursor position
2000-07-09 10:46:08 +08:00
of all the ancestors of the window to reflect the current
cursor position of the window.
< / PRE >
< H2 > RETURN VALUE< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
Routines that return an integer return the integer < STRONG > ERR< / STRONG >
upon failure and < STRONG > OK< / STRONG > (SVr4 only specifies "an integer value
other than < STRONG > ERR< / STRONG > ") upon successful completion.
2000-07-09 10:46:08 +08:00
2002-10-13 11:35:53 +08:00
< STRONG > delwin< / STRONG > returns the integer < STRONG > ERR< / STRONG > upon failure and < STRONG > OK< / STRONG > upon
2000-07-09 10:46:08 +08:00
successful completion.
2002-10-13 11:35:53 +08:00
Routines that return pointers return < STRONG > NULL< / STRONG > on error.
2000-07-09 10:46:08 +08:00
< / PRE >
< H2 > NOTES< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
If many small changes are made to the window, the < STRONG > wsyncup< / STRONG >
2000-07-09 10:46:08 +08:00
option could degrade performance.
2002-10-13 11:35:53 +08:00
Note that < STRONG > syncok< / STRONG > may be a macro.
2000-07-09 10:46:08 +08:00
< / PRE >
< H2 > BUGS< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
The subwindow functions (< EM > subwin< / EM > , < EM > derwin< / EM > , < EM > mvderwin< / EM > , < STRONG > wsyn-< / STRONG >
< STRONG > cup< / STRONG > , < STRONG > wsyncdown< / STRONG > , < STRONG > wcursyncup< / STRONG > , < STRONG > syncok< / STRONG > ) are flaky, incom-
2000-07-09 10:46:08 +08:00
pletely implemented, and not well tested.
The System V curses documentation is very unclear about
2002-10-13 11:35:53 +08:00
what < STRONG > wsyncup< / STRONG > and < STRONG > wsyncdown< / STRONG > actually do. It seems to imply
2000-07-09 10:46:08 +08:00
that they are only supposed to touch exactly those lines
that are affected by ancestor changes. The language here,
2002-10-13 11:35:53 +08:00
and the behavior of the < STRONG > curses< / STRONG > implementation, is pat-
2000-07-09 10:46:08 +08:00
terned on the XPG4 curses standard. The weaker XPG4 spec
may result in slower updates.
< / PRE >
< H2 > PORTABILITY< / H2 > < PRE >
The XSI Curses standard, Issue 4 describes these func-
tions.
< / PRE >
< H2 > SEE ALSO< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
< 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 >
2000-07-09 10:46:08 +08:00
2004-02-09 10:15:26 +08:00
< STRONG > < A HREF = "curs_window.3x.html" > curs_window(3x)< / A > < / STRONG >
2000-07-09 10:46:08 +08:00
< / PRE >
< HR >
< ADDRESS >
Man(1) output converted with
< a href = "http://www.oac.uci.edu/indiv/ehood/man2html.html" > man2html< / a >
< / ADDRESS >
< / BODY >
< / HTML >
