1.\" $NetBSD: curses_screen.3,v 1.28 2021/02/07 23:00:57 rillig 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 March 12, 2020 34.Dt CURSES_SCREEN 3 35.Os 36.Sh NAME 37.Nm curses_screen , 38.Nm filter , 39.Nm ripoffline , 40.Nm use_env , 41.Nm newterm , 42.Nm set_term , 43.Nm delscreen , 44.Nm endwin , 45.Nm initscr , 46.Nm isendwin , 47.Nm is_term_resized , 48.Nm resize_term , 49.Nm resizeterm , 50.Nm setterm , 51.Nm set_tabsize 52.Nd curses terminal and screen routines 53.Sh LIBRARY 54.Lb libcurses 55.Sh SYNOPSIS 56.In curses.h 57.Ft void 58.Fn filter "void" 59.Ft int 60.Fn ripoffline "int line" "int (*init)(WINDOW *win, int cols)" 61.Ft void 62.Fn use_env "bool value" 63.Ft SCREEN * 64.Fn newterm "char *type" "FILE *outfd" "FILE *infd" 65.Ft SCREEN * 66.Fn set_term "SCREEN *screen" 67.Ft void 68.Fn delscreen "SCREEN *screen" 69.Ft int 70.Fn endwin "void" 71.Ft WINDOW * 72.Fn initscr "void" 73.Ft bool 74.Fn isendwin "void" 75.Ft bool 76.Fn is_term_resized "int lines" "int cols" 77.Ft int 78.Fn resize_term "int lines" "int cols" 79.Ft int 80.Fn resizeterm "int lines" "int cols" 81.Ft int 82.Fn setterm "char *name" 83.Ft int 84.Fn set_tabsize "int value" 85.Pp 86.Va extern int LINES ; 87.Pp 88.Va extern int COLS ; 89.Sh DESCRIPTION 90These functions initialize terminals and screens. 91.Pp 92The 93.Fn newterm 94function initialises the curses data structures and pointers ready for 95use by curses. 96The 97.Fa type 98argument points to a 99.Xr terminfo 5 100entry, or it may be 101.Dv NULL 102in which case the TERM environment variable is used. 103The 104.Fa outfd 105and 106.Fa infd 107are the output and input file descriptors for the terminal. 108The 109.Fn newterm 110function must only be called once per terminal. 111.Pp 112The 113.Fn set_term 114function can be used to switch between the screens defined by calling 115.Fn newterm , 116a pointer to the previous screen structure that was in use will be 117returned on success. 118.Pp 119Calling 120.Fn delscreen 121will destroy the given screen and free all allocated resources. 122.Pp 123Calling 124.Fn endwin 125will end the curses session and restore the saved terminal settings. 126.Pp 127The curses session must be initialised by calling 128.Fn initscr 129which saves the current terminal state and sets up the terminal and 130internal data structures to support the curses application. 131This 132function call must be, with few exceptions, the first Curses library 133call made. 134The exception to this rule is the 135.Fn newterm 136call which may be called prior to 137.Fn initscr . 138The size of the curses screen is determined by checking the 139.Xr tty 4 140size and then the 141.Xr terminfo 5 142entries for the terminal type. 143If the environment variables 144.Ev LINES 145or 146.Ev COLUMNS 147are set, then these will be used instead. 148.Pp 149When either 150.Fn newterm 151or 152.Fn initscr 153are called, the Curses library sets up signal handlers for 154.Dv SIGTSTP 155and 156.Dv SIGWINCH . 157If a signal handler is already installed for 158.Dv SIGWINCH , 159this will also be called when the Curses library handler is called. 160.Pp 161The 162.Fn isendwin 163function can be used to determine whether or not a refresh of the 164screen has occurred since the last call to 165.Fn endwin . 166.Pp 167The size of the screen may be changed by calling 168.Fn resize_term 169with the updated number of lines and columns. 170This will resize the curses internal data structures to accommodate the 171changed terminal geometry. 172The 173.Dv curscr 174and 175.Dv stdscr 176windows and any of their subwindows will be resized to fit the new 177screen size. 178The application must redraw the screen after a call to 179.Fn resize_term . 180The 181.Fn resizeterm 182function is a wrapper for 183.Fn resize_term 184and adjusts other structure data that handles window dimensions. 185The 186.Fn is_term_resized 187function tests if either of the above functions need to be called. 188.Pp 189The 190.Fn setterm 191function sets the terminal type for the current screen to the one 192passed, initialising all the curses internal data structures with 193information related to the named terminal. 194The 195.Fa name 196argument must be a valid name or alias in the 197.Xr terminfo 5 198database for this function to succeed. 199.Pp 200The 201.Fn filter 202function changes the way the terminal is initialised. 203A subsequent call to 204.Fn initscr 205or 206.Fn newterm 207performs the following additional actions: 208.Bl -bullet -compact 209.It 210Disable use of clear, cud, cud1, cup, cuu, cuu1 and vpa. 211.It 212Set the value of the home string to the value of the cr string. 213.It 214Set lines equal to 1. 215.El 216.Pp 217The 218.Fn ripoffline 219function will rip a line from 220.Dv stdscr 221at the top if 222.Fa line 223is positive, or at the bottom if negative. 224When 225.Fn initscr 226or 227.Fn newterm 228is called, a window will be created for each line ripped and passed 229to the 230.Fa init 231function pointer alongwith the number of columns in the window. 232This init function cannot use the 233.Dv LINES 234or 235.Dv COLS 236variables and cannot call 237.Xr wrefresh 3 238or 239.Xr doupdate 3 , 240but may call 241.Xr wnoutrefresh 3 . 242.Fn ripoffline 243can be called up to five times. 244.Pp 245The 246.Fn use_env 247function determines whether the environment variables 248.Ev LINES 249and 250.Ev COLUMNS 251override the normal values. 252The default is true. 253Any call to 254.Fn use_env 255must precede calls to 256.Fn initscr , 257.Fn newterm , 258or 259.Fn setupterm . 260.Pp 261The 262.Fn set_tabsize 263function will set 264.Va TABSIZE 265of the current screen to 266.Va tabsize . 267.Sh RETURN VALUES 268Functions returning pointers will return 269.Dv NULL 270if an error is detected with the exception of 271.Fn initscr 272which will log a diagnostic to standard error output and then call 273.Xr exit 3 . 274The functions that return an int will return one of the following 275values: 276.Pp 277.Bl -tag -width ERR -compact 278.It Er OK 279The function completed successfully. 280.It Er ERR 281An error occurred in the function. 282.El 283.Sh SEE ALSO 284.Xr curses_window 3 , 285.Xr tty 4 , 286.Xr terminfo 5 , 287.Xr signal 7 288.Sh STANDARDS 289The 290.Nx 291Curses library complies with the X/Open Curses specification, part of the 292Single Unix Specification. 293.Sh HISTORY 294The Curses package appeared in 295.Bx 4.0 . 296The 297.Fn resizeterm 298function is an 299.Em ncurses 300extension to the Curses library and was added in 301.Nx 1.6 . 302The 303.Fn is_term_resized , 304.Fn resize_term 305and 306.Fn set_tabsize 307functions are 308.Em ncurses 309extensions to the Curses library and were added in 310.Nx 8.0 . 311.Sh BUGS 312There is currently an issue with cursor movement in a 1 line sized window 313which causes the screen to scroll up. 314This can obviously be seen when using 315.Fn ripoffline . 316