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

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
   2 <!--
   3   ****************************************************************************
   4   * Copyright (c) 1998 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.13 2001/12/08 18:01:25 tom Exp @
  31 -->
  32 <HTML>
  33 <HEAD>
  34 <TITLE>curs_kernel 3x</TITLE>
  35 <link rev=made href="mailto:bug-ncurses@gnu.org">
  36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  37 </HEAD>
  38 <BODY>
  39 <H1>curs_kernel 3x</H1>
  40 <HR>
  41 <PRE>
  42 <!-- Manpage converted by man2html 3.0.1 -->
  43
  44 </PRE>
  45 <H2>NAME</H2><PRE>
  46        <STRONG>def_prog_mode</STRONG>,       <STRONG>def_shell_mode</STRONG>,      <STRONG>reset_prog_mode</STRONG>,
  47        <STRONG>reset_shell_mode</STRONG>, <STRONG>resetty</STRONG>, <STRONG>savetty</STRONG>, <STRONG>getsyx</STRONG>, <STRONG>setsyx</STRONG>, <STRONG>ripof-</STRONG>
  48        <STRONG>fline</STRONG>, <STRONG>curs_set</STRONG>, <STRONG>napms</STRONG> - low-level <STRONG>curses</STRONG> routines
  49
  50
  51 </PRE>
  52 <H2>SYNOPSIS</H2><PRE>
  53        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  54
  55        <STRONG>int</STRONG> <STRONG>def_prog_mode(void);</STRONG>
  56        <STRONG>int</STRONG> <STRONG>def_shell_mode(void);</STRONG>
  57        <STRONG>int</STRONG> <STRONG>reset_prog_mode(void);</STRONG>
  58        <STRONG>int</STRONG> <STRONG>reset_shell_mode(void);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>resetty(void);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>savetty(void);</STRONG>
  61        <STRONG>void</STRONG> <STRONG>getsyx(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
  62        <STRONG>void</STRONG> <STRONG>setsyx(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
  63        <STRONG>int</STRONG> <STRONG>ripoffline(int</STRONG> <STRONG>line,</STRONG> <STRONG>int</STRONG> <STRONG>(*init)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int));</STRONG>
  64        <STRONG>int</STRONG> <STRONG>curs_set(int</STRONG> <STRONG>visibility);</STRONG>
  65        <STRONG>int</STRONG> <STRONG>napms(int</STRONG> <STRONG>ms);</STRONG>
  66
  67
  68 </PRE>
  69 <H2>DESCRIPTION</H2><PRE>
  70        The  following  routines  give low-level access to various
  71        <STRONG>curses</STRONG> capabilities.  Theses routines typically  are  used
  72        inside library routines.
  73
  74        The  <STRONG>def_prog_mode</STRONG>  and  <STRONG>def_shell_mode</STRONG>  routines save the
  75        current terminal modes as the  "program"  (in  <STRONG>curses</STRONG>)  or
  76        "shell"   (not   in   <STRONG>curses</STRONG>)   state   for   use  by  the
  77        <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG>  routines.   This  is
  78        done  automatically  by  <STRONG>initscr</STRONG>.   There is one such save
  79        area for each screen context allocated by <STRONG>newterm()</STRONG>.
  80
  81        The <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines  restore
  82        the  terminal  to "program" (in <STRONG>curses</STRONG>) or "shell" (out of
  83        <STRONG>curses</STRONG>) state.  These are  done  automatically  by  <STRONG>endwin</STRONG>
  84        and,  after  an  <STRONG>endwin</STRONG>, by <STRONG>doupdate</STRONG>, so they normally are
  85        not called.
  86
  87        The <STRONG>resetty</STRONG> and <STRONG>savetty</STRONG>  routines  save  and  restore  the
  88        state  of  the  terminal modes.  <STRONG>savetty</STRONG> saves the current
  89        state in a buffer and <STRONG>resetty</STRONG> restores the state  to  what
  90        it was at the last call to <STRONG>savetty</STRONG>.
  91
  92        The  <STRONG>getsyx</STRONG> routine returns the current coordinates of the
  93        virtual screen cursor in <EM>y</EM> and <EM>x</EM>.  If <STRONG>leaveok</STRONG> is currently
  94        <STRONG>TRUE</STRONG>,  then <STRONG>-1</STRONG>,<STRONG>-1</STRONG> is returned.  If lines have been removed
  95        from the top of the screen,  using  <STRONG>ripoffline</STRONG>,  <EM>y</EM>  and  <EM>x</EM>
  96        include  these  lines;  therefore,  <EM>y</EM> and <EM>x</EM> should be used
  97        only as arguments for <STRONG>setsyx</STRONG>.
  98
  99        The <STRONG>setsyx</STRONG> routine sets the virtual screen cursor to <EM>y</EM>, <EM>x</EM>.
 100        If <EM>y</EM> and <EM>x</EM> are both <STRONG>-1</STRONG>, then <STRONG>leaveok</STRONG> is set.  The two rou-
 101        tines <STRONG>getsyx</STRONG> and <STRONG>setsyx</STRONG> are  designed  to  be  used  by  a
 102        library routine, which manipulates <STRONG>curses</STRONG> windows but does
 103        not want to change the current position of  the  program's
 104        cursor.   The  library  routine  would  call <STRONG>getsyx</STRONG> at the
 105        beginning, do its manipulation of its own  windows,  do  a
 106        <STRONG>wnoutrefresh</STRONG>  on  its  windows, call <STRONG>setsyx</STRONG>, and then call
 107        <STRONG>doupdate</STRONG>.
 108
 109        The <STRONG>ripoffline</STRONG> routine provides access to the same  facil-
 110        ity  that  <STRONG>slk_init</STRONG>  [see <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>] uses to reduce the
 111        size of the screen.   <STRONG>ripoffline</STRONG>  must  be  called  before
 112        <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> is called.  If <EM>line</EM> is positive, a line
 113        is removed from the top of <STRONG>stdscr</STRONG>; if <EM>line</EM> is negative,  a
 114        line is removed from the bottom.  When this is done inside
 115        <STRONG>initscr</STRONG>, the routine <STRONG>init</STRONG> (supplied by the user) is called
 116        with  two arguments: a window pointer to the one-line win-
 117        dow that has been allocated and an integer with the number
 118        of columns in the window.  Inside this initialization rou-
 119        tine, the integer variables <STRONG>LINES</STRONG>  and  <STRONG>COLS</STRONG>  (defined  in
 120        <STRONG>&lt;curses.h&gt;</STRONG>) are not guaranteed to be accurate and <STRONG>wrefresh</STRONG>
 121        or <STRONG>doupdate</STRONG> must not be called.  It is allowable  to  call
 122        <STRONG>wnoutrefresh</STRONG> during the initialization routine.
 123
 124        <STRONG>ripoffline</STRONG>  can  be called up to five times before calling
 125        <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.
 126
 127        The <STRONG>curs_set</STRONG> routine sets  the  cursor  state  is  set  to
 128        invisible, normal, or very visible for <STRONG>visibility</STRONG> equal to
 129        <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG> respectively.  If  the  terminal  supports  the
 130        <EM>visibility</EM>   requested,   the  previous  <EM>cursor</EM>  state  is
 131        returned; otherwise, <STRONG>ERR</STRONG> is returned.
 132
 133        The <STRONG>napms</STRONG> routine is used to sleep for <EM>ms</EM> milliseconds.
 134
 135
 136 </PRE>
 137 <H2>RETURN VALUE</H2><PRE>
 138        Except for <STRONG>curs_set</STRONG>,  these  routines  always  return  <STRONG>OK</STRONG>.
 139        <STRONG>curs_set</STRONG>  returns the previous cursor state, or <STRONG>ERR</STRONG> if the
 140        requested <EM>visibility</EM> is not supported.
 141
 142
 143 </PRE>
 144 <H2>NOTES</H2><PRE>
 145        Note that <STRONG>getsyx</STRONG> is a macro, so <STRONG>&amp;</STRONG> is not necessary  before
 146        the variables <EM>y</EM> and <EM>x</EM>.
 147
 148        Older  SVr4  man  pages  warn  that  the  return  value of
 149        <STRONG>curs_set</STRONG> "is currently  incorrect".   This  implementation
 150        gets  it  right, but it may be unwise to count on the cor-
 151        rectness of the return value anywhere else.
 152
 153        Both ncurses and SVr4 will  call  <STRONG>curs_set</STRONG>  in  <STRONG>endwin</STRONG>  if
 154        <STRONG>curs_set</STRONG>  has  been  called  to make the cursor other than
 155        normal, i.e., either invisible or very visible.  There  is
 156        no  way  for ncurses to determine the initial cursor state
 157        to restore that.
 158
 159
 160 </PRE>
 161 <H2>PORTABILITY</H2><PRE>
 162        The functions <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> are not described  in  the
 163        XSI  Curses standard, Issue 4.  All other functions are as
 164        described in XSI Curses.
 165
 166        The SVr4 documentation describes <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> as hav-
 167        ing  return  type  int.  This  is  misleading, as they are
 168        macros with no documented semantics for the return  value.
 169
 170
 171 </PRE>
 172 <H2>SEE ALSO</H2><PRE>
 173        <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>,
 174        <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <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>
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219 </PRE>
 220 <HR>
 221 <ADDRESS>
 222 Man(1) output converted with
 223 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 224 </ADDRESS>
 225 </BODY>
 226 </HTML>