path: root/libterminput_read.3

.TH LIBTERMINPUT_READ 3 LIBTERMINPUT
.SH NAME
libterminput_read \- Read and parse input from the terminal

.SH SYNOPSIS
.nf
#include <libterminput.h>

enum libterminput_mod {
	LIBTERMINPUT_SHIFT = 0x01,
	LIBTERMINPUT_META  = 0x02,
	LIBTERMINPUT_CTRL  = 0x04
};

enum libterminput_key {
	LIBTERMINPUT_SYMBOL,
	LIBTERMINPUT_UP,
	LIBTERMINPUT_DOWN,
	LIBTERMINPUT_RIGHT,
	LIBTERMINPUT_LEFT,
	LIBTERMINPUT_BEGIN, /* keypad 5 without numlock */
	LIBTERMINPUT_TAB,
	LIBTERMINPUT_BACKTAB,
	LIBTERMINPUT_F1,
	LIBTERMINPUT_F2,
	LIBTERMINPUT_F3,
	LIBTERMINPUT_F4,
	LIBTERMINPUT_F5,
	LIBTERMINPUT_F6,
	LIBTERMINPUT_F7,
	LIBTERMINPUT_F8,
	LIBTERMINPUT_F9,
	LIBTERMINPUT_F10,
	LIBTERMINPUT_F11,
	LIBTERMINPUT_F12,
	LIBTERMINPUT_HOME,  /* = find    */
	LIBTERMINPUT_INS,
	LIBTERMINPUT_DEL,   /* = remove  */
	LIBTERMINPUT_END,   /* = select  */
	LIBTERMINPUT_PRIOR, /* page up   */
	LIBTERMINPUT_NEXT,  /* page down */
	LIBTERMINPUT_ERASE, /* backspace */
	LIBTERMINPUT_ENTER, /* return    */
	LIBTERMINPUT_ESC,
	LIBTERMINPUT_MACRO,
	LIBTERMINPUT_PAUSE,
	LIBTERMINPUT_KEYPAD_0,
	LIBTERMINPUT_KEYPAD_1,
	LIBTERMINPUT_KEYPAD_2,
	LIBTERMINPUT_KEYPAD_3,
	LIBTERMINPUT_KEYPAD_4,
	LIBTERMINPUT_KEYPAD_5,
	LIBTERMINPUT_KEYPAD_6,
	LIBTERMINPUT_KEYPAD_7,
	LIBTERMINPUT_KEYPAD_8,
	LIBTERMINPUT_KEYPAD_9,
	LIBTERMINPUT_KEYPAD_PLUS,
	LIBTERMINPUT_KEYPAD_MINUS,
	LIBTERMINPUT_KEYPAD_TIMES,
	LIBTERMINPUT_KEYPAD_DIVISION,
	LIBTERMINPUT_KEYPAD_DECIMAL,
	LIBTERMINPUT_KEYPAD_COMMA,
	LIBTERMINPUT_KEYPAD_POINT,
	LIBTERMINPUT_KEYPAD_ENTER,
};

enum libterminput_button {
	LIBTERMINPUT_NO_BUTTON,
	LIBTERMINPUT_BUTTON1,
	LIBTERMINPUT_BUTTON2,
	LIBTERMINPUT_BUTTON3,
	LIBTERMINPUT_SCROLL_UP,
	LIBTERMINPUT_SCROLL_DOWN,
	LIBTERMINPUT_SCROLL_LEFT,
	LIBTERMINPUT_SCROLL_RIGHT,
	LIBTERMINPUT_XBUTTON1,
	LIBTERMINPUT_XBUTTON2,
	LIBTERMINPUT_XBUTTON3,
	LIBTERMINPUT_XBUTTON4
};

enum libterminput_type {
	LIBTERMINPUT_NONE,
	LIBTERMINPUT_KEYPRESS,
	LIBTERMINPUT_BRACKETED_PASTE_START,
	LIBTERMINPUT_BRACKETED_PASTE_END,
	LIBTERMINPUT_TEXT,
	LIBTERMINPUT_MOUSEEVENT,
	LIBTERMINPUT_TERMINAL_IS_OK,
	LIBTERMINPUT_TERMINAL_IS_NOT_OK,
	LIBTERMINPUT_CURSOR_POSITION
};

enum libterminput_event {
	LIBTERMINPUT_PRESS,
	LIBTERMINPUT_RELEASE,
	LIBTERMINPUT_MOTION,
	LIBTERMINPUT_HIGHLIGHT_INSIDE,
	LIBTERMINPUT_HIGHLIGHT_OUTSIDE
};

struct libterminput_keypress {
	enum libterminput_type type;
	enum libterminput_key  key;
	unsigned long long int times;
	enum libterminput_mod  mods;
	char                   symbol[7];
};

struct libterminput_text {
	enum libterminput_type type;
	size_t                 nbytes;
	char                   bytes[512];
};

struct libterminput_mouseevent {
	enum libterminput_type   type;
	enum libterminput_mod    mods;
	enum libterminput_button button;
	enum libterminput_event  event;
	size_t                   x;
	size_t                   y;
	size_t                   start_x;
	size_t                   start_y;
	size_t                   end_x;
	size_t                   end_y;
};

struct libterminput_position {
	enum libterminput_type type;
	size_t                 x;
	size_t                 y;
};

union libterminput_input {
	enum libterminput_type         type;
	struct libterminput_keypress   keypress;
	struct libterminput_text       text;
	struct libterminput_mouseevent mouseevent;
};

int libterminput_read(int \fIfd\fP, union libterminput_input *\fIinput\fP, struct libterminput_state *\fIctx\fP);
.fi
.PP
Link with
.IR \-lterminput .

.SH DESCRIPTION
The
.BR libterminput_read ()
reads input from the file descriptor specified in the
.I fd
parameter, parses it as input from the terminal, and
returns the result in the
.IR *input .
.PP
.I ctx
must have been zero-initialised, e.g. with
.BR memset (3)
function.
.PP
.I input
shall be the same pointer every time the
.BR libterminput_read ()
function is called with the same
.I ctx ,
as should
.IR fd ,
except the user may choose to use a negative
file descriptor (expect
.I EBADF
exception) to read the last data that has
been buffered.
.PP
If the
.BR libterminput_read ()
function returns 1, there was input;
.I input->type
is used to detech which type of input was parsed.
Currently possible values are:
.TP
.B LIBTERMINPUT_NONE
A special value to mark that the input was either
discard or not yet completed. The function only
reads at most once so input may be complete (input
can also be bufferd, in which case it will not
read at all).
.TP
.B LIBTERMINPUT_KEYPRESS
Normal key press. The pressed key will be stored in
.I input->key
and has a value from
.IR "enum libterminput_key" ;
these values are listed above and have fairly self
explanatory names; however there are three special
values to take note of:
.RS 7
.TP
.B LIBTERMINPUT_SYMBOL
The key press generated text (or a paste was made
without bracketed paste enabled), which is stored
in
.I input->keypress.symbol
as a NUL-terminated string. For key presses (and
pastes) that generate multiple character-text, one
event will be generated per character.
.TP
.B LIBTERMINPUT_TAB
.TQ
.B LIBTERMINPUT_BACKTAB
Backtab will be reported as shift+tab unless the
.B LIBTERMINPUT_SEPARATE_BACKTAB
flag has been set with the
.BR libterminput_set_flags (3)
function.
.PP
The modifiers are stored, as a bitwise OR of
modifiers, in
.IR input->keypress.mods .
Recognised modifiers are
.BR LIBTERMINPUT_SHIFT ,
.BR LIBTERMINPUT_META ,
and
.BR LIBTERMINPUT_CTRL ,
however, if the terminal support other modifiers,
they may also appear in
.IR input->keypress.mods .
.B NB!
.IR input->keypress.mods
may be non-zero even if
.I input->key
is
.BR LIBTERMINPUT_SYMBOL .
This can happen for example if meta or control was
held down. It is even possible that
.B LIBTERMINPUT_SHIFT
is set, however this is unlikely, and exceptionally
unlikely for any other symbol than the space character.
Information about shift if normally not sent for
normal text keys as shift is used to select which
character on the key generate.

Some events, namely scrolling with the mouse, may
generate an event which as marked as repeated. This
information is stored in
.I input->keypress.times
and may be ignored and is usually 1, But the application
may choose to inspect this value, in doing so, it shall
ignore the next
.I input->keypress.times-1
events.
.RE
.TP
.B LIBTERMINPUT_BRACKETED_PASTE_START
Marks the beginning of a bracketed paste.
The application does not need to do anything,
but may choose to defer processing of the
pasted text until the end has been reached.
.TP
.B LIBTERMINPUT_BRACKETED_PASTE_END
Marks the beginning of a bracketed paste.
.TP
.B LIBTERMINPUT_TEXT
The input is text that has been pasted.
The paste may be incomplete.
.B LIBTERMINPUT_BRACKETED_PASTE_END
marks the end of the paste; however even so, a
terminal may choose to break up a paste in order
to deal with pasted escape characters, in particalur
where it looks like the escape esquence that is
used to mark the end of a bracketed paste. The
application shall treat pasted escape characters
as any other character.

The pasted text will be stored in
.IR input->text.bytes .
Be aware that this is not a NUL-terminated string,
rather, it's length is stored in
.IR input->text.nbytes .
.TP
.B LIBTERMINPUT_MOUSEEVENT
Mouse tracking input. The location of the mouse
is stored in
.I input->mouseevent.x
and
.I input->mouseevent.y
(normally this would indicate the character cell
and the cell in top left corner would have the
value 1 for both fields).

The button that has been pressed or released is
stored in
.I input->mouseevent.button
and the for a mouse motion event one of the held
done buttons (it is arbitrary which) will be stored
in this field, if any. Possible values are:
.RS 7
.TP
.B LIBTERMINPUT_NO_BUTTON
This will be used for a mouse motion event where
the mouse button is held down.
.TP
.B LIBTERMINPUT_BUTTON1
The left mouse button for a right-handed setup or
the right mouse button for a left-handed setup;
that is, it is the primary mouse button.
.TP
.B LIBTERMINPUT_BUTTON2
The middle mouse button, which is usually a scroll wheel.
.TP
.B LIBTERMINPUT_BUTTON3
The right mouse button for a right-handed setup or
the left mouse button for a left-handed setup;
that is, it is the secondary mouse button.
.TP
.B LIBTERMINPUT_SCROLL_UP
The user scrolled up with the mouse; this is reported
as a mouse press event even if it is actually a scroll
event. The terminal shall not send a corresponding
release event.
.TP
.B LIBTERMINPUT_SCROLL_DOWN
The user scrolled down with the mouse; this is reported
as a mouse press event even if it is actually a scroll
event. The terminal shall not send a corresponding
release event.
.TP
.B LIBTERMINPUT_SCROLL_LEFT
The user scrolled leftwards with the mouse. The developer
is not aware of any standisation of whether this shall
behandled by the terminal in the same manner as a scroll
up/down even, or as a normal mouse button press/release event;
however for trackpads would be unable to detect a release
event, so it will probably be handled as a scroll event.
.TP
.B LIBTERMINPUT_SCROLL_RIGHT
The user scrolled rightwards with the mouse. The developer
is not aware of any standisation of whether this shall
behandled by the terminal in the same manner as a scroll
up/down even, or as a normal mouse button press/release event;
however for trackpads would be unable to detect a release
event, so it will probably be handled as a scroll event.
.TP
.B LIBTERMINPUT_XBUTTON1
The first extended button (X1), usually used to go backwards.
.TP
.B LIBTERMINPUT_XBUTTON2
The second extended button (X2), usually used to go forwards.
.TP
.B LIBTERMINPUT_XBUTTON3
The third extended button (X3). You probably don't have this one.
.TP
.B LIBTERMINPUT_XBUTTON4
The fourth extended button (X4). You probably don't have this one.
.RE

The held down modifiers will be stored a bitwise
OR of modifiers in
.IR input->mouseevent.mods .
The modifiers than currently can appear are
.BR LIBTERMINPUT_SHIFT ,
.BR LIBTERMINPUT_META ,
and
.BR LIBTERMINPUT_CTRL .

What type of mouse action has occurred is stored in
.IR input->mouseevent.event ;
possible values are:
.RS 7
.TP
.B LIBTERMINPUT_PRESS
A mouse button was pressed.
.TP
.B LIBTERMINPUT_RELEASE
A mouse button was released.
.TP
.B LIBTERMINPUT_MOTION
The mouse moved.
.TP
.B LIBTERMINPUT_HIGHLIGHT_INSIDE
Highlight ended inside of selected region.
.I input->mouseevent.mods
and
.I input->mouseevent.button
will be set to 0 and 1, but should be ignored
as this information will not be sent by the terminal.
.TP
.B LIBTERMINPUT_HIGHLIGHT_OUTSIDE
Highlight ended outside of selected region.
.I input->mouseevent.mods
and
.I input->mouseevent.button
will be set to 0 and 1, but should be ignored
as this information will not be sent by the terminal.

For this event,
.IR input->mouseevent.start_x ,
.IR input->mouseevent.start_y ,
.IR input->mouseevent.end_x ,
and
.IR input->mouseevent.end_y
will also be set to indicate the region selected by
the application.
.RE
.TP
.B LIBTERMINPUT_TERMINAL_IS_OK
OK response for a device status query.
.TP
.B LIBTERMINPUT_TERMINAL_IS_NOT_OK
Not-OK response for a device status query.
.TP
.B LIBTERMINPUT_CURSOR_POSITION
Cursor position report even as a response to a
cursor position query. The line (indexed starting
with 1 at the top) the cursor is on will be
stored in
.I input->position.y
and the column (indexed starting with 1 at the
left edge) will be stored in
.I input->position.x

This event can conflict with both F1 and pause
key processes, therefore the
.B LIBTERMINPUT_AWAITING_CURSOR_POSITION
flag must be set with the
.BR libterminput_set_flags (3)
function.
.SH RETURN VALUE
The
.BR libterminput_read ()
function returns 0 or 1 upon successful completion,
1 if there was input, 0 if the input closed (or an
empty packet was sent, such as on control+d);
otherwise the
.BR libterminput_read ()
function returns
.B -1
and set
.I errno
it indicate the error.

.SH ERRORS
The
.BR libterminput_read ()
function may fail for any reason specified for the
.BR read (3)
function.

.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_is_ready (3),
.BR libterminput_set_flags (3)