From 1c0a623b8b031b66b69e0d163a256a01a55a85b1 Mon Sep 17 00:00:00 2001 From: nick black Date: Wed, 13 Jan 2021 04:49:55 -0500 Subject: [PATCH] document new function ncplane_abs_yx() #1286 --- NEWS.md | 3 +++ USAGE.md | 10 +++++++--- doc/man/man3/notcurses_plane.3.md | 8 ++++++++ include/notcurses/notcurses.h | 10 +++++++--- 4 files changed, 25 insertions(+), 6 deletions(-) diff --git a/NEWS.md b/NEWS.md index e38488947..934db35f6 100644 --- a/NEWS.md +++ b/NEWS.md @@ -8,6 +8,9 @@ rearrangements of Notcurses. * `ncplane_putstr_yx()`, `ncplane_putstr_stained()`, and `ncplane_putnstr_yx()` now return the number of columns output, as long documented (they were mistakenly returning the number of bytes). + * `ncplane_abs_yx()` has been added, returning the absolute coordinates of + the plane's origin (i.e. coordinates relative to its pile). This call is + O(N) on the binding depth of the plane in question. * 2.1.4 (2021-01-03): * Direct mode now supports `NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS`, and by diff --git a/USAGE.md b/USAGE.md index b89a25f04..7dd5b955a 100644 --- a/USAGE.md +++ b/USAGE.md @@ -802,12 +802,16 @@ ncplane_resize_simple(struct ncplane* n, int ylen, int xlen){ // standard plane. int ncplane_move_yx(struct ncplane* n, int y, int x); -// Get the origin of this plane relative to the standard plane, or the plane to -// which it is bound (if it is bound to a plane). +// Get the origin of plane 'n' relative to its bound plane, or its pile (if +// 'n' is a root plane). void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict x); int ncplane_y(const struct ncplane* n); int ncplane_x(const struct ncplane* n); +// Get the origin of plane 'n' relative to its pile. This is O(N) on the +// binding depth of 'n'. Either or both of 'x' and y' may be NULL. +void ncplane_abs_yx(const struct ncplane* n, int* y, int* x); + // Return the dimensions of this ncplane. void ncplane_dim_yx(struct ncplane* n, int* restrict rows, int* restrict cols); @@ -826,7 +830,7 @@ ncplane_dim_x(const struct ncplane* n){ } // provided a coordinate relative to the origin of 'src', map it to the same -// absolute coordinate relative to thte origin of 'dst'. either or both of 'y' +// absolute coordinate relative to the origin of 'dst'. either or both of 'y' // and 'x' may be NULL. if 'dst' is NULL, it is taken to be the standard plane. void ncplane_translate(const struct ncplane* src, const struct ncplane* dst, int* restrict y, int* restrict x); diff --git a/doc/man/man3/notcurses_plane.3.md b/doc/man/man3/notcurses_plane.3.md index 717af9a7c..5e3c6d289 100644 --- a/doc/man/man3/notcurses_plane.3.md +++ b/doc/man/man3/notcurses_plane.3.md @@ -61,6 +61,8 @@ typedef struct ncplane_options { **int ncplane_x(const struct ncplane* ***n***);** +**void ncplane_abs_yx(const struct ncplane* ***n***, int* ***y***, int* ***x***);** + **struct ncplane* ncplane_parent(struct ncplane* ***n***);** **const struct ncplane* ncplane_parent_const(const struct ncplane* ***n***);** @@ -230,6 +232,12 @@ to multiple ncplanes. So long as all threads are readers, multiple threads may work with a single ncplane. A reading function is any which accepts a **const struct ncplane**. +**ncplane_yx** returns the coordinates of the specified plane's origin, relative +to the plane to which it is bound. Either or both of ***y*** and ***x*** may +be **NULL**. **ncplane_y** and **ncplane_x** allow a single component of this +location to be retrieved. **ncplane_abs_yx** returns the coordinates of the +specified plane's origin relative to its pile. + **ncplane_translate** translates coordinates expressed relative to the plane ***src***, and writes the coordinates of that cell relative to ***dst***. The cell need not intersect with ***dst***, though this will yield coordinates which are diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index 13889b131..d16dd7087 100644 --- a/include/notcurses/notcurses.h +++ b/include/notcurses/notcurses.h @@ -1164,7 +1164,7 @@ API struct ncplane* ncplane_reparent_family(struct ncplane* n, struct ncplane* n API struct ncplane* ncplane_dup(const struct ncplane* n, void* opaque); // provided a coordinate relative to the origin of 'src', map it to the same -// absolute coordinate relative to thte origin of 'dst'. either or both of 'y' +// absolute coordinate relative to the origin of 'dst'. either or both of 'y' // and 'x' may be NULL. if 'dst' is NULL, it is taken to be the standard plane. API void ncplane_translate(const struct ncplane* src, const struct ncplane* dst, int* RESTRICT y, int* RESTRICT x); @@ -1311,12 +1311,16 @@ API int ncplane_base(struct ncplane* n, nccell* c); // standard plane. API int ncplane_move_yx(struct ncplane* n, int y, int x); -// Get the origin of this plane relative to the standard plane, or the plane to -// which it is bound (if it is bound to a plane). +// Get the origin of plane 'n' relative to its bound plane, or pile (if 'n' is +// a root plane). To get absolute coordinates, use ncplane_abs_yx(). API void ncplane_yx(const struct ncplane* n, int* RESTRICT y, int* RESTRICT x); API int ncplane_y(const struct ncplane* n); API int ncplane_x(const struct ncplane* n); +// Get the origin of plane 'n' relative to its pile. This is O(N) on the +// binding depth of 'n'. Either or both of 'x' and y' may be NULL. +API void ncplane_abs_yx(const struct ncplane* n, int* RESTRICT y, int* RESTRICT x); + // Get the plane to which the plane 'n' is bound, if any. API struct ncplane* ncplane_parent(struct ncplane* n); API const struct ncplane* ncplane_parent_const(const struct ncplane* n);