mirror of
https://github.com/dankamongmen/notcurses.git
synced 2024-11-18 03:25:55 +00:00
2cd8b9d82e
Extract Curses differences and adaptation sections, and move them to doc/CURSES.md. Reference this new document in README.md. We now have sufficiently few sections that we can dispense with the ToC. Do so.
83 lines
4.0 KiB
Markdown
83 lines
4.0 KiB
Markdown
# Notcurses viz Curses/NCURSES
|
|
|
|
The biggest difference, of course, is that Notcurses is neither an
|
|
implementation of X/Open (aka XSI) Curses, nor part of SUS4-2018.
|
|
|
|
## Differences from Curses
|
|
|
|
The detailed differences between Notcurses and NCURSES (a high-quality, ubiquitous
|
|
implementation of Curses) 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:
|
|
|
|
* There is no distinct `PANEL` type. The z-buffer is a fundamental property,
|
|
and all drawable surfaces are ordered along the z axis. There is no
|
|
equivalent to `update_panels()`.
|
|
* Scrolling is disabled by default, and cannot be globally enabled.
|
|
* The Curses `cchar_t` has a fixed-size array of `wchar_t`. The Notcurses
|
|
`cell` instead supports a UTF-8 encoded extended grapheme cluster of
|
|
arbitrary length. The only supported encodings are ASCII via `ANSI_X3.4-1968`
|
|
and Unicode via `UTF-8`.
|
|
* The cursor is disabled by default, when supported (`civis` capability).
|
|
* Echoing of input is disabled by default, and `cbreak` mode is used by default.
|
|
* Colors are usually specified as 24 bits in 3 components (RGB). If necessary,
|
|
these will be quantized for the actual terminal. There are no "color pairs",
|
|
but indexed palettes are supported.
|
|
* There is no distinct "pad" concept (these are NCURSES `WINDOW`s created with
|
|
the `newpad()` function). All drawable surfaces can exceed the display size.
|
|
* Multiple threads can freely call into Notcurses, so long as they're not
|
|
accessing the same data. In particular, it is always safe to concurrently
|
|
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
|
|
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
|
|
attempting to print at the cursor when it has been advanced off the plane *does*).
|
|
* Notcurses has no support for soft labels (`slk_init()`, etc.), subwindows
|
|
which share memory with their parents, nor the NCURSES tracing functionality
|
|
(`trace(3NCURSES)`).
|
|
|
|
## 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.
|
|
Will your program really benefit from Notcurses's advanced features? If not,
|
|
it's probably best left as it is.
|
|
|
|
Otherwise, most NCURSES concepts have clear partners in Notcurses. Any functions
|
|
making implicit use of `stdscr` ought be replaced with their explicit
|
|
equivalents. `stdscr` ought then be replaced with the result of
|
|
`notcurses_stdplane()` (the standard plane). `PANEL`s become `ncplane`s; the
|
|
Panels API is otherwise pretty close. Anything writing a bare character will
|
|
become a simple `cell`; multibyte or wide characters become complex `cell`s.
|
|
Color no longer uses "color pairs". You can easily enough hack together a
|
|
simple table mapping your colors to RGB values, and color pairs to foreground
|
|
and background indices into said table. That'll work for the duration of a
|
|
porting effort, certainly.
|
|
|
|
I have adapted two large (~5k lines of C UI code each) programs from NCURSES to
|
|
Notcurses, and found it a fairly painless process. It was helpful to introduce
|
|
a shim layer, e.g. `compat_mvwprintw` for NCURSES's `mvwprintw`:
|
|
|
|
```c
|
|
static int
|
|
compat_mvwprintw(struct ncplane* nc, int y, int x, const char* fmt, ...){
|
|
va_list va;
|
|
va_start(va, fmt);
|
|
if(ncplane_vprintf_yx(nc, y, x, fmt, va) < 0){
|
|
va_end(va);
|
|
return ERR;
|
|
}
|
|
va_end(va);
|
|
return OK;
|
|
}
|
|
```
|
|
|
|
These are pretty obvious, implementation-wise.
|
|
|