.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
.I DECSET 1005
sequence which is incompatible with legacy mouse
tracking. This flag shall only be set if
.I 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
.BI "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
.BI "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
.BI "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 escape keypress. This is not
always desirable behaviour as the user may manually
press escape to simulate a keypress that terminal
does not support (yes, this is a real world issue).
.TP
.B LIBTERMINPUT_AWAITING_CURSOR_POSITION
The sequence
.BI "CSI " Ps " ; " Rs " R"
shall be parsed as a cursor position report rather
than as an F3 key press.
.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 return 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
Current 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)