[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 11/17] man/curs_getch.3x: Revise (3/8).
From: |
G. Branden Robinson |
Subject: |
[PATCH 11/17] man/curs_getch.3x: Revise (3/8). |
Date: |
Wed, 13 Mar 2024 13:11:15 -0500 |
Revise discussion of ungetting characters and predefined key codes.
Content:
* Throw more light on why there are key codes for keycaps the reader has
likely never heard of.
Style:
* Recast.
* Drop angle bracket notation from "inline" header file names, set them
in italics instead of bold, and protect them from automatic
hyphenation.
* Revise table of keycodes.
- Convert from slash as a tab character (which we can usefully employ
in table entries) to literal tabs.
- Refactor table format specification: use column modifiers to set
heading rows in bold instead of populating every entry in them with
font selection escape sequences. Use 'x' column modifier to let the
lengthy "Key name" column stretch to fit the page.
- Use row spanning to present the arrow keys. Consequently drop
poorly typeset ellipsis.
- Recast descriptions of keys, favoring words over abbreviations.
- Group all the codes for shifted keys together. Place them under a
single rule. Consequently promote the single rule under the column
headings to a double one (only visible as such on typesetters).
* Revise table depicting directional keypad.
- Convert from slash as a tab character (which we can usefully employ
in table entries) to literal tabs.
- Center the table.
- Stop boldfacing every entry in the table. When everything is
emphasized, nothing is emphasized.
* Replace colon dangling at the ends of sentences with a period. The
subsequent use of bulleted paragraphs makes the structure clear.
* Favor active voice over passive.
Markup:
* Define `^` *roff string to (portably and reliably) render an ASCII
caret (0x5E).
* Favor man(7) font style macros over *roff font selection escape
sequences, except for man page cross references (because
man/make_sed.sh recognizes only certain patterns when rewriting such
cross references).
* Annotate potential future relocation of material (key code list).
---
man/curs_getch.3x | 280 +++++++++++++++++++++++++---------------------
1 file changed, 153 insertions(+), 127 deletions(-)
diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index 764538c63..54ab34ac6 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -240,154 +240,180 @@ .SS "Keypad Mode"
further typing \*(``awakens\*(''
.I curses.
.SS "Ungetting Characters"
-The \fBungetch\fP routine places \fIch\fP back onto the input queue to be
-returned by the next call to \fBwgetch\fP.
-There is just one input queue for all windows.
+.B \%ungetch
+places
+.I ch
+into the input queue to be returned by the next call to
+.BR \%wgetch .
+A single input queue serves all windows.
.SS "Predefined Key Codes"
-The following special keys are defined in \fB<curses.h>\fP.
+The header file
+.I \%curses.h
+defines the following function key codes.
.bP
-Except for the special case \fBKEY_RESIZE\fP,
-it is necessary to enable \fBkeypad\fP for \fBgetch\fP to return these codes.
+Except for the special case of
+.BR \%KEY_RESIZE ,
+a window's keypad mode must be enabled for
+.B \%wgetch
+to read these codes from it.
.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.
+The naming convention may seem obscure,
+with some apparent misspellings
+(such as \*(``RSUME\*('' for \*(``resume\*('');
+The names correspond to the
+.I \%term\%info
+capability names for the keys,
+and were standardized before the IBM PC/AT keyboard layout achieved a
+dominant position in industry.
.PP
.RS
+.\" XXX: Move this list into ncurses(3X), rather than duplicating it in
+.\" get_wch(3X) or having that page cross reference this one?
.TS
-tab(/) ;
-l l .
-\fBName\fP/\fBKey\fP \fBname\fP
-_
-KEY_BREAK/Break key
-KEY_DOWN/The four arrow keys ...
-KEY_UP
-KEY_LEFT
-KEY_RIGHT
-KEY_HOME/Home key (upward+left arrow)
-KEY_BACKSPACE/Backspace
-KEY_F0/T{
-Function keys; space for 64 keys is reserved.
+Lb Lb
+Lb Lx.
+Symbol Key name
+=
+KEY_BREAK Break key
+KEY_DOWN Arrow keys
+KEY_UP \^
+KEY_LEFT \^
+KEY_RIGHT \^
+KEY_HOME Home key (upward+left arrow)
+KEY_BACKSPACE Backspace
+KEY_F0 T{
+Function keys; space for 64 keys is reserved
T}
-KEY_F(\fIn\fP)/T{
-For 0 \(<= \fIn\fP \(<= 63
+KEY_F(\fIn\fP) T{
+Function key \fIn\fP where 0 \(<= \fIn\fP \(<= 63
T}
-KEY_DL/Delete line
-KEY_IL/Insert line
-KEY_DC/Delete character
-KEY_IC/Insert char or enter insert mode
-KEY_EIC/Exit insert char mode
-KEY_CLEAR/Clear screen
-KEY_EOS/Clear to end of screen
-KEY_EOL/Clear to end of line
-KEY_SF/Scroll 1 line forward
-KEY_SR/Scroll 1 line backward (reverse)
-KEY_NPAGE/Next page
-KEY_PPAGE/Previous page
-KEY_STAB/Set tab
-KEY_CTAB/Clear tab
-KEY_CATAB/Clear all tabs
-KEY_ENTER/Enter or send
-KEY_SRESET/Soft (partial) reset
-KEY_RESET/Reset or hard reset
-KEY_PRINT/Print or copy
-KEY_LL/Home down or bottom (lower left)
-KEY_A1/Upper left of keypad
-KEY_A3/Upper right of keypad
-KEY_B2/Center of keypad
-KEY_C1/Lower left of keypad
-KEY_C3/Lower right of keypad
-KEY_BTAB/Back tab key
-KEY_BEG/Beg(inning) key
-KEY_CANCEL/Cancel key
-KEY_CLOSE/Close key
-KEY_COMMAND/Cmd (command) key
-KEY_COPY/Copy key
-KEY_CREATE/Create key
-KEY_END/End key
-KEY_EXIT/Exit key
-KEY_FIND/Find key
-KEY_HELP/Help key
-KEY_MARK/Mark key
-KEY_MESSAGE/Message key
-KEY_MOUSE/Mouse event occurred
-KEY_MOVE/Move key
-KEY_NEXT/Next object key
-KEY_OPEN/Open key
-KEY_OPTIONS/Options key
-KEY_PREVIOUS/Previous object key
-KEY_REDO/Redo key
-KEY_REFERENCE/Ref(erence) key
-KEY_REFRESH/Refresh key
-KEY_REPLACE/Replace key
-KEY_RESIZE/Screen resized
-KEY_RESTART/Restart key
-KEY_RESUME/Resume key
-KEY_SAVE/Save key
-KEY_SBEG/Shifted beginning key
-KEY_SCANCEL/Shifted cancel key
-KEY_SCOMMAND/Shifted command key
-KEY_SCOPY/Shifted copy key
-KEY_SCREATE/Shifted create key
-KEY_SDC/Shifted delete char key
-KEY_SDL/Shifted delete line key
-KEY_SELECT/Select key
-KEY_SEND/Shifted end key
-KEY_SEOL/Shifted clear line key
-KEY_SEXIT/Shifted exit key
-KEY_SFIND/Shifted find key
-KEY_SHELP/Shifted help key
-KEY_SHOME/Shifted home key
-KEY_SIC/Shifted insert key
-KEY_SLEFT/Shifted left arrow key
-KEY_SMESSAGE/Shifted message key
-KEY_SMOVE/Shifted move key
-KEY_SNEXT/Shifted next key
-KEY_SOPTIONS/Shifted options key
-KEY_SPREVIOUS/Shifted prev key
-KEY_SPRINT/Shifted print key
-KEY_SREDO/Shifted redo key
-KEY_SREPLACE/Shifted replace key
-KEY_SRIGHT/Shifted right arrow key
-KEY_SRSUME/Shifted resume key
-KEY_SSAVE/Shifted save key
-KEY_SSUSPEND/Shifted suspend key
-KEY_SUNDO/Shifted undo key
-KEY_SUSPEND/Suspend key
-KEY_UNDO/Undo key
+KEY_DL Delete line
+KEY_IL Insert line
+KEY_DC Delete character
+KEY_IC Insert character/Enter insert mode
+KEY_EIC Exit insert character mode
+KEY_CLEAR Clear screen
+KEY_EOS Clear to end of screen
+KEY_EOL Clear to end of line
+KEY_SF Scroll one line forward
+KEY_SR Scroll one line backward (reverse)
+KEY_NPAGE Next page/Page up
+KEY_PPAGE Previous page/Page down
+KEY_STAB Set tab
+KEY_CTAB Clear tab
+KEY_CATAB Clear all tabs
+KEY_ENTER Enter/Send
+KEY_SRESET Soft (partial) reset
+KEY_RESET (Hard) reset
+KEY_PRINT Print/Copy
+KEY_LL Home down/Bottom (lower left)
+KEY_A1 Upper left of keypad
+KEY_A3 Upper right of keypad
+KEY_B2 Center of keypad
+KEY_C1 Lower left of keypad
+KEY_C3 Lower right of keypad
+KEY_BTAB Back tab key
+KEY_BEG Beg(inning) key
+KEY_CANCEL Cancel key
+KEY_CLOSE Close key
+KEY_COMMAND Cmd (command) key
+KEY_COPY Copy key
+KEY_CREATE Create key
+KEY_END End key
+KEY_EXIT Exit key
+KEY_FIND Find key
+KEY_HELP Help key
+KEY_MARK Mark key
+KEY_MESSAGE Message key
+KEY_MOUSE Mouse event occurred
+KEY_MOVE Move key
+KEY_NEXT Next object key
+KEY_OPEN Open key
+KEY_OPTIONS Options key
+KEY_PREVIOUS Previous object key
+KEY_REDO Redo key
+KEY_REFERENCE Ref(erence) key
+KEY_REFRESH Refresh key
+KEY_REPLACE Replace key
+KEY_RESIZE Screen resized
+KEY_RESTART Restart key
+KEY_RESUME Resume key
+KEY_SAVE Save key
+KEY_SELECT Select key
+KEY_SUSPEND Suspend key
+KEY_UNDO Undo key
+_
+KEY_SBEG Shifted beginning key
+KEY_SCANCEL Shifted cancel key
+KEY_SCOMMAND Shifted command key
+KEY_SCOPY Shifted copy key
+KEY_SCREATE Shifted create key
+KEY_SDC Shifted delete character key
+KEY_SDL Shifted delete line key
+KEY_SEND Shifted end key
+KEY_SEOL Shifted clear line key
+KEY_SEXIT Shifted exit key
+KEY_SFIND Shifted find key
+KEY_SHELP Shifted help key
+KEY_SHOME Shifted home key
+KEY_SIC Shifted insert key
+KEY_SLEFT Shifted left arrow key
+KEY_SMESSAGE Shifted message key
+KEY_SMOVE Shifted move key
+KEY_SNEXT Shifted next object key
+KEY_SOPTIONS Shifted options key
+KEY_SPREVIOUS Shifted previous object key
+KEY_SPRINT Shifted print key
+KEY_SREDO Shifted redo key
+KEY_SREPLACE Shifted replace key
+KEY_SRIGHT Shifted right arrow key
+KEY_SRSUME Shifted resume key
+KEY_SSAVE Shifted save key
+KEY_SSUSPEND Shifted suspend key
+KEY_SUNDO Shifted undo key
.TE
.RE
.PP
-Keypad is arranged like this:
+The keypad is arranged as follows.
.PP
.RS
.TS
-allbox tab(/) ;
-c c c .
-\fBA1\fP/\fBup\fP/\fBA3\fP
-\fBleft\fP/\fBB2\fP/\fBright\fP
-\fBC1\fP/\fBdown\fP/\fBC3\fP
+allbox center;
+C C C.
+A1 up A3
+left B2 right
+C1 down C3
.TE
.RE
.sp
-A few of these predefined values do \fInot\fP correspond to a real key:
+Two of these symbols do
+.I not
+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\fP(3X)).
-This code is returned whether or not \fBkeypad\fP has been enabled.
+.B \%wgetch
+returns
+.B \%KEY_RESIZE
+(even if the window's keypad mode is disabled)
+when
+.I \%ncurses
+detects the
+.B \%SIGWINCH
+signal;
+see \fBinitscr\fP(3X) and \fBresizeterm\fP(3X).
.bP
-.B KEY_MOUSE
-is returned for mouse-events (see \fBcurs_mouse\fP(3X)).
-This code relies upon whether or not \fBkeypad\fP(3X) has been enabled,
-because
-(e.g.,
-with \fBxterm\fP(1) mouse prototocol)
-\fI\%ncurses\fP must read escape sequences,
-just like a function key.
+.B \%wgetch
+returns
+.B \%KEY_MOUSE
+to indicate that a mouse event is pending collection;
+see \fBcurs_mouse\fP(3X).
+Receipt of this code requires a window's keypad mode to be enabled,
+because to interpret mouse input
+(as with with \fIxterm\fP(1)'s mouse prototocol),
+.I \%ncurses
+must read an escape sequence,
+as with a function key.
.SS "Testing Key Codes"
The \fBhas_key\fP routine takes a key-code value from the above list, and
returns \fBTRUE\fP or \fBFALSE\fP according to whether
--
2.30.2
signature.asc
Description: PGP signature
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [PATCH 11/17] man/curs_getch.3x: Revise (3/8).,
G. Branden Robinson <=