X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=man%2Fcurs_get_wch.3x;h=8a31a90aa264a7b02ccfd1ac2061c4dbbe59fb30;hb=6cd4a712ad4ac58bf801e5dc66648338d2aa294e;hp=dd2b4c32e82c5fa19b1a3d52be97ac6fb2a9fcf4;hpb=17c5992a16be94247b83f2bbb9accdd9b7e7bb72;p=ncurses.git diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x index dd2b4c32..8a31a90a 100644 --- a/man/curs_get_wch.3x +++ b/man/curs_get_wch.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2017,2018 Free Software Foundation, Inc. * +.\" Copyright 2018-2021,2022 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,66 +27,71 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_get_wch.3x,v 1.11 2018/07/28 22:20:54 tom Exp $ +.\" $Id: curs_get_wch.3x,v 1.17 2022/02/12 20:07:29 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 *\fIwch\fB);\fR .br -\fBint wget_wch(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR +\fBint wget_wch(WINDOW *\fIwin\fB, wint_t *\fIwch\fB);\fR .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 \fIy\fB, int \fIx\fB, wint_t *\fIwch\fB);\fR .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 *\fIwin\fB, int \fIy\fB, int \fIx\fB, wint_t *\fIwch\fB);\fR +.sp +\fBint unget_wch(const wchar_t \fIwch\fB);\fR .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 @@ -99,82 +105,90 @@ The keycodes returned by these functions are the same as those returned by \fBwgetch\fP: .bP The predefined function -keys are listed in \fB\fR as macros with values outside the range +keys are listed in \fB\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. -.PP +.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 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)