Archives/notcurses
2
0
Fork 0
mirror of https://github.com/dankamongmen/notcurses.git synced 2024-11-06 03:20:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

s/notcurses/Notcurses/g

Browse Source
This commit is contained in:
nick black 2020-10-12 09:44:03 -04:00
parent 4c15436de8
commit a44090a7f7
No known key found for this signature in database
GPG Key ID: 5F43400C21CBFACC
4 changed files with 53 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
README.md
View File

@ -191,10 +191,10 @@ necessary data files. It can be run by itself, or via `make test`.
## Differences from NCURSES
The biggest difference, of course, is that notcurses is not an implementation
The biggest difference, of course, is that Notcurses is not an implementation
of X/Open (aka XSI) Curses, nor part of SUS4-2018.
The detailed differences between notcurses and NCURSES probably can't be fully
The detailed differences between Notcurses and NCURSES probably can't be fully
enumerated, and if they could, no one would want to read them. With that said,
some design decisions might surprise NCURSES programmers:
@ -217,13 +217,13 @@ some design decisions might surprise NCURSES programmers:
mutate different `ncplane`s in different threads.
* NCURSES has thread-ignorant and thread-semi-safe versions, trace-enabled and
traceless versions, and versions with and without support for wide characters.
notcurses is one library: no tracing, UTF-8, thread safety.
* There is no `ESCDELAY` concept; notcurses expects that all bytes of a
Notcurses is one library: no tracing, UTF-8, thread safety.
* There is no `ESCDELAY` concept; Notcurses expects that all bytes of a
keyboard escape sequence arrive at the same time. This improves latency
and simplifies the API.
* It is an error in NCURSES to print to the bottommost, rightmost coordinate of
the screen when scrolling is disabled (because the cursor cannot be advanced).
Failure to advance the cursor does not result in an error in notcurses (but
Failure to advance the cursor does not result in an error in Notcurses (but
attempting to print at the cursor when it has been advanced off the plane
*does*).
@ -240,7 +240,7 @@ to implement".
### Adapting NCURSES programs
Do you really want to do such a thing? NCURSES and the Curses API it implements
are far more portable and better-tested than notcurses is ever likely to be.
are far more portable and better-tested than Notcurses is ever likely to be.
Will your program really benefit from notcurses's advanced features? If not,
it's probably best left as it is.
@ -296,7 +296,7 @@ These are pretty obvious, implementation-wise.
**Narrow**, heh.
* If you can disable BiDi in your terminal, do so while running notcurses
applications, until I have that handled better. notcurses doesn't recognize
applications, until I have that handled better. Notcurses doesn't recognize
the BiDi state machine transitions, and thus merrily continues writing
left-to-right. Likewise, ultra-wide glyphs will have interesting effects.
﷽!
@ -418,6 +418,8 @@ If things break or seem otherwise lackluster, **please** consult the
### History
* 2020-10-12: Notcurses [2.0.0 "stankonia"](https://github.com/dankamongmen/notcurses/releases/tag/v2.0.0).
* A stable API! Semantic versioning is now in effect. This API will be supported going forward.
* 2020-08-30: Notcurses [1.7.0 "don't pull the bang out"](https://github.com/dankamongmen/notcurses/releases/tag/v1.7.0).
* 2020-07-04: Notcurses [1.6.0 "aquemini"](https://github.com/dankamongmen/notcurses/releases/tag/v1.6.0).
* 2020-07-03: Notcurses is [accepted into Alpine Edge](https://gitlab.alpinelinux.org/alpine/aports/-/merge_requests/9924).
@ -437,8 +439,7 @@ If things break or seem otherwise lackluster, **please** consult the
* 2019-01-04: Notcurses [1.0.0 "track team, crack fiend, dying to geek"](https://github.com/dankamongmen/notcurses/releases/tag/v1.0.0)
is released, six days ahead of schedule. 147 issues closed. 702 commits.
* 2019-12-18: Notcurses [0.9.0 "You dig in! You dig out! You get out!"](https://github.com/dankamongmen/notcurses/releases/tag/v0.9.0),
and also the first contributor besides myself (@grendello). Last major
pre-GA release.
and also the first contributor besides myself (@grendello). Last major pre-GA release.
* 2019-12-05: Notcurses [0.4.0 "TRAP MUSIC ALL NIGHT LONG"](https://github.com/dankamongmen/notcurses/releases/tag/v0.4.0),
the first generally usable notcurses.
* I prepare a [demo](https://www.youtube.com/watch?v=eEv2YRyiEVM), and release it on YouTube.

48
USAGE.md
View File

@ -1,7 +1,7 @@
# Usage
The notcurses API is not yet stable, though it is becoming so. Starting with
version 2, notcurses will honor Semantic Versioning.
As of version 2.0.0, Notcurses honors Semantic Versioning, the API is stable,
and the project is committed to backwards compatibility.
* [Direct Mode](#direct-mode)
* [Alignment](#alignment)
@ -16,7 +16,7 @@ version 2, notcurses will honor Semantic Versioning.
* [C++](#c++)
A full API reference [is available](https://nick-black.com/notcurses/). Manual
pages ought have been installed along with notcurses. This document is a
pages ought have been installed along with Notcurses. This document is a
secondary reference, and should not be considered authoritative. For a more
unified commentary, consider the [paperback](https://www.amazon.com/dp/B086PNVNC9)
(also available as a free PDF from https://nick-black.com).
@ -48,7 +48,7 @@ supplied a struct of type `notcurses_options`:
// Get a human-readable string describing the running Notcurses version.
const char* notcurses_version(void);
// Cannot be inline, as we want to get the versions of the actual notcurses
// Cannot be inline, as we want to get the versions of the actual Notcurses
// library we loaded, not what we compile against.
void notcurses_version_components(int* major, int* minor, int* patch, int* tweak);
@ -58,7 +58,7 @@ struct notcurses; // Notcurses state for a given terminal, composed of ncplanes
// These log levels consciously map cleanly to those of libav; Notcurses itself
// does not use this full granularity. The log level does not affect the opening
// and closing banners, which can be disabled via the notcurses_option struct's
// and closing banners, which can be disabled via the Notcurses_option struct's
// 'suppress_banner'. Note that if stderr is connected to the same terminal on
// which we're rendering, any kind of logging will disrupt the output.
typedef enum {
@ -104,7 +104,7 @@ typedef enum {
// info in notcurses_stop(). This inhibits that output.
#define NCOPTION_SUPPRESS_BANNERS 0x0020
// If smcup/rmcup capabilities are indicated, notcurses defaults to making use
// If smcup/rmcup capabilities are indicated, Notcurses defaults to making use
// of the "alternate screen". This flag inhibits use of smcup/rmcup.
#define NCOPTION_NO_ALTERNATE_SCREEN 0x0040
@ -112,7 +112,7 @@ typedef enum {
typedef struct notcurses_options {
// The name of the terminfo database entry describing this terminal. If NULL,
// the environment variable TERM is used. Failure to open the terminal
// definition will result in failure to initialize notcurses.
// definition will result in failure to initialize Notcurses.
const char* termtype;
// If non-NULL, notcurses_render() will write each rendered frame to this
// FILE* in addition to outfp. This is used primarily for debugging.
@ -131,18 +131,18 @@ typedef struct notcurses_options {
uint64_t flags;
} notcurses_options;
// Lex a margin argument according to the standard notcurses definition. There
// Lex a margin argument according to the standard Notcurses definition. There
// can be either a single number, which will define all margins equally, or
// there can be four numbers separated by commas.
int notcurses_lex_margins(const char* op, notcurses_options* opts);
// Initialize a notcurses context on the connected terminal at 'fp'. 'fp' must
// Initialize a Notcurses context on the connected terminal at 'fp'. 'fp' must
// be a tty. You'll usually want stdout. NULL can be supplied for 'fp', in
// which case /dev/tty will be opened. Returns NULL on error, including any
// failure initializing terminfo.
struct notcurses* notcurses_init(const notcurses_options* opts, FILE* fp);
// Destroy a notcurses context.
// Destroy a Notcurses context.
int notcurses_stop(struct notcurses* nc);
```
@ -161,7 +161,7 @@ command line option or environment variable). Developers and motivated users
might appreciate the ability to manipulate `loglevel` and `renderfp`. The
remaining options are typically of use only to application authors.
The notcurses API draws almost entirely into the virtual buffers of `ncplane`s.
The Notcurses API draws almost entirely into the virtual buffers of `ncplane`s.
Only upon a call to `notcurses_render` will the visible terminal display be
updated to reflect the changes:
@ -277,7 +277,7 @@ bool notcurses_cansixel(const struct notcurses* nc);
## Direct mode
"Direct mode" makes a limited subset of notcurses is available for manipulating
"Direct mode" makes a limited subset of Notcurses is available for manipulating
typical scrolling or file-backed output. Its functions are exported via
`<notcurses/direct.h>`, and output directly and immediately to the provided
`FILE*`. `notcurses_render()` is neither supported nor necessary for such an
@ -286,9 +286,9 @@ instance. Use `ncdirect_init()` to create a direct mode context:
```c
struct ncdirect; // minimal state for a terminal
// Initialize a direct-mode notcurses context on the connected terminal at 'fp'.
// Initialize a direct-mode Notcurses context on the connected terminal at 'fp'.
// 'fp' must be a tty. You'll usually want stdout. Direct mode supportes a
// limited subset of notcurses routines which directly affect 'fp', and neither
// limited subset of Notcurses routines which directly affect 'fp', and neither
// supports nor requires notcurses_render(). This can be used to add color and
// styling to text in the standard output paradigm. 'flags' is a bitmask over
// NCDIRECT_OPTION_*.
@ -455,7 +455,7 @@ needn't be a terminal device (unlike the ttyfp `FILE*` passed to `notcurses_init
Generalized input ought happen soon. There is only one input queue per `struct
notcurses`.
Like NCURSES, notcurses will watch for escape sequences, check them against the
Like NCURSES, Notcurses will watch for escape sequences, check them against the
terminfo database, and return them as special keys (we hijack the Private Use
Area for special keys, specifically Supplementary Private Use Area B (u100000
through u10ffffd). Unlike NCURSES, the fundamental unit of input is the
@ -466,7 +466,7 @@ It is generally possible for a false positive to occur, wherein keypresses
intended to be distinct are combined into an escape sequence. False negatives
where an intended escape sequence are read as an ESC key followed by distinct
keystrokes are also possible. NCURSES provides the `ESCDELAY` variable to
control timing. notcurses brooks no delay; all characters of an escape sequence
control timing. Notcurses brooks no delay; all characters of an escape sequence
must be readable without delay for it to be interpreted as such.
```c
@ -608,7 +608,7 @@ with coordinate information in the `ncinput` struct.
## Planes
Fundamental to notcurses is a z-buffer of rectilinear virtual screens, known
Fundamental to Notcurses is a z-buffer of rectilinear virtual screens, known
as `ncplane`s. An `ncplane` can be larger than the physical screen, or smaller,
or the same size; it can be entirely contained within the physical screen, or
overlap in part, or lie wholly beyond the boundaries, never to be rendered.
@ -1484,7 +1484,7 @@ ncplane_bg_rgb8(const struct ncplane* n, unsigned* r, unsigned* g, unsigned*
// indicated by the "RGB" terminfo capability), the provided values will be
// interpreted in some lossy fashion. None of r, g, or b may exceed 255.
// "HP-like" terminals require setting foreground and background at the same
// time using "color pairs"; notcurses will manage color pairs transparently.
// time using "color pairs"; Notcurses will manage color pairs transparently.
int ncplane_set_fg_rgb8(struct ncplane* n, int r, int g, int b);
int ncplane_set_bg_rgb8(struct ncplane* n, int r, int g, int b);
@ -1904,7 +1904,7 @@ cell_set_bg_default(cell* c){
ncreels are a complex UI abstraction offered by notcurses, derived from my
similar work in [outcurses](https://github.com/dankamongmen/ncreels#ncreels).
The ncreel is a UI abstraction supported by notcurses in which
The ncreel is a UI abstraction supported by Notcurses in which
dynamically-created and -destroyed toplevel entities (referred to as tablets)
are arranged as if on a cylinder, allowing for infinite scrolling
(infinite scrolling can be disabled, resulting in a rectangle rather than a
@ -1923,12 +1923,12 @@ optional borders around tablets and the optional border of the reel itself. It
knows nothing about the actual content of a tablet, save the number of lines it
occupies at each information depth. The typical control flow is that an
application receives events (from the UI or other event sources), and calls
into notcurses saying e.g. "Tablet 2 now has 40 valid lines of information".
into Notcurses saying e.g. "Tablet 2 now has 40 valid lines of information".
notcurses might then call back into the application, asking it to draw some
line(s) from some tablet(s) at some particular coordinate of that tablet's
plane. Finally, control returns to the application, and the cycle starts anew.
Each tablet might be wholly, partially, or not on-screen. notcurses always
Each tablet might be wholly, partially, or not on-screen. Notcurses always
places as much of the focused tablet as is possible on-screen (if the focused
tablet has more lines than the actual reel does, it cannot be wholly on-screen.
In this case, the focused subelements of the tablet are always on-screen). The
@ -1971,7 +1971,7 @@ not fill it). If it is not desired, however, scrolling of focus can be
configured instead.
```c
// An ncreel is a notcurses region devoted to displaying zero or more
// An ncreel is a Notcurses region devoted to displaying zero or more
// line-oriented, contained tablets between which the user may navigate. If at
// least one tablets exists, there is a "focused tablet". As much of the focused
// tablet as is possible is always displayed. If there is space left over, other
@ -1991,7 +1991,7 @@ configured instead.
#define NCREEL_OPTION_CIRCULAR 0x0002ull
typedef struct ncreel_options {
// notcurses can draw a border around the ncreel, and also around the
// Notcurses can draw a border around the ncreel, and also around the
// component tablets. inhibit borders by setting all valid bits in the masks.
// partially inhibit borders by setting individual bits in the masks. the
// appropriate attr and pair values will be used to style the borders.
@ -2867,7 +2867,7 @@ typedef struct ncstats {
// future versions of Notcurses might enlarge this structure.
ncstats* notcurses_stats_alloc(const struct notcurses* nc);
// Acquire an atomic snapshot of the notcurses object's stats.
// Acquire an atomic snapshot of the Notcurses object's stats.
void notcurses_stats(const struct notcurses* nc, ncstats* stats);
// Reset all cumulative stats (immediate ones, such as fbbytes, are not reset).

6
include/notcurses/direct.h
View File

@ -23,9 +23,9 @@ extern "C" {
// echo and line buffering are turned off.
#define NCDIRECT_OPTION_INHIBIT_CBREAK 0x0002ull
// Initialize a direct-mode notcurses context on the connected terminal at 'fp'.
// Initialize a direct-mode Notcurses context on the connected terminal at 'fp'.
// 'fp' must be a tty. You'll usually want stdout. Direct mode supportes a
// limited subset of notcurses routines which directly affect 'fp', and neither
// limited subset of Notcurses routines which directly affect 'fp', and neither
// supports nor requires notcurses_render(). This can be used to add color and
// styling to text in the standard output paradigm. 'flags' is a bitmask over
// NCDIRECT_OPTION_*.
@ -34,7 +34,7 @@ API struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t flag
// Direct mode. This API can be used to colorize and stylize output generated
// outside of notcurses, without ever calling notcurses_render(). These should
// not be intermixed with standard notcurses rendering.
// not be intermixed with standard Notcurses rendering.
API int ncdirect_fg_rgb(struct ncdirect* nc, unsigned rgb);
API int ncdirect_bg_rgb(struct ncdirect* nc, unsigned rgb);

32
include/notcurses/notcurses.h
View File

@ -32,14 +32,14 @@ extern "C" {
#define API __attribute__((visibility("default")))
// Get a human-readable string describing the running notcurses version.
// Get a human-readable string describing the running Notcurses version.
API const char* notcurses_version(void);
// Cannot be inline, as we want to get the versions of the actual notcurses
// Cannot be inline, as we want to get the versions of the actual Notcurses
// library we loaded, not what we compile against.
API void notcurses_version_components(int* major, int* minor, int* patch, int* tweak);
struct notcurses; // notcurses state for a given terminal, composed of ncplanes
struct ncplane; // a drawable notcurses surface, composed of cells
struct notcurses; // Notcurses state for a given terminal, composed of ncplanes
struct ncplane; // a drawable Notcurses surface, composed of cells
struct cell; // a coordinate on an ncplane: an EGC plus styling
struct ncvisual; // a visual bit of multimedia opened with LibAV|OIIO
struct ncuplot; // a histogram, bound to a plane (uint64_ts)
@ -733,7 +733,7 @@ cell_load_char(struct ncplane* n, cell* c, char ch){
return 1;
}
// These log levels consciously map cleanly to those of libav; notcurses itself
// These log levels consciously map cleanly to those of libav; Notcurses itself
// does not use this full granularity. The log level does not affect the opening
// and closing banners, which can be disabled via the notcurses_option struct's
// 'suppress_banner'. Note that if stderr is connected to the same terminal on
@ -783,7 +783,7 @@ typedef enum {
// info in notcurses_stop(). This inhibits that output.
#define NCOPTION_SUPPRESS_BANNERS 0x0020ull
// If smcup/rmcup capabilities are indicated, notcurses defaults to making use
// If smcup/rmcup capabilities are indicated, Notcurses defaults to making use
// of the "alternate screen". This flag inhibits use of smcup/rmcup.
#define NCOPTION_NO_ALTERNATE_SCREEN 0x0040ull
@ -816,7 +816,7 @@ typedef struct notcurses_options {
uint64_t flags;
} notcurses_options;
// Lex a margin argument according to the standard notcurses definition. There
// Lex a margin argument according to the standard Notcurses definition. There
// can be either a single number, which will define all margins equally, or
// there can be four numbers separated by commas.
API int notcurses_lex_margins(const char* op, notcurses_options* opts);
@ -833,13 +833,13 @@ API int notcurses_lex_scalemode(const char* op, ncscale_e* scalemode);
// Get the name of a scaling mode.
API const char* notcurses_str_scalemode(ncscale_e scalemode);
// Initialize a notcurses context on the connected terminal at 'fp'. 'fp' must
// Initialize a Notcurses context on the connected terminal at 'fp'. 'fp' must
// be a tty. You'll usually want stdout. NULL can be supplied for 'fp', in
// which case /dev/tty will be opened. Returns NULL on error, including any
// failure initializing terminfo.
API struct notcurses* notcurses_init(const notcurses_options* opts, FILE* fp);
// Destroy a notcurses context.
// Destroy a Notcurses context.
API int notcurses_stop(struct notcurses* nc);
// Make the physical screen match the virtual screen. Changes made to the
@ -953,7 +953,7 @@ API int notcurses_mouse_disable(struct notcurses* n);
// NCKEY_RESIZE event has been read and you're not yet ready to render.
API int notcurses_refresh(struct notcurses* n, int* RESTRICT y, int* RESTRICT x);
// Extract the notcurses context to which this plane is attached.
// Extract the Notcurses context to which this plane is attached.
API struct notcurses* ncplane_notcurses(struct ncplane* n);
API const struct notcurses* ncplane_notcurses_const(const struct ncplane* n);
@ -1123,7 +1123,7 @@ typedef struct ncstats {
// future versions of Notcurses might enlarge this structure.
API ncstats* notcurses_stats_alloc(const struct notcurses* nc);
// Acquire an atomic snapshot of the notcurses object's stats.
// Acquire an atomic snapshot of the Notcurses object's stats.
API void notcurses_stats(const struct notcurses* nc, ncstats* stats);
// Reset all cumulative stats (immediate ones, such as fbbytes, are not reset).
@ -2000,7 +2000,7 @@ API uint64_t ncplane_set_bchannel(struct ncplane* n, uint32_t channel);
// indicated by the "RGB" terminfo capability), the provided values will be
// interpreted in some lossy fashion. None of r, g, or b may exceed 255.
// "HP-like" terminals require setting foreground and background at the same
// time using "color pairs"; notcurses will manage color pairs transparently.
// time using "color pairs"; Notcurses will manage color pairs transparently.
API int ncplane_set_fg_rgb8(struct ncplane* n, int r, int g, int b);
API int ncplane_set_bg_rgb8(struct ncplane* n, int r, int g, int b);
@ -2445,7 +2445,7 @@ ncpixel_set_rgb8(uint32_t* pixel, int r, int g, int b){
return 0;
}
// An ncreel is a notcurses region devoted to displaying zero or more
// An ncreel is a Notcurses region devoted to displaying zero or more
// line-oriented, contained tablets between which the user may navigate. If at
// least one tablets exists, there is a "focused tablet". As much of the focused
// tablet as is possible is always displayed. If there is space left over, other
@ -2465,7 +2465,7 @@ ncpixel_set_rgb8(uint32_t* pixel, int r, int g, int b){
#define NCREEL_OPTION_CIRCULAR 0x0002ull
typedef struct ncreel_options {
// notcurses can draw a border around the ncreel, and also around the
// Notcurses can draw a border around the ncreel, and also around the
// component tablets. inhibit borders by setting all valid bits in the masks.
// partially inhibit borders by setting individual bits in the masks. the
// appropriate attr and pair values will be used to style the borders.
@ -2837,7 +2837,7 @@ typedef struct ncmenu_options {
} ncmenu_options;
// Create a menu with the specified options. Menus are currently bound to an
// overall notcurses object (as opposed to a particular plane), and are
// overall Notcurses object (as opposed to a particular plane), and are
// implemented as ncplanes kept atop other ncplanes.
API struct ncmenu* ncmenu_create(struct ncplane* n, const ncmenu_options* opts)
__attribute__ ((nonnull (1)));
@ -3087,7 +3087,7 @@ API char* ncreader_contents(const struct ncreader* n);
// UTF-8 input will be heap-duplicated and written to 'contents'.
API void ncreader_destroy(struct ncreader* n, char** contents);
// Dump selected notcurses state to the supplied 'debugfp'. Output is freeform,
// Dump selected Notcurses state to the supplied 'debugfp'. Output is freeform,
// and subject to change. It includes geometry of all planes.
API void notcurses_debug(struct notcurses* nc, FILE* debugfp);