add ncplane_set_name()/ncplane_name() + documentation

NEWS.md

@@ -6,6 +6,7 @@ rearrangements of Notcurses.
     been removed, having never ought have been born.
   * Added functions `ncplane_move_family_top()`, `ncplane_move_family_bottom()`,
     `ncplane_move_family_above()`, and `ncplane_move_family_below()`.
+  * Added functions `ncplane_set_name()` and `ncplane_name()`.
 
 * 2.4.4 (2021-10-03)
   * Notcurses no longer uses libreadline, as it was realized to be incompatible

USAGE.md

@@ -871,6 +871,12 @@ int ncplane_resize_realign(struct ncplane* n);
 struct ncplane* ncplane_parent(struct ncplane* n);
 const struct ncplane* ncplane_parent_const(const struct ncplane* n);
 
+// Set the plane's name, replacing any current name.
+int ncplane_set_name(struct ncplane* n, const char* name);
+
+// Return a heap-allocated copy of the plane's name, or NULL if it has none.
+char* ncplane_name(const struct ncplane* n);
+
 // Duplicate an existing ncplane. The new plane will have the same geometry,
 // will duplicate all content, and will start with the same rendering state.
 struct ncplane* ncplane_dup(struct ncplane* n, void* opaque);

doc/man/man3/notcurses_plane.3.md

@@ -227,6 +227,10 @@ typedef struct ncplane_options {
 
 **void ncplane_pixelgeom(struct notcurses* ***n***, int* restrict ***pxy***, int* restrict ***pxx***, int* restrict ***celldimy***, int* restrict ***celldimx***, int* restrict ***maxbmapy***, int* restrict ***maxbmapx***);**
 
+**int ncplane_set_name(struct ncplane* ***n***, const char* ***name***);**
+
+**char* ncplane_name(const struct ncplane* ***n***);**
+
 ## DESCRIPTION
 
 Ncplanes are the fundamental drawing object of notcurses. All output functions
@@ -444,6 +448,9 @@ secondary column of a wide glyph with **ncplane_at_yx_cell** will fill in
 the **nccell** argument such that **nccell_extended_gcluster(3)** returns an
 empty string, and **nccell_wide_right_p(3)** returns **true**.
 
+**ncplane_set_name** sets the plane's name, freeing any old name. ***name***
+may be **NULL**.
+
 # RETURN VALUES
 
 **ncplane_create** and **ncplane_dup** return a new **struct ncplane** on
@@ -481,6 +488,9 @@ 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.
 
+**ncplane_name** returns a heap-allocated copy of the plane's name, or NULL if
+it has no name (or on error).
+
 Functions returning **int** return 0 on success, and non-zero on error.
 
 All other functions cannot fail (and return **void**).

include/notcurses/notcurses.h

@@ -1270,6 +1270,14 @@ API void ncplane_set_resizecb(struct ncplane* n, int(*resizecb)(struct ncplane*)
 // Returns the ncplane's current resize callback.
 API int (*ncplane_resizecb(const struct ncplane* n))(struct ncplane*);
 
+// Set the plane's name (may be NULL), replacing any current name.
+API int ncplane_set_name(struct ncplane* n, const char* name)
+  __attribute__ ((nonnull (1)));
+
+// Return a heap-allocated copy of the plane's name, or NULL if it has none.
+API ALLOC char* ncplane_name(const struct ncplane* n)
+  __attribute__ ((nonnull (1)));
+
 // Plane 'n' will be unbound from its parent plane, and will be made a bound
 // child of 'newparent'. It is an error if 'n' or 'newparent' are NULL. If
 // 'newparent' is equal to 'n', 'n' becomes the root of a new pile, unless 'n'

src/lib/notcurses.c

@@ -1217,6 +1217,8 @@ void notcurses_drop_planes(notcurses* nc){
 }
 
 int notcurses_stop(notcurses* nc){
+  logdebug("stopping notcurses\n");
+//notcurses_debug(nc, stderr);
   int ret = 0;
   if(nc){
     ret |= notcurses_stop_minimal(nc);
@@ -2432,6 +2434,20 @@ const ncplane* ncplane_parent_const(const ncplane* n){
   return n->boundto;
 }
 
+int ncplane_set_name(ncplane* n, const char* name){
+  char* copy = name ? strdup(name) : NULL;
+  if(copy == NULL && name != NULL){
+    return -1;
+  }
+  free(n->name);
+  n->name = copy;
+  return 0;
+}
+
+char* ncplane_name(const ncplane* n){
+  return n->name ? strdup(n->name) : NULL;
+}
+
 void ncplane_set_resizecb(ncplane* n, int(*resizecb)(ncplane*)){
   n->resizecb = resizecb;
 }