From 0baf4ea1b5d404df30d1cd3f5a1c67770717dd45 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomek=20Szcz=C4=99sny?=
 <44300715+tomek-szczesny@users.noreply.github.com>
Date: Sun, 11 Jul 2021 15:53:56 +0200
Subject: [PATCH] Relative cursor move (#1885)

Relative cursor move by @tomek-szczesny
---
 USAGE.md                          |  3 +++
 doc/man/man3/notcurses_plane.3.md | 14 +++++++++-----
 include/notcurses/notcurses.h     |  4 ++++
 src/lib/notcurses.c               | 10 ++++++++++
 4 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/USAGE.md b/USAGE.md
index 356055a5b..27e2b5aad 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -1118,6 +1118,9 @@ memory.
 // move would place the cursor outside the plane.
 int ncplane_cursor_move_yx(struct ncplane* n, int y, int x);
 
+// Move cursor relatively to its current position.
+int ncplane_cursor_move_rel(struct ncplane* n, int y, int x);
+
 // Get the current position of the cursor within n. y and/or x may be NULL.
 void ncplane_cursor_yx(const struct ncplane* n, int* restrict y, int* restrict x);
 
diff --git a/doc/man/man3/notcurses_plane.3.md b/doc/man/man3/notcurses_plane.3.md
index ab71f6c5b..be20242ad 100644
--- a/doc/man/man3/notcurses_plane.3.md
+++ b/doc/man/man3/notcurses_plane.3.md
@@ -285,11 +285,12 @@ the rendering area. A plane can be moved off-screen entirely, in which case
 it will not be visible following rasterization; it can also be partially
 off-screen.
 
-A plane has a virtual cursor; move it with **ncplane_cursor_move_yx**.
-Specifying -1 as either coordinate will hold that axis constant. Unless
-coordinates are specified for a call, action takes place at the plane's
-virtual cursor, which automatically moves along with output. The current
-virtual cursor location can be acquired with **ncplane_cursor_yx**.
+A plane has a virtual cursor; Set its new position with **ncplane_cursor_move_yx**.
+Specifying -1 as one or both coordinates will hold that axis constant. You may
+move a cursor relatively to its current position with **ncplane_cursor_move_rel**.
+Unless coordinates are specified for a call, action takes place at the plane's
+virtual cursor, which automatically moves along with output. The current virtual
+cursor location can be acquired with **ncplane_cursor_yx**.
 
 **ncplane_yx** returns the coordinates of the specified plane's origin, relative
 to the plane to which it is bound. Either or both of ***y*** and ***x*** may
@@ -440,6 +441,9 @@ if they specify any area beyond the plane.
 **ncplane_cursor_move_yx** returns -1 if the coordinates are beyond the
 dimensions of the specified plane (except for the special value -1).
 
+**ncplane_cursor_move_rel** returns -1 if the coordinates are beyond the
+dimensions of the specified plane.
+
 Functions returning **int** return 0 on success, and non-zero on error.
 
 All other functions cannot fail (and return **void**).
diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h
index d85b72808..37f0325de 100644
--- a/include/notcurses/notcurses.h
+++ b/include/notcurses/notcurses.h
@@ -1667,6 +1667,10 @@ ncplane_valign(const struct ncplane* n, ncalign_e align, int r){
 // move would place the cursor outside the plane.
 API int ncplane_cursor_move_yx(struct ncplane* n, int y, int x);
 
+// Move the cursor relative to the current cursor position (the cursor needn't be visible).
+// Returns -1 on error, including target position exceeding the plane's dimensions.
+API int ncplane_cursor_move_rel(struct ncplane* n, int y, int x);
+
 // Move the cursor to 0, 0. Can't fail.
 API void ncplane_home(struct ncplane* n);
 
diff --git a/src/lib/notcurses.c b/src/lib/notcurses.c
index f1ef3fa64..85d3efde1 100644
--- a/src/lib/notcurses.c
+++ b/src/lib/notcurses.c
@@ -594,6 +594,16 @@ inline int ncplane_cursor_move_yx(ncplane* n, int y, int x){
   return 0;
 }
 
+inline int ncplane_cursor_move_rel(ncplane* n, int y, int x){
+  if (n->y + y == -1){
+    logerror("Invalid target y -1\n");
+    return -1;
+  }else if (n->x + x == -1){
+    logerror("Invalid target x -1\n");
+    return -1;
+  }else return ncplane_cursor_move_yx(n, n->y + y, n->x + x);
+}
+
 ncplane* ncplane_dup(const ncplane* n, void* opaque){
   int dimy = n->leny;
   int dimx = n->lenx;