From e6d35978d4bf72ae188078eef6e2083dc1c16fa5 Mon Sep 17 00:00:00 2001
From: nick black <dankamongmen@gmail.com>
Date: Fri, 13 Dec 2019 18:02:35 -0500
Subject: [PATCH] add notcurses_refresh() declaration

---
 README.md           | 37 +++++++++++++++++++++++++++++++++++++
 include/notcurses.h | 10 +++++++++-
 src/lib/notcurses.c | 13 +++++++++++++
 3 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 182434350..38c326683 100644
--- a/README.md
+++ b/README.md
@@ -164,6 +164,43 @@ reflect the changes:
 int notcurses_render(struct notcurses* nc);
 ```
 
+Utility functions operating on the toplevel `notcurses` object include:
+
+```c
+// Refresh our idea of the terminal's dimensions, reshaping the standard plane
+// if necessary. Without a call to this function following a terminal resize
+// (as signaled via SIGWINCH), notcurses_render() might not function properly.
+// References to ncplanes remain valid following a resize operation, but the
+// cursor might have changed position.
+int notcurses_resize(struct notcurses* n, int* RESTRICT y, int* RESTRICT x);
+
+// Refresh the physical screen to match what was last rendered (i.e., without
+// reflecting any changes since the last call to notcurses_render()). This is
+// primarily useful if the screen is externally corrupted.
+int notcurses_refresh(struct notcurses* n);
+
+// Get a reference to the standard plane (one matching our current idea of the
+// terminal size) for this terminal.
+struct ncplane* notcurses_stdplane(struct notcurses* nc);
+const struct ncplane* notcurses_stdplane_const(const struct notcurses* nc);
+
+// Create a new ncplane at the specified offset (relative to the standard plane)
+// and the specified size. The number of rows and columns must both be positive.
+// This plane is initially at the top of the z-buffer, as if ncplane_move_top()
+// had been called on it. The void* 'opaque' can be retrieved (and reset) later.
+struct ncplane* notcurses_newplane(struct notcurses* nc, int rows, int cols,
+                                   int yoff, int xoff, void* opaque);
+
+// Returns a 16-bit bitmask in the LSBs of supported curses-style attributes
+// (CELL_STYLE_UNDERLINE, CELL_STYLE_BOLD, etc.) The attribute is only
+// indicated as supported if the terminal can support it together with color.
+unsigned notcurses_supported_styles(const struct notcurses* nc);
+
+// Returns the number of colors supported by the palette, or 1 if there is no
+// color support.
+int notcurses_palette_size(const struct notcurses* nc);
+```
+
 ### Input
 
 Input can currently be taken only from `stdin`, but on the plus side, stdin
diff --git a/include/notcurses.h b/include/notcurses.h
index a0eb14848..70011bfd6 100644
--- a/include/notcurses.h
+++ b/include/notcurses.h
@@ -236,7 +236,12 @@ notcurses_getc_blocking(struct notcurses* n){
 // (as signaled via SIGWINCH), notcurses_render() might not function properly.
 // References to ncplanes remain valid following a resize operation, but the
 // cursor might have changed position.
-API int notcurses_resize(struct notcurses* n, int* y, int* x);
+API int notcurses_resize(struct notcurses* n, int* RESTRICT y, int* RESTRICT x);
+
+// Refresh the physical screen to match what was last rendered (i.e., without
+// reflecting any changes since the last call to notcurses_render()). This is
+// primarily useful if the screen is externally corrupted.
+API int notcurses_refresh(struct notcurses* n);
 
 // Get a reference to the standard plane (one matching our current idea of the
 // terminal size) for this terminal.
@@ -1225,6 +1230,9 @@ bprefix(uintmax_t val, unsigned decimal, char *buf, int omitdec){
   return enmetric(val, decimal, buf, omitdec, 1024, 'i');
 }
 
+API void notcurses_cursor_enable(struct notcurses* nc);
+API void notcurses_cursor_disable(struct notcurses* nc);
+
 #undef API
 
 #ifdef __cplusplus
diff --git a/src/lib/notcurses.c b/src/lib/notcurses.c
index 0060413cd..67bf5e18e 100644
--- a/src/lib/notcurses.c
+++ b/src/lib/notcurses.c
@@ -2153,3 +2153,16 @@ int ncvisual_stream(notcurses* nc, ncvisual* ncv, int* averr){
   }
   return -1;
 }
+
+// if "retain_cursor" was set, we don't have these definitions FIXME
+void notcurses_cursor_enable(struct notcurses* nc){
+  if(nc->cnorm){
+    term_emit("cnorm", nc->cnorm, nc->ttyfp, false);
+  }
+}
+
+void notcurses_cursor_disable(struct notcurses* nc){
+  if(nc->civis){
+    term_emit("civis", nc->civis, nc->ttyfp, false);
+  }
+}