usr/src/man/man3xcurses/derwin.3xcurses

   1 '\" te
   2 .\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DERWIN 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 derwin, newwin, subwin \- create a new window or subwindow
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  13 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  14
  15 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
  16
  17 #include <curses.h>
  18
  19 \fBWINDOW *\fR\fBderwin\fR(\fBWINDOW *\fR\fIorig\fR, \fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR,
  20      \fBint\fR \fIbegin_y\fR, \fBint\fR \fIbegin_x\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBWINDOW *\fR\fBnewwin\fR(\fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR, \fBint\fR \fIbegin_y\fR, \fBint\fR \fIbegin_x\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBWINDOW *\fR\fBsubwin\fR(\fBWINDOW *\fR\fIorig\fR, \fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR, \fBint\fR \fIbegin_y\fR,
  31      \fBint\fR \fIbegin_x\fR);
  32 .fi
  33
  34 .SH DESCRIPTION
  35 .sp
  36 .LP
  37 The \fBderwin()\fR function creates a subwindow within window \fIorig\fR,  with
  38 the specified number of lines and columns, and upper left corner  positioned at
  39 \fIbegin_x\fR, \fIbegin_y\fR relative to window \fIorig\fR.  A pointer to the
  40 new window structure is returned.
  41 .sp
  42 .LP
  43 The \fBnewwin()\fR function creates a new window with the specified number of
  44 lines and columns and upper left corner positioned at \fIbegin_x\fR,
  45 \fIbegin_y\fR.  A pointer to the new window structure is returned.  A
  46 full-screen window can be created by calling \fBnewwin(0,0,0,0)\fR.
  47 .sp
  48 .LP
  49 If the number of lines specified is zero, \fBnewwin()\fR uses a default value
  50 of \fBLINES\fR minus \fIbegin_y\fR; if the number of columns specified is
  51 zero, \fBnewwin()\fR uses the default value of \fBCOLS\fR minus \fIbegin_x\fR.
  52 .sp
  53 .LP
  54 The \fBsubwin()\fR function creates a subwindow within window \fIorig\fR, with
  55 the specified number of lines and columns, and upper left corner positioned at
  56 \fIbegin_x\fR, \fIbegin_y\fR (relative to the physical screen, \fInot\fR to
  57 window \fIorig\fR). A pointer to the new window structure is returned.
  58 .sp
  59 .LP
  60 The original window and subwindow share character storage of the overlapping
  61 area (each window maintains its own pointers, cursor location, and other
  62 items). This means that characters and attributes are identical in overlapping
  63 areas regardless of which window characters are written to.
  64 .sp
  65 .LP
  66 When using subwindows, it is often necessary to call \fBtouchwin\fR(3XCURSES)
  67 before \fBwrefresh\fR(3XCURSES) to maintain proper screen contents.
  68 .SH PARAMETERS
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIorig\fR\fR
  73 .ad
  74 .RS 11n
  75 Is a pointer to the parent window for the newly created subwindow.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fInlines\fR\fR
  82 .ad
  83 .RS 11n
  84 Is the number of lines in the subwindow.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fIncols\fR\fR
  91 .ad
  92 .RS 11n
  93 Is the number of columns in the subwindow.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fIbegin_y\fR\fR
 100 .ad
 101 .RS 11n
 102 Is the y (row) coordinate of the upper left corner of the subwindow, relative
 103 to the parent window.
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fIbegin_x\fR\fR
 110 .ad
 111 .RS 11n
 112 Is the x (column) coordinate of the upper left corner of the subwindow,
 113 relative to the parent window.
 114 .RE
 115
 116 .SH RETURN VALUES
 117 .sp
 118 .LP
 119 On success, these functions return a pointer to the newly-created window.
 120 Otherwise, they return \fBERR\fR.
 121 .SH ERRORS
 122 .sp
 123 .LP
 124 None.
 125 .SH ATTRIBUTES
 126 .sp
 127 .LP
 128 See \fBattributes\fR(5) for descriptions of the following attributes:
 129 .sp
 130
 131 .sp
 132 .TS
 133 box;
 134 c | c
 135 l | l .
 136 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 137 _
 138 Interface Stability     Standard
 139 _
 140 MT-Level        Unsafe
 141 .TE
 142
 143 .SH SEE ALSO
 144 .sp
 145 .LP
 146 \fBdoupdate\fR(3XCURSES), \fBis_linetouched\fR(3XCURSES),
 147 \fBlibcurses\fR(3XCURSES), \fBattributes\fR(5), \fBstandards\fR(5)