1*23b2be97Sblymn.\" $NetBSD: curses_tty.3,v 1.1 2002/10/21 13:55:23 blymn Exp $ 2*23b2be97Sblymn.\" 3*23b2be97Sblymn.\" Copyright (c) 2002 4*23b2be97Sblymn.\" Brett Lymn (blymn@netbsd.org, brett_lymn@yahoo.com.au) 5*23b2be97Sblymn.\" 6*23b2be97Sblymn.\" This code is donated to the NetBSD Foundation by the Author. 7*23b2be97Sblymn.\" 8*23b2be97Sblymn.\" Redistribution and use in source and binary forms, with or without 9*23b2be97Sblymn.\" modification, are permitted provided that the following conditions 10*23b2be97Sblymn.\" are met: 11*23b2be97Sblymn.\" 1. Redistributions of source code must retain the above copyright 12*23b2be97Sblymn.\" notice, this list of conditions and the following disclaimer. 13*23b2be97Sblymn.\" 2. Redistributions in binary form must reproduce the above copyright 14*23b2be97Sblymn.\" notice, this list of conditions and the following disclaimer in the 15*23b2be97Sblymn.\" documentation and/or other materials provided with the distribution. 16*23b2be97Sblymn.\" 3. The name of the Author may not be used to endorse or promote 17*23b2be97Sblymn.\" products derived from this software without specific prior written 18*23b2be97Sblymn.\" permission. 19*23b2be97Sblymn.\" 20*23b2be97Sblymn.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 21*23b2be97Sblymn.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22*23b2be97Sblymn.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23*23b2be97Sblymn.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 24*23b2be97Sblymn.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25*23b2be97Sblymn.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26*23b2be97Sblymn.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27*23b2be97Sblymn.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28*23b2be97Sblymn.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29*23b2be97Sblymn.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30*23b2be97Sblymn.\" SUCH DAMAGE. 31*23b2be97Sblymn.\" 32*23b2be97Sblymn.\" 33*23b2be97Sblymn.Dd August 12, 2002 34*23b2be97Sblymn.Dt CURSES_TTY 3 35*23b2be97Sblymn.Os 36*23b2be97Sblymn.Sh NAME 37*23b2be97Sblymn.NM curses_tty , 38*23b2be97Sblymn.Nm beep , 39*23b2be97Sblymn.Nm flash , 40*23b2be97Sblymn.Nm curs_set , 41*23b2be97Sblymn.Nm def_prog_mode , 42*23b2be97Sblymn.Nm reset_prog_mode , 43*23b2be97Sblymn.Nm def_shell_mode , 44*23b2be97Sblymn.Nm reset_shell_mode , 45*23b2be97Sblymn.Nm echo , 46*23b2be97Sblymn.Nm noecho , 47*23b2be97Sblymn.Nm delay_output , 48*23b2be97Sblymn.Nm erasechar , 49*23b2be97Sblymn.Nm flushinp , 50*23b2be97Sblymn.Nm gettmode , 51*23b2be97Sblymn.Nm has_ic , 52*23b2be97Sblymn.Nm has_il , 53*23b2be97Sblymn.Nm idcok , 54*23b2be97Sblymn.Nm idlok , 55*23b2be97Sblymn.Nm intrflush , 56*23b2be97Sblymn.Nm killchar , 57*23b2be97Sblymn.Nm meta , 58*23b2be97Sblymn.Nm napms , 59*23b2be97Sblymn.Nm nl , 60*23b2be97Sblymn.Nm nonl , 61*23b2be97Sblymn.Nm cbreak , 62*23b2be97Sblymn.Nm nocbreak , 63*23b2be97Sblymn.Nm raw , 64*23b2be97Sblymn.Nm noraw , 65*23b2be97Sblymn.Nm savetty , 66*23b2be97Sblymn.Nm resetty , 67*23b2be97Sblymn.Nd curses terminal manipulation routines 68*23b2be97Sblymn.Sh LIBRARY 69*23b2be97Sblymn.Lb libcurses 70*23b2be97Sblymn.Sh SYNOPSIS 71*23b2be97Sblymn.Fd #include \*[Lt]curses.h\*[Gt] 72*23b2be97Sblymn.Ft int 73*23b2be97Sblymn.Fn beep "void" 74*23b2be97Sblymn.Ft int 75*23b2be97Sblymn.Fn flash "void" 76*23b2be97Sblymn.Ft int 77*23b2be97Sblymn.Fn curs_set "int visibility" 78*23b2be97Sblymn.Ft int 79*23b2be97Sblymn.Fn def_prog_mode "void" 80*23b2be97Sblymn.Ft int 81*23b2be97Sblymn.Fn reset_prog_mode "void" 82*23b2be97Sblymn.Ft int 83*23b2be97Sblymn.Fn def_shell_mode "void" 84*23b2be97Sblymn.Ft int 85*23b2be97Sblymn.Fn reset_shell_mode "void" 86*23b2be97Sblymn.Ft int 87*23b2be97Sblymn.Fn echo "void" 88*23b2be97Sblymn.Ft int 89*23b2be97Sblymn.Fn noecho "void" 90*23b2be97Sblymn.Ft int 91*23b2be97Sblymn.Fn delay_output "int ms" 92*23b2be97Sblymn.Ft char 93*23b2be97Sblymn.Fn erasechar "void" 94*23b2be97Sblymn.Ft int 95*23b2be97Sblymn.Fn flushinp "void" 96*23b2be97Sblymn.Ft int 97*23b2be97Sblymn.Fn gettmode "void" 98*23b2be97Sblymn.Ft int 99*23b2be97Sblymn.Fn has_ic "void" 100*23b2be97Sblymn.Ft int 101*23b2be97Sblymn.Fn has_il "void" 102*23b2be97Sblymn.Ft int 103*23b2be97Sblymn.Fn idcok "WINDOW *win" "boolf flag" 104*23b2be97Sblymn.Ft int 105*23b2be97Sblymn.Fn idlok "WINDOW *win" "boolf flag" 106*23b2be97Sblymn.Ft int 107*23b2be97Sblymn.Fn intrflush "WINDOW *win" "boolf flag" 108*23b2be97Sblymn.Ft char 109*23b2be97Sblymn.Fn killchar "void" 110*23b2be97Sblymn.Ft int 111*23b2be97Sblymn.Fn meta "WINDOW *win" "boolf flag" 112*23b2be97Sblymn.Ft int 113*23b2be97Sblymn.Fn napms "int ms" 114*23b2be97Sblymn.Ft int 115*23b2be97Sblymn.Fn nl "void" 116*23b2be97Sblymn.Ft int 117*23b2be97Sblymn.Fn nonl "void" 118*23b2be97Sblymn.Ft int 119*23b2be97Sblymn.Fn cbreak "void" 120*23b2be97Sblymn.Ft int 121*23b2be97Sblymn.Fn nocbreak "void" 122*23b2be97Sblymn.Ft int 123*23b2be97Sblymn.Fn raw "void" 124*23b2be97Sblymn.Ft int 125*23b2be97Sblymn.Fn noraw "void" 126*23b2be97Sblymn.Ft int 127*23b2be97Sblymn.Fn savetty "void" 128*23b2be97Sblymn.Ft int 129*23b2be97Sblymn.Fn resetty "void" 130*23b2be97Sblymn.Sh DESCRIPTION 131*23b2be97SblymnThese functions manipulate curses terminal settings. 132*23b2be97Sblymn.Pp 133*23b2be97SblymnThe 134*23b2be97Sblymn.Fn beep 135*23b2be97Sblymnfunction rings the terminal bell, if this is possible. 136*23b2be97SblymnFailing that, the terminal screen will be flashed. 137*23b2be97SblymnIf neither of these are possible, then no action will be taken. 138*23b2be97Sblymn.Fn flash 139*23b2be97Sblymnwill flash the terminal screen if possible. 140*23b2be97SblymnFailing that, the terminal bell will be rung. 141*23b2be97SblymnIf neither of these are possible then no action will be taken. 142*23b2be97Sblymn.Pp 143*23b2be97SblymnThe cursor 144*23b2be97Sblymnvisibility can be set by calling 145*23b2be97Sblymn.Fn curs_set . 146*23b2be97SblymnThe following visibility settings are valid for 147*23b2be97Sblymn.Fn curs_set : 148*23b2be97Sblymn.Pp 149*23b2be97Sblymn.Bl -tag -width visibility -compact -offset indent 150*23b2be97Sblymn.It Visibility 151*23b2be97SblymnEffect 152*23b2be97Sblymn.It 0 153*23b2be97Sblymncursor is invisible. 154*23b2be97Sblymn.It 1 155*23b2be97Sblymncursor is normal visibility 156*23b2be97Sblymn.It 2 157*23b2be97Sblymncursor is high visibility 158*23b2be97Sblymn.El 159*23b2be97Sblymn.Pp 160*23b2be97SblymnA successful call to 161*23b2be97Sblymn.Fn curs_set 162*23b2be97Sblymnwill return the previous visibility setting for the cursor. 163*23b2be97Sblymn.Pp 164*23b2be97SblymnThe 165*23b2be97Sblymn.Fn delay_output 166*23b2be97Sblymnfunction pauses the output to the terminal by sending the appropriate 167*23b2be97Sblymnnumber of terminal pad characters such that the transmission time of 168*23b2be97Sblymnthe pad characters will take 169*23b2be97Sblymn.Fa ms 170*23b2be97Sblymnmilliseconds. 171*23b2be97Sblymn.Pp 172*23b2be97SblymnCalling 173*23b2be97Sblymn.Fn def_prog_mode 174*23b2be97Sblymnwill cause the current terminal curses setting to be saved. 175*23b2be97SblymnA subequent call to 176*23b2be97Sblymn.Fn reset_prog_mode , 177*23b2be97Sblymnwill restore the saved settings. 178*23b2be97SblymnThis is useful when calls to external programs are made that may 179*23b2be97Sblymnreset the terminal characteristics. 180*23b2be97Sblymn.Pp 181*23b2be97SblymnThe 182*23b2be97Sblymn.Fn def_shell_mode 183*23b2be97Sblymnfunction saves the current terminal line settings. 184*23b2be97SblymnThese settings are the ones that will be restored when the curses 185*23b2be97Sblymnapplication exits. 186*23b2be97SblymnConversely, 187*23b2be97Sblymn.Fn reset_shell_mode 188*23b2be97Sblymnwill save the current terminal curses settings for later restoration and 189*23b2be97Sblymnrestores the previously saved terminal line settings. 190*23b2be97Sblymn.Pp 191*23b2be97SblymnThe 192*23b2be97Sblymn.Fn echo 193*23b2be97Sblymnfunction turns on curses echo mode, characters entered will be echoed 194*23b2be97Sblymnto the terminal by curses. 195*23b2be97SblymnThe 196*23b2be97Sblymn.Fn noecho 197*23b2be97Sblymnfunction disables this feature. 198*23b2be97Sblymn.Pp 199*23b2be97SblymnThe current erase character for the terminal can be determined by 200*23b2be97Sblymncalling the 201*23b2be97Sblymn.Fn erasechar 202*23b2be97Sblymnfunction. 203*23b2be97Sblymn.Pp 204*23b2be97SblymnThe 205*23b2be97Sblymn.Fn flushinp 206*23b2be97Sblymnfunction discards any pending input for the current screen. 207*23b2be97Sblymn.Pp 208*23b2be97SblymnThe modes 209*23b2be97Sblymnfor the current terminal can be reset by calling 210*23b2be97Sblymn.Fn gettmode , 211*23b2be97Sblymnthis will perform the initialisation on the terminal that is normally 212*23b2be97Sblymndone by curses at start up. 213*23b2be97Sblymn.Pp 214*23b2be97SblymnThe 215*23b2be97Sblymn.Fn has_ic 216*23b2be97Sblymnfunction returns either 217*23b2be97Sblymn.Dv TRUE 218*23b2be97Sblymnor 219*23b2be97Sblymn.Dv FALSE 220*23b2be97Sblymndepending on whether or not the terminal has a insert character 221*23b2be97Sblymncapability or not. 222*23b2be97SblymnSimilarly the 223*23b2be97Sblymn.Fn has_il 224*23b2be97Sblymnfunction does the same test but for a insert line capability. 225*23b2be97Sblymn.Pp 226*23b2be97SblymnThe use of the insert character capability in curses operations can be 227*23b2be97Sblymnenabled or disabled by calling 228*23b2be97Sblymn.Fn idcok 229*23b2be97Sblymnon the desired window. 230*23b2be97SblymnSimilarly, the use of the insert line capability can be controlled using the 231*23b2be97Sblymn.Fn idlok 232*23b2be97Sblymnfunction. 233*23b2be97Sblymn.Pp 234*23b2be97SblymnThe 235*23b2be97Sblymn.Fn intrflush 236*23b2be97Sblymnfunction controls whether or not a flush of the input buffer is 237*23b2be97Sblymnperformed when an interrupt key (kill, suspend or quit) is pressed. 238*23b2be97SblymnThe 239*23b2be97Sblymn.Fn win 240*23b2be97Sblymnparameter is ignored. 241*23b2be97Sblymn.Pp 242*23b2be97SblymnThe character that performs the line kill function can be determined 243*23b2be97Sblymnby calling the 244*23b2be97Sblymn.Fn killchar 245*23b2be97Sblymnfunction. 246*23b2be97Sblymn.Pp 247*23b2be97SblymnThe 248*23b2be97Sblymn.Fn meta 249*23b2be97Sblymnfunction turns on and off the generation of 8 bit characters by the 250*23b2be97Sblymnterminal, if 251*23b2be97Sblymn.Fa flag 252*23b2be97Sblymnis 253*23b2be97Sblymn.Dv FALSE 254*23b2be97Sblymnthen only 7 bit characters will be returned, if 255*23b2be97Sblymn.Fa flag 256*23b2be97Sblymnis 257*23b2be97Sblymn.Dv TRUE 258*23b2be97Sblymnthen 8 bit characters will be returned by the terminal. 259*23b2be97Sblymn.Pp 260*23b2be97SblymnThe 261*23b2be97Sblymn.Fn napms 262*23b2be97Sblymncauses the application to sleep for the number of milliseconds 263*23b2be97Sblymnspecified by 264*23b2be97Sblymn.Fa ms . 265*23b2be97Sblymn.Pp 266*23b2be97SblymnCalling 267*23b2be97Sblymn.Fn nl 268*23b2be97Sblymnwill cause curses to map all carriage returns to newlines on input, 269*23b2be97Sblymnthis functionality is enabled by default. 270*23b2be97SblymnThe 271*23b2be97Sblymn.Fn nonl 272*23b2be97Sblymnfunction disables this behaviour. 273*23b2be97Sblymn.Pp 274*23b2be97SblymnThe 275*23b2be97Sblymn.Fn cbreak 276*23b2be97Sblymnfunction will put the terminal into cbreak mode, which means that 277*23b2be97Sblymncharacters will be returned one at a time instead of waiting for a 278*23b2be97Sblymnnewline character, line discipline processing will be performed. 279*23b2be97SblymnThe 280*23b2be97Sblymn.Fn nocbreak 281*23b2be97Sblymnfunction disables this mode. 282*23b2be97Sblymn.Pp 283*23b2be97SblymnThe 284*23b2be97Sblymn.Fn noraw 285*23b2be97Sblymnfunction sets the input mode for the current terminal into Cooked mode, 286*23b2be97Sblymnthat is input character translation and signal character processing is 287*23b2be97Sblymnperformed. 288*23b2be97SblymnThe 289*23b2be97Sblymn.Fn raw 290*23b2be97Sblymnfunction puts the terminal into Raw mode, no input character 291*23b2be97Sblymntranslation is done nor is signal character processing. 292*23b2be97Sblymn.Pp 293*23b2be97SblymnThe terminal 294*23b2be97Sblymntty flags can be saved by calling 295*23b2be97Sblymn.Fn savetty 296*23b2be97Sblymnand may be restored by calling 297*23b2be97Sblymn.Fn resetty , 298*23b2be97Sblymnthe use of these functions is discouraged as they may cause the 299*23b2be97Sblymnterminal to be put into a state that is incompatiable with curses 300*23b2be97Sblymnoperation. 301*23b2be97Sblymn.Sh RETURN VALUES 302*23b2be97SblymnFunctions returning pointers will return 303*23b2be97Sblymn.Dv NULL 304*23b2be97Sblymnif an error is detected. 305*23b2be97SblymnThe functions that return an int will return one of the following 306*23b2be97Sblymnvalues: 307*23b2be97Sblymn.Pp 308*23b2be97Sblymn.Bl -tag -width ERR -compact 309*23b2be97Sblymn.It Er OK 310*23b2be97SblymnThe function completed successfully. 311*23b2be97Sblymn.It Er ERR 312*23b2be97SblymnAn error occurred in the function. 313*23b2be97Sblymn.El 314*23b2be97Sblymn.Sh SEE ALSO 315*23b2be97Sblymn.Xr getch 3 , 316*23b2be97Sblymn.Xr termios 4 317*23b2be97Sblymn.Sh NOTES 318*23b2be97SblymnThe 319*23b2be97Sblymn.Fn idcok 320*23b2be97Sblymnand 321*23b2be97Sblymn.Fn idlok 322*23b2be97Sblymncurrently have no effect on the curses code at all, currently curses 323*23b2be97Sblymnwill always use the terminal insert character and insert line 324*23b2be97Sblymncapabilities if available. 325*23b2be97Sblymn.Sh STANDARDS 326*23b2be97SblymnThe 327*23b2be97Sblymn.Nx 328*23b2be97SblymnCurses library complies with the X/Open Curses specification, part of the 329*23b2be97SblymnSingle Unix Specification. 330*23b2be97Sblymn.Sh HISTORY 331*23b2be97SblymnThe Curses package appeared in 332*23b2be97Sblymn.Bx 4.0 . 333