diff options
Diffstat (limited to 'upstream/debian-unstable/man3/get_wch.3ncurses')
| -rw-r--r-- | upstream/debian-unstable/man3/get_wch.3ncurses | 294 |
1 files changed, 179 insertions, 115 deletions
diff --git a/upstream/debian-unstable/man3/get_wch.3ncurses b/upstream/debian-unstable/man3/get_wch.3ncurses index 9f0ce118..aeafa868 100644 --- a/upstream/debian-unstable/man3/get_wch.3ncurses +++ b/upstream/debian-unstable/man3/get_wch.3ncurses @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 2002-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_get_wch.3x,v 1.31 2023/12/23 16:35:10 tom Exp $ -.TH get_wch 3NCURSES 2023-12-23 "ncurses 6.4" "Library calls" +.\" $Id: curs_get_wch.3x,v 1.40 2024/04/20 19:23:03 tom Exp $ +.TH get_wch 3NCURSES 2024-04-20 "ncurses 6.5" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -60,136 +60,200 @@ get (or push back) a wide character from \fIcurses\fR terminal keyboard \fBint mvget_wch(int \fIy\fP, int \fIx\fP, wint_t *\fIwch\fP); \fBint mvwget_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, wint_t *\fIwch\fP); .PP -\fBint unget_wch(const wchar_t \fIwch\fP); +\fBint unget_wch(const wchar_t \fIwc\fP); .fi .SH DESCRIPTION -.SS wget_wch -The -\fBget_wch\fP, -\fBwget_wch\fP, -\fBmvget_wch\fP, and -\fBmvwget_wch\fP -functions read a character -from the terminal associated with the current or specified window. -In no-delay mode, -if no input is waiting, the value \fBERR\fP is returned. -In delay mode, -the program waits until the system passes text through to the program. -Depending on the setting of \fBcbreak\fP, -this is after one character (cbreak mode), -or after the first newline (nocbreak mode). -In half-delay mode, -the program waits until the user types a character or the specified -timeout interval has elapsed. +.SS "Reading Characters" +.B \%wget_wch +gathers a key stroke +.I wch +from the terminal keyboard associated with a +.I curses +window +.IR win , +returning +.B OK +if a wide character is read, +.B \%KEY_CODE_YES +if a function key is read, +and +.B ERR +if no key event is available. +\fB\%ncurses\fP(3NCURSES) describes the variants of this function. .PP -Unless \fBnoecho\fP has been set, -these routines echo the character into the designated window. +When input is pending, +.B \%wget_wch +stores an integer +identifying the key stroke in +.IR wch ; +for alphanumeric and punctuation keys, +this value corresponds to the character encoding used by the terminal. +Use of the control key as a modifier often results in a distinct code. +The behavior of other keys depends on whether +.I win +is in keypad mode; +see subsections \*(``Keypad Mode\*('' and \*(``Predefined Key Codes\*('' +in \fB\%getch\fP(3NCURSES). .PP -If the window is not a pad and has been moved or modified since the -last call to \fBwrefresh\fP, -\fBwrefresh\fP will be called before another character is read. +If no input is pending, +then if the no-delay flag is set in the window +(see \fB\%nodelay\fP(3NCURSES)), +the function returns +.BR ERR ; +otherwise, +.I curses +waits until the terminal has input. +If \fB\%cbreak\fP(3NCURSES) +has been called, +this happens after one character is read. +If \fB\%nocbreak\fP(3NCURSES) +has been called, +it occurs when the next newline is read. +If \fB\%halfdelay\fP(3NCURSES) +has been called, +.I curses +waits until a character is typed or the specified delay elapses. .PP -If \fBkeypad\fP is enabled, -these functions respond to -the pressing of a function key by setting the object pointed to by -\fIwch\fP -to the keycode assigned to the function key, -and returning \fBKEY_CODE_YES\fP. -If a character (such as escape) that could be the -beginning of a function key is received, curses sets a timer. -If the remainder -of the sequence does arrive within the designated time, curses passes through -the character; otherwise, curses returns the function key value. -For this -reason, many terminals experience a delay between the time a user presses -the escape key and the time the escape is returned to the program. -.PP -The keycodes returned by these functions are the same as those -returned by \fBwgetch\fP: +If \fB\%echo\fP(3NCURSES) has been called, +and the window is not a pad, +.I curses +writes +.I wch +to the window +(at the cursor position) +per the following rules. +.bP +If +.I wch +matches the terminal's erase character, +the cursor moves leftward one position +and the new position is erased +as if \fB\%wmove\fP(3NCURSES) and then \fB\%wdelch\fP(3NCURSES) were called. +When the window's keypad mode is enabled +(see below), +.B \%KEY_LEFT +and +.B \%KEY_BACKSPACE +are handled the same way. .bP -The predefined function -keys are listed in \fB<curses.h>\fP as macros with values outside the range -of 8-bit characters. -Their names begin with \fBKEY_\fP. +.I curses +writes any other +.I wch +to the window, +as with \fB\%wecho_wchar\fP(3NCURSES). .bP -Other (user-defined) function keys -which may be defined using \fB\%define_key\fP(3NCURSES) have no names, -but also are expected to have values outside the range of 8-bit characters. -.SS unget_wch -The -\fBunget_wch\fP -function pushes the wide character -\fIwch\fP -back onto the head of the input queue, so the wide character -is returned by the next call to -\fBget_wch\fP. -The pushback of -one character is guaranteed. -If the program calls -\fBunget_wch\fP -too many times without an intervening call to -\fBget_wch\fP, -the operation may fail. +If the window has been moved or modified since the last call to +\fB\%wrefresh\fP(3NCURSES), +.I curses +calls +.BR \%wrefresh . .PP -Unlike \fBungetch\fP and \fBwgetch\fP, -\fBunget_wch\fP cannot distinguish special characters -returned by \fBwget_wch\fP from ordinary characters. -An application can push special keys -which it may read via \fBwget_wch\fP -by checking for the \fBKEY_CODE_YES\fP result, -and using \fBungetch\fP for those special keys. +If +.I wch +is a carriage return and \fB\%nl\fP(3NCURSES) has been called, +.B \%wgetch +stores the the character code for newline +(line feed) +in +.I wch +instead. +.SS "Ungetting Characters" +.B \%unget_wch +places +.I wch +into the input queue to be returned by the next call to +.BR \%wget_wch . +A single input queue serves all windows. .SH RETURN VALUE -When -\fBget_wch\fP, -\fBwget_wch\fP, -\fBmvget_wch\fP, and -\fBmvwget_wch\fP -functions successfully -report the pressing of a function key, they return -\fBKEY_CODE_YES\fP. -When they successfully report a wide character, they return -\fBOK\fP. -Otherwise, they return -\fBERR\fP. -.PP -Upon successful completion, -\fBunget_wch\fP +.B \%wget_wch returns -\fBOK\fP. -Otherwise, the function returns -\fBERR\fP. +.B OK +when it reads a wide character and +.B \%KEY_CODE_YES +when it reads a function key code. +It returns +.B ERR +if +.bP +the +.I \%WINDOW +pointer is +.BR NULL , +or +.bP +its timeout expires without any data arriving, +or +.bP +execution was interrupted by a signal, +in which case +.B \%errno +is set to +.BR \%EINTR . .PP -Functions with a \*(``mv\*('' prefix first perform a cursor movement using -\fBwmove\fP, and return an error if the position is outside the window, -or if the window pointer is null. -.SH NOTES -Applications should not define the escape key by itself as a single-character -function. +Functions prefixed with \*(``mv\*('' first perform cursor movement and +fail if the position +.RI ( y , +.IR x ) +is outside the window boundaries. .PP -When using -\fBget_wch\fP, -\fBwget_wch\fP, -\fBmvget_wch\fP, or -\fBmvwget_wch\fP, applications should -not use -\fBnocbreak\fP -mode and -\fBecho\fP -mode -at the same time. -Depending on the state of the tty driver when each character -is typed, the program may produce undesirable results. +.B \%unget_wch +returns +.B OK +on success and +.B ERR +if there is no more room in the input queue. +.SH NOTES +See the \*(``NOTES\*('' section of \fB\%wgetch\fP(3NCURSES). .PP All of these functions except -\fB\%wget_wch\fP and -\fB\%unget_wch\fP +.B \%wget_wch +and +.B \%unget_wch may be implemented as macros. +.PP +Unlike \fB\%wgetch\fP(3NCURSES), +.B \%wget_wch +and its variants store the value of the input character in an additional +.I wch +parameter instead of the return value. +.PP +Unlike +.BR \%ungetch , +.B \%unget_wch +cannot distinguish function key codes +.B \%wget_wch +from conventional character codes. +An application can overcome this limitation by pushing function key +codes with +.B \%ungetch +and subsequently checking the return value of +.B \%wget_wch +for a match with +.BR \%KEY_CODE_YES . +.SH EXTENSIONS +See the \*(``EXTENSIONS\*('' section of \fB\%wgetch\fP(3NCURSES). .SH PORTABILITY -These functions are described in the XSI Curses standard, Issue 4. +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. +.PP +X/Open Curses, +Issue 4 describes these functions. +It specifies no error conditions for them. +.PP +See the \*(``PORTABILITY\*('' section of \fB\%wgetch\fP(3NCURSES) regarding +the interaction of +.B \%wget_wch +with signal handlers. .SH SEE ALSO +\fB\%getch\fP(3NCURSES) describes comparable functions of the +.I \%ncurses +library in its non-wide-character configuration. +.PP \fB\%ncurses\fP(3NCURSES), -\fB\%getch\fP(3NCURSES), +\fB\%add_wch\fP(3NCURSES), \fB\%inopts\fP(3NCURSES), -\fB\%ins_wch\fP(3NCURSES), \fB\%move\fP(3NCURSES), \fB\%refresh\fP(3NCURSES) |