export ncplane_family_destroy() #2839

NEWS.md

@@ -1,6 +1,9 @@
 This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
+* 3.0.14 (not yet released)
+  * `ncplane_family_destroy()` has been added to the API.
+
 * 3.0.13 (2025-01-11)
   * Fix regression when building with `USE_CXX=off`.
   * Use `distutils` from its own Python component rather than assuming

USAGE.md

@@ -863,6 +863,15 @@ struct ncplane* ncplane_reparent(struct ncplane* n, struct ncplane* newparent);
 // with it to its new destination. Their z-order is maintained.
 struct ncplane* ncplane_reparent_family(struct ncplane* n, struct ncplane* newparent);
 
+// Destroy ncplane 'n'. None of its contents will be visible after the next
+// call to notcurses_render(). It is an error to attempt to destroy the
+// standard plane. It is a noop if 'n' is NULL.
+int ncplane_destroy(struct ncplane* n);
+
+// Destroy ncplane 'n' and all its bound descendants. It is a noop if 'n'
+// is NULL. It is an error to attempt to destroy the standard plane.
+int ncplane_family_destroy(struct ncplane *n);
+
 // Replace the ncplane's existing resizecb with 'resizecb' (which may be NULL).
 void ncplane_set_resizecb(struct ncplane* n, int(*resizecb)(struct ncplane*));
 

doc/man/man3/notcurses_plane.3.md

@@ -205,7 +205,9 @@ typedef struct ncplane_options {
 
 **int ncplane_blit_rgba(struct ncplane* ***nc***, int ***placey***, int ***placex***, int ***linesize***, ncblitter_e ***blitter***, const unsigned char* ***data***, int ***begy***, int ***begx***, int ***leny***, int ***lenx***);**
 
-**int ncplane_destroy(struct ncplane* ***ncp***);**
+**int ncplane_destroy(struct ncplane* ***n***);**
+
+**int ncplane_family_destroy(struct ncplane ***n***);**
 
 **void notcurses_drop_planes(struct notcurses* ***nc***);**
 

include/notcurses/notcurses.h

@@ -1865,9 +1865,9 @@ ncplane_resize_simple(struct ncplane* n, unsigned ylen, unsigned xlen){
   return ncplane_resize(n, 0, 0, keepleny, keeplenx, 0, 0, ylen, xlen);
 }
 
-// Destroy the specified ncplane. None of its contents will be visible after
+// Destroy ncplane 'n'. None of its contents will be visible after the next
-// the next call to notcurses_render(). It is an error to attempt to destroy
+// call to notcurses_render(). It is an error to attempt to destroy the
-// the standard plane.
+// standard plane. It is a noop if 'n' is NULL.
 API int ncplane_destroy(struct ncplane* n);
 
 // Set the ncplane's base nccell to 'c'. The base cell is used for purposes of
@@ -1984,6 +1984,10 @@ ncplane_move_family_bottom(struct ncplane* n){
   ncplane_move_family_above(n, NULL);
 }
 
+// Destroy ncplane 'n' and all its bound descendants. It is a noop if 'n'
+// is NULL. It is an error to attempt to destroy the standard plane.
+API int ncplane_family_destroy(struct ncplane *n);
+
 // 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/internal.h

@@ -1287,9 +1287,6 @@ cell_set_blitquadrants(nccell* c, unsigned tl, unsigned tr, unsigned bl, unsigne
   c->channels = ((c->channels & ~NC_BLITTERSTACK_MASK) | newval);
 }
 
-// Destroy a plane and all its bound descendants.
-int ncplane_destroy_family(ncplane *ncp);
-
 // Extract the 32-bit background channel from a cell.
 static inline uint32_t
 cell_bchannel(const nccell* cl){

src/lib/notcurses.c

@@ -1065,7 +1065,7 @@ int ncplane_destroy(ncplane* ncp){
   return ret;
 }
 
-int ncplane_destroy_family(ncplane *ncp){
+int ncplane_family_destroy(ncplane *ncp){
   if(ncp == NULL){
     return 0;
   }
@@ -1075,7 +1075,7 @@ int ncplane_destroy_family(ncplane *ncp){
   }
   int ret = 0;
   while(ncp->blist){
-    ret |= ncplane_destroy_family(ncp->blist);
+    ret |= ncplane_family_destroy(ncp->blist);
   }
   ret |= ncplane_destroy(ncp);
   return ret;

src/lib/reel.c

@@ -239,7 +239,7 @@ static void
 nctablet_wipeout(nctablet* t){
   if(t){
     if(ncplane_set_widget(t->p, NULL, NULL) == 0){
-      ncplane_destroy_family(t->p);
+      ncplane_family_destroy(t->p);
     }
     t->p = NULL;
     t->cbp = NULL;
@@ -276,7 +276,7 @@ nctablet_delete_internal(struct nctablet* t){
   t->next->prev = t->prev;
   if(t->p){
     if(ncplane_set_widget(t->p, NULL, NULL) == 0){
-      ncplane_destroy_family(t->p);
+      ncplane_family_destroy(t->p);
     }
   }
   free(t);
@@ -379,7 +379,7 @@ ncreel_draw_tablet(const ncreel* nr, nctablet* t, int frontiertop,
       if(ll){ // must be smaller than the space we provided; add back bottom
         ncplane_resize_simple(t->cbp, ll, cblenx);
       }else{
-        ncplane_destroy_family(t->cbp);
+        ncplane_family_destroy(t->cbp);
         t->cbp = NULL;
       }
       // resize the borderplane iff we got smaller
@@ -491,7 +491,7 @@ trim_reel_overhang(ncreel* r, nctablet* top, nctablet* bottom){
 //fprintf(stderr, "top: %dx%d @ %d, miny: %d\n", ylen, xlen, y, miny);
   if(boty < miny){
 //fprintf(stderr, "NUKING top!\n");
-    ncplane_destroy_family(top->p);
+    ncplane_family_destroy(top->p);
     top->p = NULL;
     top->cbp = NULL;
     top = top->next;
@@ -499,7 +499,7 @@ trim_reel_overhang(ncreel* r, nctablet* top, nctablet* bottom){
   }else if(y < miny){
     int ynew = ylen - (miny - y);
     if(ynew <= 0){
-      ncplane_destroy_family(top->p);
+      ncplane_family_destroy(top->p);
       top->p = NULL;
       top->cbp = NULL;
     }else{
@@ -508,7 +508,7 @@ trim_reel_overhang(ncreel* r, nctablet* top, nctablet* bottom){
       }
       if(top->cbp){
         if(ynew == !(r->ropts.tabletmask & NCBOXMASK_TOP)){
-          ncplane_destroy_family(top->cbp);
+          ncplane_family_destroy(top->cbp);
           top->cbp = NULL;
         }else{
           ncplane_dim_yx(top->cbp, &ylen, &xlen);
@@ -532,7 +532,7 @@ trim_reel_overhang(ncreel* r, nctablet* top, nctablet* bottom){
     if(maxy < y){
   //fprintf(stderr, "NUKING bottom!\n");
       if(ncplane_set_widget(bottom->p, NULL, NULL) == 0){
-        ncplane_destroy_family(bottom->p);
+        ncplane_family_destroy(bottom->p);
       }
       bottom->p = NULL;
       bottom->cbp = NULL;
@@ -541,7 +541,7 @@ trim_reel_overhang(ncreel* r, nctablet* top, nctablet* bottom){
     }if(maxy < boty){
       int ynew = ylen - (boty - maxy);
       if(ynew <= 0){
-        ncplane_destroy_family(bottom->p);
+        ncplane_family_destroy(bottom->p);
         bottom->p = NULL;
         bottom->cbp = NULL;
       }else{
@@ -551,7 +551,7 @@ trim_reel_overhang(ncreel* r, nctablet* top, nctablet* bottom){
   //fprintf(stderr, "TRIMMED bottom %p from %d to %d (%d)\n", bottom->p, ylen, ynew, maxy - boty);
         if(bottom->cbp){
           if(ynew == !(r->ropts.tabletmask & NCBOXMASK_BOTTOM)){
-            ncplane_destroy_family(bottom->cbp);
+            ncplane_family_destroy(bottom->cbp);
             bottom->cbp = NULL;
           }else{
             ncplane_dim_yx(bottom->cbp, &ylen, &xlen);

src/lib/tabbed.c

@@ -220,7 +220,7 @@ nctabbed* nctabbed_create(ncplane* n, const nctabbed_options* topts){
   return nt;
 
 err:
-  ncplane_destroy_family(n);
+  ncplane_family_destroy(n);
   if(nt){
     free(nt->opts.separator);
     free(nt);
@@ -427,7 +427,7 @@ void nctabbed_destroy(nctabbed* nt){
       free(t);
       t = tmp;
     }
-    ncplane_destroy_family(nt->ncp);
+    ncplane_family_destroy(nt->ncp);
     free(nt->opts.separator);
     free(nt);
   }