- 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 include these lines; therefore, y and x should be
- used only as arguments for setsyx.
+ 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 will use this feature, most use getyx instead.
+ Few applications use this feature; most call getyx(3x) instead.
- The setsyx routine sets the virtualscreen cursor to y, x. If y and x
- are both -1, then leaveok is set. The two routines getsyx and setsyx
- are designed to be used by a library 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
- beginning, do its manipulation of its own windows, do a wnoutrefresh on
- its windows, call setsyx, and then call doupdate.
+ 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.
+
- Few applications will use this feature, most use wmove instead.
+
+ 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.
+
+
+
- The ripoffline routine provides access to the same facility 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, to
- prepare these initial actions:
+ 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.
@@ -147,18 +176,6 @@
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 requested, the previous cursor state
- is returned; otherwise, ERR is returned.
-
-
-
Except for curs_set, these routines always return OK.
@@ -168,12 +185,12 @@
X/Open defines no error conditions. In this implementation
def_prog_mode, def_shell_mode, reset_prog_mode, reset_shell_mode
- return an error if the terminal was not initialized, or if the I/O
- call to obtain the terminal settings fails.
+ 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 (5).
+ returns ERR if the maximum number of ripped-off lines exceeds the
+ maximum (5).
+ 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 virtualscreen functions setsyx and getsyx are not described in the
- XSI Curses standard, Issue 4. All other functions are as described in
- XSI Curses.
+ Applications employing ncurses extensions should condition their use on
+ the visibility of the NCURSES_VERSION preprocessor macro.
+
+ 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
+ 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.
@@ -209,7 +249,7 @@
-ncurses 6.4 2024-01-05 curs_kernel(3x)
+ncurses 6.5 2024-06-08 curs_kernel(3x)