ncurses 4.2
[ncurses.git] / Ada95 / html / curs_kernel.3x.html
1 <HTML>
2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
3 <PRE>
4        <STRONG>def_prog_mode</STRONG>,       <STRONG>def_shell_mode</STRONG>,      <STRONG>reset_prog_mode</STRONG>,
5        <STRONG>reset_shell_mode</STRONG>, <STRONG>resetty</STRONG>, <STRONG>savetty</STRONG>, <STRONG>getsyx</STRONG>, <STRONG>setsyx</STRONG>, <STRONG>ripof-</STRONG>
6        <STRONG>fline</STRONG>, <STRONG>curs_set</STRONG>, <STRONG>napms</STRONG> - low-level <STRONG>curses</STRONG> routines
7
8
9 </PRE>
10 <H2>SYNOPSIS</H2><PRE>
11        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
12
13        <STRONG>int</STRONG> <STRONG>def_prog_mode(void);</STRONG>
14        <STRONG>int</STRONG> <STRONG>def_shell_mode(void);</STRONG>
15        <STRONG>int</STRONG> <STRONG>reset_prog_mode(void);</STRONG>
16        <STRONG>int</STRONG> <STRONG>reset_shell_mode(void);</STRONG>
17        <STRONG>int</STRONG> <STRONG>resetty(void);</STRONG>
18        <STRONG>int</STRONG> <STRONG>savetty(void);</STRONG>
19        <STRONG>void</STRONG> <STRONG>getsyx(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
20        <STRONG>void</STRONG> <STRONG>setsyx(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
21        <STRONG>int</STRONG> <STRONG>ripoffline(int</STRONG> <STRONG>line,</STRONG> <STRONG>int</STRONG> <STRONG>(*init)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int));</STRONG>
22        <STRONG>int</STRONG> <STRONG>curs_set(int</STRONG> <STRONG>visibility);</STRONG>
23        <STRONG>int</STRONG> <STRONG>napms(int</STRONG> <STRONG>ms);</STRONG>
24
25
26 </PRE>
27 <H2>DESCRIPTION</H2><PRE>
28        The  following  routines  give low-level access to various
29        <STRONG>curses</STRONG> capabilities.  Theses routines typically  are  used
30        inside library routines.
31
32        The  <STRONG>def_prog_mode</STRONG>  and  <STRONG>def_shell_mode</STRONG>  routines save the
33        current terminal modes as the  "program"  (in  <STRONG>curses</STRONG>)  or
34        "shell"   (not   in   <STRONG>curses</STRONG>)   state   for   use  by  the
35        <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG>  routines.   This  is
36        done  automatically  by  <STRONG>initscr</STRONG>.   There is one such save
37        area for each screen context allocated by <STRONG>newterm()</STRONG>.
38
39        The <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines  restore
40        the  terminal  to "program" (in <STRONG>curses</STRONG>) or "shell" (out of
41        <STRONG>curses</STRONG>) state.  These are  done  automatically  by  <STRONG>endwin</STRONG>
42        and,  after  an  <STRONG>endwin</STRONG>, by <STRONG>doupdate</STRONG>, so they normally are
43        not called.
44
45        The <STRONG>resetty</STRONG> and <STRONG>savetty</STRONG>  routines  save  and  restore  the
46        state  of  the  terminal modes.  <STRONG>savetty</STRONG> saves the current
47        state in a buffer and <STRONG>resetty</STRONG> restores the state  to  what
48        it was at the last call to <STRONG>savetty</STRONG>.
49
50        The  <STRONG>getsyx</STRONG> routine returns the current coordinates of the
51        virtual screen cursor in <EM>y</EM> and <EM>x</EM>.  If <STRONG>leaveok</STRONG> is currently
52        <STRONG>TRUE</STRONG>,  then <STRONG>-1</STRONG>,<STRONG>-1</STRONG> is returned.  If lines have been removed
53        from the top of the screen,  using  <STRONG>ripoffline</STRONG>,  <EM>y</EM>  and  <EM>x</EM>
54        include  these  lines;  therefore,  <EM>y</EM> and <EM>x</EM> should be used
55        only as arguments for <STRONG>setsyx</STRONG>.
56
57        The <STRONG>setsyx</STRONG> routine sets the virtual screen cursor to <EM>y</EM>, <EM>x</EM>.
58        If <EM>y</EM> and <EM>x</EM> are both <STRONG>-1</STRONG>, then <STRONG>leaveok</STRONG> is set.  The two rou-
59        tines <STRONG>getsyx</STRONG> and <STRONG>setsyx</STRONG> are  designed  to  be  used  by  a
60        cursor.   The  library  routine  would  call <STRONG>getsyx</STRONG> at the
61        beginning, do its manipulation of its own  windows,  do  a
62        <STRONG>wnoutrefresh</STRONG>  on  its  windows, call <STRONG>setsyx</STRONG>, and then call
63        <STRONG>doupdate</STRONG>.
64
65        The <STRONG>ripoffline</STRONG> routine provides access to the same  facil-
66        ity  that  <STRONG>slk_init</STRONG>  [see <STRONG><A HREF="curs_slk.3x.html">curs_slk(3X)</A></STRONG>] uses to reduce the
67        size of the screen.   <STRONG>ripoffline</STRONG>  must  be  called  before
68        <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> is called.  If <EM>line</EM> is positive, a line
69        is removed from the top of <STRONG>stdscr</STRONG>; if <EM>line</EM> is negative,  a
70        line is removed from the bottom.  When this is done inside
71        <STRONG>initscr</STRONG>, the routine <STRONG>init</STRONG> (supplied by the user) is called
72        with  two arguments: a window pointer to the one-line win-
73        dow that has been allocated and an integer with the number
74        of columns in the window.  Inside this initialization rou-
75        tine, the integer variables <STRONG>LINES</STRONG>  and  <STRONG>COLS</STRONG>  (defined  in
76        <STRONG>&lt;curses.h&gt;</STRONG>) are not guaranteed to be accurate and <STRONG>wrefresh</STRONG>
77        or <STRONG>doupdate</STRONG> must not be called.  It is allowable  to  call
78        <STRONG>wnoutrefresh</STRONG> during the initialization routine.
79
80        <STRONG>ripoffline</STRONG>  can  be called up to five times before calling
81        <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.
82
83        The <STRONG>curs_set</STRONG> routine sets  the  cursor  state  is  set  to
84        invisible, normal, or very visible for <STRONG>visibility</STRONG> equal to
85        <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG> respectively.  If  the  terminal  supports  the
86        <EM>visibility</EM>   requested,   the  previous  <EM>cursor</EM>  state  is
87        returned; otherwise, <STRONG>ERR</STRONG> is returned.
88
89        The <STRONG>napms</STRONG> routine is used to sleep for <EM>ms</EM> milliseconds.
90
91
92 </PRE>
93 <H2>RETURN VALUE</H2><PRE>
94        Except for <STRONG>curs_set</STRONG>,  these  routines  always  return  <STRONG>OK</STRONG>.
95        <STRONG>curs_set</STRONG>  returns the previous cursor state, or <STRONG>ERR</STRONG> if the
96        requested <EM>visibility</EM> is not supported.
97
98
99 </PRE>
100 <H2>NOTES</H2><PRE>
101        Note that <STRONG>getsyx</STRONG> is a macro, so <STRONG>&amp;</STRONG> is not necessary  before
102        the variables <EM>y</EM> and <EM>x</EM>.
103
104        The  SVr4 man pages warn that the return value of <STRONG>curs_set</STRONG>
105        "is currently incorrect".   This  implementation  gets  it
106        right, but it may be unwise to count on the correctness of
107        the return value anywhere else.
108
109
110 </PRE>
111 <H2>PORTABILITY</H2><PRE>
112        The functions <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> are not described  in  the
113        XSI  Curses standard, Issue 4.  All other functions are as
114        described in XSI Curses.
115
116        The SVr4 documentation describes <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> as hav-
117        ing  return  type  int.  This  is  misleading, as they are
118        <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>,
119        <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>
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
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 </PRE>
171 </BODY>
172 </HTML>