| 1 | .\"***************************************************************************
|
|---|
| 2 | .\" Copyright (c) 1998-2003,2005 Free Software Foundation, Inc. *
|
|---|
| 3 | .\" *
|
|---|
| 4 | .\" Permission is hereby granted, free of charge, to any person obtaining a *
|
|---|
| 5 | .\" copy of this software and associated documentation files (the *
|
|---|
| 6 | .\" "Software"), to deal in the Software without restriction, including *
|
|---|
| 7 | .\" without limitation the rights to use, copy, modify, merge, publish, *
|
|---|
| 8 | .\" distribute, distribute with modifications, sublicense, and/or sell *
|
|---|
| 9 | .\" copies of the Software, and to permit persons to whom the Software is *
|
|---|
| 10 | .\" furnished to do so, subject to the following conditions: *
|
|---|
| 11 | .\" *
|
|---|
| 12 | .\" The above copyright notice and this permission notice shall be included *
|
|---|
| 13 | .\" in all copies or substantial portions of the Software. *
|
|---|
| 14 | .\" *
|
|---|
| 15 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|---|
| 16 | .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|---|
| 17 | .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|---|
| 18 | .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|---|
| 19 | .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|---|
| 20 | .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|---|
| 21 | .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|---|
| 22 | .\" *
|
|---|
| 23 | .\" Except as contained in this notice, the name(s) of the above copyright *
|
|---|
| 24 | .\" holders shall not be used in advertising or otherwise to promote the *
|
|---|
| 25 | .\" sale, use or other dealings in this Software without prior written *
|
|---|
| 26 | .\" authorization. *
|
|---|
| 27 | .\"***************************************************************************
|
|---|
| 28 | .\"
|
|---|
| 29 | .\" $Id: curs_initscr.3x,v 1.14 2005/05/15 16:18:01 tom Exp $
|
|---|
| 30 | .TH curs_initscr 3X ""
|
|---|
| 31 | .na
|
|---|
| 32 | .hy 0
|
|---|
| 33 | .SH NAME
|
|---|
| 34 | \fBinitscr\fR,
|
|---|
| 35 | \fBnewterm\fR,
|
|---|
| 36 | \fBendwin\fR,
|
|---|
| 37 | \fBisendwin\fR,
|
|---|
| 38 | \fBset_term\fR,
|
|---|
| 39 | \fBdelscreen\fR - \fBcurses\fR screen initialization and manipulation routines
|
|---|
| 40 | .ad
|
|---|
| 41 | .hy
|
|---|
| 42 | .SH SYNOPSIS
|
|---|
| 43 | \fB#include <curses.h>\fR
|
|---|
| 44 | .sp
|
|---|
| 45 | \fBWINDOW *initscr(void);\fR
|
|---|
| 46 | .br
|
|---|
| 47 | \fBint endwin(void);\fR
|
|---|
| 48 | .br
|
|---|
| 49 | \fBbool isendwin(void);\fR
|
|---|
| 50 | .br
|
|---|
| 51 | \fBSCREEN *newterm(char *type, FILE *outfd, FILE *infd);\fR
|
|---|
| 52 | .br
|
|---|
| 53 | \fBSCREEN *set_term(SCREEN *new);\fR
|
|---|
| 54 | .br
|
|---|
| 55 | \fBvoid delscreen(SCREEN* sp);\fR
|
|---|
| 56 | .br
|
|---|
| 57 | .SH DESCRIPTION
|
|---|
| 58 | \fBinitscr\fR is normally the first \fBcurses\fR routine to call when
|
|---|
| 59 | initializing a program. A few special routines sometimes need to be
|
|---|
| 60 | called before it; these are \fBslk_init\fR, \fBfilter\fR, \fBripoffline\fR,
|
|---|
| 61 | \fBuse_env\fR. For multiple-terminal applications, \fBnewterm\fR may be
|
|---|
| 62 | called before \fBinitscr\fR.
|
|---|
| 63 | .PP
|
|---|
| 64 | The initscr code determines the terminal type and initializes all \fBcurses\fR
|
|---|
| 65 | data structures. \fBinitscr\fR also causes the first call to \fBrefresh\fR to
|
|---|
| 66 | clear the screen. If errors occur, \fBinitscr\fR writes an appropriate error
|
|---|
| 67 | message to standard error and exits; otherwise, a pointer is returned to
|
|---|
| 68 | \fBstdscr\fR.
|
|---|
| 69 | .PP
|
|---|
| 70 | A program that outputs to more than one terminal should use the \fBnewterm\fR
|
|---|
| 71 | routine for each terminal instead of \fBinitscr\fR. A program that needs to
|
|---|
| 72 | inspect capabilities, so it can continue to run in a line-oriented mode if the
|
|---|
| 73 | terminal cannot support a screen-oriented program, would also use
|
|---|
| 74 | \fBnewterm\fR. The routine \fBnewterm\fR should be called once for each
|
|---|
| 75 | terminal. It returns a variable of type \fBSCREEN *\fR which should be saved
|
|---|
| 76 | as a reference to that terminal. The arguments are the \fItype\fR of the
|
|---|
| 77 | terminal to be used in place of \fB$TERM\fR, a file pointer for output to the
|
|---|
| 78 | terminal, and another file pointer for input from the terminal (if \fItype\fR
|
|---|
| 79 | is \fBNULL\fR, \fB$TERM\fR will be used). The program must also call
|
|---|
| 80 | \fBendwin\fR for each terminal being used before exiting from \fBcurses\fR.
|
|---|
| 81 | If \fBnewterm\fR is called more than once for the same terminal, the first
|
|---|
| 82 | terminal referred to must be the last one for which \fBendwin\fR is called.
|
|---|
| 83 | .PP
|
|---|
| 84 | A program should always call \fBendwin\fR before exiting or escaping from
|
|---|
| 85 | \fBcurses\fR mode temporarily. This routine restores tty modes, moves the
|
|---|
| 86 | cursor to the lower left-hand corner of the screen and resets the terminal into
|
|---|
| 87 | the proper non-visual mode. Calling \fBrefresh\fR or \fBdoupdate\fR after a
|
|---|
| 88 | temporary escape causes the program to resume visual mode.
|
|---|
| 89 | .PP
|
|---|
| 90 | The \fBisendwin\fR routine returns \fBTRUE\fR if \fBendwin\fR has been
|
|---|
| 91 | called without any subsequent calls to \fBwrefresh\fR, and \fBFALSE\fR
|
|---|
| 92 | otherwise.
|
|---|
| 93 | .PP
|
|---|
| 94 | The \fBset_term\fR routine is used to switch between different
|
|---|
| 95 | terminals. The screen reference \fBnew\fR becomes the new current
|
|---|
| 96 | terminal. The previous terminal is returned by the routine. This is
|
|---|
| 97 | the only routine which manipulates \fBSCREEN\fR pointers; all other
|
|---|
| 98 | routines affect only the current terminal.
|
|---|
| 99 | .PP
|
|---|
| 100 | The \fBdelscreen\fR routine frees storage associated with the
|
|---|
| 101 | \fBSCREEN\fR data structure. The \fBendwin\fR routine does not do
|
|---|
| 102 | this, so \fBdelscreen\fR should be called after \fBendwin\fR if a
|
|---|
| 103 | particular \fBSCREEN\fR is no longer needed.
|
|---|
| 104 | .SH RETURN VALUE
|
|---|
| 105 | \fBendwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR
|
|---|
| 106 | upon successful completion.
|
|---|
| 107 | .PP
|
|---|
| 108 | Routines that return pointers always return \fBNULL\fR on error.
|
|---|
| 109 | .PP
|
|---|
| 110 | X/Open defines no error conditions.
|
|---|
| 111 | In this implementation
|
|---|
| 112 | \fBendwin\fP returns an error if the terminal was not initialized.
|
|---|
| 113 | .SH NOTES
|
|---|
| 114 | Note that \fBinitscr\fR and \fBnewterm\fR may be macros.
|
|---|
| 115 | .SH PORTABILITY
|
|---|
| 116 | These functions are described in the XSI Curses standard, Issue 4. It
|
|---|
| 117 | specifies that portable applications must not call \fBinitscr\fR more than
|
|---|
| 118 | once.
|
|---|
| 119 | .PP
|
|---|
| 120 | Old versions of curses, e.g., BSD 4.4, may have returned a null pointer
|
|---|
| 121 | from \fBinitscr\fR when an error is detected, rather than exiting.
|
|---|
| 122 | It is safe but redundant to check the return value of \fBinitscr\fR
|
|---|
| 123 | in XSI Curses.
|
|---|
| 124 | .SH SEE ALSO
|
|---|
| 125 | \fBcurses\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_refresh\fR(3X),
|
|---|
| 126 | \fBcurs_slk\fR(3X), \fBcurs_util\fR(3X)
|
|---|
| 127 | .\"#
|
|---|
| 128 | .\"# The following sets edit modes for GNU EMACS
|
|---|
| 129 | .\"# Local Variables:
|
|---|
| 130 | .\"# mode:nroff
|
|---|
| 131 | .\"# fill-column:79
|
|---|
| 132 | .\"# End:
|
|---|
