# curs_window

## NAME



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


## 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



       **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_
    
           If either _nlines_ or _ncols_ is zero, they default to
                  **LINES -**_begin_ __y_ and
                  **COLS -**_begin_ __x_.
    
           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 creat‐
           ed:
    
                  idcok, idlok, immedok, keypad, leaveok, nodelay, scrollok,
                  setscrreg, syncok, wbkgdset, wbkgrndset, and wtimeout
    
       **delwin**
           Calling  **delwin** deletes the named window, freeing all memory asso‐
           ciated with it (it does not actually erase the window's screen im‐
           age).  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.  Mov‐
           ing 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_ , 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.
    
           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 manu‐
           ally.
    
       **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 fail‐
           ure 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 implementation
    
           **delwin**
                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 re‐
                sulting 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 cre‐
                ated, 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.
    
           **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.
    
           **newwin**
                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 re‐
                sulting 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**.
    


## 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** , **wsyncup** , **wsync‐**
           **down** , **wcursyncup** , **syncok**) are flaky, incompletely implemented, and
           not well tested.
    
           The System V curses documentation is very unclear about what **wsyn‐**
           **cup** 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 patterned on the XPG4 curses standard.
           The weaker XPG4 spec may result in slower updates.
    


## PORTABILITY



           The XSI Curses standard, Issue 4 describes these functions.
    
           X/Open Curses states regarding **delwin** :
    
           •   It must delete subwindows before deleting their parent.
    
           •   If **delwin** is asked to delete a parent window, it can only suc‐
               ceed 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 subwin‐
               dows.
    
           •   Since release 4.0 (1996), ncurses maintains a list of windows
               for each screen, to ensure that a window has no subwindows be‐
               fore allowing deletion.
    
           •   NetBSD copied this feature of ncurses in 2003.
               PDCurses follows the scheme used in Solaris X/Open curses.
    


* * *