.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_get_wch.3x,v 1.15 2021/05/22 22:33:19 tom Exp $
+.\" $Id: curs_get_wch.3x,v 1.16 2021/12/25 17:39:16 tom Exp $
.TH curs_get_wch 3X ""
.na
.hy 0
.el .IP \(bu 2
..
.SH NAME
-\fBget_wch\fR,
-\fBwget_wch\fR,
-\fBmvget_wch\fR,
-\fBmvwget_wch\fR,
-\fBunget_wch\fR \- get (or push back) a wide character from curses terminal keyboard
+\fBget_wch\fP,
+\fBwget_wch\fP,
+\fBmvget_wch\fP,
+\fBmvwget_wch\fP,
+\fBunget_wch\fP \- get (or push back) a wide character from curses terminal keyboard
.ad
.hy
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+\fB#include <curses.h>\fP
.sp
-\fBint get_wch(wint_t *\fR\fIwch\fR\fB);\fR
+\fBint get_wch(wint_t *\fP\fIwch\fP\fB);\fP
.br
-\fBint wget_wch(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR
+\fBint wget_wch(WINDOW *\fP\fIwin\fP\fB, wint_t *\fP\fIwch\fP\fB);\fP
.br
-\fBint mvget_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR
+\fBint mvget_wch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, wint_t *\fP\fIwch\fP\fB);\fP
.br
-\fBint mvwget_wch(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR
+\fBint mvwget_wch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, wint_t *\fP\fIwch\fP\fB);\fP
.sp
-\fBint unget_wch(const wchar_t \fR\fIwch\fR\fB);\fR
+\fBint unget_wch(const wchar_t \fP\fIwch\fP\fB);\fP
.SH DESCRIPTION
.SS wget_wch
The
-\fBget_wch\fR,
-\fBwget_wch\fR,
-\fBmvget_wch\fR, and
-\fBmvwget_wch\fR
+\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\fR is returned.
+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\fR,
+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.
.PP
-Unless \fBnoecho\fR has been set,
+Unless \fBnoecho\fP has been set,
these routines echo the character into the designated window.
.PP
If the window is not a pad and has been moved or modified since the
-last call to \fBwrefresh\fR,
-\fBwrefresh\fR will be called before another character is read.
+last call to \fBwrefresh\fP,
+\fBwrefresh\fP will be called before another character is read.
.PP
-If \fBkeypad\fR is enabled,
+If \fBkeypad\fP is enabled,
these functions respond to
the pressing of a function key by setting the object pointed to by
-\fIwch\fR
+\fIwch\fP
to the keycode assigned to the function key,
-and returning \fBKEY_CODE_YES\fR.
+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
returned by \fBwgetch\fP:
.bP
The predefined function
-keys are listed in \fB<curses.h>\fR as macros with values outside the range
+keys are listed in \fB<curses.h>\fP as macros with values outside the range
of 8-bit characters.
-Their names begin with \fBKEY_\fR.
+Their names begin with \fBKEY_\fP.
.bP
Other (user-defined) function keys
which may be defined using \fBdefine_key\fP(3X) have no names,
but also are expected to have values outside the range of 8-bit characters.
.SS unget_wch
The
-\fBunget_wch\fR
+\fBunget_wch\fP
function pushes the wide character
-\fIwch\fR
+\fIwch\fP
back onto the head of the input queue, so the wide character
is returned by the next call to
-\fBget_wch\fR.
+\fBget_wch\fP.
The pushback of
one character is guaranteed.
If the program calls
-\fBunget_wch\fR
+\fBunget_wch\fP
too many times without an intervening call to
-\fBget_wch\fR,
+\fBget_wch\fP,
the operation may fail.
.PP
Unlike \fBungetch\fP and \fBwgetch\fP,
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\fR result,
+by checking for the \fBKEY_CODE_YES\fP result,
and using \fBungetch\fP for those special keys.
.SH NOTES
The header file
-\fB<curses.h>\fR
+\fB<curses.h>\fP
automatically
includes the header file
-\fB<stdio.h>\fR.
+\fB<stdio.h>\fP.
.PP
Applications should not define the escape key by itself as a single-character
function.
.PP
When using
-\fBget_wch\fR,
-\fBwget_wch\fR,
-\fBmvget_wch\fR, or
-\fBmvwget_wch\fR, applications should
+\fBget_wch\fP,
+\fBwget_wch\fP,
+\fBmvget_wch\fP, or
+\fBmvwget_wch\fP, applications should
not use
-\fBnocbreak\fR
+\fBnocbreak\fP
mode and
-\fBecho\fR
+\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.
.PP
-All functions except \fBwget_wch\fR and \fBunget_wch\fR
+All functions except \fBwget_wch\fP and \fBunget_wch\fP
may be macros.
.SH RETURN VALUE
When
-\fBget_wch\fR,
-\fBwget_wch\fR,
-\fBmvget_wch\fR, and
-\fBmvwget_wch\fR
+\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\fR.
+\fBKEY_CODE_YES\fP.
When they successfully report a wide character, they return
-\fBOK\fR.
+\fBOK\fP.
Otherwise, they return
-\fBERR\fR.
+\fBERR\fP.
.PP
Upon successful completion,
-\fBunget_wch\fR
+\fBunget_wch\fP
returns
-\fBOK\fR.
+\fBOK\fP.
Otherwise, the function returns
-\fBERR\fR.
+\fBERR\fP.
.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 SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_getch\fR(3X),
-\fBcurs_ins_wch\fR(3X),
-\fBcurs_inopts\fR(3X),
-\fBcurs_move\fR(3X),
-\fBcurs_refresh\fR(3X)
+\fBcurses\fP(3X),
+\fBcurs_getch\fP(3X),
+\fBcurs_ins_wch\fP(3X),
+\fBcurs_inopts\fP(3X),
+\fBcurs_move\fP(3X),
+\fBcurs_refresh\fP(3X)
projects / ncurses.git / blobdiff