Relative cursor move (#1885)

Relative cursor move by @tomek-szczesny

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);
 

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**.
+A plane has a virtual cursor; Set its new position with **ncplane_cursor_move_yx**.
-Specifying -1 as either coordinate will hold that axis constant. Unless
+Specifying -1 as one or both coordinates will hold that axis constant. You may
-coordinates are specified for a call, action takes place at the plane's
+move a cursor relatively to its current position with **ncplane_cursor_move_rel**.
-virtual cursor, which automatically moves along with output. The current
+Unless coordinates are specified for a call, action takes place at the plane's
-virtual cursor location can be acquired with **ncplane_cursor_yx**.
+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**).

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);
 

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;