From 029256e6fc6c76aa4b7c4e0b6e20187df5836a6b Mon Sep 17 00:00:00 2001 From: nick black Date: Wed, 1 Jan 2020 22:39:16 -0500 Subject: [PATCH] notcurses-input docs --- doc/man/man3/notcurses_input.3.md | 79 ++++++++++++++++++++++++++++++- 1 file changed, 78 insertions(+), 1 deletion(-) diff --git a/doc/man/man3/notcurses_input.3.md b/doc/man/man3/notcurses_input.3.md index 1864ab8bd..e60df0b93 100644 --- a/doc/man/man3/notcurses_input.3.md +++ b/doc/man/man3/notcurses_input.3.md @@ -35,9 +35,86 @@ typedef struct ncinput { # DESCRIPTION +notcurses supports input from keyboards and mice, and any device that looks +like them. Mouse support requires a broker such as GPM, Wayland, or Xorg, and +must be explicitly enabled via **notcurses_mouse_enable(3)**. The full 32-bit +range of Unicode is supported (see **unicode(7)**), with synthesized events +mapped into the [Supplementary Private Use Area-B](https://unicode.org/charts/PDF/U100000.pdf). +Unicode characters are returned directly as UCS-32, one codepoint at a time. + +notcurses takes its keyboard input from **stdin**, which will be placed into +non-blocking mode for the duration of operation. The terminal is put into raw +mode (see **cfmakeraw(3)**), and thus keys are received without line-buffering. +notcurses maintains its own buffer of input characters, which it will attempt +to fill whenever it reads. + +**notcurses_getc(3)** allows a **struct timespec** to be specified as a timeout. +If **ts** is **NULL**, **notcurses_getc(3)** will block until it reads input, or +is interrupted by a signal. If its values are zeroes, there will be no blocking. +Otherwise, **ts** specifies a minimum time to wait for input before giving up. +On timeout, 0 is returned. Signals in **sigmask** will be masked and blocked in +the same manner as a call to **ppoll(2)**. **sigmask** may be **NULL**. Event +details will be reported in **ni**, unless **ni** is NULL. + +## Mice + +For mouse events, the additional fields **y** and **x** are set. These fields +are not meaningful for keypress events. Mouse events can be distinguished using +the **nckey_mouse_p(3)** predicate. Once enabled, mouse button presses are +detected, as are mouse motions made while a button is held down. If no button +is depressed, mouse movement _does not result in events_. This is known as +"button-event tracking" mode in the nomenclature of [Xterm Control +Sequences](https://www.xfree86.org/current/ctlseqs.html). + +## Synthesized keypresses + +Many keys do not have a Unicode representation, let alone ASCII. Examples +include the modifier keys (Alt, Meta, etc.), the "function" keys, and the arrow +keys on the numeric keypad. The special keys available to the terminal are +defined in the **terminfo(5)** entry, which notcurses loads on startup. Upon +receiving an escape code matching a terminfo input capability, notcurses +synthesizes a special value. An escape sequence must arrive in its entirety to +notcurses; running out of input in the middle of an escape sequence will see it +rejected. Likewise, any error while handling an escape sequence will see the +lex aborted, and the sequence thus far played back as independent literal +keystrokes. + +The full list of synthesized keys (there are well over one hundred) can be +found in ****. For more details, consult **terminfo(5)**. + +## **NCKEY_RESIZE** + +Unless the **SIGWINCH** handler has been inhibited (see **notcurses_init(3)**), +notcurses will automatically catch screen resizes, and synthesize an +**NCKEY_RESIZE** event. Upon receiving this event, the user may call +**notcurses_resize(3)** to force an immediate reflow, or just wait until the +next call to **notcurses_render(3)**, when notcurses will pick up the resize +itself. If the **SIGWINCH** handler is inhibited, **NCKEY_RESIZE** is never +generated. # RETURN VALUES +On error, the **_getc** family of functions returns **(char32_t)-1**. The cause of the error may be determined +using **errno(3)**. Unless the error was a temporary one (especially e.g. **EINTR**), +**notcurses_getc(3)** probably cannot be usefully called forthwith. On a +timeout, 0 is returned. Otherwise, the UCS-32 value of a Unicode codepoint, or +a synthesized event, is returned. + +**notcurses_mouse_enable(3)** returns 0 on success, and non-zero on failure, as +does **notcurses_mouse_disable(3)**. + +# NOTES + +Like any other notcurses function, it is an error to call **notcurses_getc(3)** +during or after a call to **notcurses_stop(3)**. If a thread is always sitting +on blocking input, it can be tricky to guarantee that this doesn't happen. + +# BUGS + +Failed escape sequences are not yet played back in their entirety; only an +ESC (ASCII 0x1b) will be seen by the application. + # SEE ALSO -**notcurses(3)**, **poll(2)**, **unicode(7)** +**notcurses(3)**, **poll(2)**, **unicode(7)**, **cfmakeraw(3)**, **terminfo(5)**, +**ascii(7)**, **signal(7)**, **termios(3)**