From c68db9963d4cbedacc2a0a29fc6cafe8bcc92432 Mon Sep 17 00:00:00 2001 From: nick black Date: Mon, 13 Jan 2025 23:04:11 -0500 Subject: [PATCH] export ncplane_family_destroy() #2839 --- NEWS.md | 3 +++ USAGE.md | 9 +++++++++ doc/man/man3/notcurses_plane.3.md | 4 +++- include/notcurses/notcurses.h | 10 +++++++--- src/lib/internal.h | 3 --- src/lib/notcurses.c | 4 ++-- src/lib/reel.c | 18 +++++++++--------- src/lib/tabbed.c | 4 ++-- 8 files changed, 35 insertions(+), 20 deletions(-) diff --git a/NEWS.md b/NEWS.md index c3b28bdc3..1454e8188 100644 --- a/NEWS.md +++ b/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 diff --git a/USAGE.md b/USAGE.md index 992ca249e..8bc5d5e10 100644 --- a/USAGE.md +++ b/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*)); diff --git a/doc/man/man3/notcurses_plane.3.md b/doc/man/man3/notcurses_plane.3.md index 37eff3bd1..34d91b225 100644 --- a/doc/man/man3/notcurses_plane.3.md +++ b/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***);** diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index dd1a0a63d..fd6f01dba 100644 --- a/include/notcurses/notcurses.h +++ b/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 -// the next call to notcurses_render(). It is an error to attempt to destroy -// the standard plane. +// 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. 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))); diff --git a/src/lib/internal.h b/src/lib/internal.h index 49a08bbba..2ad909e17 100644 --- a/src/lib/internal.h +++ b/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){ diff --git a/src/lib/notcurses.c b/src/lib/notcurses.c index 6d0f83e8d..1228d206e 100644 --- a/src/lib/notcurses.c +++ b/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; diff --git a/src/lib/reel.c b/src/lib/reel.c index ec6fb84b7..66a716f72 100644 --- a/src/lib/reel.c +++ b/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); diff --git a/src/lib/tabbed.c b/src/lib/tabbed.c index 7dc20f49e..5b4bfb6a3 100644 --- a/src/lib/tabbed.c +++ b/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); }