diff options
Diffstat (limited to 'doc/html/man/curs_get_wch.3x.html')
| -rw-r--r-- | doc/html/man/curs_get_wch.3x.html | 184 |
1 files changed, 108 insertions, 76 deletions
diff --git a/doc/html/man/curs_get_wch.3x.html b/doc/html/man/curs_get_wch.3x.html index ad6619f2d77e..291ef67f1c0a 100644 --- a/doc/html/man/curs_get_wch.3x.html +++ b/doc/html/man/curs_get_wch.3x.html @@ -1,6 +1,6 @@ -<!-- +<!-- **************************************************************************** - * Copyright 2018-2019,2020 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,28 +27,28 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_get_wch.3x,v 1.14 2020/10/17 23:17:05 tom Exp @ + * @Id: curs_get_wch.3x,v 1.40 2024/04/20 19:23:03 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_get_wch 3x</TITLE> +<TITLE>curs_get_wch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + </HEAD> <BODY> -<H1 class="no-header">curs_get_wch 3x</H1> +<H1 class="no-header">curs_get_wch 3x 2024-04-20 ncurses 6.5 Library calls</H1> <PRE> -<STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> +<STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>get_wch</STRONG>, <STRONG>wget_wch</STRONG>, <STRONG>mvget_wch</STRONG>, <STRONG>mvwget_wch</STRONG>, <STRONG>unget_wch</STRONG> - get (or push - back) a wide character from curses terminal keyboard + <STRONG>get_wch</STRONG>, <STRONG>wget_wch</STRONG>, <STRONG>mvget_wch</STRONG>, <STRONG>mvwget_wch</STRONG>, <STRONG>unget_wch</STRONG> - get (or push + back) a wide character from <EM>curses</EM> terminal keyboard </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -59,98 +59,130 @@ <STRONG>int</STRONG> <STRONG>mvget_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>mvwget_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>unget_wch(const</STRONG> <STRONG>wchar_t</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>unget_wch(const</STRONG> <STRONG>wchar_t</STRONG> <EM>wc</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The <STRONG>get_wch</STRONG>, <STRONG>wget_wch</STRONG>, <STRONG>mvget_wch</STRONG>, and <STRONG>mvwget_wch</STRONG> functions read a char- - acter from the terminal associated with the current or specified win- - dow. In no-delay mode, if no input is waiting, the value <STRONG>ERR</STRONG> is re- - turned. In delay mode, the program waits until the system passes text - through to the program. Depending on the setting of <STRONG>cbreak</STRONG>, 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. - - Unless <STRONG>noecho</STRONG> has been set, these routines echo the character into the - designated window. - - If the window is not a pad and has been moved or modified since the - last call to <STRONG>wrefresh</STRONG>, <STRONG>wrefresh</STRONG> will be called before another character - is read. - - If <STRONG>keypad</STRONG> is enabled, these functions respond to the pressing of a - function key by setting the object pointed to by <EM>wch</EM> to the keycode as- - signed to the function key, and returning <STRONG>KEY_CODE_YES</STRONG>. If a character - (such as escape) that could be the beginning of a function key is re- - ceived, curses sets a timer. If the remainder of the sequence does ar- - rive 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. - - The keycodes returned by these functions are the same as those returned - by <STRONG>wgetch</STRONG>: - - <STRONG>o</STRONG> The predefined function keys are listed in <STRONG><curses.h></STRONG> as macros - with values outside the range of 8-bit characters. Their names be- - gin with <STRONG>KEY_</STRONG>. - - <STRONG>o</STRONG> Other (user-defined) function keys which may be defined using <STRONG>de-</STRONG> - <STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG> have no names, but also are expected to have values - outside the range of 8-bit characters. - - The <STRONG>unget_wch</STRONG> function pushes the wide character <EM>wch</EM> back onto the head - of the input queue, so the wide character is returned by the next call - to <STRONG>get_wch</STRONG>. The pushback of one character is guaranteed. If the pro- - gram calls <STRONG>unget_wch</STRONG> too many times without an intervening call to - <STRONG>get_wch</STRONG>, the operation may fail. +</PRE><H3><a name="h3-Reading-Characters">Reading Characters</a></H3><PRE> + <STRONG>wget_wch</STRONG> gathers a key stroke <EM>wch</EM> from the terminal keyboard associated + with a <EM>curses</EM> window <EM>win</EM>, returning <STRONG>OK</STRONG> if a wide character is read, + <STRONG>KEY_CODE_YES</STRONG> if a function key is read, and <STRONG>ERR</STRONG> if no key event is + available. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function. -</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - The header file <STRONG><curses.h></STRONG> automatically includes the header file - <STRONG><stdio.h></STRONG>. + When input is pending, <STRONG>wget_wch</STRONG> stores an integer identifying the key + stroke in <EM>wch</EM>; 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 <EM>win</EM> is in keypad mode; see + subsections "Keypad Mode" and "Predefined Key Codes" in <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>. + + If no input is pending, then if the no-delay flag is set in the window + (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits + until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this + happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called, + it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been + called, <EM>curses</EM> waits until a character is typed or the specified delay + elapses. + + If <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> has been called, and the window is not a pad, <EM>curses</EM> writes + <EM>wch</EM> to the window (at the cursor position) per the following rules. + + <STRONG>o</STRONG> If <EM>wch</EM> matches the terminal's erase character, the cursor moves + leftward one position and the new position is erased as if + <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. When the window's + keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are + handled the same way. + + <STRONG>o</STRONG> <EM>curses</EM> writes any other <EM>wch</EM> to the window, as with <STRONG><A HREF="curs_add_wch.3x.html">wecho_wchar(3x)</A></STRONG>. + + <STRONG>o</STRONG> If the window has been moved or modified since the last call to + <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG>. - Applications should not define the escape key by itself as a single- - character function. + If <EM>wch</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> stores + the the character code for newline (line feed) in <EM>wch</EM> instead. - When using <STRONG>get_wch</STRONG>, <STRONG>wget_wch</STRONG>, <STRONG>mvget_wch</STRONG>, or <STRONG>mvwget_wch</STRONG>, applications - should not use <STRONG>nocbreak</STRONG> mode and <STRONG>echo</STRONG> mode at the same time. Depending - on the state of the tty driver when each character is typed, the pro- - gram may produce undesirable results. - All functions except <STRONG>wget_wch</STRONG> and <STRONG>unget_wch</STRONG> may be macros. +</PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE> + <STRONG>unget_wch</STRONG> places <EM>wch</EM> into the input queue to be returned by the next + call to <STRONG>wget_wch</STRONG>. A single input queue serves all windows. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - When <STRONG>get_wch</STRONG>, <STRONG>wget_wch</STRONG>, <STRONG>mvget_wch</STRONG>, and <STRONG>mvwget_wch</STRONG> functions successful- - ly report the pressing of a function key, they return <STRONG>KEY_CODE_YES</STRONG>. - When they successfully report a wide character, they return <STRONG>OK</STRONG>. Other- - wise, they return <STRONG>ERR</STRONG>. + <STRONG>wget_wch</STRONG> returns <STRONG>OK</STRONG> when it reads a wide character and <STRONG>KEY_CODE_YES</STRONG> + when it reads a function key code. It returns <STRONG>ERR</STRONG> if - Upon successful completion, <STRONG>unget_wch</STRONG> returns <STRONG>OK</STRONG>. Otherwise, the func- - tion returns <STRONG>ERR</STRONG>. + <STRONG>o</STRONG> the <EM>WINDOW</EM> pointer is <STRONG>NULL</STRONG>, or + + <STRONG>o</STRONG> its timeout expires without any data arriving, or + + <STRONG>o</STRONG> execution was interrupted by a signal, in which case <STRONG>errno</STRONG> is set + to <STRONG>EINTR</STRONG>. + + Functions prefixed with "mv" first perform cursor movement and fail if + the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. + + <STRONG>unget_wch</STRONG> returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> if there is no more room in the + input queue. + + +</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> + See the "NOTES" section of <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>. - Functions with a "mv" prefix first perform a cursor movement using - <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if - the window pointer is null. + All of these functions except <STRONG>wget_wch</STRONG> and <STRONG>unget_wch</STRONG> may be implemented + as macros. + + Unlike <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>, <STRONG>wget_wch</STRONG> and its variants store the value of the + input character in an additional <EM>wch</EM> parameter instead of the return + value. + + Unlike <STRONG>ungetch</STRONG>, <STRONG>unget_wch</STRONG> cannot distinguish function key codes + <STRONG>wget_wch</STRONG> from conventional character codes. An application can + overcome this limitation by pushing function key codes with <STRONG>ungetch</STRONG> and + subsequently checking the return value of <STRONG>wget_wch</STRONG> for a match with + <STRONG>KEY_CODE_YES</STRONG>. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + See the "EXTENSIONS" section of <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>. + + +</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + X/Open Curses, Issue 4 describes these functions. It specifies no + error conditions for them. + + See the "PORTABILITY" section of <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> regarding the interaction + of <STRONG>wget_wch</STRONG> with signal handlers. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, - <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> + <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in + its non-wide-character configuration. + + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, + <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> - <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> +ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> <li><a href="#h2-NAME">NAME</a></li> <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> -<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> -<li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> +<ul> +<li><a href="#h3-Reading-Characters">Reading Characters</a></li> +<li><a href="#h3-Ungetting-Characters">Ungetting Characters</a></li> +</ul> +</li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> +<li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> |