lib/libncurses/curs_window.3

   1 .\" $FreeBSD$
   2 .\"
   3 .TH curs_window 3 ""
   4 .SH NAME
   5 \fBnewwin\fR, \fBdelwin\fR, \fBmvwin\fR,
   6 \fBsubwin\fR, \fBderwin\fR, \fBmvderwin\fR, \fBdupwin\fR,
   7 \fBwsyncup\fR, \fBsyncok\fR, \fBwcursyncup\fR,
   8 \fBwsyncdown\fR - create \fBncurses\fR windows
   9 .SH SYNOPSIS
  10 \fB#include <ncurses.h>\fR
  11
  12 \fBWINDOW *newwin(int nlines, int ncols, int begin_y,\fR
  13       \fBintbegin_x);\fR
  14
  15 \fBint delwin(WINDOW *win);\fR
  16 .br
  17 \fBint mvwin(WINDOW *win, int y, int x);\fR
  18 .br
  19 \fBWINDOW *subwin(WINDOW *orig, int nlines, int ncols,
  20       int begin_y, int begin_x);\fR
  21 \fBWINDOW *derwin(WINDOW *orig, int nlines, int ncols,
  22       int begin_y, int begin_x);\fR
  23 \fBint mvderwin(WINDOW *win, int par_y, int par_x);\fR
  24 .br
  25 \fBWINDOW *dupwin(WINDOW *win);\fR
  26 .br
  27 \fBvoid wsyncup(WINDOW *win);\fR
  28 .br
  29 \fBint syncok(WINDOW *win, bool bf);\fR
  30 .br
  31 \fBvoid wcursyncup(WINDOW *win);\fR
  32 .br
  33 \fBvoid wsyncdown(WINDOW *win);\fR
  34 .br
  35 .SH DESCRIPTION
  36 The \fBnewwin\fR routine creates and returns a pointer to a new window with the
  37 given number of lines and columns.  The upper left-hand corner of the window is
  38 at line \fIbegin\fR_\fIy\fR, column \fIbegin\fR_\fIx\fR.  If either
  39 \fInlines\fR or \fIncols\fR is zero, they default to \fBLINES -\fR
  40 \fIbegin\fR_\fIy\fR and \fBCOLS -\fR \fIbegin\fR_\fIx\fR.  A new full-screen
  41 window is created by calling \fBnewwin(0,0,0,0)\fR.
  42
  43 The \fBdelwin\fR routine deletes the named window, freeing all memory
  44 associated with it (it does not actually erase the window's screen
  45 image).  Subwindows must be deleted before the main window can be
  46 deleted.
  47
  48 The \fBmvwin\fR routine moves the window so that the upper left-hand
  49 corner is at position (\fIx\fR, \fIy\fR).  If the move would cause the
  50 window to be off the screen, it is an error and the window is not
  51 moved.  Moving subwindows is allowed, but should be avoided.
  52
  53 The \fBsubwin\fR routine creates and returns a pointer to a new window
  54 with the given number of lines, \fInlines\fR, and columns,
  55 \fIncols\fR.  The window is at position (\fIbegin\fR_\fIy\fR,
  56 \fIbegin\fR_\fIx\fR) on the screen.  (This position is relative to the
  57 screen, and not to the window \fIorig\fR.)  The window is made in the
  58 middle of the window \fIorig\fR, so that changes made to one window
  59 will affect both windows.  The subwindow shares memory with the window
  60 \fIorig\fR.  When using this routine, it is necessary to call
  61 \fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before calling
  62 \fBwrefresh\fR on the subwindow.
  63
  64 The \fBderwin\fR routine is the same as \fBsubwin,\fR except that
  65 \fIbegin\fR_\fIy\fR and \fIbegin\fR_\fIx\fR are relative to the origin
  66 of the window \fIorig\fR rather than the screen.  There is no
  67 difference between the subwindows and the derived windows.
  68
  69 The \fBmvderwin\fR routine moves a derived window (or subwindow)
  70 inside its parent window.  The screen-relative parameters of the
  71 window are not changed.  This routine is used to display different
  72 parts of the parent window at the same physical position on the
  73 screen.
  74
  75 The \fBdupwin\fR routine creates an exact duplicate of the window \fIwin\fR.
  76
  77 Each \fBncurses\fR window maintains two data structures: the character
  78 image structure and the status structure.  The character image
  79 structure is shared among all windows in the window hierarchy
  80 (\fIi\fR.\fIe\fR., the window with all subwindows).  The status
  81 structure, which contains information about individual line changes in
  82 the window, is private to each window.  The routine \fBwrefresh\fR
  83 uses the status data structure when performing screen updating.  Since
  84 status structures are not shared, changes made to one window in the
  85 hierarchy may not be properly reflected on the screen.
  86
  87 The routine \fBwsyncup\fR causes the changes in the status structure
  88 of a window to be reflected in the status structures of its ancestors.
  89 If \fBsyncok\fR is called with second argument \fBTRUE\fR then
  90 \fBwsyncup\fR is called automatically whenever there is a change in
  91 the window.
  92
  93 The routine \fBwcursyncup\fR updates the current cursor position of all the
  94 ancestors of the window to reflect the current cursor position of the
  95 window.
  96
  97 The routine \fBwsyncdown\fR updates the status structure of the window
  98 to reflect the changes in the status structures of its ancestors.
  99 Applications seldom call this routine because it is called
 100 automatically by \fBwrefresh\fR.
 101 .SH RETURN VALUE
 102 Routines that return an integer return the integer \fBERR\fR upon failure and
 103 an integer value other than \fBERR\fR upon successful completion.
 104
 105 \fBdelwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR
 106 upon successful completion.
 107
 108 Routines that return pointers return \fBNULL\fR on error.
 109 .SH NOTES
 110 If many small changes are made to the window, the \fBwsyncup\fR option could
 111 degrade performance.
 112
 113 Note that \fBsyncok\fR may be a macro.
 114 .SH BUGS
 115 The subwindow functions (\fIsubwin\fR, \fIderwin\fR, etc.) are flaky,
 116 incompletely implemented, and not well tested, especially in their
 117 interaction with scrolling.
 118 .SH SEE ALSO
 119 \fBncurses\fR(3), \fBcurs_refresh\fR(3), \fBcurs_touch\fR(3)
 120 .\"#
 121 .\"# The following sets edit modes for GNU EMACS
 122 .\"# Local Variables:
 123 .\"# mode:nroff
 124 .\"# fill-column:79
 125 .\"# End: