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