X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_get_wch.3x;h=2dec02e37a76619ac3d97ea8d2752a873014b21c;hb=74433bcf4f6fe40862a28f3c00edaedcd5054b01;hp=fe49849a2ecd613b26f35fd613ce69ac9b3a8cb2;hpb=9bb12d03d854ce72b456e525f0c560f2fa91545d;p=ncurses.git diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x index fe49849a..2dec02e3 100644 --- a/man/curs_get_wch.3x +++ b/man/curs_get_wch.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * +.\" Copyright 2002-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,63 +27,71 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_get_wch.3x,v 1.7 2010/08/14 23:31:42 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 +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.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 \fR +\fB#include \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 -.br -\fBint unget_wch(const wchar_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 \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 -to the corresponding -\fBKEY_\fR -value defined -in -\fB\fR -and returning -\fBKEY_CODE_YES\fR. +\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 @@ -92,74 +101,94 @@ 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: +.bP +The predefined function +keys are listed in \fB\fP as macros with values outside the range +of 8-bit characters. +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, +\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. .SH NOTES The header file -\fB\fR +\fB\fP automatically includes the header file -\fB\fR. +\fB\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 VALUES +.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 +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)