path: root/usr/src/man/man3xcurses/curses.3xcurses

'\" 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 CURSES 3XCURSES "Jun 5, 2002"
.SH NAME
curses \- introduction and overview of X/Open Curses
.SH DESCRIPTION
.sp
.LP
The Curses screen management package conforms fully with Issue 4, Version 2 of
the  X/Open Curses specification.   It provides a set of internationalized
functions and macros for creating and  modifying input and output to a terminal
screen.  This includes functions for creating windows, highlighting text,
writing to  the screen, reading from user input, and moving the cursor.
.sp
.LP
X/Open Curses is a terminal-independent package, providing a common user
interface to a variety of terminal types.  Its portability  is facilitated by
the Terminfo database which contains a compiled  definition of each terminal
type.  By referring to the database information X/Open Curses gains access to
low-level details about individual terminals.
.sp
.LP
X/Open Curses tailors its activities to the terminal type specified by the
\fBTERM\fR environment variable.  The  \fBTERM\fR environment  variable may be
set in the Korn Shell (see \fBksh\fR(1)) by typing:
.sp
.in +2
.nf
\fBexport TERM=\fR\fIterminal_name\fR
.fi
.in -2
.sp

.sp
.LP
To set environment variables using other command line interfaces or shells, see
the \fBenviron\fR(5) manual page.
.sp
.LP
Three additional environment variables are useful, and can be set in the Korn
Shell:
.RS +4
.TP
1.
If you have an alternate Terminfo database containing terminal types that
are not available in the system default database
\fB/usr/share/lib/terminfo\fR, you can specify the  \fBTERMINFO\fR environment
variable to point to this alternate database:
.sp
.in +2
.nf
\fBexport TERMINFO=\fR\fIpath\fR
.fi
.in -2
.sp

This \fIpath\fR specifies the location of the alternate compiled Terminfo
database whose structure consists of directory names 0 to 9 and a to z  (which
represent the first letter of the compiled terminal definition file  name).
.sp
The alternate database specified by  \fBTERMINFO\fR is  examined before the
system default database.  If the terminal type  specified by  \fBTERM\fR cannot
be found in either database, the default terminal type \fIdumb\fR is assumed.
.RE
.RS +4
.TP
2.
To specify a window width smaller than your screen width (for example, in
situations where your communications line is slow), set the  \fBCOLUMNS\fR
environment  variable to the number of vertical columns you want between the
left and  right margins:
.sp
.in +2
.nf
\fBexport COLUMNS=\fR\fInumber\fR
.fi
.in -2
.sp

The \fInumber\fR of columns may be set to a number smaller than the screen
size; however, if set larger than the screen or window width, the results are
undefined.
.sp
The value set using this environment variable takes precedence over the  value
normally used for the terminal.
.RE
.RS +4
.TP
3.
To specify a window height smaller than your current screen height (for
example, in situations where your communications line is slow), override the
\fBLINES\fR environment variable by setting it to a smaller number of
horizontal lines:
.sp
.in +2
.nf
\fBexport LINES=\fR\fInumber\fR
.fi
.in -2
.sp

The \fInumber\fR of lines may be set to a number smaller than the screen
height; however, if set larger than the screen or window height, the results
are undefined.
.sp
The value set using this environment variable takes precedence over the value
normally used for the terminal.
.RE
.SS "Data Types"
.sp
.LP
X/Open Curses defines the following data types:
.sp
.ne 2
.na
\fB\fBattr_t\fR\fR
.ad
.RS 12n
An integral type that holds an OR-ed set of attributes. The attributes
acceptable are those which begin with the \fBWA_\fR prefix .
.RE

.sp
.ne 2
.na
\fB\fBbool\fR\fR
.ad
.RS 12n
Boolean data type.
.RE

.sp
.ne 2
.na
\fB\fBcchar_t\fR\fR
.ad
.RS 12n
A type that refers to a string consisting of a spacing wide character, up to  5
non-spacing wide characters, and zero or more attributes of any type. See
Attributes, Color Pairs, and Renditions. A null \fBcchar_t\fR object terminates
arrays of \fBcchar_t\fR objects.
.RE

.sp
.ne 2
.na
\fB\fBchtype\fR\fR
.ad
.RS 12n
An integral type whose values are formed by OR-ing an \fB"unsigned char"\fR
with a color pair.  and with zero or more attributes. The attributes acceptable
are those which begin with the \fBA_\fR prefix and \fBCOLOR_PAIR\fR(3XCURSES)
.RE

.sp
.ne 2
.na
\fB\fBSCREEN\fR\fR
.ad
.RS 12n
An opaque data type associated with a terminal's display screen.
.RE

.sp
.ne 2
.na
\fB\fBTERMINAL\fR\fR
.ad
.RS 12n
An opaque data type associated with a terminal. It contains information about
the terminal's capabilities (as defined by \fBterminfo\fR), the terminal modes,
and current state of input/output operations.
.RE

.sp
.ne 2
.na
\fB\fBwchar_t\fR\fR
.ad
.RS 12n
An integral data type whose values represent wide characters.
.RE

.sp
.ne 2
.na
\fB\fBWINDOW\fR\fR
.ad
.RS 12n
An opaque data type associated with a window.
.RE

.SS "Screens, Windows, and Terminals"
.sp
.LP
The X/Open Curses manual pages refer at various points to screens, windows
(also subwindows, derived windows, and pads), and terminals. The following list
defines each of these terms.
.sp
.ne 2
.na
\fBScreen\fR
.ad
.RS 10n
A screen is a terminal's physical output device.  The \fBSCREEN\fR data type is
associated with a terminal.
.RE

.sp
.ne 2
.na
\fBWindow\fR
.ad
.RS 10n
Window objects are two-dimensional arrays of characters and their renditions.
X/Open Curses provides \fIstdscr\fR, a default window which is the size of of
the terminal screen. You can use the \fBnewwin\fR(3XCURSES) function to create
others.
.RE

.sp
.LP
To refer to a window, use a variable declared as \fBWINDOW *\fR. X/Open Curses
includes both functions that modify \fIstdscr\fR, and more general versions
that let you specify a window.
.sp
.LP
There are three sub-types of windows:
.sp
.ne 2
.na
\fBSubwindow\fR
.ad
.RS 18n
A window which has been created within another window (the parent window) and
whose position has been specified with absolute screen coordinates. The
\fBderwin\fR(3XCURSES) and \fBsubwin\fR(3XCURSES) functions can be used to
create  subwindows.
.RE

.sp
.ne 2
.na
\fBDerived Window\fR
.ad
.RS 18n
A subwindow whose position is defined relative to the parent window's
coordinates rather than in absolute terms.
.RE

.sp
.ne 2
.na
\fBPad\fR
.ad
.RS 18n
A special type of window that can be larger than the screen. For more
information, see the  \fBnewpad\fR(3XCURSES) man page.
.RE

.sp
.ne 2
.na
\fBTerminal\fR
.ad
.RS 18n
A terminal is the input and output device which character-based applications
use to interact with the user. The \fBTERMINAL\fR data type is associated with
such a device.
.RE

.SS "Attributes, Color Pairs, and Renditions"
.sp
.LP
A character's rendition consists of its attributes (such as underlining or
reverse video) and its color pair (the foreground and background colors). When
using \fBwaddstr\fR(3XCURSES), \fBwaddchstr\fR(3XCURSES),
\fBwprintw\fR(3XCURSES), \fBwinsch\fR(3XCURSES), and so on, the window's
rendition is combined with that character's renditions. The window rendition is
the attributes and color set using the  \fBattroff\fR(3XCURSES) and
\fBattr_off\fR(3XCURSES) sets of functions. The window's background character
and rendition are set with the  \fBbkgdset\fR(3XCURSES) and
\fBbkgrndset\fR(3XCURSES) sets of functions.
.sp
.LP
When spaces are written to the screen, the background character and window
rendition replace the space. For example, if the background rendition and
character is  \fBA_UNDERLINE|'*'\fR, text written to the window appears
underlined and the spaces appear as underlined asterisks.
.sp
.LP
Each character written retains the rendition that it has obtained. This allows
the character to be copied "as is" to or from a window with the
\fBaddchstr\fR(3XCURSES) or \fBinch\fR(3XCURSES) functions.
.SS "A_ Constant Values for Attributes"
.sp
.LP
You can specify Attributes, Color Pairs, and Renditions attributes using the
constants listed in the tables below. The following constants modify objects of
type \fBchtype\fR:
.sp

.sp
.TS
box;
c c
l l .
\fBConstant\fR	\fBDescription\fR
_
\fBA_ALTCHARSET\fR	Alternate character set
\fBA_ATTRIBUTES\fR	Bit-mask to extract attributes
\fBA_BLINK\fR	Blinking
\fBA_BOLD\fR	Bold
\fBA_CHARTEXT\fR	Bit-mask to extract a character
\fBA_COLOR\fR	T{
Bit-mask to extract color-pair information
T}
\fBA_DIM\fR	Half-bright
\fBA_INVIS\fR	Invisible
\fBA_PROTECT\fR	Protected
\fBA_REVERSE\fR	Reverse video
\fBA_STANDOUT\fR	Highlights specific to terminal
\fBA_UNDERLINE\fR	Underline
.TE

.SS "WA_ Constant Values for Attributes"
.sp
.LP
The following constants modify objects of type \fBattr_t\fR:
.sp

.sp
.TS
box;
c c
l l .
\fBConstant\fR	\fBDescription\fR
_
\fBWA_ALTCHARSET\fR	Alternate character set
\fBWA_ATTRIBUTES\fR	Attribute mask
\fBWA_BLINK\fR	Blinking
\fBWA_BOLD\fR	Bold
\fBWA_DIM\fR	Half-bright
\fBWA_HORIZONTAL\fR	Horizontal highlight
\fBWA_INVIS\fR	Invisible
\fBWA_LEFT\fR	Left highlist
\fBWA_LOW\fR	Low highlist
\fBWA_PROTECT\fR	Protected
\fBWA_REVERSE\fR	Reverse video
\fBWA_RIGHT\fR	Right highlight
\fBWA_STANDOUT\fR	Highlights specific to terminal
\fBWA_TOP\fR	Top highlight
\fBWA_UNDERLINE\fR	Underline
\fBWA_VERTICAL\fR	Vertical highlight
.TE

.SS "Color Macros"
.sp
.LP
Colors always appear in pairs; the foreground color of the character itself and
the background color of the field on which it is displayed. The following color
macros are defined:
.sp

.sp
.TS
box;
c c
l l .
\fBMacro\fR	\fBDescription\fR
_
\fBCOLOR_BLACK\fR	Black
\fBCOLOR_BLUE\fR	Blue
\fBCOLOR_GREEN\fR	Green
\fBCOLOR_CYAN\fR	Cyan
\fBCOLOR_RED\fR	Red
\fBCOLOR_MAGENTA\fR	Magenta
\fBCOLOR_YELLOW\fR	Yellow
\fBCOLOR_WHITE\fR	White
.TE

.sp
.LP
Together, a character's attributes and its color pair form the character's
rendition. A character's rendition moves with the character during any
scrolling or insert/delete operations. If your terminal lacks support for the
specified rendition, X/Open Curses may  substitute a different rendition.
.sp
.LP
The \fBCOLOR_PAIR\fR(3XCURSES) function modifies a \fBchtype\fR object.  The
\fBPAIR_NUMBER\fR(3XCURSES) function extracts the color pair from a
\fBchtype\fR object.
.SS "Functions for Modifying a Window's Color"
.sp
.LP
The following functions modify a window's color:
.sp

.sp
.TS
box;
c c
l l .
\fBFunction\fR	\fBDescription\fR
_
\fBattr_set()\fR, wattr_set(\|)	Change the window's rendition.
\fBcolor_set()\fR, wcolor_set(\|)	Set the window's color
.TE

.SS "Non-Spacing Characters"
.sp
.LP
When the \fBwcwidth\fR(3C) function returns a width of zero for a character,
that character is called a non-spacing character. Non-spacing characters can be
written to a window. Each non-spacing character is associated with a spacing
character (that is, one which does not have a width of zero) and modifies that
character. You cannot address a non-spacing character directly. Whenever you
perform an X/Open Curses operation on the associated character,  you are
implicitly addressing the non-spacing character.
.sp
.LP
Non-spacing characters do not have a rendition. For functions that use wide
characters and a rendition, X/Open Curses ignores any rendition specified for
non-spacing characters. Multi-column characters have one rendition that applies
to all columns spanned.
.SS "Complex Characters"
.sp
.LP
The \fBcchar_t\fR date type represents a complex character. A complex character
may contain a spacing character, its associated non-spacing characters, and its
rendition. This implementation of complex characters supports up to 5
non-spacing characters for each spacing character.
.sp
.LP
When a \fBcchar_t\fR object representing a non-spacing complex character is
written to the screen, its rendition is not used, but rather it becomes
associated with the rendition of the existing character at that location. The
\fBsetcchar\fR(3XCURSES) function initializes an object of type \fBcchar_t\fR.
The \fBgetcchar\fR(3XCURSES) function extracts the contents of a \fBcchar_t\fR
object.
.SS "Display Operations"
.sp
.LP
In adding internationalization support to X/Open Curses, every attempt was made
to minimize the number of changes to the historical CURSES package. This
enables programs written to use the historical implementation of CURSES to use
the internationalized version with little or no modification. The following
rules apply to the internationalized X/Open Curses package:
.RS +4
.TP
.ie t \(bu
.el o
The cursor can be placed anywhere in the window.   Window and screen origins
are (0,0).
.RE
.RS +4
.TP
.ie t \(bu
.el o
A multi-column character cannot be displayed in the last column, because the
character would appear truncated. Instead, the background character is
displayed in the last column and the multi-column character appears at the
beginning of the next line. This is called wrapping.
.sp
If the original line is the last line in the scroll region and scrolling is
enabled, X/Open Curses moves the contents of each line in the region to the
previous line.   The first line of the region is lost. The last line of the
scrolling region contains any wrapped characters.   The remainder of that line
is filled with the background character. If scrolling is disabled, X/Open
Curses truncates any character that would extend past the last column of the
screen.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Overwrites operate on screen columns. If displaying a single-column or
multi-column character results in overwriting  only a portion of a multi-column
character or characters, background characters  are displayed in place of the
non-overwritten portions.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Insertions and deletions operate on whole characters. The cursor is moved to
the first column of the character prior to performing  the operation.
.RE
.SS "Overlapping Windows"
.sp
.LP
When windows overlap, it may be necessary to overwrite only part of a
multi-column character.   As mentioned earlier, the non-overwritten portions
are replaced with the background character. This results in issues concerning
the \fBoverwrite\fR(3XCURSES), \fBoverlay\fR(3XCURSES),
\fBcopywin\fR(3XCURSES), \fBwnoutrefresh\fR(3XCURSES), and
\fBwrefresh\fR(3XCURSES) functions.
.SS "Special Characters"
.sp
.LP
Some functions assign special meanings to certain special characters:
.sp
.ne 2
.na
\fBBackspace\fR
.ad
.RS 22n
Moves the cursor one column towards the beginning of the line.   If the cursor
was already at the beginning of the line, it remains there. All subsequent
characters are added or inserted at this point.
.RE

.sp
.ne 2
.na
\fBCarriage Return\fR
.ad
.RS 22n
Moves the cursor to the beginning of the current line. If the cursor was
already at the beginning of the line, it remains there. All subsequent
characters are added or inserted at this point.
.RE

.sp
.ne 2
.na
\fBNewline\fR
.ad
.RS 22n
When adding characters, X/Open Curses fills the remainder of the line with the
background character (effectively truncating the newline) and scrolls the
window as described earlier. All subsequent characters are inserted at the
start of the new line.
.sp
When inserting characters, X/Open Curses fills the remainder of the line with
the background character (effectively truncating the line), moves the cursor to
the beginning of a new line, and scrolls the window as described earlier. All
subsequent characters are placed at the start of the new line.
.RE

.sp
.ne 2
.na
\fBTab\fR
.ad
.RS 22n
moves subsequent characters to next horizontal tab strop. Default tab stops are
set at 0, 8, 16, and so on.
.sp
When adding or inserting characters, X/Open Curses inserts or adds the
background character into each column until the next tab stop is reached. If
there are no remaining tab stops on the current line, wrapping and  scrolling
occur as described earlier.
.RE

.sp
.ne 2
.na
\fBControl Characters\fR
.ad
.RS 22n
When X/Open Curses functions perform special character processing, they convert
control characters to the \fB^\fR\fIX\fR notation, where \fIX\fR is a
single-column character (uppercase, if it is a letter) and writes that
notation to the window. Functions that retrieve text from the window will
retrieve the converted notation not the original.
.RE

.sp
.LP
X/Open Curses displays non-printable bytes, that have their high bit set, using
the \fBM-\fR\fIX\fR meta notation where \fIX\fR is the non-printable byte with
its high bit turned off.
.SS "Input Processing"
.sp
.LP
There are four input modes possible with X/Open Curses that affect the behavior
of input functions like \fBgetch\fR(3XCURSES) and \fBgetnstr\fR(3XCURSES).
.sp
.ne 2
.na
\fBLine Canonical (Cooked)\fR
.ad
.RS 27n
In line input mode, the terminal driver handles the input of line units as well
as  \fBSIGERASE\fR and \fBSIGKILL\fR character processing.   See
\fBtermio\fR(7I) for more information.
.sp
In this mode, the \fBgetch()\fR and \fBgetnstr()\fR functions will not return
until a complete line has been read by the terminal driver, at which point only
the requested number of bytes/characters are returned.  The rest of the line
unit remains unread until subsequent call to the  \fBgetch()\fR or
\fBgetnstr()\fR functions.
.sp
The functions \fBnocbreak\fR(3XCURSES) and \fBnoraw\fR(3XCURSES) are used to
enter this mode.  These functions are described on the  \fBcbreak\fR(3XCURSES)
man page which also details which \fBtermios\fR flags are enabled.
.sp
Of the modes available, this one gives applications the least amount of control
over input.   However, it is the only input mode possible on a block mode
terminal.
.RE

.sp
.ne 2
.na
\fB\fBcbreak\fR Mode\fR
.ad
.RS 27n
Byte/character input provides a finer degree of control.   The terminal driver
passes each byte read to the application without interpreting erase and kill
characters.   It is the application's responsibility to handle line editing. It
is unknown whether the signal characters (\fBSIGINTR\fR, \fBSIGQUIT\fR,
\fBSIGSUSP\fR) and flow control characters (\fBSIGSTART\fR, \fBSIGSTOP\fR) are
enabled.   To ensure that they are, call the \fBnoraw()\fR function first, then
call the \fBcbreak()\fR function.
.RE

.sp
.ne 2
.na
\fB\fBhalfdelay\fR Mode\fR
.ad
.RS 27n
This is the same as the \fBcbreak()\fR mode with a timeout.   The terminal
driver waits for a byte to be received or for a timer to  expire, in which case
the \fBgetch()\fR function either returns a byte or  \fBERR\fR respectively.
This mode overrides timeouts set for an individual window with the
\fBwtimeout()\fR function.
.RE

.sp
.ne 2
.na
\fB\fBraw\fR Mode\fR
.ad
.RS 27n
This mode provides byte/character input with the most control for  an
application. It is similar to \fBcbreak()\fR mode, but also disables signal
character processing (\fBSIGINTR\fR, \fBSIGSUSP\fR, \fBSIGQUIT\fR) and flow
control  processing (\fBSIGSTART\fR, \fBSIGSTOP\fR) so that the application can
process  them as it wants.
.RE

.sp
.LP
These modes affect all X/Open Curses input.  The default input mode is
inherited from the parent process when the  application starts up.
.sp
.LP
A timeout similar to \fBhalfdelay\fR(3XCURSES) can be applied to individual
windows (see  \fBtimeout\fR(3XCURSES)). The \fBnodelay\fR(3XCURSES) function is
equivalent to setting \fBwtimeout\fR(3XCURSES) for a window with a zero timeout
(non-blocking) or infinite delay (blocking).
.sp
.LP
To handle function keys, \fBkeypad\fR(3XCURSES) must be enabled.   When it is
enabled, the \fBgetch()\fR function returns a \fBKEY_\fR constant for a
uniquely encoded key defined for that terminal.   When \fBkeypad()\fR is
disabled, the \fBgetch()\fR function returns the  individual bytes composing
the function key (see  \fBgetch\fR(3XCURSES) and  \fBwget_wch\fR(3XCURSES)). By
default, \fBkeypad()\fR is disabled.
.sp
.LP
When processing function keys, once the first byte is recognized, a timer is
set for each subsequent byte in the sequence.   If any byte in the function key
sequence is not received before the timer  expires, the bytes already received
are pushed into a buffer and the original  first byte is returned. Subsequent
X/Open Curses input would take bytes from the buffer until exhausted,  after
which new input from the terminal will be requested.   Enabling and disabling
of the function key interbyte timer is handled by  the
\fBnotimeout\fR(3XCURSES) function.   By default, \fBnotimeout()\fR is disabled
(that is, the timer is used).
.sp
.LP
X/Open Curses always disables the terminal driver's echo processing.   The
\fBecho\fR(3XCURSES) and \fBnoecho\fR(3XCURSES) functions control X/Open Curses
software  echoing.   When software echoing is enabled, X/Open Curses input
functions echo printable  characters, control keys, and meta keys in the input
window at the last cursor  position.   Functions keys are never echoed.   When
software echoing is disabled, it is the application's responsibility to  handle
echoing.
.SH EXAMPLES
.LP
\fBExample 1 \fRCopying Single-Column Characters Over Single-Column Characters
.sp
.LP
In the upcoming examples, some characters have special meanings:

.RS +4
.TP
.ie t \(bu
.el o
\fB{\fR, \fB[\fR, and \fB(\fR represent the left halves of multi-column
characters. \fB}\fR, \fB]\fR, and \fB)\fR represent the corresponding right
halves  of the same multi-column characters.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Alphanumeric characters and periods (\fB\&.\fR) represent single-column
characters.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The number sign (\fB#\fR) represents the background character.
.RE
.sp
.in +2
.nf
copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

            s               t         \(->     t
        abcdef        ......          .bcd..
        ghijkl        ......          .hij..
.fi
.in -2

.sp
.LP
  There are no special problems with this situation.

.LP
\fBExample 2 \fRCopying Multi-column Characters Over Single-Column Characters
.sp
.in +2
.nf
copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

            s               t         \(->     t
        a[]def        ......          .[]d..
        gh()kl        ......          .h()..
.fi
.in -2

.sp
.LP
There are no special problems with this situation.

.LP
\fBExample 3 \fRCopying Single-Column Characters From Source Overlaps
Multi-column Characters In Target
.sp
.in +2
.nf
copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

            s               t         \(->     t
        abcdef        []....          #bcd..
        ghijk tol        ...().          .hij#.
.fi
.in -2

.sp
.LP
Overwriting multi-column characters in \fBt\fR has resulted in the \fB#\fR
background characters being required to erase the remaining halves of the
target's multi-column characters.

.LP
\fBExample 4 \fRCopy Incomplete Multi-column Characters From Source To Target.
.sp
.in +2
.nf
copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

            s               t         \(->     t
        []cdef        123456          []cd56
        ghi()l        789012          7hi()2
.fi
.in -2

.sp
.LP
The \fB]\fR and \fB(\fR halves of the multi-column characters have been copied
from the source and expanded in the target outside of the specified target
region.

.sp
.LP
Consider a pop-up dialog box that contains single-column characters and a base
window that contains multi-column characters and you do the following:

.sp
.in +2
.nf
save=dupwin(dialog);     /* create backing store */
overwrite(cursor, save); /* save region to be overlayed */
wrefresh(dialog);        /* display dialog */
wrefresh(save);          /* restore screen image */
delwin(save);            /* release backing store */
.fi
.in -2

.sp
.LP
You can use code similar to this to implement generic \fBpopup()\fR and
\fBpopdown()\fR routines in a variety of CURSES implementations (including  BSD
UNIX, and UNIX System V). In the simple case where the base window contains
single-column characters  only, it would correctly restore the image that
appeared on the screen before  the dialog box was displayed.

.sp
.LP
However, with multi-column characters, the \fBoverwrite()\fR function might
save a region with incomplete multi-column characters. The
\fBwrefresh(dialog)\fR statement results in the behavior described in example 3
above. The behavior described in this example (that is, example 4) allows the
\fBwrefresh(save)\fR statement to restore the window correctly.

.LP
\fBExample 5 \fRCopying An Incomplete Multi-column Character To  Region Next To
Screen Margin  (Not A Window Edge)
.sp
.LP
 Two cases of copying an incomplete multi-column character to a region next to
a screen margin follow:

.sp
.in +2
.nf
copywin(s, t, 0, 1, 0, 0, 1, 2, 0)

            s               t         \(->     t
        []cdef        123456          #cd456
        ghijkl        789012          hij012
.fi
.in -2

.sp
.LP
The background character (\fB#\fR) replaces the \fB]\fR character that would
have been copied from the source, because it is not possible to expand the
multi-column character to its complete form.

.sp
.in +2
.nf
copywin(s, t, 0, 1, 0, 3, 1, 5, 0)

            s               t         \(->     t
        abcdef        123456          123bcd
        ghi()l        789012          789hi#
.fi
.in -2

.sp
.LP
This second example is the same as the first, but with the right margin.

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBksh\fR(1), \fBCOLOR_PAIR\fR(3XCURSES), \fBPAIR_NUMBER\fR(3XCURSES),
\fBaddchstr\fR(3XCURSES), \fBattr_off\fR(3XCURSES), \fBattroff\fR(3XCURSES),
\fBbkgdset\fR(3XCURSES), \fBbkgrndset\fR(3XCURSES), \fBcbreak\fR(3XCURSES),
\fBcopywin\fR(3XCURSES), \fBderwin\fR(3XCURSES), \fBecho\fR(3XCURSES),
\fBgetcchar\fR(3XCURSES), \fBgetch\fR(3XCURSES), \fBgetnstr\fR(3XCURSES),
\fBhalfdelay\fR(3XCURSES), \fBinch\fR(3XCURSES), \fBkeypad\fR(3XCURSES),
\fBlibcurses\fR(3XCURSES), \fBnewpad\fR(3XCURSES), \fBnewwin\fR(3XCURSES),
\fBnocbreak\fR(3XCURSES), \fBnodelay\fR(3XCURSES), \fBnoecho\fR(3XCURSES),
\fBnoraw\fR(3XCURSES), \fBnotimeout\fR(3XCURSES), \fBoverlay\fR(3XCURSES),
\fBoverwrite\fR(3XCURSES), \fBsetcchar\fR(3XCURSES), \fBsubwin\fR(3XCURSES),
\fBtimeout\fR(3XCURSES), \fBwaddchstr\fR(3XCURSES), \fBwaddstr\fR(3XCURSES),
\fBwcwidth\fR(3C), \fBwget_wch\fR(3XCURSES), \fBwinsch\fR(3XCURSES),
\fBwnoutrefresh\fR(3XCURSES), \fBwprintw\fR(3XCURSES),
\fBwrefresh\fR(3XCURSES), \fBwtimeout\fR(3XCURSES), \fBattributes\fR(5),
\fBenviron\fR(5), \fBstandards\fR(5), \fBtermio\fR(7I)