document notcurses_cursor_yx() #1681

NEWS.md

@@ -6,6 +6,7 @@ rearrangements of Notcurses.
     memory (e.g. `ncvisual_from_rgba()`).
   * `ncinput_nomod_p()` has been added. This function returns `true` if and
     only if its `ncinput` argument has no modifiers active.
+  * Added `notcurses_cursor_yx()` to get the current location of the cursor.
 
 * 2.3.1 (2021-05-18)
   * Sprixels no longer interact with their associated plane's framebuffer. This

USAGE.md

@@ -263,10 +263,18 @@ notcurses_term_dim_yx(const struct notcurses* n, int* restrict rows,
 // NCKEY_RESIZE event has been read and you're not ready to render.
 int notcurses_refresh(struct notcurses* n, int* restrict y, int* restrict x);
 
-// Enable or disable the terminal's cursor, if supported. Immediate effect.
-// It is an error to supply coordinates outside of the standard plane.
-void notcurses_cursor_enable(struct notcurses* nc, int y, int x);
-void notcurses_cursor_disable(struct notcurses* nc);
+// Enable or disable the terminal's cursor, if supported, placing it at
+// 'y', 'x'. Immediate effect (no need for a call to notcurses_render()).
+// It is an error if 'y', 'x' lies outside the standard plane. Can be
+// called while already visible to move the cursor.
+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);
+
+// Disable the hardware cursor. It is an error to call this while the
+// cursor is already disabled.
+int notcurses_cursor_disable(struct notcurses* nc);
 
 // Returns a 16-bit bitmask in the LSBs of supported curses-style attributes
 // (NCSTYLE_UNDERLINE, NCSTYLE_BOLD, etc.) The attribute is only

doc/man/man3/notcurses_init.3.md

@@ -48,6 +48,8 @@ typedef struct notcurses_options {
 
 **int notcurses_cursor_enable(struct notcurses* ***nc***, int ***y***, int ***x***);**
 
+**int notcurses_cursor_yx(struct notcurses* ***nc***, int* ***y***, int* ***x***);**
+
 **int notcurses_cursor_disable(struct notcurses* ***nc***);**
 
 # DESCRIPTION
@@ -78,8 +80,10 @@ strong opinions regarding the alternate screen, so it's often useful to expose
 this via a command-line option.
 
 notcurses hides the cursor by default. It can be dynamically enabled, moved, or
-disabled during execution via **notcurses_cursor_enable(3)** and
-**notcurses_cursor_disable(3)**.
+disabled during execution via **notcurses_cursor_enable** and
+**notcurses_cursor_disable**. It will be hidden while updating the screen.
+The current location of the terminal cursor can be acquired with
+**notcurses_cursor_yx**, whether visible or not.
 
 **notcurses_init** typically emits some diagnostics at startup, including version
 information and some details of the configured terminal. This can be inhibited
@@ -185,6 +189,8 @@ across the new screen geometry.
 **struct notcurses**, which can be used until it is provided to
 **notcurses_stop(3)**.
 
+**notcurses_cursor_disable** returns -1 if the cursor is already invisible.
+
 # SEE ALSO
 
 **getenv(3)**,

include/notcurses/notcurses.h

@@ -2909,8 +2909,15 @@ bprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
 
 // Enable or disable the terminal's cursor, if supported, placing it at
 // 'y', 'x'. Immediate effect (no need for a call to notcurses_render()).
-// It is an error if 'y', 'x' lies outside the standard plane.
+// It is an error if 'y', 'x' lies outside the standard plane. Can be
+// called while already visible to move the cursor.
 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);
+
+// Disable the hardware cursor. It is an error to call this while the
+// cursor is already disabled.
 API int notcurses_cursor_disable(struct notcurses* nc);
 
 // Palette API. Some terminals only support 256 colors, but allow the full