Documentation on new TERMKEY_TYPE_POSITION events

2 files changed, 31 insertions, 0 deletions

diff --git a/man/termkey.7 b/man/termkey.7
index bae9a36..33f267d 100644
--- a/man/termkey.7
+++ b/man/termkey.7
@@ -47,6 +47,9 @@ a symbolic key. This value indicates that \fIcode.sym\fP is valid, and contains
 .TP
 .B TERMKEY_TYPE_MOUSE
 a mouse button press, release, or movement. The \fIcode.mouse\fP array should be considered opaque.
+.TP
+.B TERMKEY_TYPE_POSITION
+a cursor position report.
 .PP
 The \fImodifiers\fP bitmask is composed of a bitwise-or of the constants \fBTERMKEY_KEYMOD_SHIFT\fP, \fBTERMKEY_KEYMOD_CTRL\fP and \fBTERMKEY_KEYMOD_ALT\fP.
 .PP
@@ -105,6 +108,8 @@ The amount of time that the \fBtermkey\fP instance will wait is set by \fBtermke
 The \fBTERMKEY_TYPE_MOUSE\fP event type indicates a mouse event. The \fIcode\fP field of the event structure should be considered opaque, though \fImodifiers\fP will be valid. In order to obtain the details of the mouse event, call \fBtermkey_interpret_mouse\fP(3) passing the event structure and pointers to integers to store the result in. 
 .PP
 \fBtermkey\fP recognises three mouse protocols: the original X10 protocol (\f(CWCSI M\fP followed by three bytes), SGR encoding (\f(CWCSI < ... M\fP, as requested by \f(CWCSI ? 1006 h\fP), and rxvt encoding (\f(CWCSI ... M\fP, as requested by \f(CWCSI ? 1015 h\fP). Which encoding is in use is inferred automatically by \fBtermkey\fP, and does not need to be specified explicitly.
+.SS Position Events
+The \fBTERMKEY_TYPE_POSITION\fP event type indicates a cursor position report. This is typically sent by a terminal in response to the Report Cursor Position command (\f(CWCSI 6n\fP). The event bytes are opaque, but can be obtained by calling \fBtermkey_interpret_position\fP(3) passing the event structure and pointers to integers to store the result in.
 .SH "SEE ALSO"
 .BR termkey_new (3),
 .BR termkey_waitkey (3),
diff --git a/man/termkey_interpret_position.3 b/man/termkey_interpret_position.3
new file mode 100644
index 0000000..e4fb091
--- /dev/null
+++ b/man/termkey_interpret_position.3
@@ -0,0 +1,26 @@
+.TH TERMKEY_INTERPRET_POSITION 3
+.SH NAME
+termkey_interpret_position \- interpret opaque cursor position event data
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "TermKeyResult termkey_interpret_position(TermKey *" tk ", const TermKeyKey *" key ", "
+.BI "    int *" line ", int *" col );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_interpret_position\fP() fills in variables in the passed pointers according to the cursor position report event found in \fIkey\fP. It should be called if \fBtermkey_getkey\fP(3) or similar have returned a key event with the type of \fBTERMKEY_TYPE_POSITION\fP.
+.PP
+Any pointer may instead be given as \fBNULL\fP to not return that value.
+.PP
+The \fIline\fP and \fIcol\fP variables will be filled in with the cursor position, indexed from 1. Note that due to the limited number of bytes in the \fBTermKeyKey\fP structure, the line and column numbers are limited to 2047 and 4095 respectively.
+.SH "RETURN VALUE"
+If passed a \fIkey\fP event of the type \fBTERMKEY_TYPE_POSITION\fP, this function will return \fBTERMKEY_RES_KEY\fP and will affect the variables whose pointers were passed in, as described above.
+.PP
+For other event types it will return \fBTERMKEY_RES_NONE\fP, and its effects on any variables whose pointers were passed in, are undefined.
+.SH "SEE ALSO"
+.BR termkey_waitkey (3),
+.BR termkey_getkey (3),
+.BR termkey (7)