- The following routines give low-level access to various
- curses capabilities. These routines typically are used
- inside library routines.
-
- The def_prog_mode and def_shell_mode routines save the
- current terminal modes as the "program" (in curses) or
- "shell" (not in curses) state for use by the re-
- set_prog_mode and reset_shell_mode routines. This is done
- automatically by initscr. There is one such save area for
- each screen context allocated by newterm().
-
- The reset_prog_mode and reset_shell_mode routines restore
- the terminal to "program" (in curses) or "shell" (out of
- curses) state. These are done automatically by endwin
- and, after an endwin, by doupdate, so they normally are
- not called.
-
- The resetty and savetty routines save and restore the
- state of the terminal modes. savetty saves the current
- state in a buffer and resetty restores the state to what
- it was at the last call to savetty.
-
- The getsyx routine returns the current coordinates of the
- virtual screen cursor in y and x. If leaveok is currently
- TRUE, then -1,-1 is returned. If lines have been removed
- from the top of the screen, using ripoffline, y and x in-
- clude these lines; therefore, y and x should be used only
- as arguments for setsyx.
-
- The setsyx routine sets the virtual screen cursor to y, x.
- If y and x are both -1, then leaveok is set. The two rou-
- tines getsyx and setsyx are designed to be used by a li-
- brary routine, which manipulates curses windows but does
- not want to change the current position of the program's
- cursor. The library routine would call getsyx at the be-
- ginning, do its manipulation of its own windows, do a
- wnoutrefresh on its windows, call setsyx, and then call
- doupdate.
-
- The ripoffline routine provides access to the same facili-
- ty that slk_init [see curs_slk(3x)] uses to reduce the
- size of the screen. ripoffline must be called before
- initscr or newterm is called. If line is positive, a line
- is removed from the top of stdscr; if line is negative, a
- line is removed from the bottom. When this is done inside
- initscr, the routine init (supplied by the user) is called
- with two arguments: a window pointer to the one-line win-
- dow that has been allocated and an integer with the number
- of columns in the window. Inside this initialization rou-
- tine, the integer variables LINES and COLS (defined in
- <curses.h>) are not guaranteed to be accurate and wrefresh
- or doupdate must not be called. It is allowable to call
- wnoutrefresh during the initialization routine.
+ intcurs_set(intvisibility);
+ intmvcur(intoldrow,intoldcol,intnewrow,intnewcol);
+ intnapms(intms);
+ intripoffline(intline,int(*init)(WINDOW*,int));
- ripoffline can be called up to five times before calling
- initscr or newterm.
- The curs_set routine sets the cursor state to invisible,
- normal, or very visible for visibility equal to 0, 1, or 2
- respectively. If the terminal supports the visibility re-
- quested, the previous cursor state is returned; otherwise,
- ERR is returned.
+
+ The following routines give low-level access to various curses
+ capabilities. These routines typically are used inside library
+ routines.
- The napms routine is used to sleep for ms milliseconds.
+
+ The def_prog_mode and def_shell_mode routines save the current terminal
+ modes as the "program" (in curses) or "shell" (not in curses) state for
+ use by the reset_prog_mode and reset_shell_mode routines. This is done
+ automatically by initscr. There is one such save area for each screen
+ context allocated by newterm.
-
+ The reset_prog_mode and reset_shell_mode routines restore the terminal
+ to "program" (in curses) or "shell" (out of curses) state. These are
+ done automatically by endwin(3x) and, after an endwin, by doupdate, so
+ they normally are not called.
+
+
+
+ The resetty and savetty routines save and restore the state of the
+ terminal modes. savetty saves the current state in a buffer and
+ resetty restores the state to what it was at the last call to savetty.
+
+
+
+ getsyx stores the coordinates of virtual screen (newscr) cursor in y
+ and x. If newscr's leaveok(3x) output option is TRUE, getsyx stores -1
+ in both y and x. If lines have been removed from the top of the screen
+ using ripoffline, y includes these lines; therefore, y and x populated
+ by getsyx should be used only as arguments for setsyx.
+
+ Few applications use this feature; most call getyx(3x) instead.
+
+
+
+ setsyx sets the virtual screen (newscr) cursor location to (y, x).
+ setsyx(-1,-1) is equivalent to leaveok(newscr,TRUE).
+
+ getsyx and setsyx are designed to be used by a function that
+ manipulates curses windows but seeks to avoid changing the cursor
+ position. Such a function would first call getsyx, modify its windows'
+ content, call wnoutrefresh(3x) on them, call setsyx, then call
+ doupdate(3x).
+
+ Few applications use this feature; most call wmove(3x) instead.
+
+
+
+ The curs_set routine sets the cursor state to invisible, normal, or
+ very visible for visibility equal to 0, 1, or 2 respectively. If the
+ terminal supports the visibility requested, the previous cursor state
+ is returned; otherwise, ERR is returned.
+
+
+
+ mvcur provides low-level cursor motion. It takes effect immediately,
+ rather than at the next refresh. Unlike the other low-level output
+ functions, which either write to the standard output stream or are
+ passed a function pointer to perform output, mvcur uses a file
+ descriptor derived from the output stream parameter of newterm(3x).
+
+ One application of mvcur accompanies the temporary use of another
+ program to write to the terminal screen. For example, first call
+ refresh(3x) to ensure that the screen and the library's model of it is
+ up to date; then call reset_shell_mode; write to the screen with the
+ external application; call reset_prog_mode; and finally call mvcur to
+ set the cursor's location to where curses thinks it is, since the
+ library has no knowledge of how the external application moved it.
+
+
+
+ ripoffline provides access to the same facility that slk_init(3x) uses
+ to reduce the size of the screen. ripoffline must be called before
+ initscr or newterm is called, to prepare these initial actions:
+
+ o If line is positive, a line is removed from the top of stdscr.
+
+ o if line is negative, a line is removed from the bottom.
+
+ When the resulting initialization is done inside initscr, the routine
+ init (supplied by the user) is called with two arguments:
+
+ o a window pointer to the one-line window that has been allocated and
+
+ o an integer with the number of columns in the window.
+
+ Inside this initialization routine, the integer variables LINES and
+ COLS (defined in <curses.h>) are not guaranteed to be accurate and
+ wrefresh or doupdate must not be called. It is allowable to call
+ wnoutrefresh during the initialization routine.
+
+ ripoffline can be called up to five times before calling initscr or
+ newterm.
+
+
+
Except for curs_set, these routines always return OK.
- curs_set returns the previous cursor state, or ERR if the
- requested visibility is not supported.
+ curs_set returns the previous cursor state, or ERR if the requested
+ visibility is not supported.
- X/Open defines no error conditions. In this implementa-
- tion
+ X/Open defines no error conditions. In this implementation
- def_prog_mode, def_shell_mode, reset_prog_mode, re-
- set_shell_mode
- return an error if the terminal was not ini-
- tialized, or if the I/O call to obtain the
- terminal settings fails.
+ def_prog_mode, def_shell_mode, reset_prog_mode, reset_shell_mode
+ return ERR if the terminal was not initialized, or if the I/O call
+ to obtain the terminal settings fails.
- ripoffline
- returns an error if the maximum number of
- ripped-off lines exceeds the maximum (NRIPS =
- 5).
+ ripoffline
+ returns ERR if the maximum number of ripped-off lines exceeds the
+ maximum (5).
-
-
NOTES
- Note that getsyx is a macro, so & is not necessary before
- the variables y and x.
+
+ Note that getsyx is a macro, so & is not necessary before the variables
+ y and x.
- Older SVr4 man pages warn that the return value of
- curs_set "is currently incorrect". This implementation
- gets it right, but it may be unwise to count on the cor-
- rectness of the return value anywhere else.
+ Older SVr4 man pages warn that the return value of curs_set "is
+ currently incorrect". This implementation gets it right, but it may be
+ unwise to count on the correctness of the return value anywhere else.
- Both ncurses and SVr4 will call curs_set in endwin if
- curs_set has been called to make the cursor other than
- normal, i.e., either invisible or very visible. There is
- no way for ncurses to determine the initial cursor state
- to restore that.
+ Both ncurses and SVr4 will call curs_set in endwin if curs_set has been
+ called to make the cursor other than normal, i.e., either invisible or
+ very visible. There is no way for ncurses to determine the initial
+ cursor state to restore that.
-
-
PORTABILITY
- The functions setsyx and getsyx are not described in the
- XSI Curses standard, Issue 4. All other functions are as
- described in XSI Curses.
+
+ In ncurses, mvcur accepts -1 for either or both old coordinates. This
+ value tells ncurses that the old location is unknown, and that it must
+ use only absolute motion, as with the cursor_address (cup) capability,
+ rather than the least costly combination of absolute and relative
+ motion.
- The SVr4 documentation describes setsyx and getsyx as hav-
- ing return type int. This is misleading, as they are
- macros with no documented semantics for the return value.
+
+ Applications employing ncurses extensions should condition their use on
+ the visibility of the NCURSES_VERSION preprocessor macro.
-
-
SEE ALSO
- curses(3x), curs_initscr(3x), curs_outopts(3x), curs_re-
- fresh(3x), curs_scr_dump(3x), curs_slk(3x)
+ The virtualscreen functions setsyx and getsyx are not described in
+ X/Open Curses, Issue 4. All other functions are as described in X/Open
+ Curses.
+
+ The SVr4 documentation describes setsyx and getsyx as having return
+ type int. This is misleading, as they are macros with no documented
+ semantics for the return value.
+
+ X/Open Curses notes:
+
+ "After use of mvcur(), the model Curses maintains of the state
+ of the terminal might not match the actual state of the
+ terminal. An application should touch and refresh the window
+ before resuming conventional use of Curses."
+
+ Both ncurses and SVr4 curses implement mvcur using the SCREEN data
+ allocated in either initscr(3x) or newterm(3x). X/Open Curses states
+ that the old location must be given for mvcur to accommodate terminals
+ that lack absolute cursor positioning.
+
+ If interrupted, ncurses restarts napms. That, and the limitation to 30
+ seconds, are different from other implementations.
+
+
+