X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_getch.3x;h=1cf9d18ba7bd86066d98b24217d6d7caed5c0cd8;hp=92ab55a0c16789f35fe350b24180ba65a86f7a9e;hb=14d46fadc442db9df4567357cda396235418120e;hpb=0819b56c3096ed77dd36312b0c4e8f37e7d46c88 diff --git a/man/curs_getch.3x b/man/curs_getch.3x index 92ab55a0..1cf9d18b 100644 --- a/man/curs_getch.3x +++ b/man/curs_getch.3x @@ -1,6 +1,7 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. * +.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 1998-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 * @@ -27,12 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getch.3x,v 1.40 2015/04/11 10:23:49 tom Exp $ +.\" $Id: curs_getch.3x,v 1.56 2020/10/17 23:18:32 tom Exp $ .TH curs_getch 3X "" .na .hy 0 +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. .SH NAME \fBgetch\fR, @@ -48,17 +54,20 @@ .PP \fBint getch(void);\fR .br -\fBint wgetch(WINDOW *win);\fR -.br -\fBint mvgetch(int y, int x);\fR -.br -\fBint mvwgetch(WINDOW *win, int y, int x);\fR +\fBint wgetch(WINDOW *\fP\fIwin);\fR +.sp +\fBint mvgetch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br -\fBint ungetch(int ch);\fR +\fBint mvwgetch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR +.sp +\fBint ungetch(int \fP\fIch\fP\fB);\fR +.sp +/* extension */ .br -\fBint has_key(int ch);\fR +\fBint has_key(int \fP\fIch\fP\fB);\fR .br .SH DESCRIPTION +.SS Reading characters The \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR and \fBmvwgetch\fR, routines read a character from the window. In no-delay mode, if no input is waiting, the value \fBERR\fR is returned. @@ -91,12 +100,21 @@ Otherwise the character is simply output to the screen. If the window is not a pad, and it has been moved or modified since the last call to \fBwrefresh\fR, \fBwrefresh\fR will be called before another character is read. +.SS Keypad mode .PP If \fBkeypad\fR is \fBTRUE\fR, and a function key is pressed, the token for -that function key is returned instead of the raw characters. -Possible function -keys are defined in \fB\fR as macros with values outside the range -of 8-bit characters whose names begin with \fBKEY_\fR. +that function key is returned instead of the raw characters: +.bP +The predefined function +keys are listed in \fB\fR as macros with values outside the range +of 8-bit characters. +Their names begin with \fBKEY_\fR. +.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 Thus, a variable intended to hold the return value of a function key must be of short size or larger. @@ -110,15 +128,31 @@ otherwise, the function key value is returned. For this reason, many terminals experience a delay between the time a user presses the escape key and the escape is returned to the program. .PP +In \fBncurses\fP, the timer normally expires after +the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3X)). +If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire; +it is an infinite (or very large) value. +Because function keys usually begin with an escape character, +the terminal may appear to hang in notimeout mode after pressing the escape key +until another key is pressed. +.SS Ungetting characters +.PP The \fBungetch\fR routine places \fIch\fR back onto the input queue to be returned by the next call to \fBwgetch\fR. There is just one input queue for all windows. .PP -.SS Function Keys -The following function keys, defined in \fB\fR, might be returned by -\fBgetch\fR if \fBkeypad\fR has been enabled. -Note that not all of these are -necessarily supported on any particular terminal. +.SS Predefined key-codes +The following special keys are defined in \fB\fR. +.bP +Except for the special case \fBKEY_RESIZE\fP, +it is necessary to enable \fBkeypad\fR for \fBgetch\fP to return these codes. +.bP +Not all of these are necessarily supported on any particular terminal. +.bP +The naming convention may seem obscure, with some apparent +misspellings (such as \*(``RSUME\*('' for \*(``resume\*(''). +The names correspond to the long terminfo capability names for the keys, +and were defined long ago, in the 1980s. .PP .TS center tab(/) ; @@ -224,7 +258,7 @@ KEY_UNDO/Undo key .TE .PP Keypad is arranged like this: -.sp +.br .TS center allbox tab(/) ; c c c . @@ -233,31 +267,55 @@ c c c . \fBC1\fR/\fBdown\fR/\fBC3\fR .TE .sp -The \fBhas_key\fR routine takes a key value from the above list, and +A few of these predefined values do \fInot\fP correspond to a real key: +.bP +.B KEY_RESIZE +is returned when the \fBSIGWINCH\fP signal has been detected +(see \fBinitscr\fP(3X) and \fBresizeterm\fR(3X)). +This code is returned whether or not \fBkeypad\fP has been enabled. +.bP +.B KEY_MOUSE +is returned for mouse-events (see \fBcurs_mouse\fR(3X)). +This code relies upon whether or not \fBkeypad\fP(3X) has been enabled, +because (e.g., with \fIxterm\fP mouse prototocol) ncurses must +read escape sequences, +just like a function key. +.SS Testing key-codes +.PP +The \fBhas_key\fR routine takes a key-code value from the above list, and returns \fBTRUE\fP or \fBFALSE\fP according to whether the current terminal type recognizes a key with that value. -Note that a few values do not correspond to a real key, -e.g., \fBKEY_RESIZE\fP and \fBKEY_MOUSE\fP. -See \fBresizeterm\fR(3X) for more details about \fBKEY_RESIZE\fP, and -\fBcurs_mouse\fR(3X) for a discussion of \fBKEY_MOUSE\fP. +.PP +The library also supports these extensions: +.RS 3 +.TP 5 +.B define_key +defines a key-code for a given string (see \fBdefine_key\fP(3X)). +.TP 5 +.B key_defined +checks if there is a key-code defined for a given +string (see \fBkey_defined\fP(3X)). +.RE .PP .SH RETURN VALUE All routines return the integer \fBERR\fR upon failure and an integer value -other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful +other than \fBERR\fR (\fBOK\fR in the case of \fBungetch\fP) upon successful completion. .RS 3 .TP 5 \fBungetch\fP -returns ERR +returns \fBERR\fP if there is no more room in the FIFO. .TP \fBwgetch\fP -returns ERR +returns \fBERR\fP if the window pointer is null, or -if its timeout expires without having any data. +if its timeout expires without having any data, or +if the execution was interrupted by a signal (\fBerrno\fR will be set to +\fBEINTR\fR). .RE .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 NOTES @@ -265,8 +323,10 @@ Use of the escape key by a programmer for a single character function is discouraged, as it will cause a delay of up to one second while the keypad code looks for a following function-key sequence. .PP -Note that some keys may be the same as commonly used control -keys, e.g., \fBKEY_ENTER\fP versus control/M, \fBKEY_BACKSPACE\fP versus control/H. +Some keys may be the same as commonly used control +keys, e.g., +\fBKEY_ENTER\fP versus control/M, +\fBKEY_BACKSPACE\fP versus control/H. Some curses implementations may differ according to whether they treat these control keys specially (and ignore the terminfo), or use the terminfo definitions. @@ -284,10 +344,10 @@ the \fIEnter\fP key on the regular keyboard is already handled by the standard ASCII characters for carriage-return and line-feed, .bP depending on whether \fBnl\fP or \fBnonl\fP was called, -pressing "Enter" on the regular keyboard may return either a carriage-return -or line-feed, and finally +pressing \*(``Enter\*('' on the regular keyboard +may return either a carriage-return or line-feed, and finally .bP -"Enter or send" is the standard description for this key. +\*(``Enter or send\*('' is the standard description for this key. .PP When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or \fBmvwgetch\fR, nocbreak mode (\fBnocbreak\fR) and echo mode @@ -328,12 +388,17 @@ implementation of handled signal receipt interrupts a \fBread\fR(2) call in progress or not, and also (in some implementations) depending on whether an input timeout or non-blocking mode has been set. .PP +\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related +terminfo capabilities, but no higher-level functions use the feature. +The implementation in ncurses is an extension. +.PP +\fBKEY_RESIZE\fP is an extension first implemented for ncurses. +NetBSD curses later added this extension. +.PP Programmers concerned about portability should be prepared for either of two cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt -interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to +interrupts \fBgetch\fR and causes it to return \fBERR\fP with \fBerrno\fR set to \fBEINTR\fR. -Under the \fBncurses\fR implementation, handled signals never -interrupt \fBgetch\fR. .PP The \fBhas_key\fR function is unique to \fBncurses\fR. We recommend that @@ -345,6 +410,7 @@ any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro. \fBcurs_mouse\fR(3X), \fBcurs_move\fR(3X), \fBcurs_refresh\fR(3X), +\fBcurs_variables\fR(3X), \fBresizeterm\fR(3X). .PP Comparable functions in the wide-character (ncursesw) library are