X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_kernel.3x;h=73dec7b1734c515d00cc7850bf15614a08a831a1;hp=727a2721cf71caee2d61219fb55b245fd638e8a5;hb=HEAD;hpb=c3b21f65a2687f3894a0d3217006c23f162c893a diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x index 727a2721..8c4119de 100644 --- a/man/curs_kernel.3x +++ b/man/curs_kernel.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2015,2016 Free Software Foundation, Inc. * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -26,109 +27,174 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_kernel.3x,v 1.21 2016/10/15 16:42:55 tom Exp $ +.\" $Id: curs_kernel.3x,v 1.63 2024/05/25 21:13:56 tom Exp $ +.TH curs_kernel 3X 2024-05-25 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. -.TH curs_kernel 3X "" -.na -.hy 0 .SH NAME -\fBdef_prog_mode\fR, -\fBdef_shell_mode\fR, -\fBreset_prog_mode\fR, -\fBreset_shell_mode\fR, -\fBresetty\fR, -\fBsavetty\fR, -\fBgetsyx\fR, -\fBsetsyx\fR, -\fBripoffline\fR, -\fBcurs_set\fR, -\fBnapms\fR \- low-level \fBcurses\fR routines -.ad -.hy +\fB\%def_prog_mode\fP, +\fB\%def_shell_mode\fP, +\fB\%reset_prog_mode\fP, +\fB\%reset_shell_mode\fP, +\fB\%resetty\fP, +\fB\%savetty\fP, +\fB\%getsyx\fP, +\fB\%setsyx\fP, +\fB\%curs_set\fP, +\fB\%mvcur\fP, +\fB\%napms\fP, +\fB\%ripoffline\fP \- +low-level \fIcurses\fR routines .SH SYNOPSIS -\fB#include \fR -.sp -\fBint def_prog_mode(void);\fR -.br -\fBint def_shell_mode(void);\fR -.br -\fBint reset_prog_mode(void);\fR -.br -\fBint reset_shell_mode(void);\fR -.br -\fBint resetty(void);\fR -.br -\fBint savetty(void);\fR -.br -\fBvoid getsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR -.br -\fBvoid setsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR -.br -\fBint ripoffline(int \fP\fIline\fP\fB, int (*\fP\fIinit\fP\fB)(WINDOW *, int));\fR -.br -\fBint curs_set(int \fP\fIvisibility\fP\fB);\fR -.br -\fBint napms(int \fP\fIms\fP\fB);\fR -.br +.nf +\fB#include +.PP +\fBint def_prog_mode(void); +\fBint def_shell_mode(void); +.PP +\fBint reset_prog_mode(void); +\fBint reset_shell_mode(void); +.PP +\fBint resetty(void); +\fBint savetty(void); +.PP +\fBvoid getsyx(int \fIy\fP, int \fIx\fP); +\fBvoid setsyx(int \fIy\fP, int \fIx\fP); +.PP +\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 to various \fBcurses\fR -capabilities. These routines typically are used inside library -routines. -.SS def_prog_mode, def_shell_mode -.PP -The \fBdef_prog_mode\fR and \fBdef_shell_mode\fR routines save the -current terminal modes as the "program" (in \fBcurses\fR) or "shell" -(not in \fBcurses\fR) state for use by the \fBreset_prog_mode\fR and -\fBreset_shell_mode\fR routines. This is done automatically by -\fBinitscr\fR. There is one such save area for each screen context -allocated by \fBnewterm\fR. -.SS reset_prog_mode, reset_shell_mode -.PP -The \fBreset_prog_mode\fR and \fBreset_shell_mode\fR routines restore -the terminal to "program" (in \fBcurses\fR) or "shell" (out of -\fBcurses\fR) state. These are done automatically by \fBendwin\fR -and, after an \fBendwin\fR, by \fBdoupdate\fR, so they normally are -not called. -.SS resetty, savetty -.PP -The \fBresetty\fR and \fBsavetty\fR routines save and restore the -state of the terminal modes. \fBsavetty\fR saves the current state in -a buffer and \fBresetty\fR restores the state to what it was at the -last call to \fBsavetty\fR. +The following routines give low-level access +to various \fBcurses\fP capabilities. +These routines typically are used inside library routines. +.SS "def_prog_mode, def_shell_mode" +The \fBdef_prog_mode\fP and \fBdef_shell_mode\fP routines save the +current terminal modes as the \*(``program\*('' +(in \fBcurses\fP) or \*(``shell\*('' +(not in \fBcurses\fP) state for use by the \fBreset_prog_mode\fP and +\fBreset_shell_mode\fP routines. +This is done automatically by \fBinitscr\fP. +There is one such save area for each screen context +allocated by \fBnewterm\fP. +.SS "reset_prog_mode, reset_shell_mode" +The \fBreset_prog_mode\fP and \fBreset_shell_mode\fP routines restore +the terminal to \*(``program\*('' (in \fBcurses\fP) or \*(``shell\*('' (out of +\fBcurses\fP) state. +These are done automatically by \fBendwin\fP(3X) and, +after an \fBendwin\fP, by \fBdoupdate\fP, +so they normally are not called. +.SS "resetty, savetty" +The \fBresetty\fP and \fBsavetty\fP routines save and restore the +state of the terminal modes. +\fBsavetty\fP saves the current state in +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 -The \fBgetsyx\fR routine returns the current coordinates of the virtual screen -cursor in \fIy\fR and \fIx\fR. If \fBleaveok\fR is currently \fBTRUE\fR, then -\fB\-1\fR,\fB\-1\fR is returned. If lines have been removed from the top of the -screen, using \fBripoffline\fR, \fIy\fR and \fIx\fR include these lines; -therefore, \fIy\fR and \fIx\fR should be used only as arguments for -\fBsetsyx\fR. +Few applications will use this feature, +most use \fBgetyx\fP instead. .SS setsyx -.PP -The \fBsetsyx\fR routine sets the virtual screen cursor to -\fIy\fR, \fIx\fR. If \fIy\fR and \fIx\fR are both \fB\-1\fR, then -\fBleaveok\fR is set. The two routines \fBgetsyx\fR and \fBsetsyx\fR +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\fR windows but does not want to change the current position -of the program's cursor. The library routine would call \fBgetsyx\fR +\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\fR on its windows, call \fBsetsyx\fR, and then call -\fBdoupdate\fR. -.SS ripoffline +\fBwnoutrefresh\fP on its windows, call \fBsetsyx\fP, and then call +\fBdoupdate\fP. .PP -The \fBripoffline\fR routine provides access to the same facility that -\fBslk_init\fR [see \fBcurs_slk\fR(3X)] uses to reduce the size of the -screen. \fBripoffline\fR must be called before \fBinitscr\fR or -\fBnewterm\fR is called, to prepare these initial actions: +Few applications will use this feature, +most use \fBwmove\fP 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. +.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 is 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 +.B \%mvcur +to set the cursor's location 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 +.I ms +milliseconds. +If +.I ms +exceeds 30,000 +(thirty seconds), +it is capped 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. +\fB\%ripoffline\fP must be called before \fBinitscr\fP or +\fBnewterm\fP is called, to prepare these initial actions: .bP -If \fIline\fR is positive, a line is removed from the top of \fBstdscr\fR. +If \fIline\fP is positive, a line is removed from the top of \fBstdscr\fP. .bP -if \fIline\fR is negative, a line is removed from the bottom. +if \fIline\fP is negative, a line is removed from the bottom. .PP -When the resulting initialization is done inside \fBinitscr\fR, the -routine \fBinit\fR (supplied by the user) is called with two +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 @@ -136,72 +202,109 @@ allocated and .bP an integer with the number of columns in the window. .PP -Inside this initialization routine, the integer variables \fBLINES\fR -and \fBCOLS\fR (defined in \fB\fR) are not guaranteed to be -accurate and \fBwrefresh\fR or \fBdoupdate\fR must not be called. It -is allowable to call \fBwnoutrefresh\fR during the initialization -routine. -.PP -\fBripoffline\fR can be called up to five times before calling \fBinitscr\fR or -\fBnewterm\fR. -.SS curs_set -.PP -The \fBcurs_set\fR routine sets the cursor state to invisible, -normal, or very visible for \fBvisibility\fR equal to \fB0\fR, -\fB1\fR, or \fB2\fR respectively. If the terminal supports the -\fIvisibility\fR requested, the previous \fIcursor\fR state is -returned; otherwise, \fBERR\fR is returned. -.SS napms +Inside this initialization routine, the integer variables \fBLINES\fP +and \fBCOLS\fP (defined in \fB\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. .PP -The \fBnapms\fR routine is used to sleep for \fIms\fR milliseconds. +\fBripoffline\fP can be called up to five times before calling \fBinitscr\fP or +\fBnewterm\fP. .SH RETURN VALUE -Except for \fBcurs_set\fR, these routines always return \fBOK\fR. +Except for \fBcurs_set\fP, these routines always return \fBOK\fP. .PP -\fBcurs_set\fR -returns the previous cursor state, or \fBERR\fR if the -requested \fIvisibility\fR is not supported. +\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 -.na -.hy 0 -\fBdef_prog_mode\fR, \fBdef_shell_mode\fR, \fBreset_prog_mode\fR, \fBreset_shell_mode\fR -.hy -.ad -return an error +\fBdef_prog_mode\fP, \fBdef_shell_mode\fP, \fBreset_prog_mode\fP, \fBreset_shell_mode\fP +return +.B ERR 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 (NRIPS = 5). +returns +.B ERR +if the maximum number of ripped-off lines +exceeds the maximum (5). .SH NOTES -Note that \fBgetsyx\fR is a macro, so \fB&\fR is not necessary before -the variables \fIy\fR and \fIx\fR. +Note that \fBgetsyx\fP is a macro, so \fB&\fP is not necessary before +the variables \fIy\fP and \fIx\fP. .PP -Older SVr4 man pages warn that the return value of \fBcurs_set\fR "is currently -incorrect". This implementation gets it right, but it may be unwise to count +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. .PP -Both ncurses and SVr4 will call \fBcurs_set\fR in \fBendwin\fR -if \fBcurs_set\fR +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 invisible or very visible. -There is no way for ncurses to determine the initial cursor state to -restore that. +There is no way for \fI\%ncurses\fP to determine the initial cursor +state to restore that. +.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 functions \fBsetsyx\fR and \fBgetsyx\fR are not described in the XSI -Curses standard, Issue 4. All other functions are as described in XSI Curses. +The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP +are not described in X/Open Curses, Issue 4. +All other functions are as described in X/Open Curses. .PP -The SVr4 documentation describes \fBsetsyx\fR and \fBgetsyx\fR as having return -type int. This is misleading, as they are macros with no documented semantics +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. +.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 +Both +.I \%ncurses +and SVr4 +.I curses +implement +.B \%mvcur +using the +.I SCREEN +data allocated in either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X). +X/Open Curses states that the old location must be given for +.B \%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. .SH SEE ALSO -\fBcurses\fR(3X), -\fBcurs_initscr\fR(3X), -\fBcurs_outopts\fR(3X), -\fBcurs_refresh\fR(3X), -\fBcurs_scr_dump\fR(3X), -\fBcurs_slk\fR(3X), -\fBcurs_variables\fR(3X). +\fB\%curses\fP(3X), +\fB\%curs_initscr\fP(3X), +\fB\%curs_outopts\fP(3X), +\fB\%curs_refresh\fP(3X), +\fB\%curs_scr_dump\fP(3X), +\fB\%curs_slk\fP(3X), +\fB\%curs_variables\fP(3X)