diff options
Diffstat (limited to 'man/curs_kernel.3x')
| -rw-r--r-- | man/curs_kernel.3x | 467 |
1 files changed, 365 insertions, 102 deletions
diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x index e85c132768a3..98c93aa64061 100644 --- a/man/curs_kernel.3x +++ b/man/curs_kernel.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 2018-2024,2025 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_kernel.3x,v 1.61 2024/04/20 21:24:19 tom Exp $ -.TH curs_kernel 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.\" $Id: curs_kernel.3x,v 1.89 2025/08/16 19:50:07 tom Exp $ +.TH curs_kernel 3X 2025-08-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -53,9 +53,10 @@ \fB\%savetty\fP, \fB\%getsyx\fP, \fB\%setsyx\fP, -\fB\%ripoffline\fP, \fB\%curs_set\fP, -\fB\%napms\fP \- +\fB\%mvcur\fP, +\fB\%napms\fP, +\fB\%ripoffline\fP \- low-level \fIcurses\fR routines .SH SYNOPSIS .nf @@ -73,9 +74,10 @@ low-level \fIcurses\fR routines \fBvoid getsyx(int \fIy\fP, int \fIx\fP); \fBvoid setsyx(int \fIy\fP, int \fIx\fP); .PP -\fBint ripoffline(int \fIline\fP, int (*\fIinit\fP)(WINDOW *, int)); \fBint curs_set(int \fIvisibility\fP); +\fBint mvcur(int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP); \fBint napms(int \fIms\fP); +\fBint ripoffline(int \fIline\fP, int (*\fIinit\fP)(WINDOW *, int)); .fi .SH DESCRIPTION The following routines give low-level access @@ -104,67 +106,118 @@ state of the terminal modes. a buffer and \fBresetty\fP restores the state to what it was at the last call to \fBsavetty\fP. .SS getsyx -The \fBgetsyx\fP routine returns the current coordinates -of the \fIvirtual screen\fP cursor in \fIy\fP and \fIx\fP. -If \fBleaveok\fP is currently \fBTRUE\fP, then -\fB\-1\fP,\fB\-1\fP is returned. -If lines have been removed from the top of the -screen, using \fBripoffline\fP, \fIy\fP and \fIx\fP include these lines; -therefore, \fIy\fP and \fIx\fP should be used only as arguments for -\fBsetsyx\fP. -.PP -Few applications will use this feature, -most use \fBgetyx\fP instead. -.SS setsyx -The \fBsetsyx\fP routine sets -the \fIvirtual screen\fP cursor to \fIy\fP, \fIx\fP. -If \fIy\fP and \fIx\fP are both \fB\-1\fP, then -\fBleaveok\fP is set. -The two routines \fBgetsyx\fP and \fBsetsyx\fP -are designed to be used by a library routine, which manipulates -\fBcurses\fP windows but does not want to change the current position -of the program's cursor. -The library routine would call \fBgetsyx\fP -at the beginning, do its manipulation of its own windows, do a -\fBwnoutrefresh\fP on its windows, call \fBsetsyx\fP, and then call -\fBdoupdate\fP. -.PP -Few applications will use this feature, -most use \fBwmove\fP instead. -.SS ripoffline -.B \%ripoffline -provides access to the same facility that \fB\%slk_init\fP(3X) uses to -reduce the size of the screen. -\fB\%ripoffline\fP must be called before \fBinitscr\fP or -\fBnewterm\fP is called, to prepare these initial actions: -.bP -If \fIline\fP is positive, a line is removed from the top of \fBstdscr\fP. -.bP -if \fIline\fP is negative, a line is removed from the bottom. +.B \%getsyx +stores the coordinates of virtual screen +.RB \%( newscr ) +cursor in +.I y +and +.IR x "." +If +.BR \%newscr 's +\fB\%leaveok\fP(3X) output option is +.BR TRUE "," +.B \%getsyx +stores +.B \-1 +in both +.I y +and +.IR x "." +If lines have been removed from the top of the screen using +.BR \%ripoffline "," +.I y +includes these lines; +therefore, +.I y +and +.I x +populated by +.B \%getsyx +should be used only as arguments for +.BR \%setsyx "." .PP -When the resulting initialization is done inside \fBinitscr\fP, the -routine \fBinit\fP (supplied by the user) is called with two -arguments: -.bP -a window pointer to the one-line window that has been -allocated and -.bP -an integer with the number of columns in the window. +Few applications use this feature; +most call \fB\%getyx\fP(3X) instead. +.SS setsyx +.B \%setsyx +sets the virtual screen +.RB \%( newscr ) +cursor location to +.RI ( y , +.IR x ")." +.B "\%setsyx(\-1, \-1)" +is equivalent to +.BR "\%leaveok(newscr, TRUE)" "." .PP -Inside this initialization routine, the integer variables \fBLINES\fP -and \fBCOLS\fP (defined in \fB<curses.h>\fP) are not guaranteed to be -accurate and \fBwrefresh\fP or \fBdoupdate\fP must not be called. -It is allowable to call \fBwnoutrefresh\fP during the initialization routine. +.B \%getsyx +and +.B \%setsyx +are designed to be used by a function that manipulates +.I curses +windows but seeks to avoid changing the cursor position. +Such a function would first call +.BR \%getsyx "," +modify its windows' content, +call \fB\%wnoutrefresh\fP(3X) on them, +call +.BR \%setsyx "," +then call \fB\%doupdate\fP(3X). .PP -\fBripoffline\fP can be called up to five times before calling \fBinitscr\fP or -\fBnewterm\fP. +Few applications use this feature; +most call \fB\%wmove\fP(3X) instead. .SS curs_set -The \fBcurs_set\fP routine sets the cursor state to invisible, -normal, or very visible for \fBvisibility\fP equal to \fB0\fP, -\fB1\fP, or \fB2\fP respectively. -If the terminal supports the \fIvisibility\fP requested, -the previous \fIcursor\fP state is returned; -otherwise, \fBERR\fP is returned. +.B \%curs_set +adjusts the cursor visibility to +\*(``invisible\*('', +\*(``visible\*('', +\*(``very visible\*('', +as its argument is +.BR 0 , +.BR 1 , +or +.BR 2 , +respectively. +It returns the previous +.I visibility +if the requested one is supported, +and +.B ERR +otherwise. +.SS mvcur +.B \%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, +.B \%mvcur +uses a file descriptor derived from the output stream parameter of +\fB\%newterm\fP(3X). +.PP +One application of +.B \%mvcur +accompanies the temporary use of another program to write to the +terminal screen. +For example, +first call \fB\%refresh\fP(3X) to ensure that the screen and the +library's model of it are up to date; +then call +.BR \%reset_shell_mode ";" +write to the screen with the external application; +call +.BR \%reset_prog_mode ";" +and finally call +.BR \%mvcur( ".\|.\|." , +.RB .\|.\|. , +.B \-1, \-1) +to move the terminal cursor to where +.I \%curses +thinks it is, +since the library has no knowledge of how the external application +moved it. +.\" https://lists.gnu.org/archive/html/bug-ncurses/2016-10/msg00002.html .SS napms .B \%napms sleeps for @@ -174,53 +227,263 @@ If .I ms exceeds 30,000 (thirty seconds), -it is capped at that value. +.I \%ncurses +caps it at that value. +.SS ripoffline +.B \%ripoffline +provides access to the same facility that \fB\%slk_init\fP(3X) uses to +reduce the size of the screen. +The application must call +.B \%ripoffline +before \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) +so that the latter functions prepare a +.B \%stdscr +of the correct size. +.bP +If +.I line +is positive, +.B \%ripoffline +removes a line from the top of what will become +.BR \%stdscr "." +.bP +If +.I line +is negative, +.B \%ripoffline +removes a line from the bottom of what will become +.BR \%stdscr "." +.PP +When +.B \%initscr +initializes +.IR curses "," +it calls the +.I init +function supplied to +.B \%ripoffline +by the application with two arguments: +.bP +a pointer to the one-line +.I \%WINDOW +that it allocates, +and +.bP +an integer with the number of columns in the window. +.PP +Inside this +.I init +function, +the values of the integer variables +.B LINES +and +.B COLS +(see \fB\%curs_variables\fP(3X)) +are not guaranteed to be reliable; +it must not call \fB\%wrefresh\fP(3X) or \fB\%doupdate\fP(3X). +A \fB\%wnoutrefresh\fP(3X) call is permissible. +.PP +.B \%ripoffline +can be called up to five times before +.B \%initscr +or +.BR \%newterm "." .SH RETURN VALUE -Except for \fBcurs_set\fP, these routines always return \fBOK\fP. -.PP -\fBcurs_set\fP -returns the previous cursor state, or \fBERR\fP if the -requested \fIvisibility\fP is not supported. -.PP -X/Open defines no error conditions. -In this implementation -.TP 5 -\fBdef_prog_mode\fP, \fBdef_shell_mode\fP, \fBreset_prog_mode\fP, \fBreset_shell_mode\fP -return an error -if the terminal was not initialized, or -if the I/O call to obtain the terminal settings fails. -.TP 5 -\fBripoffline\fP -returns an error if the maximum number of ripped-off lines -exceeds the maximum (5). -.SH NOTES -Note that \fBgetsyx\fP is a macro, so \fB&\fP is not necessary before -the variables \fIy\fP and \fIx\fP. +Except for +.BR \%curs_set "," +these functions return +.B OK +on success and +.B ERR +on failure. .PP -Older SVr4 man pages warn that the return value -of \fBcurs_set\fP \*(``is currently incorrect\*(''. -This implementation gets it right, but it may be unwise to count -on the correctness of the return value anywhere else. +.B \%curs_set +returns the previous cursor visibility, +and returns +.B ERR +if the terminal type does not support the requested +.IR visibility "." +.PP +.B \%napms +always succeeds. +.PP +.B \%mvcur +fails if the position +.RI ( newrow , +.IR newcol ) +is outside the screen boundaries. +.PP +In +.IR \%ncurses "," +.bP +.BR \%def_prog_mode "," +.BR \%def_shell_mode "," +.BR \%reset_prog_mode "," +and +.B \%reset_shell_mode +return +.B ERR +if the terminal was not initialized, +or if the operating system's function for obtaining terminal settings +fails. +.bP +.B \%ripoffline +returns +.B ERR +if the accumulated quantity of ripped-off lines +would exceed the maximum (5). +.SH NOTES +.B \%getsyx +is a macro; +use of the +.B & +operator before its arguments is unnecessary. .PP -Both \fI\%ncurses\fP and SVr4 will call \fBcurs_set\fP in \fBendwin\fP -if \fBcurs_set\fP -has been called to make the cursor other than normal, i.e., either +The +.B \%endwin +function of both +.I \%ncurses +and SVr4 +.I curses +calls +.B \%curs_set +if the latter has previously been called to set the cursor visibility +to a value other than normal; +that is, +either invisible or very visible. -There is no way for \fI\%ncurses\fP to determine the initial cursor -state to restore that. +There is no way for +.I \%ncurses +to determine the initial cursor visibility to restore it. +.PP +.I \%ncurses +imposes a limit of 30 seconds on a delay requested of +.BR \%napms . +.PP +While the +.I init +function called by +.B \%ripoffline +is specified to return an +.IR int "," +.I \%ncurses +pays no attention to its return value. +.PP +If +.B \%ripoffline +cannot allocate memory for the required +.I \%WINDOW +structure backing the ripped-off line, +it stores a null pointer to the +.I \%WINDOW +pointer argument supplied by the +.I init +function the application specifies. +The application must check this argument for validity after calling +.B \%initscr +and prior to performing +.I curses +operations on that window. +.SH EXTENSIONS +In +.IR \%ncurses "," +.B \%mvcur +accepts +.B \-1 +for either or both old coordinates. +This value tells +.I \%ncurses +that the old location is unknown, +and that it must use only absolute motion, +as with the +.B \%cursor_address +.RB ( cup ) +capability, +rather than the least costly combination of absolute and relative +motion. .SH PORTABILITY -The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP -are not described in X/Open Curses, Issue 4. +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. +.PP +The +.I "virtual screen" +functions +.I \%setsyx +and +.I \%getsyx +are not described in X/Open Curses Issue\ 4. +SVr4 documents each of them +as returning an +.IR int "." +This is misleading, +as they are macros with no documented semantics for returning values. +.PP All other functions are as described in X/Open Curses. +It specifies no error conditions for them, +except as described for +.I \%curs_set +in section \*(``RETURN VALUE\*('' above. +.PP +The System\ V Interface Definition, +Version 4 (1995), +specified all of these functions except +.I \%curs_set +as returning +.IR OK "." +.\" SVID 4, vol 3., p. 518 +.PP +Older SVr4 man pages warn that the return value of +.I \%curs_set +\*(``is currently incorrect\*(''. +This implementation gets it right, +but counting on its correctness anywhere else may be unwise. +.PP +X/Open Curses specifies +.I \%ripoffline +as returning +.I OK +with no possibility of failure +(\*(``[c]alls to +.I \%ripoffline +above this limit +[five lines] +have no effect but report success\*(''). +.PP +X/Open Curses notes: +.RS +.PP +After use of +.IR \%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. +.RE .PP -The SVr4 documentation describes \fBsetsyx\fP and \fBgetsyx\fP -as having return type int. -This is misleading, as they are macros with no documented semantics -for the return value. +Both +.I \%ncurses +and SVr4 +.I curses +implement +.I \%mvcur +using the +.I SCREEN +object allocated in either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X). +X/Open Curses states that the old location must be given for +.I \%mvcur +to accommodate terminals that lack absolute cursor positioning. +.\" X/Open Curses Issue 7, p. 161 .PP -If interrupted, \fI\%ncurses\fP restarts \fBnapms\fP. -That, and the limitation to 30 seconds, -are different from other implementations. +If interrupted by a signal, +.I \%ncurses +restarts +.IR \%napms "." +That, +and the limitation to 30 seconds, +differ from other implementations. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_initscr\fP(3X), |