diff --git a/USAGE.md b/USAGE.md index 6068eb966..60ca5c6cb 100644 --- a/USAGE.md +++ b/USAGE.md @@ -732,6 +732,10 @@ int ncplane_at_yx_cell(struct ncplane* n, int y, int x, cell* c); uint32_t* ncplane_rgba(const struct ncplane* nc, int begy, int begx, int leny, int lenx); +// return a nul-terminated, heap copy of the current (UTF-8) contents. +API char* ncplane_contents(const struct ncplane* nc, int begy, int begx, + int leny, int lenx); + // Manipulate the opaque user pointer associated with this plane. // ncplane_set_userptr() returns the previous userptr after replacing // it with 'opaque'. the others simply return the userptr. @@ -2131,7 +2135,7 @@ struct ncplane* ncreader_plane(struct ncreader* n); // are relevant to an ncreader, save synthesized ones. bool ncreader_offer_input(struct ncreader* n, const struct ncinput* ni); -// return a heap-allocated copy of the current (UTF-8) contents. +// return a nul-terminated heap copy of the current (UTF-8) contents. char* ncreader_contents(const struct ncreader* n); // destroy the reader and its bound plane. if 'contents' is not NULL, the diff --git a/doc/man/man3/notcurses_plane.3.md b/doc/man/man3/notcurses_plane.3.md index 75d8cc82f..1454e53b1 100644 --- a/doc/man/man3/notcurses_plane.3.md +++ b/doc/man/man3/notcurses_plane.3.md @@ -52,6 +52,8 @@ notcurses_plane - operations on ncplanes **uint32_t* ncplane_rgba(const struct ncplane* nc, int begy, int begx, int leny, int lenx);** +**char* ncplane_contents(const struct ncplane* nc, int begy, int begx, int leny, int lenx);** + **void* ncplane_set_userptr(struct ncplane* n, void* opaque);** **void* ncplane_userptr(struct ncplane* n);** diff --git a/include/ncpp/Plane.hh b/include/ncpp/Plane.hh index c8d6d329f..ac2a7205c 100644 --- a/include/ncpp/Plane.hh +++ b/include/ncpp/Plane.hh @@ -628,6 +628,16 @@ namespace ncpp return error_guard (ncplane_polyfill_yx (plane, y, x, c), -1); } + uint32_t* rgba(int begy, int begx, int leny, int lenx) const noexcept + { + return ncplane_rgba (plane, begy, begx, leny, lenx); + } + + char* content(int begy, int begx, int leny, int lenx) const noexcept + { + return ncplane_contents (plane, begy, begx, leny, lenx); + } + uint64_t get_channels () const noexcept { return ncplane_channels (plane); diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index 101a64406..d36e07277 100644 --- a/include/notcurses/notcurses.h +++ b/include/notcurses/notcurses.h @@ -1190,9 +1190,17 @@ ncplane_at_yx_cell(struct ncplane* n, int y, int x, cell* c){ // Start at the plane's 'begy'x'begx' coordinate (which must lie on the // plane), continuing for 'leny'x'lenx' cells. Either or both of 'leny' and // 'lenx' can be specified as -1 to go through the boundary of the plane. +// Only spaces, half blocks, and full blocks may be present. API uint32_t* ncplane_rgba(const struct ncplane* nc, int begy, int begx, int leny, int lenx); +// Create a flat string from the EGCs of the selected region of the ncplane +// 'nc'. Start at the plane's 'begy'x'begx' coordinate (which must lie on the +// plane), continuing for 'leny'x'lenx' cells. Either or both of 'leny' and +// 'lenx' can be specified as -1 to go through the boundary of the plane. +API char* ncplane_contents(const struct ncplane* nc, int begy, int begx, + int leny, int lenx); + // Manipulate the opaque user pointer associated with this plane. // ncplane_set_userptr() returns the previous userptr after replacing // it with 'opaque'. the others simply return the userptr. diff --git a/python/src/notcurses/build_notcurses.py b/python/src/notcurses/build_notcurses.py index 959114808..2dfa0c60e 100644 --- a/python/src/notcurses/build_notcurses.py +++ b/python/src/notcurses/build_notcurses.py @@ -142,6 +142,7 @@ int ncplane_at_cursor_cell(struct ncplane* n, cell* c); char* ncplane_at_yx(const struct ncplane* n, int y, int x, uint32_t* attrword, uint64_t* channels); int ncplane_at_yx_cell(struct ncplane* n, int y, int x, cell* c); uint32_t* ncplane_rgba(const struct ncplane* nc, int begy, int begx, int leny, int lenx); +char* ncplane_contents(const struct ncplane* nc, int begy, int begx, int leny, int lenx); void* ncplane_set_userptr(struct ncplane* n, void* opaque); void* ncplane_userptr(struct ncplane* n); int ncplane_resize(struct ncplane* n, int keepy, int keepx, int keepleny,