X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_window.3x.html;h=786ca4f93fe95c8e32df62d7a9471de7ce52fc8b;hp=a28edd6c3bf2767c1685ac87530af30df0c39656;hb=HEAD;hpb=b0b1980be11bba618d84beb8b30ac94e2c820602;ds=sidebyside diff --git a/doc/html/man/curs_window.3x.html b/doc/html/man/curs_window.3x.html index a28edd6c..ea99659e 100644 --- a/doc/html/man/curs_window.3x.html +++ b/doc/html/man/curs_window.3x.html @@ -1,7 +1,7 @@ - - + -curs_window 3x - - + + +curs_window 3x 2024-04-20 ncurses 6.5 Library calls + + -

curs_window 3x

-
+

curs_window 3x 2024-04-20 ncurses 6.5 Library calls

-
-curs_window(3x)                                         curs_window(3x)
+curs_window(3x)                  Library calls                 curs_window(3x)
 
 
 
 
-
-

NAME

-       newwin, delwin, mvwin, subwin, derwin, mvderwin, dupwin,
-       wsyncup, syncok, wcursyncup, wsyncdown - create curses
-       windows
+

NAME

+       newwin,  delwin,  mvwin,  subwin,  derwin,  mvderwin,  dupwin, wsyncup,
+       syncok, wcursyncup, wsyncdown - create and manipulate curses windows
 
 
-
-

SYNOPSIS

+

SYNOPSIS

        #include <curses.h>
 
        WINDOW *newwin(
-             int nlines, int ncols,
-             int begin_y, int begin_x);
-       int delwin(WINDOW *win);
-       int mvwin(WINDOW *win, int y, int x);
-       WINDOW *subwin(WINDOW *orig,
-             int nlines, int ncols,
-             int begin_y, int begin_x);
-       WINDOW *derwin(WINDOW *orig,
-             int nlines, int ncols,
-             int begin_y, int begin_x);
-       int mvderwin(WINDOW *win, int par_y, int par_x);
-       WINDOW *dupwin(WINDOW *win);
-       void wsyncup(WINDOW *win);
-       int syncok(WINDOW *win, bool bf);
-       void wcursyncup(WINDOW *win);
-       void wsyncdown(WINDOW *win);
-
-
-
-

DESCRIPTION

-       Calling newwin creates and returns a pointer to a new win-
-       dow with the given number of lines and columns.  The upper
-       left-hand corner of the window is at
+             int nlines, int ncols,
+             int begin_y, int begin_x);
+       int delwin(WINDOW *win);
+       int mvwin(WINDOW *win, int y, int x);
+       WINDOW *subwin(WINDOW *orig,
+             int nlines, int ncols,
+             int begin_y, int begin_x);
+       WINDOW *derwin(WINDOW *orig,
+             int nlines, int ncols,
+             int begin_y, int begin_x);
+       int mvderwin(WINDOW *win, int par_y, int par_x);
+       WINDOW *dupwin(WINDOW *win);
+       void wsyncup(WINDOW *win);
+       int syncok(WINDOW *win, bool bf);
+       void wcursyncup(WINDOW *win);
+       void wsyncdown(WINDOW *win);
+
+
+

DESCRIPTION

+
+

newwin

+       Calling newwin creates and returns a pointer to a new window  with  the
+       given  number  of lines and columns.  The upper left-hand corner of the
+       window is at
               line begin_y,
               column begin_x
 
@@ -87,154 +86,202 @@
               LINES - begin_y and
               COLS - begin_x.
 
-       A   new   full-screen   window   is   created  by  calling
-       newwin(0,0,0,0).
-
-       Calling delwin deletes the named window, freeing all memo-
-       ry associated with it (it does not actually erase the win-
-       dow's screen image).  Subwindows must  be  deleted  before
-       the main window can be deleted.
-
-       Calling mvwin moves the window so that the upper left-hand
-       corner is at position (x, y).  If the move would cause the
-       window to be off the screen, it is an error and the window
-       is not moved.  Moving subwindows is allowed, but should be
-       avoided.
-
-       Calling subwin creates and returns a pointer to a new win-
-       dow with the given number of lines, nlines,  and  columns,
-       ncols.   The  window  is at position (begin_y, begin_x) on
-       the screen.  The subwindow shares memory with  the  window
-       orig,  so that changes made to one window will affect both
-       windows.  When using this routine, it is necessary to call
-       touchwin  or  touchline on orig before calling wrefresh on
-       the subwindow.
-
-       Calling derwin is the same as calling subwin, except  that
-       begin_y and begin_x are relative to the origin of the win-
-       dow orig rather than the screen.  There is  no  difference
-       between the subwindows and the derived windows.
-
-       Calling mvderwin moves a derived window (or subwindow) in-
-       side its parent window.  The screen-relative parameters of
-       the  window are not changed.  This routine is used to dis-
-       play different parts of the  parent  window  at  the  same
-       physical position on the screen.
-
-       Calling  dupwin  creates  an exact duplicate of the window
-       win.
-
-       Calling wsyncup touches all locations in ancestors of  win
-       that  are changed in win.  If syncok is called with second
-       argument TRUE then wsyncup is called automatically whenev-
-       er there is a change in the window.
-
-       The  wsyncdown  routine  touches each location in win that
-       has been touched in any of  its  ancestor  windows.   This
-       routine  is  called by wrefresh, so it should almost never
-       be necessary to call it manually.
-
-       The routine wcursyncup updates the current cursor position
-       of  all the ancestors of the window to reflect the current
-       cursor position of the window.
+       A new full-screen window is created by calling newwin(0,0,0,0).
 
+       Regardless of the function  used  for  creating  a  new  window  (e.g.,
+       newwin, subwin, derwin, newpad), rather than a duplicate (with dupwin),
+       all of the window modes are initialized to the default  values.   These
+       functions set window modes after a window is created:
 
-
-

RETURN VALUE

-       Routines that return an integer return the integer ERR up-
-       on  failure  and OK (SVr4 only specifies "an integer value
-       other than ERR") upon successful completion.
+              idcok  idlok  immedok  keypad leaveok nodelay scrollok setscrreg
+              syncok wbkgdset wbkgrndset and wtimeout.
+
+
+

delwin

+       Calling delwin deletes the named window, freeing all memory  associated
+       with  it  (it  does  not  actually  erase  the  window's screen image).
+       Subwindows must be deleted before the main window can be deleted.
+
+
+

mvwin

+       Calling mvwin moves the window so that the upper left-hand corner is at
+       position  (x,  y).   If  the  move would cause the window to be off the
+       screen, it is an error and the window is not moved.  Moving  subwindows
+       is allowed, but should be avoided.
+
+
+

subwin

+       Calling  subwin  creates and returns a pointer to a new window with the
+       given number of lines, nlines, and columns, ncols.  The  window  is  at
+       position (begin_y, begin_x) on the screen.  The subwindow shares memory
+       with the window orig, its ancestor, so that changes made to one  window
+       will  affect both windows.  When using this routine, it is necessary to
+       call touchwin or touchline on  orig  before  calling  wrefresh  on  the
+       subwindow.
+
+
+

derwin

+       Calling  derwin  is the same as calling subwin, except that begin_y and
+       begin_x are relative to the origin of the window orig rather  than  the
+       screen.   There is no difference between the subwindows and the derived
+       windows.
+
+
+

mvderwin

+       Calling mvderwin moves a  derived  window  (or  subwindow)  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.
+
+
+

dupwin

+       Calling dupwin creates an exact duplicate of the window win.
+
+
+

wsyncup

+       Calling  wsyncup  touches  all  locations  in ancestors of win that are
+       changed in win.  If syncok is called with  second  argument  TRUE  then
+       wsyncup  is  called  automatically  whenever  there  is a change in the
+       window.
+
+
+

wsyncdown

+       The wsyncdown routine touches  each  location  in  win  that  has  been
+       touched  in  any  of  its  ancestor windows.  This routine is called by
+       wrefresh, so it should almost never be necessary to call it manually.
+
+
+

wcursyncup

+       The routine wcursyncup updates the current cursor position of  all  the
+       ancestors  of  the window to reflect the current cursor position of the
+       window.
+
+
+

RETURN VALUE

+       Routines that return an integer return the integer ERR upon failure and
+       OK  (SVr4  only  specifies  "an  integer  value  other  than ERR") upon
+       successful completion.
 
        Routines that return pointers return NULL on error.
 
-       X/Open defines no error conditions.  In  this  implementa-
-       tion
+       X/Open defines no error conditions.  In this implementation
 
        delwin
-            returns an error if the window pointer is null, or if
-            the window is the parent of another window.
+            returns an error if the window pointer is null, or if  the  window
+            is the parent of another window.
 
        derwin
-            returns an error if  the  parent  window  pointer  is
-            null,  or  if  any  of its ordinates or dimensions is
-            negative, or if the resulting window does not fit in-
-            side the parent window.
+            returns  an  error if the parent window pointer is null, or if any
+            of its ordinates or dimensions is negative, or  if  the  resulting
+            window does not fit inside the parent window.
 
        dupwin
             returns an error if the window pointer is null.
 
-            This implementation also maintains a list of windows,
-            and checks that the pointer passed to delwin  is  one
-            that it created, returning an error if it was not..
+            This  implementation  also maintains a list of windows, and checks
+            that the  pointer  passed  to  delwin  is  one  that  it  created,
+            returning an error if it was not..
 
        mvderwin
-            returns an error if the window pointer is null, or if
-            some part of the window would be placed off-screen.
+            returns an error if the window pointer is null, or if some part of
+            the window would be placed off-screen.
 
        mvwin
-            returns an error if the window pointer is null, or if
-            the  window  is  really a pad, or if some part of the
-            window would be placed off-screen.
+            returns an error if the window pointer is null, or if  the  window
+            is  really  a  pad,  or if some part of the window would be placed
+            off-screen.
 
        newwin
-            will fail if either of  its  beginning  ordinates  is
-            negative, or if either the number of lines or columns
-            is negative.
+            will fail if either of its beginning ordinates is negative, or  if
+            either the number of lines or columns is negative.
 
        syncok
             returns an error if the window pointer is null.
 
        subwin
-            returns an error if  the  parent  window  pointer  is
-            null,  or  if  any  of its ordinates or dimensions is
-            negative, or if the resulting window does not fit in-
-            side the parent window.
+            returns  an  error if the parent window pointer is null, or if any
+            of its ordinates or dimensions is negative, or  if  the  resulting
+            window does not fit inside the parent window.
 
-       The  functions which return a window pointer may also fail
-       if there is insufficient memory for its  data  structures.
-       Any  of  these  functions  will fail if the screen has not
-       been initialized, i.e., with initscr or newterm.
+       The  functions  which return a window pointer may also fail if there is
+       insufficient memory for its data structures.  Any  of  these  functions
+       will fail if the screen has not been initialized, i.e., with initscr or
+       newterm.
 
 
-
-

NOTES

-       If many small changes are made to the window, the  wsyncup
-       option could degrade performance.
+

NOTES

+       If many small changes are made to the window, the wsyncup option  could
+       degrade performance.
 
        Note that syncok may be a macro.
 
 
-
-

BUGS

-       The  subwindow  functions (subwin, derwin, mvderwin, wsyn-
-       cup, wsyncdown, wcursyncup, syncok) are flaky, incomplete-
-       ly implemented, and not well tested.
+

PORTABILITY

+       X/Open Curses, Issue 4 describes these functions.
 
-       The  System  V  curses documentation is very unclear about
-       what wsyncup and wsyncdown actually do.  It seems to imply
-       that  they  are only supposed to touch exactly those lines
-       that are affected by ancestor changes.  The language here,
-       and  the  behavior  of  the curses implementation, is pat-
-       terned on the XPG4 curses standard.  The weaker XPG4  spec
-       may result in slower updates.
+       X/Open Curses states regarding delwin:
 
+       o   It must delete subwindows before deleting their parent.
 
-
-

PORTABILITY

-       The  XSI  Curses  standard,  Issue 4 describes these func-
-       tions.
+       o   If  delwin  is asked to delete a parent window, it can only succeed
+           if the curses library keeps a list of the subwindows.  SVr4  curses
+           kept  a  count  of the number of subwindows rather than a list.  It
+           simply returned ERR when asked  to  delete  a  subwindow.   Solaris
+           X/Open  curses  does  not  even  make that check, and will delete a
+           parent window which still has subwindows.
 
+       o   Since release 4.0 (1996), ncurses maintains a list of  windows  for
+           each  screen,  to  ensure  that  a  window has no subwindows before
+           allowing deletion.
 
-
-

SEE ALSO

-       curses(3x), curs_refresh(3x),  curs_touch(3x),  curs_vari-
-       ables(3x)
+       o   NetBSD copied this feature of ncurses in 2003.
+           PDCurses follows the scheme used in Solaris X/Open curses.
+
+
+

BUGS

+       The subwindow functions subwin, derwin, mvderwin,  wsyncup,  wsyncdown,
+       wcursyncup,  and  syncok  are  flaky, incompletely implemented, and not
+       well tested.
+
+       System V's curses documentation  is  unclear  about  what  wsyncup  and
+       wsyncdown  actually  do.   It  seems to imply that they are supposed to
+       touch only those lines that are  affected  by  changes  to  a  window's
+       ancestors.  The language here, and behavior of ncurses, is patterned on
+       the X/Open Curses standard; this approach may result in slower updates.
+
+
+

SEE ALSO

+       curses(3x),   curs_initscr(3x),    curs_refresh(3x),    curs_touch(3x),
+       curs_variables(3x)
 
 
 
-                                                        curs_window(3x)
+ncurses 6.5                       2024-04-20                   curs_window(3x)
-
-Man(1) output converted with man2html +
+ +