X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_get_wch.3x;h=7f73ff2ce000fc7f6e3f868480cd316536baf3fb;hb=64845eab0d05cd928ed2455d5bc5b58e0b33c893;hp=dfa5c7e914dea5778edd784d40c2acdb241c1bde;hpb=e5d1530ca229aef94a3c84ad33f8ae89f35c4045;p=ncurses.git diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x index dfa5c7e9..7f73ff2c 100644 --- a/man/curs_get_wch.3x +++ b/man/curs_get_wch.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2022,2023 Thomas E. Dickey * .\" Copyright 2002-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,70 +27,74 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_get_wch.3x,v 1.14 2020/10/17 23:17:05 tom Exp $ -.TH curs_get_wch 3X "" -.na -.hy 0 -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' +.\" $Id: curs_get_wch.3x,v 1.26 2023/10/07 21:19:07 tom Exp $ +.TH curs_get_wch 3X 2023-10-07 "ncurses 6.4" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.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 -.ad -.hy +\fB\%get_wch\fP, +\fB\%wget_wch\fP, +\fB\%mvget_wch\fP, +\fB\%mvwget_wch\fP, +\fB\%unget_wch\fP \- +get (or push back) a wide character from \fIcurses\fR terminal keyboard .SH SYNOPSIS -\fB#include \fR -.sp -\fBint get_wch(wint_t *\fR\fIwch\fR\fB);\fR -.br -\fBint wget_wch(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR -.br -\fBint mvget_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\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 -.sp -\fBint unget_wch(const wchar_t \fR\fIwch\fR\fB);\fR +.nf +\fB#include +.PP +\fBint get_wch(wint_t *\fIwch\fP); +\fBint wget_wch(WINDOW *\fIwin\fP, wint_t *\fIwch\fP); +\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); +.fi .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 @@ -104,82 +108,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 \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) +\fB\%curses\fP(3X), +\fB\%curs_getch\fP(3X), +\fB\%curs_ins_wch\fP(3X), +\fB\%curs_inopts\fP(3X), +\fB\%curs_move\fP(3X), +\fB\%curs_refresh\fP(3X)