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.44 2023/09/16 23:37:03 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-09-16 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-09-16 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.
 159
 160
 161 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 162        Except for <STRONG>curs_set</STRONG>, these routines always return <STRONG>OK</STRONG>.
 163
 164        <STRONG>curs_set</STRONG>  returns  the  previous  cursor state, or <STRONG>ERR</STRONG> if the requested
 165        <EM>visibility</EM> is not supported.
 166
 167        X/Open defines no error conditions.  In this implementation
 168
 169        <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>, <STRONG>reset_shell_mode</STRONG>
 170             return an error if the terminal was not initialized, or if the I/O
 171             call to obtain the terminal settings fails.
 172
 173        <STRONG>ripoffline</STRONG>
 174             returns an error if the maximum number of ripped-off lines exceeds
 175             the maximum (5).
 176
 177
 178 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 179        Note that <STRONG>getsyx</STRONG> is a macro, so <STRONG>&amp;</STRONG> is not necessary before the variables
 180        <EM>y</EM> and <EM>x</EM>.
 181
 182        Older  SVr4  man  pages  warn  that  the  return  value of <STRONG>curs_set</STRONG> "is
 183        currently incorrect".  This implementation gets it right, but it may be
 184        unwise to count on the correctness of the return value anywhere else.
 185
 186        Both ncurses and SVr4 will call <STRONG>curs_set</STRONG> in <STRONG>endwin</STRONG> if <STRONG>curs_set</STRONG> has been
 187        called to make the cursor other than normal, i.e., either invisible  or
 188        very  visible.   There  is  no way for ncurses to determine the initial
 189        cursor state to restore that.
 190
 191
 192 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 193        The <EM>virtual</EM> <EM>screen</EM> functions <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> are not described in the
 194        XSI  Curses standard, Issue 4.  All other functions are as described in
 195        XSI Curses.
 196
 197        The SVr4 documentation describes <STRONG>setsyx</STRONG> and  <STRONG>getsyx</STRONG>  as  having  return
 198        type  int.   This  is misleading, as they are macros with no documented
 199        semantics for the return value.
 200
 201
 202 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 203        <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>,
 204        <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>.
 205
 206
 207
 208 ncurses 6.4                       2023-09-16                   <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
 209 </PRE>
 210 <div class="nav">
 211 <ul>
 212 <li><a href="#h2-NAME">NAME</a></li>
 213 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 214 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 215 <ul>
 216 <li><a href="#h3-def_prog_mode_-def_shell_mode">def_prog_mode, def_shell_mode</a></li>
 217 <li><a href="#h3-reset_prog_mode_-reset_shell_mode">reset_prog_mode, reset_shell_mode</a></li>
 218 <li><a href="#h3-resetty_-savetty">resetty, savetty</a></li>
 219 <li><a href="#h3-getsyx">getsyx</a></li>
 220 <li><a href="#h3-setsyx">setsyx</a></li>
 221 <li><a href="#h3-ripoffline">ripoffline</a></li>
 222 <li><a href="#h3-curs_set">curs_set</a></li>
 223 <li><a href="#h3-napms">napms</a></li>
 224 </ul>
 225 </li>
 226 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 227 <li><a href="#h2-NOTES">NOTES</a></li>
 228 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 229 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 230 </ul>
 231 </div>
 232 </BODY>
 233 </HTML>