add a section on hardware cursor to notcurses_init.3 #1681

USAGE.md

@@ -270,7 +270,7 @@ int notcurses_refresh(struct notcurses* n, int* restrict y, int* restrict x);
 int notcurses_cursor_enable(struct notcurses* nc, int y, int x);
 
 // Get the current location of the terminal's cursor, whether visible or not.
-int notcurses_cursor_yx(struct notcurses* nc, int y, int x);
+int notcurses_cursor_yx(struct notcurses* nc, int* y, int* x);
 
 // Disable the hardware cursor. It is an error to call this while the
 // cursor is already disabled.

doc/man/man3/notcurses_init.3.md

@@ -183,6 +183,26 @@ standard plane (see **notcurses_stdplane(3)**) will be resized to the new
 screen size. The next **notcurses_render(3)** call will function as expected
 across the new screen geometry.
 
+## The hardware cursor
+
+Most terminals provide a cursor, a visual indicator of where output will next
+be placed. There is usually (but not always) some degree of control over what
+glyph forms this cursor, and whether it e.g. blinks.
+
+By default, Notcurses disables this cursor in rendered mode. It can be turned
+back on with **notcurses_enable_cursor**, which has immediate effect (there is
+no need to call **notcurses_render(3)**. If already visible, this function
+updates the location. Each time the physical screen is updated, Notcurses will
+disable the cursor, write the update, move the cursor back to this location,
+and finally make the cursor visible. **notcurses_cursor_yx** retrieves the
+location of the cursor, whether visible or not. **notcurses_disable_cursor**
+hides the cursor.
+
+You generally shouldn't need to touch the terminal cursor. It's only really
+relevant with echoed user input, and you don't want echoed user input in
+rendered mode (instead, read the input, and write it to a plane yourself).
+A subprocess can be streamed to a plane with an **ncsubproc**, etc.
+
 # RETURN VALUES
 
 **NULL** is returned on failure. Otherwise, the return value points at a valid

include/notcurses/notcurses.h

@@ -2914,7 +2914,7 @@ bprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
 API int notcurses_cursor_enable(struct notcurses* nc, int y, int x);
 
 // Get the current location of the terminal's cursor, whether visible or not.
-API int notcurses_cursor_yx(struct notcurses* nc, int y, int x);
+API int notcurses_cursor_yx(struct notcurses* nc, int* y, int* x);
 
 // Disable the hardware cursor. It is an error to call this while the
 // cursor is already disabled.

src/lib/render.c

@@ -1464,6 +1464,12 @@ int ncdirect_set_fg_rgb(ncdirect* nc, unsigned rgb){
   return 0;
 }
 
+int notcurses_cursor_yx(notcurses* nc, int* y, int* x){
+  *y = nc->rstate.y;
+  *x = nc->rstate.x;
+  return 0;
+}
+
 int notcurses_cursor_enable(notcurses* nc, int y, int x){
   if(y < 0 || x < 0){
     logerror(nc, "Illegal cursor placement: %d, %d\n", y, x);
@@ -1481,6 +1487,7 @@ int notcurses_cursor_enable(notcurses* nc, int y, int x){
   if(nc->ttyfd < 0 || !nc->tcache.cnorm){
     return -1;
   }
+  // updates nc->rstate.cursor{y,x}
   if(goto_location(nc, nc->ttyfp, y + nc->stdplane->absy, x + nc->stdplane->absx)){
     return -1;
   }

src/lib/tree.c

@@ -462,7 +462,7 @@ void* nctree_focused(nctree* n){
 }
 
 void* nctree_goto(nctree* n, const unsigned* spec, int* failspec){
-  (void)n;
+  n->activerow = 0;
   (void)spec;
   (void)failspec;
   // FIXME