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