blackbeard420/notcurses
1
0
Fork 0
mirror of https://github.com/dankamongmen/notcurses synced 2025-03-09 17:19:03 -04:00
Code Issues Projects Releases Wiki Activity

ncplane: flesh out API

Browse Source
This commit is contained in:
nick black 2019-11-22 22:47:12 -05:00
parent 826ddbc7c7
commit a8721df75a
No known key found for this signature in database
GPG Key ID: 5F43400C21CBFACC
4 changed files with 86 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
include/notcurses.h
View File

@ -13,6 +13,9 @@ const char* notcurses_version(void);
struct ncplane; // a drawable notcurses surface
struct notcurses; // notcurses state for a given terminal
// FIXME we'll need to expose this definition for ncplane_getwc()
struct cell; // the contents of a single cell on a single plane
// Configuration for notcurses_init().
typedef struct notcurses_options {
// The name of the terminfo database entry describing this terminal. If NULL,
@ -35,16 +38,40 @@ struct notcurses* notcurses_init(const notcurses_options* opts);
// Destroy a notcurses context.
int notcurses_stop(struct notcurses* nc);
// Make the physical screen match the virtual screen. Changes made to the
// virtual screen (i.e. most other calls) will not be visible until after a
// successful call to notcurses_render().
int notcurses_render(struct notcurses* nc);
// Refresh our idea of the terminal's dimensions, reshaping the standard plane
// if necessary. Without a call to this function following a terminal resize
// (as signaled via SIGWINCH), notcurses_render() might not function properly.
// Following a call to notcurses_resize(), any references to the standard plane
// ought be considered invalidated.
int notcurses_resize(struct notcurses* n);
// Get a reference to the standard plane (one matching our current idea of the
// terminal size) for this terminal. Invalidated following a call to
// notcurses_resize().
struct ncplane* notcurses_stdplane(struct notcurses* nc);
const struct ncplane* notcurses_stdplane_const(const struct notcurses* nc);
// Make the physical screen match the virtual screen. Changes made to the
// virtual screen (i.e. most other calls) will not be visible until after a
// successful call to notcurses_render().
int notcurses_render(struct notcurses* nc);
// Create a new plane at the specified offset (relative to the standard plane)
// and the specified size. The number of rows and columns must both be positive.
// This plane is initially at the top of the z-buffer, as if ncplane_move_top()
// had been called on it. The void* 'opaque' can be retrieved (and reset) later.
struct ncplane* notcurses_newplane(struct notcurses* nc, int rows, int cols,
int yoff, int xoff, void* opaque);
// 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.
int ncplane_destroy(struct ncplane* n);
// Manipulate the opaque user pointer associated with this plane.
void ncplane_set_userptr(struct ncplane* n, void* opaque);
void* ncplane_userptr(struct ncplane* n);
const void* ncplane_userptr_const(const struct ncplane* n);
// Returns the dimensions of this ncplane.
void ncplane_dimyx(const struct ncplane* n, int* rows, int* cols);
@ -55,26 +82,49 @@ notcurses_term_dimyx(const struct notcurses* n, int* rows, int* cols){
ncplane_dimyx(notcurses_stdplane_const(n), rows, cols);
}
// Refresh our idea of the terminal's dimensions, reshaping the standard plane
// if necessary. Without a call to this function following a terminal resize
// (as signaled via SIGWINCH), notcurses_render() might not function properly.
// Following a call to notcurses_resize(), any references to the standard plane
// ought be considered invalidated.
int notcurses_resize(struct notcurses* n);
// Move the cursor to the specified position (the cursor needn't be visible).
// Returns -1 on error, including negative parameters, or ones exceeding the
// plane's dimensions.
int ncplane_movyx(struct ncplane* n, int y, int x);
int ncplane_cursor_move_yx(struct ncplane* n, int y, int x);
// Get the current position of the cursor within n. y and/or x may be NULL.
void ncplane_posyx(const struct ncplane* n, int* y, int* x);
void ncplane_cursor_yx(const struct ncplane* n, int* y, int* x);
// Move this plane relative to the standard plane.
int ncplane_move_yx(struct ncplane* n, int y, int x);
// Get the origin of this plane relative to the standard plane.
void ncplane_yx(const struct ncplane* n, int* y, int* x);
// Splice ncplane 'n' out of the z-buffer, and reinsert it above 'above'.
void ncplane_move_above(struct ncplane* n, struct ncplane* above);
// Splice ncplane 'n' out of the z-buffer, and reinsert it below 'below'.
void ncplane_move_below(struct ncplane* n, struct ncplane* below);
// Splice ncplane 'n' out of the z-buffer, and reinsert it at the top or bottom.
void ncplane_move_top(struct ncplane* n);
void ncplane_move_bottom(struct ncplane* n);
// Set the current cell in the specified plane to the provided wchar_t array.
// The array must not be more than one column worth of wchar_t's, among other
// restrictions. Advances the cursor by one cell.
int ncplane_putwc(struct ncplane* n, const wchar_t* wcs);
// Retrieve the cell under the cursor, returning it in 'c'.
void ncplane_getwc(const struct ncplane* n, struct cell* c);
// Write a series of wchar_ts to the current location. They will be interpreted
// as a series of columns (according to the definition of ncplane_putwc()).
// Advances the cursor by some positive number of cells; this number is returned
// on success. On error, a non-positive number is returned, indicating the
// number of cells which were written before the error.
int ncplane_putwstr(struct ncplane* n, const wchar_t* wstr);
// The ncplane equivalent of wprintf(3) and vwprintf(3), themselves the
// wide-character equivalents of printf(3) and vprintf(3).
int ncplane_wprintf(struct ncplane* n, const wchar_t* format, ...);
// Set the current fore/background color using RGB specifications. If the
// terminal does not support directly-specified 3x8b cells (24-bit "Direct
// Color", indicated by the "RGB" terminfo capability), the provided values

2
src/bin/demo.c
View File

@ -26,7 +26,7 @@ int main(void){
}
int x, cols;
ncplane_dimyx(ncp, NULL, &cols);
if(ncplane_movyx(ncp, 1, 1)){
if(ncplane_cursor_move_yx(ncp, 1, 1)){
goto err;
}
for(x = 1 ; x < cols - 1 ; ++x){

4
src/lib/notcurses.c
View File

@ -497,7 +497,7 @@ int notcurses_render(notcurses* nc){
return ret;
}
int ncplane_movyx(ncplane* n, int y, int x){
int ncplane_cursor_move_yx(ncplane* n, int y, int x){
if(x >= n->lenx || x < 0){
return -1;
}
@ -509,7 +509,7 @@ int ncplane_movyx(ncplane* n, int y, int x){
return 0;
}
void ncplane_posyx(const ncplane* n, int* y, int* x){
void ncplane_cursor_yx(const ncplane* n, int* y, int* x){
if(y){
*y = n->y;
}

40
tests/ncplane.cpp
View File

@ -29,7 +29,7 @@ class NcplaneTest : public :: testing::Test {
// Starting position ought be 0, 0 (the origin)
TEST_F(NcplaneTest, StdPlanePosition) {
int x, y;
ncplane_posyx(n_, &y, &x);
ncplane_cursor_yx(n_, &y, &x);
EXPECT_EQ(0, x);
EXPECT_EQ(0, y);
}
@ -48,21 +48,21 @@ TEST_F(NcplaneTest, StdPlaneDimensions) {
TEST_F(NcplaneTest, MoveStdPlaneDimensions) {
int cols, rows;
notcurses_term_dimyx(nc_, &rows, &cols);
EXPECT_EQ(0, ncplane_movyx(n_, 0, 0));
EXPECT_EQ(0, ncplane_cursor_move_yx(n_, 0, 0));
int x, y;
ncplane_posyx(n_, &y, &x);
ncplane_cursor_yx(n_, &y, &x);
EXPECT_EQ(y, 0);
EXPECT_EQ(x, 0);
EXPECT_EQ(0, ncplane_movyx(n_, rows - 1, 0));
ncplane_posyx(n_, &y, &x);
EXPECT_EQ(0, ncplane_cursor_move_yx(n_, rows - 1, 0));
ncplane_cursor_yx(n_, &y, &x);
EXPECT_EQ(y, rows - 1);
EXPECT_EQ(x, 0);
EXPECT_EQ(0, ncplane_movyx(n_, rows - 1, cols - 1));
ncplane_posyx(n_, &y, &x);
EXPECT_EQ(0, ncplane_cursor_move_yx(n_, rows - 1, cols - 1));
ncplane_cursor_yx(n_, &y, &x);
EXPECT_EQ(y, rows - 1);
EXPECT_EQ(x, cols - 1);
EXPECT_EQ(0, ncplane_movyx(n_, 0, cols - 1));
ncplane_posyx(n_, &y, &x);
EXPECT_EQ(0, ncplane_cursor_move_yx(n_, 0, cols - 1));
ncplane_cursor_yx(n_, &y, &x);
EXPECT_EQ(y, 0);
EXPECT_EQ(x, cols - 1);
}
@ -71,16 +71,16 @@ TEST_F(NcplaneTest, MoveStdPlaneDimensions) {
TEST_F(NcplaneTest, MoveBeyondPlaneFails) {
int cols, rows;
notcurses_term_dimyx(nc_, &rows, &cols);
EXPECT_NE(0, ncplane_movyx(n_, -1, 0));
EXPECT_NE(0, ncplane_movyx(n_, -1, -1));
EXPECT_NE(0, ncplane_movyx(n_, 0, -1));
EXPECT_NE(0, ncplane_movyx(n_, rows - 1, -1));
EXPECT_NE(0, ncplane_movyx(n_, rows, 0));
EXPECT_NE(0, ncplane_movyx(n_, rows + 1, 0));
EXPECT_NE(0, ncplane_movyx(n_, rows, cols));
EXPECT_NE(0, ncplane_movyx(n_, -1, cols - 1));
EXPECT_NE(0, ncplane_movyx(n_, 0, cols));
EXPECT_NE(0, ncplane_movyx(n_, 0, cols + 1));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, -1, 0));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, -1, -1));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, 0, -1));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, rows - 1, -1));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, rows, 0));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, rows + 1, 0));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, rows, cols));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, -1, cols - 1));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, 0, cols));
EXPECT_NE(0, ncplane_cursor_move_yx(n_, 0, cols + 1));
}
TEST_F(NcplaneTest, SetPlaneRGB) {
@ -104,7 +104,7 @@ TEST_F(NcplaneTest, EmitWchar) {
wchar_t cchar[] = L"✔";
EXPECT_EQ(0, ncplane_putwc(n_, cchar));
int x, y;
ncplane_posyx(n_, &y, &x);
ncplane_cursor_yx(n_, &y, &x);
EXPECT_EQ(y, 0);
EXPECT_EQ(x, 1);
}