From f2b26723c91f293737879da0adaef745c3f61075 Mon Sep 17 00:00:00 2001
From: nick black <dankamongmen@gmail.com>
Date: Sat, 22 May 2021 23:07:11 -0400
Subject: [PATCH] document notcurses_cursor_yx() #1681

---
 NEWS.md                          |  1 +
 USAGE.md                         | 16 ++++++++++++----
 doc/man/man3/notcurses_init.3.md | 10 ++++++++--
 include/notcurses/notcurses.h    |  9 ++++++++-
 4 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index e0c2c5ffa..1eae64f14 100644
--- a/NEWS.md
+++ b/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
diff --git a/USAGE.md b/USAGE.md
index 8e299a28a..c1b0e1bea 100644
--- a/USAGE.md
+++ b/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
diff --git a/doc/man/man3/notcurses_init.3.md b/doc/man/man3/notcurses_init.3.md
index 464d85174..38b82fc0c 100644
--- a/doc/man/man3/notcurses_init.3.md
+++ b/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)**,
diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h
index 2e402c987..4eb472a4d 100644
--- a/include/notcurses/notcurses.h
+++ b/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