man/curs_window.3x

   1 .TH curs_window 3X ""
   2 .SH NAME
   3 \fBnewwin\fR, \fBdelwin\fR, \fBmvwin\fR,
   4 \fBsubwin\fR, \fBderwin\fR, \fBmvderwin\fR, \fBdupwin\fR,
   5 \fBwsyncup\fR, \fBsyncok\fR, \fBwcursyncup\fR, \fBwsyncdown\fR -
   6 create \fBcurses\fR windows
   7 .SH SYNOPSIS
   8 \fB#include <curses.h>\fR
   9
  10 \fBWINDOW *newwin(int nlines, int ncols, int begin_y,\fR
  11       \fBintbegin_x);\fR
  12 .br
  13 \fBint delwin(WINDOW *win);\fR
  14 .br
  15 \fBint mvwin(WINDOW *win, int y, int x);\fR
  16 .br
  17 \fBWINDOW *subwin(WINDOW *orig, int nlines, int ncols,
  18       int begin_y, int begin_x);\fR
  19 .br
  20 \fBWINDOW *derwin(WINDOW *orig, int nlines, int ncols,
  21       int begin_y, int begin_x);\fR
  22 .br
  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 Calling \fBnewwin\fR 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 Calling \fBdelwin\fR 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 Calling \fBmvwin\fR 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 Calling \fBsubwin\fR 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 Calling \fBderwin\fR is the same as calling \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 Calling \fBmvderwin\fR 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 Calling \fBdupwin\fR creates an exact duplicate of the window \fIwin\fR.
  76
  77 Calling \fBwsyncup\fR touches all locations in ancestors of \fIwin\fR that are
  78 changed in \fIwin\fR.  If \fBsyncok\fR is called with second argument
  79 \fBTRUE\fR then \fBwsyncup\fR is called automatically whenever there is a
  80 change in the window.
  81
  82 The \fBwsyncdown\fR routine touches each location in \fIwin\fR that has been
  83 touched in any of its ancestor windows.  This routine is called by
  84 \fBwrefresh\fR, so it should almost never be necessary to call it manually.
  85
  86 The routine \fBwcursyncup\fR updates the current cursor position of all the
  87 ancestors of the window to reflect the current cursor position of the
  88 window.
  89 .SH RETURN VALUE
  90 Routines that return an integer return the integer \fBERR\fR upon failure and
  91 \fBOK\fR (SVr4 only specifies "an integer value other than \fBERR\fR") upon
  92 successful completion.
  93
  94 \fBdelwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR
  95 upon successful completion.
  96
  97 Routines that return pointers return \fBNULL\fR on error.
  98 .SH NOTES
  99 If many small changes are made to the window, the \fBwsyncup\fR option could
 100 degrade performance.
 101
 102 Note that \fBsyncok\fR may be a macro.
 103 .SH BUGS
 104 The subwindow functions (\fIsubwin\fR, \fIderwin\fR, \fImvderwin\fR,
 105 \fBwsyncup\fR, \fBwsyncdown\fR, \fBwcursyncup\fR, \fBsyncok\fR) are flaky,
 106 incompletely implemented, and not well tested.
 107
 108 The System V curses documentation is very unclear about what \fBwsyncup\fR
 109 and \fBwsyncdown\fR actually do.  It seems to imply that they are only
 110 supposed to touch exactly those lines that are affected by ancestor changes.
 111 The language here, and the behavior of the \fBcurses\fR implementation,
 112 is patterned on the XPG4 curses standard.  The weaker XPG4 spec may result
 113 in slower updates.
 114 .SH PORTABILITY
 115 The XSI Curses standard, Issue 4 describes these functions.
 116 .SH SEE ALSO
 117 \fBcurses\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_touch\fR(3X)
 118 .\"#
 119 .\"# The following sets edit modes for GNU EMACS
 120 .\"# Local Variables:
 121 .\"# mode:nroff
 122 .\"# fill-column:79
 123 .\"# End: