| 1 | .\"***************************************************************************
|
|---|
| 2 | .\" Copyright (c) 1998-2001,2005 Free Software Foundation, Inc. *
|
|---|
| 3 | .\" *
|
|---|
| 4 | .\" Permission is hereby granted, free of charge, to any person obtaining a *
|
|---|
| 5 | .\" copy of this software and associated documentation files (the *
|
|---|
| 6 | .\" "Software"), to deal in the Software without restriction, including *
|
|---|
| 7 | .\" without limitation the rights to use, copy, modify, merge, publish, *
|
|---|
| 8 | .\" distribute, distribute with modifications, sublicense, and/or sell *
|
|---|
| 9 | .\" copies of the Software, and to permit persons to whom the Software is *
|
|---|
| 10 | .\" furnished to do so, subject to the following conditions: *
|
|---|
| 11 | .\" *
|
|---|
| 12 | .\" The above copyright notice and this permission notice shall be included *
|
|---|
| 13 | .\" in all copies or substantial portions of the Software. *
|
|---|
| 14 | .\" *
|
|---|
| 15 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|---|
| 16 | .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|---|
| 17 | .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|---|
| 18 | .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|---|
| 19 | .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|---|
| 20 | .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|---|
| 21 | .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|---|
| 22 | .\" *
|
|---|
| 23 | .\" Except as contained in this notice, the name(s) of the above copyright *
|
|---|
| 24 | .\" holders shall not be used in advertising or otherwise to promote the *
|
|---|
| 25 | .\" sale, use or other dealings in this Software without prior written *
|
|---|
| 26 | .\" authorization. *
|
|---|
| 27 | .\"***************************************************************************
|
|---|
| 28 | .\"
|
|---|
| 29 | .\" $Id: curs_kernel.3x,v 1.15 2005/05/15 16:18:13 tom Exp $
|
|---|
| 30 | .TH curs_kernel 3X ""
|
|---|
| 31 | .na
|
|---|
| 32 | .hy 0
|
|---|
| 33 | .SH NAME
|
|---|
| 34 | \fBdef_prog_mode\fR,
|
|---|
| 35 | \fBdef_shell_mode\fR,
|
|---|
| 36 | \fBreset_prog_mode\fR,
|
|---|
| 37 | \fBreset_shell_mode\fR,
|
|---|
| 38 | \fBresetty\fR,
|
|---|
| 39 | \fBsavetty\fR,
|
|---|
| 40 | \fBgetsyx\fR,
|
|---|
| 41 | \fBsetsyx\fR,
|
|---|
| 42 | \fBripoffline\fR,
|
|---|
| 43 | \fBcurs_set\fR,
|
|---|
| 44 | \fBnapms\fR - low-level \fBcurses\fR routines
|
|---|
| 45 | .ad
|
|---|
| 46 | .hy
|
|---|
| 47 | .SH SYNOPSIS
|
|---|
| 48 | \fB#include <curses.h>\fR
|
|---|
| 49 | .sp
|
|---|
| 50 | \fBint def_prog_mode(void);\fR
|
|---|
| 51 | .br
|
|---|
| 52 | \fBint def_shell_mode(void);\fR
|
|---|
| 53 | .br
|
|---|
| 54 | \fBint reset_prog_mode(void);\fR
|
|---|
| 55 | .br
|
|---|
| 56 | \fBint reset_shell_mode(void);\fR
|
|---|
| 57 | .br
|
|---|
| 58 | \fBint resetty(void);\fR
|
|---|
| 59 | .br
|
|---|
| 60 | \fBint savetty(void);\fR
|
|---|
| 61 | .br
|
|---|
| 62 | \fBvoid getsyx(int y, int x);\fR
|
|---|
| 63 | .br
|
|---|
| 64 | \fBvoid setsyx(int y, int x);\fR
|
|---|
| 65 | .br
|
|---|
| 66 | \fBint ripoffline(int line, int (*init)(WINDOW *, int));\fR
|
|---|
| 67 | .br
|
|---|
| 68 | \fBint curs_set(int visibility);\fR
|
|---|
| 69 | .br
|
|---|
| 70 | \fBint napms(int ms);\fR
|
|---|
| 71 | .br
|
|---|
| 72 | .SH DESCRIPTION
|
|---|
| 73 | The following routines give low-level access to various \fBcurses\fR
|
|---|
| 74 | capabilities. Theses routines typically are used inside library
|
|---|
| 75 | routines.
|
|---|
| 76 | .PP
|
|---|
| 77 | The \fBdef_prog_mode\fR and \fBdef_shell_mode\fR routines save the
|
|---|
| 78 | current terminal modes as the "program" (in \fBcurses\fR) or "shell"
|
|---|
| 79 | (not in \fBcurses\fR) state for use by the \fBreset_prog_mode\fR and
|
|---|
| 80 | \fBreset_shell_mode\fR routines. This is done automatically by
|
|---|
| 81 | \fBinitscr\fR. There is one such save area for each screen context
|
|---|
| 82 | allocated by \fBnewterm()\fR.
|
|---|
| 83 | .PP
|
|---|
| 84 | The \fBreset_prog_mode\fR and \fBreset_shell_mode\fR routines restore
|
|---|
| 85 | the terminal to "program" (in \fBcurses\fR) or "shell" (out of
|
|---|
| 86 | \fBcurses\fR) state. These are done automatically by \fBendwin\fR
|
|---|
| 87 | and, after an \fBendwin\fR, by \fBdoupdate\fR, so they normally are
|
|---|
| 88 | not called.
|
|---|
| 89 | .PP
|
|---|
| 90 | The \fBresetty\fR and \fBsavetty\fR routines save and restore the
|
|---|
| 91 | state of the terminal modes. \fBsavetty\fR saves the current state in
|
|---|
| 92 | a buffer and \fBresetty\fR restores the state to what it was at the
|
|---|
| 93 | last call to \fBsavetty\fR.
|
|---|
| 94 | .PP
|
|---|
| 95 | The \fBgetsyx\fR routine returns the current coordinates of the virtual screen
|
|---|
| 96 | cursor in \fIy\fR and \fIx\fR. If \fBleaveok\fR is currently \fBTRUE\fR, then
|
|---|
| 97 | \fB-1\fR,\fB-1\fR is returned. If lines have been removed from the top of the
|
|---|
| 98 | screen, using \fBripoffline\fR, \fIy\fR and \fIx\fR include these lines;
|
|---|
| 99 | therefore, \fIy\fR and \fIx\fR should be used only as arguments for
|
|---|
| 100 | \fBsetsyx\fR.
|
|---|
| 101 | .PP
|
|---|
| 102 | The \fBsetsyx\fR routine sets the virtual screen cursor to
|
|---|
| 103 | \fIy\fR, \fIx\fR. If \fIy\fR and \fIx\fR are both \fB-1\fR, then
|
|---|
| 104 | \fBleaveok\fR is set. The two routines \fBgetsyx\fR and \fBsetsyx\fR
|
|---|
| 105 | are designed to be used by a library routine, which manipulates
|
|---|
| 106 | \fBcurses\fR windows but does not want to change the current position
|
|---|
| 107 | of the program's cursor. The library routine would call \fBgetsyx\fR
|
|---|
| 108 | at the beginning, do its manipulation of its own windows, do a
|
|---|
| 109 | \fBwnoutrefresh\fR on its windows, call \fBsetsyx\fR, and then call
|
|---|
| 110 | \fBdoupdate\fR.
|
|---|
| 111 | .PP
|
|---|
| 112 | The \fBripoffline\fR routine provides access to the same facility that
|
|---|
| 113 | \fBslk_init\fR [see \fBcurs_slk\fR(3X)] uses to reduce the size of the
|
|---|
| 114 | screen. \fBripoffline\fR must be called before \fBinitscr\fR or
|
|---|
| 115 | \fBnewterm\fR is called. If \fIline\fR is positive, a line is removed
|
|---|
| 116 | from the top of \fBstdscr\fR; if \fIline\fR is negative, a line is
|
|---|
| 117 | removed from the bottom. When this is done inside \fBinitscr\fR, the
|
|---|
| 118 | routine \fBinit\fR (supplied by the user) is called with two
|
|---|
| 119 | arguments: a window pointer to the one-line window that has been
|
|---|
| 120 | allocated and an integer with the number of columns in the window.
|
|---|
| 121 | Inside this initialization routine, the integer variables \fBLINES\fR
|
|---|
| 122 | and \fBCOLS\fR (defined in \fB<curses.h>\fR) are not guaranteed to be
|
|---|
| 123 | accurate and \fBwrefresh\fR or \fBdoupdate\fR must not be called. It
|
|---|
| 124 | is allowable to call \fBwnoutrefresh\fR during the initialization
|
|---|
| 125 | routine.
|
|---|
| 126 | .PP
|
|---|
| 127 | \fBripoffline\fR can be called up to five times before calling \fBinitscr\fR or
|
|---|
| 128 | \fBnewterm\fR.
|
|---|
| 129 | .PP
|
|---|
| 130 | The \fBcurs_set\fR routine sets the cursor state is set to invisible,
|
|---|
| 131 | normal, or very visible for \fBvisibility\fR equal to \fB0\fR,
|
|---|
| 132 | \fB1\fR, or \fB2\fR respectively. If the terminal supports the
|
|---|
| 133 | \fIvisibility\fR requested, the previous \fIcursor\fR state is
|
|---|
| 134 | returned; otherwise, \fBERR\fR is returned.
|
|---|
| 135 | .PP
|
|---|
| 136 | The \fBnapms\fR routine is used to sleep for \fIms\fR milliseconds.
|
|---|
| 137 | .SH RETURN VALUE
|
|---|
| 138 | Except for \fBcurs_set\fR, these routines always return \fBOK\fR.
|
|---|
| 139 | .PP
|
|---|
| 140 | \fBcurs_set\fR
|
|---|
| 141 | returns the previous cursor state, or \fBERR\fR if the
|
|---|
| 142 | requested \fIvisibility\fR is not supported.
|
|---|
| 143 | .PP
|
|---|
| 144 | X/Open defines no error conditions.
|
|---|
| 145 | In this implementation
|
|---|
| 146 | .RS
|
|---|
| 147 | .TP 5
|
|---|
| 148 | \fBdef_prog_mode\fR, \fBdef_shell_mode\fR, \fBreset_prog_mode\fR, \fBreset_shell_mode\fR
|
|---|
| 149 | return an error
|
|---|
| 150 | if the terminal was not initialized, or
|
|---|
| 151 | if the I/O call to obtain the terminal settings fails.
|
|---|
| 152 | .TP 5
|
|---|
| 153 | \fBripoffline\fP
|
|---|
| 154 | returns an error if the maximum number of ripped-off lines
|
|---|
| 155 | exceeds the maximum (NRIPS = 5).
|
|---|
| 156 | .RE
|
|---|
| 157 | .SH NOTES
|
|---|
| 158 | Note that \fBgetsyx\fR is a macro, so \fB&\fR is not necessary before
|
|---|
| 159 | the variables \fIy\fR and \fIx\fR.
|
|---|
| 160 | .PP
|
|---|
| 161 | Older SVr4 man pages warn that the return value of \fBcurs_set\fR "is currently
|
|---|
| 162 | incorrect". This implementation gets it right, but it may be unwise to count
|
|---|
| 163 | on the correctness of the return value anywhere else.
|
|---|
| 164 | .PP
|
|---|
| 165 | Both ncurses and SVr4 will call \fBcurs_set\fR in \fBendwin\fR
|
|---|
| 166 | if \fBcurs_set\fR
|
|---|
| 167 | has been called to make the cursor other than normal, i.e., either
|
|---|
| 168 | invisible or very visible.
|
|---|
| 169 | There is no way for ncurses to determine the initial cursor state to
|
|---|
| 170 | restore that.
|
|---|
| 171 | .SH PORTABILITY
|
|---|
| 172 | The functions \fBsetsyx\fR and \fBgetsyx\fR are not described in the XSI
|
|---|
| 173 | Curses standard, Issue 4. All other functions are as described in XSI Curses.
|
|---|
| 174 | .PP
|
|---|
| 175 | The SVr4 documentation describes \fBsetsyx\fR and \fBgetsyx\fR as having return
|
|---|
| 176 | type int. This is misleading, as they are macros with no documented semantics
|
|---|
| 177 | for the return value.
|
|---|
| 178 | .SH SEE ALSO
|
|---|
| 179 | \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_outopts\fR(3X), \fBcurs_refresh\fR(3X),
|
|---|
| 180 | \fBcurs_scr_dump\fR(3X), \fBcurs_slk\fR(3X)
|
|---|
| 181 | .\"#
|
|---|
| 182 | .\"# The following sets edit modes for GNU EMACS
|
|---|
| 183 | .\"# Local Variables:
|
|---|
| 184 | .\"# mode:nroff
|
|---|
| 185 | .\"# fill-column:79
|
|---|
| 186 | .\"# End:
|
|---|
