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.63 2024/05/25 21:13:56 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-05-25 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-05-25 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        The <STRONG>getsyx</STRONG> routine returns  the  current  coordinates  of  the  <EM>virtual</EM>
 105        <EM>screen</EM>  cursor in <EM>y</EM> and <EM>x</EM>.  If <STRONG>leaveok</STRONG> is currently <STRONG>TRUE</STRONG>, then <STRONG>-1</STRONG>,<STRONG>-1</STRONG> is
 106        returned.  If lines have been removed from the top of the screen, using
 107        <STRONG>ripoffline</STRONG>,  <EM>y</EM>  and <EM>x</EM> include these lines; therefore, <EM>y</EM> and <EM>x</EM> should be
 108        used only as arguments for <STRONG>setsyx</STRONG>.
 109
 110        Few applications will use this feature, most use <STRONG>getyx</STRONG> instead.
 111
 112
 113 </PRE><H3><a name="h3-setsyx">setsyx</a></H3><PRE>
 114        The <STRONG>setsyx</STRONG> routine sets the <EM>virtual</EM> <EM>screen</EM> cursor to <EM>y</EM>, <EM>x</EM>.  If <EM>y</EM> and  <EM>x</EM>
 115        are  both  <STRONG>-1</STRONG>, then <STRONG>leaveok</STRONG> is set.  The two routines <STRONG>getsyx</STRONG> and <STRONG>setsyx</STRONG>
 116        are designed to be used by a library routine, which manipulates  <STRONG>curses</STRONG>
 117        windows  but  does  not  want  to  change  the  current position of the
 118        program's cursor.   The  library  routine  would  call  <STRONG>getsyx</STRONG>  at  the
 119        beginning, do its manipulation of its own windows, do a <STRONG>wnoutrefresh</STRONG> on
 120        its windows, call <STRONG>setsyx</STRONG>, and then call <STRONG>doupdate</STRONG>.
 121
 122        Few applications will use this feature, most use <STRONG>wmove</STRONG> instead.
 123
 124
 125 </PRE><H3><a name="h3-curs_set">curs_set</a></H3><PRE>
 126        The <STRONG>curs_set</STRONG> routine sets the cursor state  to  invisible,  normal,  or
 127        very  visible  for <STRONG>visibility</STRONG> equal to <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG> respectively.  If the
 128        terminal supports the <EM>visibility</EM> requested, the previous  <EM>cursor</EM>  state
 129        is returned; otherwise, <STRONG>ERR</STRONG> is returned.
 130
 131
 132 </PRE><H3><a name="h3-mvcur">mvcur</a></H3><PRE>
 133        <STRONG>mvcur</STRONG>  provides  low-level cursor motion.  It takes effect immediately,
 134        rather than at the next refresh.  Unlike  the  other  low-level  output
 135        functions,  which  either  write  to  the standard output stream or are
 136        passed a  function  pointer  to  perform  output,  <STRONG>mvcur</STRONG>  uses  a  file
 137        descriptor derived from the output stream parameter of <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>.
 138
 139        One  application  of  <STRONG>mvcur</STRONG>  accompanies  the  temporary use of another
 140        program to write to the  terminal  screen.   For  example,  first  call
 141        <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>  to ensure that the screen and the library's model of it is
 142        up to date; then call <STRONG>reset_shell_mode</STRONG>; write to the  screen  with  the
 143        external  application;  call <STRONG>reset_prog_mode</STRONG>; and finally call <STRONG>mvcur</STRONG> to
 144        set the cursor's location to where  <EM>curses</EM>  thinks  it  is,  since  the
 145        library has no knowledge of how the external application moved it.
 146
 147
 148 </PRE><H3><a name="h3-napms">napms</a></H3><PRE>
 149        <STRONG>napms</STRONG>  sleeps  for  <EM>ms</EM>  milliseconds.   If  <EM>ms</EM>  exceeds  30,000 (thirty
 150        seconds), it is capped at that value.
 151
 152
 153 </PRE><H3><a name="h3-ripoffline">ripoffline</a></H3><PRE>
 154        <STRONG>ripoffline</STRONG> provides access to the same facility that <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG>  uses
 155        to  reduce  the  size  of the screen.  <STRONG>ripoffline</STRONG> must be called before
 156        <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> is called, to prepare these initial actions:
 157
 158        <STRONG>o</STRONG>   If <EM>line</EM> is positive, a line is removed from the top of <STRONG>stdscr</STRONG>.
 159
 160        <STRONG>o</STRONG>   if <EM>line</EM> is negative, a line is removed from the bottom.
 161
 162        When the resulting initialization is done inside <STRONG>initscr</STRONG>,  the  routine
 163        <STRONG>init</STRONG> (supplied by the user) is called with two arguments:
 164
 165        <STRONG>o</STRONG>   a window pointer to the one-line window that has been allocated and
 166
 167        <STRONG>o</STRONG>   an integer with the number of columns in the window.
 168
 169        Inside  this  initialization  routine,  the integer variables <STRONG>LINES</STRONG> and
 170        <STRONG>COLS</STRONG> (defined in <STRONG>&lt;curses.h&gt;</STRONG>) are not  guaranteed  to  be  accurate  and
 171        <STRONG>wrefresh</STRONG>  or  <STRONG>doupdate</STRONG>  must  not  be  called.  It is allowable to call
 172        <STRONG>wnoutrefresh</STRONG> during the initialization routine.
 173
 174        <STRONG>ripoffline</STRONG> can be called up to five times  before  calling  <STRONG>initscr</STRONG>  or
 175        <STRONG>newterm</STRONG>.
 176
 177
 178 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 179        Except for <STRONG>curs_set</STRONG>, these routines always return <STRONG>OK</STRONG>.
 180
 181        <STRONG>curs_set</STRONG>  returns  the  previous  cursor state, or <STRONG>ERR</STRONG> if the requested
 182        <EM>visibility</EM> is not supported.
 183
 184        X/Open defines no error conditions.  In this implementation
 185
 186        <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>, <STRONG>reset_shell_mode</STRONG>
 187             return <STRONG>ERR</STRONG> if the terminal was not initialized, or if the I/O call
 188             to obtain the terminal settings fails.
 189
 190        <STRONG>ripoffline</STRONG>
 191             returns  <STRONG>ERR</STRONG> if the maximum number of ripped-off lines exceeds the
 192             maximum (5).
 193
 194
 195 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 196        Note that <STRONG>getsyx</STRONG> is a macro, so <STRONG>&amp;</STRONG> is not necessary before the variables
 197        <EM>y</EM> and <EM>x</EM>.
 198
 199        Older  SVr4  man  pages  warn  that  the  return  value of <STRONG>curs_set</STRONG> "is
 200        currently incorrect".  This implementation gets it right, but it may be
 201        unwise to count on the correctness of the return value anywhere else.
 202
 203        Both <EM>ncurses</EM> and SVr4 will call <STRONG>curs_set</STRONG> in <STRONG>endwin</STRONG> if <STRONG>curs_set</STRONG> has been
 204        called to make the cursor other than normal, i.e., either invisible  or
 205        very  visible.   There  is  no way for <EM>ncurses</EM> to determine the initial
 206        cursor state to restore that.
 207
 208
 209 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 210        In <EM>ncurses</EM>, <STRONG>mvcur</STRONG> accepts <STRONG>-1</STRONG> for either or both old coordinates.   This
 211        value  tells <EM>ncurses</EM> that the old location is unknown, and that it must
 212        use only absolute motion, as with the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>)  capability,
 213        rather  than  the  least  costly  combination  of absolute and relative
 214        motion.
 215
 216
 217 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 218        The <EM>virtual</EM> <EM>screen</EM> functions <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG>  are  not  described  in
 219        X/Open Curses, Issue 4.  All other functions are as described in X/Open
 220        Curses.
 221
 222        The SVr4 documentation describes <STRONG>setsyx</STRONG> and  <STRONG>getsyx</STRONG>  as  having  return
 223        type  int.   This  is misleading, as they are macros with no documented
 224        semantics for the return value.
 225
 226        X/Open Curses notes:
 227
 228               "After use of <EM>mvcur</EM>(), the model Curses maintains of  the  state
 229               of  the  terminal  might  not  match  the  actual  state  of the
 230               terminal.  An application should touch and  refresh  the  window
 231               before resuming conventional use of Curses."
 232
 233        Both  <EM>ncurses</EM>  and  SVr4  <EM>curses</EM>  implement <STRONG>mvcur</STRONG> using the <EM>SCREEN</EM> data
 234        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
 235        that  the old location must be given for <STRONG>mvcur</STRONG> to accommodate terminals
 236        that lack absolute cursor positioning.
 237
 238        If interrupted, <EM>ncurses</EM> restarts <STRONG>napms</STRONG>.  That, and the limitation to 30
 239        seconds, are different from other implementations.
 240
 241
 242 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 243        <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>,
 244        <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>
 245
 246
 247
 248 ncurses 6.5                       2024-05-25                   <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
 249 </PRE>
 250 <div class="nav">
 251 <ul>
 252 <li><a href="#h2-NAME">NAME</a></li>
 253 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 254 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 255 <ul>
 256 <li><a href="#h3-def_prog_mode_def_shell_mode">def_prog_mode, def_shell_mode</a></li>
 257 <li><a href="#h3-reset_prog_mode_reset_shell_mode">reset_prog_mode, reset_shell_mode</a></li>
 258 <li><a href="#h3-resetty_savetty">resetty, savetty</a></li>
 259 <li><a href="#h3-getsyx">getsyx</a></li>
 260 <li><a href="#h3-setsyx">setsyx</a></li>
 261 <li><a href="#h3-curs_set">curs_set</a></li>
 262 <li><a href="#h3-mvcur">mvcur</a></li>
 263 <li><a href="#h3-napms">napms</a></li>
 264 <li><a href="#h3-ripoffline">ripoffline</a></li>
 265 </ul>
 266 </li>
 267 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 268 <li><a href="#h2-NOTES">NOTES</a></li>
 269 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 270 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 271 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 272 </ul>
 273 </div>
 274 </BODY>
 275 </HTML>