'\" te
.\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH derwin 3XCURSES "5 Jun 2002" "SunOS 5.11" "X/Open Curses Library Functions"
.SH NAME
derwin, newwin, subwin \- create a new window or subwindow
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
\fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]

\fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
 
#include <curses.h>

\fBWINDOW *\fR\fBderwin\fR(\fBWINDOW *\fR\fIorig\fR, \fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR,
     \fBint\fR \fIbegin_y\fR, \fBint\fR \fIbegin_x\fR);
.fi

.LP
.nf
\fBWINDOW *\fR\fBnewwin\fR(\fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR, \fBint\fR \fIbegin_y\fR, \fBint\fR \fIbegin_x\fR);
.fi

.LP
.nf
\fBWINDOW *\fR\fBsubwin\fR(\fBWINDOW *\fR\fIorig\fR, \fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR, \fBint\fR \fIbegin_y\fR,
     \fBint\fR \fIbegin_x\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBderwin()\fR function creates a subwindow within window \fIorig\fR,  with
the specified number of lines and columns, and upper left corner  positioned at
\fIbegin_x\fR, \fIbegin_y\fR relative to window \fIorig\fR.  A pointer to the
new window structure is returned.
.sp
.LP
The \fBnewwin()\fR function creates a new window with the specified number of
lines and columns and upper left corner positioned at \fIbegin_x\fR,
\fIbegin_y\fR.  A pointer to the new window structure is returned.  A
full-screen window can be created by calling \fBnewwin(0,0,0,0)\fR.
.sp
.LP
If the number of lines specified is zero, \fBnewwin()\fR uses a default value
of \fBLINES\fR minus \fIbegin_y\fR; if the number of columns specified is
zero, \fBnewwin()\fR uses the default value of \fBCOLS\fR minus \fIbegin_x\fR.
.sp
.LP
The \fBsubwin()\fR function creates a subwindow within window \fIorig\fR, with
the specified number of lines and columns, and upper left corner positioned at
\fIbegin_x\fR, \fIbegin_y\fR (relative to the physical screen, \fInot\fR to
window \fIorig\fR). A pointer to the new window structure is returned.
.sp
.LP
The original window and subwindow share character storage of the overlapping
area (each window maintains its own pointers, cursor location, and other
items). This means that characters and attributes are identical in overlapping
areas regardless of which window characters are written to.
.sp
.LP
When using subwindows, it is often necessary to call \fBtouchwin\fR(3XCURSES)
before \fBwrefresh\fR(3XCURSES) to maintain proper screen contents.
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIorig\fR\fR
.ad
.RS 11n
.rt  
Is a pointer to the parent window for the newly created subwindow.
.RE

.sp
.ne 2
.mk
.na
\fB\fInlines\fR\fR
.ad
.RS 11n
.rt  
Is the number of lines in the subwindow.
.RE

.sp
.ne 2
.mk
.na
\fB\fIncols\fR\fR
.ad
.RS 11n
.rt  
Is the number of columns in the subwindow.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbegin_y\fR\fR
.ad
.RS 11n
.rt  
Is the y (row) coordinate of the upper left corner of the subwindow, relative
to the parent window.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbegin_x\fR\fR
.ad
.RS 11n
.rt  
Is the x (column) coordinate of the upper left corner of the subwindow,
relative to the parent window.
.RE

.SH RETURN VALUES
.sp
.LP
On success, these functions return a pointer to the newly-created window.
Otherwise, they return \fBERR\fR.
.SH ERRORS
.sp
.LP
None.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityStandard
_
MT-LevelUnsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBdoupdate\fR(3XCURSES), \fBis_linetouched\fR(3XCURSES),
\fBlibcurses\fR(3XCURSES), \fBattributes\fR(5), \fBstandards\fR(5)