2 ****************************************************************************
3 * Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
5 * Permission is hereby granted, free of charge, to any person obtaining a *
6 * copy of this software and associated documentation files (the *
7 * "Software"), to deal in the Software without restriction, including *
8 * without limitation the rights to use, copy, modify, merge, publish, *
9 * distribute, distribute with modifications, sublicense, and/or sell *
10 * copies of the Software, and to permit persons to whom the Software is *
11 * furnished to do so, subject to the following conditions: *
13 * The above copyright notice and this permission notice shall be included *
14 * in all copies or substantial portions of the Software. *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * Except as contained in this notice, the name(s) of the above copyright *
25 * holders shall not be used in advertising or otherwise to promote the *
26 * sale, use or other dealings in this Software without prior written *
28 ****************************************************************************
29 * @Id: curs_kernel.3x,v 1.19 2010/12/04 18:38:55 tom Exp @
31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
36 <TITLE>curs_kernel 3x</TITLE>
37 <link rev=made href="mailto:bug-ncurses@gnu.org">
38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
41 <H1>curs_kernel 3x</H1>
44 <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
50 <H2><a name="h2-NAME">NAME</a></H2><PRE>
51 <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>,
52 <STRONG>reset_shell_mode</STRONG>, <STRONG>resetty</STRONG>, <STRONG>savetty</STRONG>, <STRONG>getsyx</STRONG>, <STRONG>setsyx</STRONG>,
53 <STRONG>ripoffline</STRONG>, <STRONG>curs_set</STRONG>, <STRONG>napms</STRONG> - low-level <STRONG>curses</STRONG> routines
57 <H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
58 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
60 <STRONG>int</STRONG> <STRONG>def_prog_mode(void);</STRONG>
61 <STRONG>int</STRONG> <STRONG>def_shell_mode(void);</STRONG>
62 <STRONG>int</STRONG> <STRONG>reset_prog_mode(void);</STRONG>
63 <STRONG>int</STRONG> <STRONG>reset_shell_mode(void);</STRONG>
64 <STRONG>int</STRONG> <STRONG>resetty(void);</STRONG>
65 <STRONG>int</STRONG> <STRONG>savetty(void);</STRONG>
66 <STRONG>void</STRONG> <STRONG>getsyx(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
67 <STRONG>void</STRONG> <STRONG>setsyx(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
68 <STRONG>int</STRONG> <STRONG>ripoffline(int</STRONG> <STRONG>line,</STRONG> <STRONG>int</STRONG> <STRONG>(*init)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int));</STRONG>
69 <STRONG>int</STRONG> <STRONG>curs_set(int</STRONG> <STRONG>visibility);</STRONG>
70 <STRONG>int</STRONG> <STRONG>napms(int</STRONG> <STRONG>ms);</STRONG>
74 <H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
75 The following routines give low-level access to various
76 <STRONG>curses</STRONG> capabilities. These routines typically are used
77 inside library routines.
79 The <STRONG>def_prog_mode</STRONG> and <STRONG>def_shell_mode</STRONG> routines save the
80 current terminal modes as the "program" (in <STRONG>curses</STRONG>) or
81 "shell" (not in <STRONG>curses</STRONG>) state for use by the <STRONG>re-</STRONG>
82 <STRONG>set_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines. This is done
83 automatically by <STRONG>initscr</STRONG>. There is one such save area for
84 each screen context allocated by <STRONG>newterm()</STRONG>.
86 The <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines restore
87 the terminal to "program" (in <STRONG>curses</STRONG>) or "shell" (out of
88 <STRONG>curses</STRONG>) state. These are done automatically by <STRONG>endwin</STRONG>
89 and, after an <STRONG>endwin</STRONG>, by <STRONG>doupdate</STRONG>, so they normally are
92 The <STRONG>resetty</STRONG> and <STRONG>savetty</STRONG> routines save and restore the
93 state of the terminal modes. <STRONG>savetty</STRONG> saves the current
94 state in a buffer and <STRONG>resetty</STRONG> restores the state to what
95 it was at the last call to <STRONG>savetty</STRONG>.
97 The <STRONG>getsyx</STRONG> routine returns the current coordinates of the
98 virtual screen cursor in <EM>y</EM> and <EM>x</EM>. If <STRONG>leaveok</STRONG> is currently
99 <STRONG>TRUE</STRONG>, then <STRONG>-1</STRONG>,<STRONG>-1</STRONG> is returned. If lines have been removed
100 from the top of the screen, using <STRONG>ripoffline</STRONG>, <EM>y</EM> and <EM>x</EM> in-
101 clude these lines; therefore, <EM>y</EM> and <EM>x</EM> should be used only
102 as arguments for <STRONG>setsyx</STRONG>.
104 The <STRONG>setsyx</STRONG> routine sets the virtual screen cursor to <EM>y</EM>, <EM>x</EM>.
105 If <EM>y</EM> and <EM>x</EM> are both <STRONG>-1</STRONG>, then <STRONG>leaveok</STRONG> is set. The two rou-
106 tines <STRONG>getsyx</STRONG> and <STRONG>setsyx</STRONG> are designed to be used by a li-
107 brary routine, which manipulates <STRONG>curses</STRONG> windows but does
108 not want to change the current position of the program's
109 cursor. The library routine would call <STRONG>getsyx</STRONG> at the be-
110 ginning, do its manipulation of its own windows, do a
111 <STRONG>wnoutrefresh</STRONG> on its windows, call <STRONG>setsyx</STRONG>, and then call
112 <STRONG>doupdate</STRONG>.
114 The <STRONG>ripoffline</STRONG> routine provides access to the same facili-
115 ty that <STRONG>slk_init</STRONG> [see <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>] uses to reduce the
116 size of the screen. <STRONG>ripoffline</STRONG> must be called before
117 <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> is called. If <EM>line</EM> is positive, a line
118 is removed from the top of <STRONG>stdscr</STRONG>; if <EM>line</EM> is negative, a
119 line is removed from the bottom. When this is done inside
120 <STRONG>initscr</STRONG>, the routine <STRONG>init</STRONG> (supplied by the user) is called
121 with two arguments: a window pointer to the one-line win-
122 dow that has been allocated and an integer with the number
123 of columns in the window. Inside this initialization rou-
124 tine, the integer variables <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG> (defined in
125 <STRONG><curses.h></STRONG>) are not guaranteed to be accurate and <STRONG>wrefresh</STRONG>
126 or <STRONG>doupdate</STRONG> must not be called. It is allowable to call
127 <STRONG>wnoutrefresh</STRONG> during the initialization routine.
129 <STRONG>ripoffline</STRONG> can be called up to five times before calling
130 <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.
132 The <STRONG>curs_set</STRONG> routine sets the cursor state to invisible,
133 normal, or very visible for <STRONG>visibility</STRONG> equal to <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>
134 respectively. If the terminal supports the <EM>visibility</EM> re-
135 quested, the previous <EM>cursor</EM> state is returned; otherwise,
136 <STRONG>ERR</STRONG> is returned.
138 The <STRONG>napms</STRONG> routine is used to sleep for <EM>ms</EM> milliseconds.
142 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
143 Except for <STRONG>curs_set</STRONG>, these routines always return <STRONG>OK</STRONG>.
145 <STRONG>curs_set</STRONG> returns the previous cursor state, or <STRONG>ERR</STRONG> if the
146 requested <EM>visibility</EM> is not supported.
148 X/Open defines no error conditions. In this implementa-
151 <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>, <STRONG>re-</STRONG>
152 <STRONG>set_shell_mode</STRONG>
153 return an error if the terminal was not ini-
154 tialized, or if the I/O call to obtain the
155 terminal settings fails.
157 <STRONG>ripoffline</STRONG>
158 returns an error if the maximum number of
159 ripped-off lines exceeds the maximum (NRIPS =
164 <H2><a name="h2-NOTES">NOTES</a></H2><PRE>
165 Note that <STRONG>getsyx</STRONG> is a macro, so <STRONG>&</STRONG> is not necessary before
166 the variables <EM>y</EM> and <EM>x</EM>.
168 Older SVr4 man pages warn that the return value of
169 <STRONG>curs_set</STRONG> "is currently incorrect". This implementation
170 gets it right, but it may be unwise to count on the cor-
171 rectness of the return value anywhere else.
173 Both ncurses and SVr4 will call <STRONG>curs_set</STRONG> in <STRONG>endwin</STRONG> if
174 <STRONG>curs_set</STRONG> has been called to make the cursor other than
175 normal, i.e., either invisible or very visible. There is
176 no way for ncurses to determine the initial cursor state
181 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
182 The functions <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> are not described in the
183 XSI Curses standard, Issue 4. All other functions are as
184 described in XSI Curses.
186 The SVr4 documentation describes <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> as hav-
187 ing return type int. This is misleading, as they are
188 macros with no documented semantics for the return value.
192 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
193 <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>curs_re-</STRONG>
194 <STRONG><A HREF="curs_refresh.3x.html">fresh(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>, <STRONG>curs_vari-</STRONG>
195 <STRONG><A HREF="curs_variables.3x.html">ables(3x)</A></STRONG>.
199 <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
203 <li><a href="#h2-NAME">NAME</a></li>
204 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
205 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
206 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
207 <li><a href="#h2-NOTES">NOTES</a></li>
208 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
209 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>