doc/html/man/curs_kernel.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2023,2024 Thomas E. Dickey                                *
   4   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: curs_kernel.3x,v 1.67 2024/06/22 21:24:26 tom Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>curs_kernel 3x 2024-06-22 ncurses 6.5 Library calls</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_kernel 3x 2024-06-22 ncurses 6.5 Library calls</H1>
  43 <PRE>
  44 <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>                  Library calls                 <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <STRONG>def_prog_mode</STRONG>,   <STRONG>def_shell_mode</STRONG>,   <STRONG>reset_prog_mode</STRONG>,   <STRONG>reset_shell_mode</STRONG>,
  51        <STRONG>resetty</STRONG>, <STRONG>savetty</STRONG>, <STRONG>getsyx</STRONG>, <STRONG>setsyx</STRONG>, <STRONG>curs_set</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>napms</STRONG>, <STRONG>ripoffline</STRONG>  -
  52        low-level <EM>curses</EM> routines
  53
  54
  55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  57
  58        <STRONG>int</STRONG> <STRONG>def_prog_mode(void);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>def_shell_mode(void);</STRONG>
  60
  61        <STRONG>int</STRONG> <STRONG>reset_prog_mode(void);</STRONG>
  62        <STRONG>int</STRONG> <STRONG>reset_shell_mode(void);</STRONG>
  63
  64        <STRONG>int</STRONG> <STRONG>resetty(void);</STRONG>
  65        <STRONG>int</STRONG> <STRONG>savetty(void);</STRONG>
  66
  67        <STRONG>void</STRONG> <STRONG>getsyx(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
  68        <STRONG>void</STRONG> <STRONG>setsyx(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
  69
  70        <STRONG>int</STRONG> <STRONG>curs_set(int</STRONG> <EM>visibility</EM><STRONG>);</STRONG>
  71        <STRONG>int</STRONG> <STRONG>mvcur(int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newcol</EM><STRONG>);</STRONG>
  72        <STRONG>int</STRONG> <STRONG>napms(int</STRONG> <EM>ms</EM><STRONG>);</STRONG>
  73        <STRONG>int</STRONG> <STRONG>ripoffline(int</STRONG> <EM>line</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>init</EM><STRONG>)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int));</STRONG>
  74
  75
  76 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  77        The   following  routines  give  low-level  access  to  various  <STRONG>curses</STRONG>
  78        capabilities.   These  routines  typically  are  used  inside   library
  79        routines.
  80
  81
  82 </PRE><H3><a name="h3-def_prog_mode_def_shell_mode">def_prog_mode, def_shell_mode</a></H3><PRE>
  83        The <STRONG>def_prog_mode</STRONG> and <STRONG>def_shell_mode</STRONG> routines save the current terminal
  84        modes as the "program" (in <STRONG>curses</STRONG>) or "shell" (not in <STRONG>curses</STRONG>) state for
  85        use by the <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines.  This is done
  86        automatically by <STRONG>initscr</STRONG>.  There is one such save area for each  screen
  87        context allocated by <STRONG>newterm</STRONG>.
  88
  89
  90 </PRE><H3><a name="h3-reset_prog_mode_reset_shell_mode">reset_prog_mode, reset_shell_mode</a></H3><PRE>
  91        The  <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines restore the terminal
  92        to "program" (in <STRONG>curses</STRONG>) or "shell" (out of <STRONG>curses</STRONG>) state.   These  are
  93        done  automatically by <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> and, after an <STRONG>endwin</STRONG>, by <STRONG>doupdate</STRONG>, so
  94        they normally are not called.
  95
  96
  97 </PRE><H3><a name="h3-resetty_savetty">resetty, savetty</a></H3><PRE>
  98        The <STRONG>resetty</STRONG> and <STRONG>savetty</STRONG> routines save and  restore  the  state  of  the
  99        terminal  modes.   <STRONG>savetty</STRONG>  saves  the  current  state  in a buffer and
 100        <STRONG>resetty</STRONG> restores the state to what it was at the last call to <STRONG>savetty</STRONG>.
 101
 102
 103 </PRE><H3><a name="h3-getsyx">getsyx</a></H3><PRE>
 104        <STRONG>getsyx</STRONG> stores the coordinates of virtual screen (<STRONG>newscr</STRONG>)  cursor  in  <EM>y</EM>
 105        and <EM>x</EM>.  If <STRONG>newscr</STRONG>'s <STRONG><A HREF="leaveok.3x.html">leaveok(3x)</A></STRONG> output option is <STRONG>TRUE</STRONG>, <STRONG>getsyx</STRONG> stores <STRONG>-1</STRONG>
 106        in both <EM>y</EM> and <EM>x</EM>.  If lines have been removed from the top of the screen
 107        using  <STRONG>ripoffline</STRONG>, <EM>y</EM> includes these lines; therefore, <EM>y</EM> and <EM>x</EM> populated
 108        by <STRONG>getsyx</STRONG> should be used only as arguments for <STRONG>setsyx</STRONG>.
 109
 110        Few applications use this feature; most call <STRONG><A HREF="curs_getyx.3x.html">getyx(3x)</A></STRONG> instead.
 111
 112
 113 </PRE><H3><a name="h3-setsyx">setsyx</a></H3><PRE>
 114        <STRONG>setsyx</STRONG> sets the virtual screen (<STRONG>newscr</STRONG>)  cursor  location  to  (<EM>y</EM>,  <EM>x</EM>).
 115        <STRONG>setsyx(-1,</STRONG> <STRONG>-1)</STRONG> is equivalent to <STRONG>leaveok(newscr,</STRONG> <STRONG>TRUE)</STRONG>.
 116
 117        <STRONG>getsyx</STRONG>  and  <STRONG>setsyx</STRONG>  are  designed  to  be  used  by  a  function  that
 118        manipulates <EM>curses</EM> windows but  seeks  to  avoid  changing  the  cursor
 119        position.  Such a function would first call <STRONG>getsyx</STRONG>, modify its windows'
 120        content,  call  <STRONG><A HREF="curs_refresh.3x.html">wnoutrefresh(3x)</A></STRONG>  on  them,  call  <STRONG>setsyx</STRONG>,  then   call
 121        <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG>.
 122
 123        Few applications use this feature; most call <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> instead.
 124
 125
 126 </PRE><H3><a name="h3-curs_set">curs_set</a></H3><PRE>
 127        The  <STRONG>curs_set</STRONG>  routine  sets  the cursor state to invisible, normal, or
 128        very visible for <STRONG>visibility</STRONG> equal to <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG> respectively.   If  the
 129        terminal  supports  the <EM>visibility</EM> requested, the previous <EM>cursor</EM> state
 130        is returned; otherwise, <STRONG>ERR</STRONG> is returned.
 131
 132
 133 </PRE><H3><a name="h3-mvcur">mvcur</a></H3><PRE>
 134        <STRONG>mvcur</STRONG> provides low-level cursor motion.  It takes  effect  immediately,
 135        rather  than  at  the  next refresh.  Unlike the other low-level output
 136        functions, which either write to the  standard  output  stream  or  are
 137        passed  a  function  pointer  to  perform  output,  <STRONG>mvcur</STRONG>  uses  a file
 138        descriptor derived from the output stream parameter of <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>.
 139
 140        One application of <STRONG>mvcur</STRONG>  accompanies  the  temporary  use  of  another
 141        program  to  write  to  the  terminal  screen.  For example, first call
 142        <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> to ensure that the screen and the library's model of it  is
 143        up  to  date;  then call <STRONG>reset_shell_mode</STRONG>; write to the screen with the
 144        external application; call <STRONG>reset_prog_mode</STRONG>; and finally call <STRONG>mvcur(</STRONG>...<STRONG>,</STRONG>
 145        ...<STRONG>,</STRONG>  <STRONG>-1,</STRONG> <STRONG>-1)</STRONG> to move the terminal cursor to where <EM>curses</EM> thinks it is,
 146        since the library has no knowledge  of  how  the  external  application
 147        moved it.
 148
 149
 150 </PRE><H3><a name="h3-napms">napms</a></H3><PRE>
 151        <STRONG>napms</STRONG>  sleeps  for  <EM>ms</EM>  milliseconds.   If  <EM>ms</EM>  exceeds  30,000 (thirty
 152        seconds), it is capped at that value.
 153
 154
 155 </PRE><H3><a name="h3-ripoffline">ripoffline</a></H3><PRE>
 156        <STRONG>ripoffline</STRONG> provides access to the same facility that <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG>  uses
 157        to  reduce  the  size  of the screen.  <STRONG>ripoffline</STRONG> must be called before
 158        <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> is called, to prepare these initial actions:
 159
 160        <STRONG>o</STRONG>   If <EM>line</EM> is positive, a line is removed from the top of <STRONG>stdscr</STRONG>.
 161
 162        <STRONG>o</STRONG>   if <EM>line</EM> is negative, a line is removed from the bottom.
 163
 164        When the resulting initialization is done inside <STRONG>initscr</STRONG>,  the  routine
 165        <STRONG>init</STRONG> (supplied by the user) is called with two arguments:
 166
 167        <STRONG>o</STRONG>   a window pointer to the one-line window that has been allocated and
 168
 169        <STRONG>o</STRONG>   an integer with the number of columns in the window.
 170
 171        Inside  this  initialization  routine,  the integer variables <STRONG>LINES</STRONG> and
 172        <STRONG>COLS</STRONG> (defined in <STRONG>&lt;curses.h&gt;</STRONG>) are not  guaranteed  to  be  accurate  and
 173        <STRONG>wrefresh</STRONG>  or  <STRONG>doupdate</STRONG>  must  not  be  called.  It is allowable to call
 174        <STRONG>wnoutrefresh</STRONG> during the initialization routine.
 175
 176        <STRONG>ripoffline</STRONG> can be called up to five times  before  calling  <STRONG>initscr</STRONG>  or
 177        <STRONG>newterm</STRONG>.
 178
 179
 180 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 181        Except for <STRONG>curs_set</STRONG>, these routines always return <STRONG>OK</STRONG>.
 182
 183        <STRONG>curs_set</STRONG>  returns  the  previous  cursor state, or <STRONG>ERR</STRONG> if the requested
 184        <EM>visibility</EM> is not supported.
 185
 186        X/Open defines no error conditions.  In this implementation
 187
 188        <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>, <STRONG>reset_shell_mode</STRONG>
 189             return <STRONG>ERR</STRONG> if the terminal was not initialized, or if the I/O call
 190             to obtain the terminal settings fails.
 191
 192        <STRONG>ripoffline</STRONG>
 193             returns  <STRONG>ERR</STRONG> if the maximum number of ripped-off lines exceeds the
 194             maximum (5).
 195
 196
 197 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 198        Note that <STRONG>getsyx</STRONG> is a macro, so <STRONG>&amp;</STRONG> is not necessary before the variables
 199        <EM>y</EM> and <EM>x</EM>.
 200
 201        Older  SVr4  man  pages  warn  that  the  return  value of <STRONG>curs_set</STRONG> "is
 202        currently incorrect".  This implementation gets it right, but it may be
 203        unwise to count on the correctness of the return value anywhere else.
 204
 205        Both <EM>ncurses</EM> and SVr4 will call <STRONG>curs_set</STRONG> in <STRONG>endwin</STRONG> if <STRONG>curs_set</STRONG> has been
 206        called to make the cursor other than normal, i.e., either invisible  or
 207        very  visible.   There  is  no way for <EM>ncurses</EM> to determine the initial
 208        cursor state to restore that.
 209
 210
 211 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 212        In <EM>ncurses</EM>, <STRONG>mvcur</STRONG> accepts <STRONG>-1</STRONG> for either or both old coordinates.   This
 213        value  tells <EM>ncurses</EM> that the old location is unknown, and that it must
 214        use only absolute motion, as with the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>)  capability,
 215        rather  than  the  least  costly  combination  of absolute and relative
 216        motion.
 217
 218
 219 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 220        Applications employing <EM>ncurses</EM> extensions should condition their use on
 221        the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
 222
 223        The  <EM>virtual</EM>  <EM>screen</EM>  functions  <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> are not described in
 224        X/Open Curses, Issue 4.  All other functions are as described in X/Open
 225        Curses.
 226
 227        The  SVr4  documentation  describes  <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> as having return
 228        type int.  This is misleading, as they are macros  with  no  documented
 229        semantics for the return value.
 230
 231        X/Open Curses notes:
 232
 233               "After  use  of <EM>mvcur</EM>(), the model Curses maintains of the state
 234               of the  terminal  might  not  match  the  actual  state  of  the
 235               terminal.   An  application  should touch and refresh the window
 236               before resuming conventional use of Curses."
 237
 238        Both <EM>ncurses</EM> and SVr4 <EM>curses</EM> implement  <STRONG>mvcur</STRONG>  using  the  <EM>SCREEN</EM>  data
 239        allocated  in  either <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>.  X/Open Curses states
 240        that the old location must be given for <STRONG>mvcur</STRONG> to accommodate  terminals
 241        that lack absolute cursor positioning.
 242
 243        If interrupted, <EM>ncurses</EM> restarts <STRONG>napms</STRONG>.  That, and the limitation to 30
 244        seconds, are different from other implementations.
 245
 246
 247 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 248        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,   <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,   <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>,   <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>,
 249        <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>, <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 250
 251
 252
 253 ncurses 6.5                       2024-06-22                   <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
 254 </PRE>
 255 <div class="nav">
 256 <ul>
 257 <li><a href="#h2-NAME">NAME</a></li>
 258 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 259 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 260 <ul>
 261 <li><a href="#h3-def_prog_mode_def_shell_mode">def_prog_mode, def_shell_mode</a></li>
 262 <li><a href="#h3-reset_prog_mode_reset_shell_mode">reset_prog_mode, reset_shell_mode</a></li>
 263 <li><a href="#h3-resetty_savetty">resetty, savetty</a></li>
 264 <li><a href="#h3-getsyx">getsyx</a></li>
 265 <li><a href="#h3-setsyx">setsyx</a></li>
 266 <li><a href="#h3-curs_set">curs_set</a></li>
 267 <li><a href="#h3-mvcur">mvcur</a></li>
 268 <li><a href="#h3-napms">napms</a></li>
 269 <li><a href="#h3-ripoffline">ripoffline</a></li>
 270 </ul>
 271 </li>
 272 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 273 <li><a href="#h2-NOTES">NOTES</a></li>
 274 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 275 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 276 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 277 </ul>
 278 </div>
 279 </BODY>
 280 </HTML>