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

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2022,2023 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.49 2023/10/14 22:03:52 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 2023-10-14 ncurses 6.4 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 2023-10-14 ncurses 6.4 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>ripoffline</STRONG>, <STRONG>curs_set</STRONG>,  <STRONG>napms</STRONG>  -  low-
  52        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>ripoffline(int</STRONG> <EM>line</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>init</EM><STRONG>)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int));</STRONG>
  71        <STRONG>int</STRONG> <STRONG>curs_set(int</STRONG> <EM>visibility</EM><STRONG>);</STRONG>
  72        <STRONG>int</STRONG> <STRONG>napms(int</STRONG> <EM>ms</EM><STRONG>);</STRONG>
  73
  74
  75 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  76        The   following  routines  give  low-level  access  to  various  <STRONG>curses</STRONG>
  77        capabilities.   These  routines  typically  are  used  inside   library
  78        routines.
  79
  80
  81 </PRE><H3><a name="h3-def_prog_mode_-def_shell_mode">def_prog_mode, def_shell_mode</a></H3><PRE>
  82        The <STRONG>def_prog_mode</STRONG> and <STRONG>def_shell_mode</STRONG> routines save the current terminal
  83        modes as the "program" (in <STRONG>curses</STRONG>) or "shell" (not in <STRONG>curses</STRONG>) state for
  84        use by the <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines.  This is done
  85        automatically by <STRONG>initscr</STRONG>.  There is one such save area for each  screen
  86        context allocated by <STRONG>newterm</STRONG>.
  87
  88
  89 </PRE><H3><a name="h3-reset_prog_mode_-reset_shell_mode">reset_prog_mode, reset_shell_mode</a></H3><PRE>
  90        The  <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines restore the terminal
  91        to "program" (in <STRONG>curses</STRONG>) or "shell" (out of <STRONG>curses</STRONG>) state.   These  are
  92        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
  93        they normally are not called.
  94
  95
  96 </PRE><H3><a name="h3-resetty_-savetty">resetty, savetty</a></H3><PRE>
  97        The <STRONG>resetty</STRONG> and <STRONG>savetty</STRONG> routines save and  restore  the  state  of  the
  98        terminal  modes.   <STRONG>savetty</STRONG>  saves  the  current  state  in a buffer and
  99        <STRONG>resetty</STRONG> restores the state to what it was at the last call to <STRONG>savetty</STRONG>.
 100
 101
 102 </PRE><H3><a name="h3-getsyx">getsyx</a></H3><PRE>
 103        The <STRONG>getsyx</STRONG> routine returns  the  current  coordinates  of  the  <EM>virtual</EM>
 104        <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
 105        returned.  If lines have been removed from the top of the screen, using
 106        <STRONG>ripoffline</STRONG>,  <EM>y</EM>  and <EM>x</EM> include these lines; therefore, <EM>y</EM> and <EM>x</EM> should be
 107        used only as arguments for <STRONG>setsyx</STRONG>.
 108
 109        Few applications will use this feature, most use <STRONG>getyx</STRONG> instead.
 110
 111
 112 </PRE><H3><a name="h3-setsyx">setsyx</a></H3><PRE>
 113        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>
 114        are  both  <STRONG>-1</STRONG>, then <STRONG>leaveok</STRONG> is set.  The two routines <STRONG>getsyx</STRONG> and <STRONG>setsyx</STRONG>
 115        are designed to be used by a library routine, which manipulates  <STRONG>curses</STRONG>
 116        windows  but  does  not  want  to  change  the  current position of the
 117        program's cursor.   The  library  routine  would  call  <STRONG>getsyx</STRONG>  at  the
 118        beginning, do its manipulation of its own windows, do a <STRONG>wnoutrefresh</STRONG> on
 119        its windows, call <STRONG>setsyx</STRONG>, and then call <STRONG>doupdate</STRONG>.
 120
 121        Few applications will use this feature, most use <STRONG>wmove</STRONG> instead.
 122
 123
 124 </PRE><H3><a name="h3-ripoffline">ripoffline</a></H3><PRE>
 125        The <STRONG>ripoffline</STRONG> routine  provides  access  to  the  same  facility  that
 126        <STRONG>slk_init</STRONG>  [see  <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>]  uses  to  reduce the size of the screen.
 127        <STRONG>ripoffline</STRONG> must be called before  <STRONG>initscr</STRONG>  or  <STRONG>newterm</STRONG>  is  called,  to
 128        prepare these initial actions:
 129
 130        <STRONG>o</STRONG>   If <EM>line</EM> is positive, a line is removed from the top of <STRONG>stdscr</STRONG>.
 131
 132        <STRONG>o</STRONG>   if <EM>line</EM> is negative, a line is removed from the bottom.
 133
 134        When  the  resulting initialization is done inside <STRONG>initscr</STRONG>, the routine
 135        <STRONG>init</STRONG> (supplied by the user) is called with two arguments:
 136
 137        <STRONG>o</STRONG>   a window pointer to the one-line window that has been allocated and
 138
 139        <STRONG>o</STRONG>   an integer with the number of columns in the window.
 140
 141        Inside this initialization routine, the  integer  variables  <STRONG>LINES</STRONG>  and
 142        <STRONG>COLS</STRONG>  (defined  in  <STRONG>&lt;curses.h&gt;</STRONG>)  are  not guaranteed to be accurate and
 143        <STRONG>wrefresh</STRONG> or <STRONG>doupdate</STRONG> must not be  called.   It  is  allowable  to  call
 144        <STRONG>wnoutrefresh</STRONG> during the initialization routine.
 145
 146        <STRONG>ripoffline</STRONG>  can  be  called  up to five times before calling <STRONG>initscr</STRONG> or
 147        <STRONG>newterm</STRONG>.
 148
 149
 150 </PRE><H3><a name="h3-curs_set">curs_set</a></H3><PRE>
 151        The <STRONG>curs_set</STRONG> routine sets the cursor state  to  invisible,  normal,  or
 152        very  visible  for <STRONG>visibility</STRONG> equal to <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG> respectively.  If the
 153        terminal supports the <EM>visibility</EM> requested, the previous  <EM>cursor</EM>  state
 154        is returned; otherwise, <STRONG>ERR</STRONG> is returned.
 155
 156
 157 </PRE><H3><a name="h3-napms">napms</a></H3><PRE>
 158        The  <STRONG>napms</STRONG>  routine is used to sleep for <EM>ms</EM> milliseconds.  If the value
 159        of <EM>ms</EM> exceeds 30,000 (thirty seconds), it is capped at that value.
 160
 161
 162 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 163        Except for <STRONG>curs_set</STRONG>, these routines always return <STRONG>OK</STRONG>.
 164
 165        <STRONG>curs_set</STRONG> returns the previous cursor state, or  <STRONG>ERR</STRONG>  if  the  requested
 166        <EM>visibility</EM> is not supported.
 167
 168        X/Open defines no error conditions.  In this implementation
 169
 170        <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>, <STRONG>reset_shell_mode</STRONG>
 171             return an error if the terminal was not initialized, or if the I/O
 172             call to obtain the terminal settings fails.
 173
 174        <STRONG>ripoffline</STRONG>
 175             returns an error if the maximum number of ripped-off lines exceeds
 176             the maximum (5).
 177
 178
 179 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 180        Note that <STRONG>getsyx</STRONG> is a macro, so <STRONG>&amp;</STRONG> is not necessary before the variables
 181        <EM>y</EM> and <EM>x</EM>.
 182
 183        Older SVr4 man pages  warn  that  the  return  value  of  <STRONG>curs_set</STRONG>  "is
 184        currently incorrect".  This implementation gets it right, but it may be
 185        unwise to count on the correctness of the return value anywhere else.
 186
 187        Both ncurses and SVr4 will call <STRONG>curs_set</STRONG> in <STRONG>endwin</STRONG> if <STRONG>curs_set</STRONG> has been
 188        called  to make the cursor other than normal, i.e., either invisible or
 189        very visible.  There is no way for ncurses  to  determine  the  initial
 190        cursor state to restore that.
 191
 192
 193 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 194        The <EM>virtual</EM> <EM>screen</EM> functions <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> are not described in the
 195        XSI Curses standard, Issue 4.  All other functions are as described  in
 196        XSI Curses.
 197
 198        The  SVr4  documentation  describes  <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> as having return
 199        type int.  This is misleading, as they are macros  with  no  documented
 200        semantics for the return value.
 201
 202        If interrupted, ncurses restarts <STRONG>napms</STRONG>.  That, and the limitation to 30
 203        seconds, are different from other implementations.
 204
 205
 206 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 207        <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>,
 208        <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>
 209
 210
 211
 212 ncurses 6.4                       2023-10-14                   <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
 213 </PRE>
 214 <div class="nav">
 215 <ul>
 216 <li><a href="#h2-NAME">NAME</a></li>
 217 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 218 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 219 <ul>
 220 <li><a href="#h3-def_prog_mode_-def_shell_mode">def_prog_mode, def_shell_mode</a></li>
 221 <li><a href="#h3-reset_prog_mode_-reset_shell_mode">reset_prog_mode, reset_shell_mode</a></li>
 222 <li><a href="#h3-resetty_-savetty">resetty, savetty</a></li>
 223 <li><a href="#h3-getsyx">getsyx</a></li>
 224 <li><a href="#h3-setsyx">setsyx</a></li>
 225 <li><a href="#h3-ripoffline">ripoffline</a></li>
 226 <li><a href="#h3-curs_set">curs_set</a></li>
 227 <li><a href="#h3-napms">napms</a></li>
 228 </ul>
 229 </li>
 230 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 231 <li><a href="#h2-NOTES">NOTES</a></li>
 232 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 233 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 234 </ul>
 235 </div>
 236 </BODY>
 237 </HTML>