xref: /netbsd/lib/libcurses/curses_screen.3 (revision c4a72b64)
1.\"	$NetBSD: curses_screen.3,v 1.3 2002/12/05 19:13:12 jdc Exp $
2.\"
3.\" Copyright (c) 2002
4.\"	Brett Lymn (blymn@netbsd.org, brett_lymn@yahoo.com.au)
5.\"
6.\" This code is donated to the NetBSD Foundation by the Author.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. The name of the Author may not be used to endorse or promote
17.\"    products derived from this software without specific prior written
18.\"    permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"
33.Dd August 12, 2002
34.Dt CURSES_SCREEN 3
35.Os
36.Sh NAME
37.Nm curses_screen ,
38.Nm newterm ,
39.Nm set_term ,
40.Nm delscreen ,
41.Nm endwin ,
42.Nm initscr ,
43.Nm isendwin ,
44.Nm resizeterm ,
45.Nm setterm
46.Nd curses terminal and screen routines
47.Sh LIBRARY
48.Lb libcurses
49.Sh SYNOPSIS
50.Fd #include \*[Lt]curses.h\*[Gt]
51.Ft SCREEN *
52.Fn newterm "char *type" "FILE *outfd" "FILE *infd"
53.Ft SCREEN *
54.Fn set_term "SCREEN *screen"
55.Ft void
56.Fn delscreen "SCREEN *screen"
57.Ft int
58.Fn endwin "void"
59.Ft int
60.Fn initscr "void"
61.Ft bool
62.Fn isendwin "void"
63.Ft int
64.Fn resizeterm "int lines" "int cols"
65.Ft int
66.Fn setterm "char *name"
67.Sh DESCRIPTION
68These functions initialize terminals and screens.
69.Pp
70The
71.Fn newterm
72function initialises the curses datastructures and pointers ready for
73use by curses.
74The
75.Fa type
76argument points to a
77.Xr termcap 5
78capability name, or it may be
79.Dv NULL
80in which case the TERM environment variable is used.
81The
82.Fa outfd
83and
84.Fa infd
85are the output and input file descriptors for the terminal.
86The
87.Fn newterm
88function must only be called once  per terminal.
89.Pp
90The
91.Fn set_term
92function can be used to switch between the screens defined by calling
93.Fn newterm ,
94a pointer to the previous screen structure that was in use will be
95returned on success.
96.Pp
97Calling
98.Fn delscreen
99will destroy the given screen and free all allocated resources.
100.Pp
101Calling
102.Fn endwin
103will end the curses session and restore the saved terminal settings.
104.Pp
105The curses session must be initialised by calling
106.Fn initscr
107which saves the current terminal state and sets up the terminal and
108internal data structures to support the curses application.
109This
110function call must be, with few exceptions, the first curses library
111call made.
112The exception to this rule is the
113.Fn newterm
114call which may be called prior to
115.Fn initscr .
116.Pp
117The
118.Fn isendwin
119function can be used to determine whether or not a refresh of the
120screen has occurred since the last call to
121.Fn endwin .
122.Pp
123The size of the screen may be changed  by calling
124.Fn resizeterm
125with the updated number of lines and columns.
126This will resize the curses internal data structures to accomodate the
127changed terminal geometry.
128The application must redraw the screen after a call to
129.Fn resizeterm .
130.Pp
131The
132.Fn setterm
133function sets the terminal type for the current screen to the one
134passed, initialising all the curses internal data structures with
135information related to the named terminal.
136The
137.Fa name
138argument must be a valid name or alias in the
139.Xr termcap 5
140database for this function to succeed.
141.Sh RETURN VALUES
142Functions returning pointers will return
143.Dv NULL
144if an error is detected.
145The functions that return an int will return one of the following
146values:
147.Pp
148.Bl -tag -width ERR -compact
149.It Er OK
150The function completed successfully.
151.It Er ERR
152An error occurred in the function.
153.El
154.Sh SEE ALSO
155.Xr curses_window 3 ,
156.Xr termcap 5
157.Sh STANDARDS
158The
159.Lb libcurses
160library complies with the X/Open Curses specification, part of the
161Single Unix Specification.
162.Nx
163.Sh HISTORY
164The Curses package appeared in
165.Bx 4.0 .
166The
167.Fn resizeterm
168function is a ncurses extension to the Curses library and was added in
169.Nx 1.6 .
170