ncplane_move_family_{above, below}() #2232

NEWS.md

@@ -1,6 +1,12 @@
 This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
+* 2.4.5 (not yet released)
+  * The poorly-considered function `ncplane_boundlist()`, added in 2.3.17, has
+    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()`.
+
 * 2.4.4 (2021-10-03)
   * Notcurses no longer uses libreadline, as it was realized to be incompatible
     with the new input system. `ncdirect_readline()` has been rewritten to

USAGE.md

@@ -1107,15 +1107,25 @@ void ncplane_move_bottom(struct ncplane* n);
 void ncplane_move_family_top(struct ncplane* n);
 void ncplane_move_family_bottom(struct ncplane* n);
 
-// Splice ncplane 'n' out of the z-buffer, and reinsert it below 'below'.
-// Returns non-zero if 'n' is already in the desired location. 'n' and
-// 'below' must not be the same plane.
-int ncplane_move_below(struct ncplane* restrict n, struct ncplane* restrict below);
-
 // Splice ncplane 'n' out of the z-buffer, and reinsert it above 'above'.
 // Returns non-zero if 'n' is already in the desired location. 'n' and
-// 'above' must not be the same plane.
+// 'above' must not be the same plane. If 'above' is NULL, 'n' is moved
-int ncplane_move_above(struct ncplane* restrict n, struct ncplane* restrict above);
+// to the bottom of its pile.
+int ncplane_move_above(struct ncplane* RESTRICT n,
+                       struct ncplane* RESTRICT above);
+
+// Splice ncplane 'n' out of the z-buffer, and reinsert it below 'below'.
+// Returns non-zero if 'n' is already in the desired location. 'n' and
+// 'below' must not be the same plane. If 'below' is NULL, 'n' is moved to
+// the top of its pile.
+int ncplane_move_below(struct ncplane* RESTRICT n,
+                       struct ncplane* RESTRICT below);
+
+void ncplane_move_family_above(struct ncplane* RESTRICT n,
+                               struct ncplane* RESTRICT above);
+
+void ncplane_move_family_below(struct ncplane* RESTRICT n,
+                               struct ncplane* RESTRICT below);
 
 // Return the ncplane below this one, or NULL if this is at the stack's bottom.
 struct ncplane* ncplane_below(struct ncplane* n);

doc/man/man3/notcurses_plane.3.md

@@ -107,6 +107,10 @@ typedef struct ncplane_options {
 
 **int ncplane_move_below(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
 
+**void ncplane_move_family_above(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
+
+**void ncplane_move_family_below(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
+
 **struct ncplane* ncplane_below(struct ncplane* ***n***);**
 
 **struct ncplane* ncplane_above(struct ncplane* ***n***);**

include/notcurses/notcurses.h

@@ -1629,7 +1629,9 @@ ncplane_descendant_p(const struct ncplane* n, const struct ncplane* ancestor){
   return 1;
 }
 
-// Splice ncplane 'n' out of the z-buffer, and reinsert it at the top or bottom.
+// Splice ncplane 'n' out of the z-buffer, and reinsert it at the top or
+// bottom. FIXME these both become static inline wrappers around
+// ncplane_move_below() and ncplane_move_above() in ABI3.
 API void ncplane_move_top(struct ncplane* n)
   __attribute__ ((nonnull (1)));
 API void ncplane_move_bottom(struct ncplane* n)
@@ -1647,18 +1649,28 @@ API void ncplane_move_family_bottom(struct ncplane* n)
 
 // Splice ncplane 'n' out of the z-buffer, and reinsert it above 'above'.
 // Returns non-zero if 'n' is already in the desired location. 'n' and
-// 'above' must not be the same plane.
+// 'above' must not be the same plane. If 'above' is NULL, 'n' is moved
+// to the bottom of its pile.
 API int ncplane_move_above(struct ncplane* RESTRICT n,
                            struct ncplane* RESTRICT above)
   __attribute__ ((nonnull (1, 2)));
 
 // Splice ncplane 'n' out of the z-buffer, and reinsert it below 'below'.
 // Returns non-zero if 'n' is already in the desired location. 'n' and
-// 'below' must not be the same plane.
+// 'below' must not be the same plane. If 'below' is NULL, 'n' is moved to
+// the top of its pile.
 API int ncplane_move_below(struct ncplane* RESTRICT n,
                            struct ncplane* RESTRICT below)
   __attribute__ ((nonnull (1, 2)));
 
+API void ncplane_move_family_above(struct ncplane* RESTRICT n,
+                                   struct ncplane* RESTRICT above)
+  __attribute__ ((nonnull (1, 2)));
+
+API void ncplane_move_family_below(struct ncplane* RESTRICT n,
+                                   struct ncplane* RESTRICT below)
+  __attribute__ ((nonnull (1, 2)));
+
 // Return the plane below this one, or NULL if this is at the bottom.
 API struct ncplane* ncplane_below(struct ncplane* n)
   __attribute__ ((nonnull (1)));

src/lib/in.c

@@ -689,6 +689,7 @@ bgdef_cb(inputctx* ictx){
         r = g = b = 0;
       }
       ictx->initdata->bg = (r << 16u) | (g << 8u) | b;
+      ictx->initdata->got_bg = true;
       loginfo("default background 0x%02x%02x%02x\n", r, g, b);
       free(str);
     }

src/lib/in.h

@@ -60,6 +60,7 @@ struct initial_responses {
   queried_terminals_e qterm;   // determined terminal
   unsigned kitty_graphics;     // kitty graphics supported
   uint32_t bg;                 // default background
+  bool got_bg;                 // have we read default background?
   int pixx;                    // screen geometry in pixels
   int pixy;                    // screen geometry in pixels
   int dimx;                    // screen geometry in cells