diff options
| -rw-r--r-- | Makefile | 5 | ||||
| -rw-r--r-- | libterminput.h | 4 | ||||
| -rw-r--r-- | libterminput_set_flags.3 | 131 |
3 files changed, 138 insertions, 2 deletions
@@ -51,11 +51,14 @@ interactive-test: interactive-test.o libterminput.a install: libterminput.a libterminput.$(LIBEXT) mkdir -p -- "$(DESTDIR)$(PREFIX)/lib" mkdir -p -- "$(DESTDIR)$(PREFIX)/include" + mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3" cp -- libterminput.a "$(DESTDIR)$(PREFIX)/lib/" cp -- libterminput.h "$(DESTDIR)$(PREFIX)/include/" cp -- libterminput.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBMINOREXT)" ln -sf -- libterminput.$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBMAJOREXT)" ln -sf -- libterminput.$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBEXT)" + cp -- libterminput_set_flags.3 "$(DESTDIR)$(MANPREFIX)/man3" + ln -sf -- libterminput_set_flags.3 "$(DESTDIR)$(MANPREFIX)/man3/libterminput_clear_flags.3" uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBMAJOREXT)" @@ -63,6 +66,8 @@ uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBEXT)" -rm -rf -- "$(DESTDIR)$(PREFIX)/lib/libterminput.a" -rm -rf -- "$(DESTDIR)$(PREFIX)/include/libterminput.h" + -rm -rf -- "$(DESTDIR)$(MANPREFIX)/man3/libterminput_set_flags.3" + -rm -rf -- "$(DESTDIR)$(MANPREFIX)/man3/libterminput_clear_flags.3" clean: -rm -f -- *.o *.a *.lo *.so *.su *.dll *.dylib interactive-test diff --git a/libterminput.h b/libterminput.h index 8318dff..45ac2a4 100644 --- a/libterminput.h +++ b/libterminput.h @@ -8,7 +8,7 @@ /** * Flags for supporting incompatible input; the user must * set or clear his flag after setting or clearing it on - * the terminal, and the use must make sure that the + * the terminal, and the user must make sure that the * terminal support this flag if set. */ enum libterminput_flags { @@ -21,7 +21,7 @@ enum libterminput_flags { /** * If an ESC is received without anything after it, * return ESC keypress. This is not always desirable - * behaviour as the use may manually press ESC to + * behaviour as the user may manually press ESC to * simulate a keypress that terminal does not support * (yes, this is a real world issue). */ diff --git a/libterminput_set_flags.3 b/libterminput_set_flags.3 new file mode 100644 index 0000000..bce609d --- /dev/null +++ b/libterminput_set_flags.3 @@ -0,0 +1,131 @@ +.TH LIBTERMINPUT_SET_FLAGS 3 LIBTERMINPUT +.SH NAME +libterminput_set_flags \- Add input parsing flags +.br +libterminput_clear_flags \- Remove input parsing flags + +.SH SYNOPSIS +.nf +#include <libterminput.h> + +int libterminput_set_flags(struct libterminput_state *ctx *\fIctx\fP, enum libterminput_flags \fIflags\fP); +int libterminput_clear_flags(struct libterminput_state *ctx *\fIctx\fP, enum libterminput_flags \fIflags\fP); +.fi +.PP +Link with +.IR \-lterminput . + +.SH DESCRIPTION +The +.BR libterminput_set_flags () +function sets the flags specified in the +.I flags +parameter on +.IR ctx , +whereas the +.BR libterminput_clear_flags () +function clears the flags. +.PP +Flags are used to change the behaviour parsing +rules in order to support escape sequences that +are incompatible with the default parsing rules. +The available flags are +.TP +.B LIBTERMINPUT_DECSET_1005 +The sequence +.B CSI M +shall be parsed be parse as a DECSET 1005 sequence +which is incompatible with legacy mouse tracking. +This flag shall only be set if DECSET 1005 has sent +to the terminal and the user is sure it is supported +by the terminal. +.TP +.B LIBTERMINPUT_MACRO_ON_CSI_M +The sequence +.B CSI Pm M +shall be parsed as a key press of the macro key. +This is incompatible with all mouse tracking modes +except +.IR "DECSET 1006" . +Applications that do not use mouse tracking, or +know that their terminal supports +.I DECSET 1006 +and therefore uses it, can safely use this flag. +.TP +.B LIBTERMINPUT_PAUSE_ON_CSI_P +The sequence +.B CSI Pm M +shall be parsed as a key press of the pause key +instead of the F1 key. +.TP +.B LIBTERMINPUT_INS_ON_CSI_AT +The sequence +.B CSI Pm @ +shall be parsed as a key press of the insert key +instead of a number of possible special keys +combined with the control and shift modifiers. +.TP +.B LIBTERMINPUT_SEPARATE_BACKTAB +Backtab shall be treated as a separate key, and +not be reported as tab with the shift modifier. +This flag is just a usability issue. Keyboards +put backtab on shift+tab, which is why the tab +keycap has both a backward arrow (backtab) and +a forward arrow (tab); but most users are unfamiliar +with backtab, and just see it as shift+tab. +.TP +.B LIBTERMINPUT_ESC_ON_BLOCK +If an ESC is received without anything after it, +it shall be parsed as an ESC keypress. This is not +always desirable behaviour as the user may manually +press ESC to simulate a keypress that terminal does +not support (yes, this is a real world issue). +.PP +.I ctx +must have been zero-initialised, e.g. with +.BR memset (3) +function. + +.SH RETURN VALUE +The +.BR libterminput_set_flags () +and +.BR libterminput_clear_flags () +functions returns 0 upon successful completion; +otherwise the +.BR libterminput_set_flags () +and +.BR libterminput_clear_flags () +functions return +.B -1 +and set +.I errno +it indicate the error. + +.SH ERRORS +Currnet versions of the +.BR libterminput_set_flags () +and +.BR libterminput_clear_flags () +functions cannot fail. + +.SH EXAMPLES +None. + +.SH APPLICATION USAGE +None. + +.SH RATIONALE +None. + +.SH FUTURE DIRECTIONS +None. + +.SH NOTES +None. + +.SH BUGS +None. + +.SH SEE ALSO +.BR libterminput_read (3) |