From 9185ea000cca0f483fcbcb5eae2565427367cf33 Mon Sep 17 00:00:00 2001 From: nick black Date: Mon, 4 Oct 2021 20:46:47 -0400 Subject: [PATCH] add ncplane_set_name()/ncplane_name() + documentation --- NEWS.md | 1 + USAGE.md | 6 ++++++ doc/man/man3/notcurses_plane.3.md | 10 ++++++++++ include/notcurses/notcurses.h | 8 ++++++++ src/lib/notcurses.c | 16 ++++++++++++++++ 5 files changed, 41 insertions(+) diff --git a/NEWS.md b/NEWS.md index d89028176..52ddb313f 100644 --- a/NEWS.md +++ b/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 diff --git a/USAGE.md b/USAGE.md index c35dc1bff..ab114d023 100644 --- a/USAGE.md +++ b/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); diff --git a/doc/man/man3/notcurses_plane.3.md b/doc/man/man3/notcurses_plane.3.md index 6678c5d61..d4bd0c32b 100644 --- a/doc/man/man3/notcurses_plane.3.md +++ b/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**). diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index 8489a46c4..5a1cf7cff 100644 --- a/include/notcurses/notcurses.h +++ b/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' diff --git a/src/lib/notcurses.c b/src/lib/notcurses.c index a6d0f3f56..d60e09b2d 100644 --- a/src/lib/notcurses.c +++ b/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; }