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.65 2024/06/08 21:00:58 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-08 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-08 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>  to
 145        set  the  cursor's  location  to  where  <EM>curses</EM> thinks it is, since the
 146        library has no knowledge of how the external application moved it.
 147
 148
 149 </PRE><H3><a name="h3-napms">napms</a></H3><PRE>
 150        <STRONG>napms</STRONG> sleeps  for  <EM>ms</EM>  milliseconds.   If  <EM>ms</EM>  exceeds  30,000  (thirty
 151        seconds), it is capped at that value.
 152
 153
 154 </PRE><H3><a name="h3-ripoffline">ripoffline</a></H3><PRE>
 155        <STRONG>ripoffline</STRONG>  provides access to the same facility that <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG> uses
 156        to reduce the size of the screen.  <STRONG>ripoffline</STRONG>  must  be  called  before
 157        <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> is called, to prepare these initial actions:
 158
 159        <STRONG>o</STRONG>   If <EM>line</EM> is positive, a line is removed from the top of <STRONG>stdscr</STRONG>.
 160
 161        <STRONG>o</STRONG>   if <EM>line</EM> is negative, a line is removed from the bottom.
 162
 163        When  the  resulting initialization is done inside <STRONG>initscr</STRONG>, the routine
 164        <STRONG>init</STRONG> (supplied by the user) is called with two arguments:
 165
 166        <STRONG>o</STRONG>   a window pointer to the one-line window that has been allocated and
 167
 168        <STRONG>o</STRONG>   an integer with the number of columns in the window.
 169
 170        Inside this initialization routine, the  integer  variables  <STRONG>LINES</STRONG>  and
 171        <STRONG>COLS</STRONG>  (defined  in  <STRONG>&lt;curses.h&gt;</STRONG>)  are  not guaranteed to be accurate and
 172        <STRONG>wrefresh</STRONG> or <STRONG>doupdate</STRONG> must not be  called.   It  is  allowable  to  call
 173        <STRONG>wnoutrefresh</STRONG> during the initialization routine.
 174
 175        <STRONG>ripoffline</STRONG>  can  be  called  up to five times before calling <STRONG>initscr</STRONG> or
 176        <STRONG>newterm</STRONG>.
 177
 178
 179 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 180        Except for <STRONG>curs_set</STRONG>, these routines always return <STRONG>OK</STRONG>.
 181
 182        <STRONG>curs_set</STRONG> returns the previous cursor state, or  <STRONG>ERR</STRONG>  if  the  requested
 183        <EM>visibility</EM> is not supported.
 184
 185        X/Open defines no error conditions.  In this implementation
 186
 187        <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>, <STRONG>reset_shell_mode</STRONG>
 188             return <STRONG>ERR</STRONG> if the terminal was not initialized, or if the I/O call
 189             to obtain the terminal settings fails.
 190
 191        <STRONG>ripoffline</STRONG>
 192             returns <STRONG>ERR</STRONG> if the maximum number of ripped-off lines exceeds  the
 193             maximum (5).
 194
 195
 196 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 197        Note that <STRONG>getsyx</STRONG> is a macro, so <STRONG>&amp;</STRONG> is not necessary before the variables
 198        <EM>y</EM> and <EM>x</EM>.
 199
 200        Older SVr4 man pages  warn  that  the  return  value  of  <STRONG>curs_set</STRONG>  "is
 201        currently incorrect".  This implementation gets it right, but it may be
 202        unwise to count on the correctness of the return value anywhere else.
 203
 204        Both <EM>ncurses</EM> and SVr4 will call <STRONG>curs_set</STRONG> in <STRONG>endwin</STRONG> if <STRONG>curs_set</STRONG> has been
 205        called  to make the cursor other than normal, i.e., either invisible or
 206        very visible.  There is no way for <EM>ncurses</EM>  to  determine  the  initial
 207        cursor state to restore that.
 208
 209
 210 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 211        In  <EM>ncurses</EM>, <STRONG>mvcur</STRONG> accepts <STRONG>-1</STRONG> for either or both old coordinates.  This
 212        value tells <EM>ncurses</EM> that the old location is unknown, and that it  must
 213        use  only absolute motion, as with the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability,
 214        rather than the least  costly  combination  of  absolute  and  relative
 215        motion.
 216
 217
 218 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 219        Applications employing <EM>ncurses</EM> extensions should condition their use on
 220        the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
 221
 222        The <EM>virtual</EM> <EM>screen</EM> functions <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG>  are  not  described  in
 223        X/Open Curses, Issue 4.  All other functions are as described in X/Open
 224        Curses.
 225
 226        The SVr4 documentation describes <STRONG>setsyx</STRONG> and  <STRONG>getsyx</STRONG>  as  having  return
 227        type  int.   This  is misleading, as they are macros with no documented
 228        semantics for the return value.
 229
 230        X/Open Curses notes:
 231
 232               "After use of <EM>mvcur</EM>(), the model Curses maintains of  the  state
 233               of  the  terminal  might  not  match  the  actual  state  of the
 234               terminal.  An application should touch and  refresh  the  window
 235               before resuming conventional use of Curses."
 236
 237        Both  <EM>ncurses</EM>  and  SVr4  <EM>curses</EM>  implement <STRONG>mvcur</STRONG> using the <EM>SCREEN</EM> data
 238        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
 239        that  the old location must be given for <STRONG>mvcur</STRONG> to accommodate terminals
 240        that lack absolute cursor positioning.
 241
 242        If interrupted, <EM>ncurses</EM> restarts <STRONG>napms</STRONG>.  That, and the limitation to 30
 243        seconds, are different from other implementations.
 244
 245
 246 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 247        <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>,
 248        <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>
 249
 250
 251
 252 ncurses 6.5                       2024-06-08                   <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
 253 </PRE>
 254 <div class="nav">
 255 <ul>
 256 <li><a href="#h2-NAME">NAME</a></li>
 257 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 258 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 259 <ul>
 260 <li><a href="#h3-def_prog_mode_def_shell_mode">def_prog_mode, def_shell_mode</a></li>
 261 <li><a href="#h3-reset_prog_mode_reset_shell_mode">reset_prog_mode, reset_shell_mode</a></li>
 262 <li><a href="#h3-resetty_savetty">resetty, savetty</a></li>
 263 <li><a href="#h3-getsyx">getsyx</a></li>
 264 <li><a href="#h3-setsyx">setsyx</a></li>
 265 <li><a href="#h3-curs_set">curs_set</a></li>
 266 <li><a href="#h3-mvcur">mvcur</a></li>
 267 <li><a href="#h3-napms">napms</a></li>
 268 <li><a href="#h3-ripoffline">ripoffline</a></li>
 269 </ul>
 270 </li>
 271 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 272 <li><a href="#h2-NOTES">NOTES</a></li>
 273 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 274 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 275 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 276 </ul>
 277 </div>
 278 </BODY>
 279 </HTML>