diff --git a/NEWS.md b/NEWS.md index 2b65d6dd5..3a9299e9c 100644 --- a/NEWS.md +++ b/NEWS.md @@ -5,6 +5,7 @@ rearrangements of Notcurses. * `notcurses_detected_terminal()` and `ncdirect_detected_terminal()` now both return a heap-allocated string, which will contain the terminal version if Notcurses was able to detect it. This result ought be free()d. + * Added `ncplane_moverel()`. * 2.3.8 (2021-07-04) * Marked all capability functions `__attribute__ ((pure))`. If you were diff --git a/USAGE.md b/USAGE.md index dafcf6680..bad3ceac5 100644 --- a/USAGE.md +++ b/USAGE.md @@ -917,6 +917,15 @@ ncplane_resize_simple(struct ncplane* n, int ylen, int xlen){ // standard plane. Specifying a coordinate as -1 will hold it constant. int ncplane_move_yx(struct ncplane* n, int y, int x); +// Move this plane relative to its current location. Negative values move up +// and left, respectively. Pass 0 to hold an axis constant. +__attribute__ ((nonnull (1))) static inline int +ncplane_moverel(struct ncplane* n, int y, int x){ + int oy, ox; + ncplane_yx(n, &oy, &ox); + return ncplane_move_yx(n, oy + y, ox + x); +} + // 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); diff --git a/doc/man/man3/notcurses_plane.3.md b/doc/man/man3/notcurses_plane.3.md index 265450c31..38015f5c3 100644 --- a/doc/man/man3/notcurses_plane.3.md +++ b/doc/man/man3/notcurses_plane.3.md @@ -70,6 +70,8 @@ typedef struct ncplane_options { **int ncplane_move_yx(struct ncplane* ***n***, int ***y***, int ***x***);** +**int ncplane_moverel(struct ncplane* ***n***, int ***y***, int ***x***);** + **void ncplane_yx(const struct ncplane* ***n***, int* restrict ***y***, int* restrict ***x***);** **int ncplane_y(const struct ncplane* ***n***);** diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index ed7c21bd1..6a6cd580a 100644 --- a/include/notcurses/notcurses.h +++ b/include/notcurses/notcurses.h @@ -1490,11 +1490,6 @@ API int ncplane_set_base(struct ncplane* n, const char* egc, // 'ncp' is destroyed. API int ncplane_base(struct ncplane* n, nccell* c); -// Move this plane relative to the standard plane, or the plane to which it is -// bound (if it is bound to a plane). It is an error to attempt to move the -// standard plane. Specifying a coordinate as -1 will hold it constant. -API int ncplane_move_yx(struct ncplane* n, int y, int x); - // 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) @@ -1502,6 +1497,20 @@ API void ncplane_yx(const struct ncplane* n, int* RESTRICT y, int* RESTRICT x) API int ncplane_y(const struct ncplane* n) __attribute__ ((pure)); API int ncplane_x(const struct ncplane* n) __attribute__ ((pure)); +// Move this plane relative to the standard plane, or the plane to which it is +// bound (if it is bound to a plane). It is an error to attempt to move the +// standard plane. Specifying a coordinate as -1 will hold it constant. +API int ncplane_move_yx(struct ncplane* n, int y, int x); + +// Move this plane relative to its current location. Negative values move up +// and left, respectively. Pass 0 to hold an axis constant. +__attribute__ ((nonnull (1))) static inline int +ncplane_moverel(struct ncplane* n, int y, int x){ + int oy, ox; + ncplane_yx(n, &oy, &ox); + return ncplane_move_yx(n, oy + y, ox + x); +} + // Get the origin of plane 'n' relative to its pile. 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)