mirror of
https://github.com/dankamongmen/notcurses
synced 2025-03-09 17:19:03 -04:00
ronn -> pandoc #245
This commit is contained in:
nick black
Nick Black
parent
390ca477bd
commit
94f597a9bb
@ -112,18 +112,18 @@ foreach(f ${POCSRCS})
|
||||
endforeach()
|
||||
|
||||
# Documentation
|
||||
file(GLOB MANSOURCE3 CONFIGURE_DEPENDS doc/man/man3/*.ronn)
|
||||
FIND_PROGRAM(RONN ronn)
|
||||
iF(NOT RONN)
|
||||
message(WARNING "ronn not found, won't regenerate man pages")
|
||||
file(GLOB MANSOURCE3 CONFIGURE_DEPENDS doc/man/man3/*.md)
|
||||
FIND_PROGRAM(PANDOC pandoc)
|
||||
iF(NOT PANDOC)
|
||||
message(WARNING "pandoc not found, won't generate documentation")
|
||||
else()
|
||||
foreach(m ${MANSOURCE3})
|
||||
get_filename_component(me ${m} NAME_WLE)
|
||||
add_custom_command(
|
||||
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${me}
|
||||
DEPENDS ${m}
|
||||
COMMAND ${RONN}
|
||||
ARGS -r --pipe ${m} > ${CMAKE_CURRENT_BINARY_DIR}/${me}
|
||||
COMMAND ${PANDOC}
|
||||
ARGS --to man --standalone ${m} > ${CMAKE_CURRENT_BINARY_DIR}/${me}
|
||||
COMMENT "Building man page ${me}"
|
||||
)
|
||||
add_custom_target(${me}.man
|
||||
@ -134,8 +134,8 @@ foreach(m ${MANSOURCE3})
|
||||
add_custom_command(
|
||||
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${me}.html
|
||||
DEPENDS ${m}
|
||||
COMMAND ${RONN}
|
||||
ARGS -5 --pipe ${m} > ${CMAKE_CURRENT_BINARY_DIR}/${me}.html
|
||||
COMMAND ${PANDOC}
|
||||
ARGS --to html --standalone ${m} > ${CMAKE_CURRENT_BINARY_DIR}/${me}.html
|
||||
COMMENT "Building HTML5 ${me}.html"
|
||||
)
|
||||
add_custom_target(${me}.html5
|
||||
|
||||
@ -106,7 +106,7 @@ that fine library.
|
||||
* CMake 3.14.0+
|
||||
* From NCURSES: terminfo 6.1+
|
||||
* (OPTIONAL) From FFMpeg: libswscale 5.0+, libavformat 57.0+, libavutil 56.0+
|
||||
* (man pages) [ronn](https://github.com/rtomayko/ronn) 0.8+
|
||||
* (documentation) [pandoc](https://pandoc.org/index.html) 1.19.2+
|
||||
|
||||
### Building
|
||||
|
||||
|
||||
@ -1,22 +0,0 @@
|
||||
notcurses(3) notcurses.3.ronn
|
||||
notcurses_init(3) notcurses_init.3.ronn
|
||||
notcurses_stdplane(3) notcurses_stdplane.3.ronn
|
||||
notcurses_ncplane(3) notcurses_ncplane.3.ronn
|
||||
notcurses_channels(3) notcurses_channels.3.ronn
|
||||
notcurses_cell(3) notcurses_cell.3.ronn
|
||||
notcurses_lines(3) notcurses_lines.3.ronn
|
||||
notcurses_input(3) notcurses_input.3.ronn
|
||||
notcurses_output(3) notcurses_output.3.ronn
|
||||
notcurses_render(3) notcurses_render.3.ronn
|
||||
notcurses_stats(3) notcurses_stats.3.ronn
|
||||
notcurses_stop(3) notcurses_stop.3.ronn
|
||||
|
||||
poll(2) http://man7.org/linux/man-pages/man2/poll.2.html
|
||||
getenv(3) http://man7.org/linux/man-pages/man3/getenv.3.html
|
||||
termios(3) http://man7.org/linux/man-pages/man3/termios.3.html
|
||||
ncurses(3NCURSES) http://man7.org/linux/man-pages/man3/ncurses.3x.html
|
||||
console_codes(4) http://man7.org/linux/man-pages/man4/console_codes.4.html
|
||||
terminfo(5) http://man7.org/linux/man-pages/man5/terminfo.5.html
|
||||
signal(7) http://man7.org/linux/man-pages/man7/signal.7.html
|
||||
unicode(7) http://man7.org/linux/man-pages/man7/unicode.7.html
|
||||
utf-8(7) http://man7.org/linux/man-pages/man7/utf-8.7.html
|
||||
92
doc/man/man3/notcurses.3.md
Normal file
92
doc/man/man3/notcurses.3.md
Normal file
@ -0,0 +1,92 @@
|
||||
% notcurses(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
notcurses—TUI library for modern terminal emulators
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
**-lnotcurses**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
notcurses builds atop the **terminfo(5)** abstraction layer to provide
|
||||
reasonably portable vivid character displays. It is an intellectual descendant
|
||||
of **ncurses(3NCURSES)**, but goes beyond that library (and the X/Open Curses
|
||||
API it implements). notcurses is capable of subregion fades, 24bpp DirectColor,
|
||||
transparency, multimedia, and safe multithreaded use.
|
||||
|
||||
A program wishing to use notcurses will need to link it, ideally using the
|
||||
output of **pkg-config --libs notcurses** (see **pkg-config(1)**). It is
|
||||
advised to compile with the output of **pkg-config --cflags notcurses**. If
|
||||
using CMake, a support file is provided, and can be accessed as **notcurses**
|
||||
(see **cmake(1)**).
|
||||
|
||||
**notcurses_init(3)** can then be used to initialize a notcurses instance for a
|
||||
given **FILE** (usually **stdout**), after calling **setlocale(3)** to prepare a
|
||||
UTF-8 locale (see [Construction][]).
|
||||
|
||||
## Construction
|
||||
|
||||
Before calling into notcurses—and usually as one of the first calls of the
|
||||
program—be sure to call **setlocale** with an appropriate UTF-8 **LC_ALL**
|
||||
locale. It is usually appropriate to use **setlocale(LC_ALL, "")**, relying on
|
||||
the user to properly set the **LANG** environment variable. notcurses will
|
||||
refuse to start if **nl_langinfo(3)** doesn't indicate UTF-8.
|
||||
|
||||
**notcurses_init(3)** accepts a **struct notcurses_options** allowing fine-grained
|
||||
control of notcurses behavior, including signal handlers, alternative screens,
|
||||
and overriding the TERM environment variable. A **terminfo** entry appropriate
|
||||
for the actual terminal must be available.
|
||||
|
||||
## Output
|
||||
|
||||
All output is performed on **struct ncplane**s (see [Ncplanes][] below). Output
|
||||
is not visible until explicitly rendered via **notcurses_render(3)**. It is safe to
|
||||
output from multiple threads. Information on drawing functions is available at
|
||||
**notcurses_output(3)**.
|
||||
|
||||
## Input
|
||||
|
||||
notcurses supports input from keyboards (via **stdin**) and pointing devices (via
|
||||
a broker such as GPM, X, or Wayland). Input is delivered as 32-bit Unicode
|
||||
code points. Synthesized events such as mouse button presses and arrow keys
|
||||
are mapped into Unicode's
|
||||
[Supplementary Private Use Area-B](https://unicode.org/charts/PDF/U100000.pdf).
|
||||
Information on input is available at **notcurses_input(3)**.
|
||||
|
||||
## Ncplanes
|
||||
|
||||
Following initialization, a single ncplane exists, the "standard plane" (see
|
||||
**notcurses_stdplane(3)**). This plane cannot be destoyed nor manually resized,
|
||||
and is always exactly as large as the screen. Further ncplanes can be created
|
||||
with **ncplane_new(3)**. A total z-ordering always exists on the set of
|
||||
ncplanes, and new ncplanes are placed at the top of the z-buffer. Ncplanes can
|
||||
be larger, smaller, or the same size as the physical screen, and can be placed
|
||||
anywhere relative to it (including entirely off-screen). Ncplanes are made up
|
||||
of cells (see [Cells][] below). Information on ncplanes is available at
|
||||
**notcurses_ncplane(3)**.
|
||||
|
||||
## Cells
|
||||
|
||||
Information on cells is available at **notcurses_cell(3)**.
|
||||
|
||||
## Destruction
|
||||
|
||||
Before exiting, **notcurses_stop(3)** should be called. In addition to freeing up
|
||||
resources, this is necessary to restore the terminal to a state useful for the
|
||||
shell. By default, **notcurses_init(3)** installs signal handlers to catch all
|
||||
signals which would normally terminate the process. The new handlers will try
|
||||
to call **notcurses_stop(3)**, and then propagate the received signal to the
|
||||
previous action.
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses-demo(1)**, **notcurses_cell(3)**, **notcurses_init(3)**,
|
||||
**notcurses_input(3)**, **notcurses_ncplane(3)**, **ncplane_new(3)**,
|
||||
**notcurses_output(3)**, **notcurses_render(3)**, **notcurses_stdplane(3)**,
|
||||
**notcurses_stop(3)**, **ncurses(3NCURSES)**, **terminfo(5)**
|
||||
@ -1,89 +0,0 @@
|
||||
notcurses(3) -- TUI library for modern terminal emulators
|
||||
=========================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
`-lnotcurses`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
notcurses builds atop the terminfo(5) abstraction layer to provide reasonably
|
||||
portable vivid character displays. It is an intellectual descendant of
|
||||
ncurses(3NCURSES), but goes beyond that library (and the X/Open Curses API it
|
||||
implements). notcurses is capable of subregion fades, 24bpp DirectColor,
|
||||
transparency, multimedia, and safe multithreaded use.
|
||||
|
||||
A program wishing to use notcurses will need to link it, ideally using the
|
||||
output of `pkg-config --libs notcurses` (see pkg-config(1)). It is advised to
|
||||
compile with the output of `pkg-config --cflags notcurses`. If using CMake, a
|
||||
support file is provided, and can be accessed as `notcurses` (see cmake(1)).
|
||||
|
||||
notcurses_init(3) can then be used to initialize a notcurses instance for a
|
||||
given `FILE*` (usually `stdout`), after calling setlocale(3) to prepare a
|
||||
UTF-8 locale (see [Construction][]).
|
||||
|
||||
### Construction
|
||||
|
||||
Before calling into notcurses—and usually as one of the first calls of the
|
||||
program—be sure to call `setlocale` with an appropriate UTF-8 `LC_ALL`
|
||||
locale. It is usually appropriate to use `setlocale(LC_ALL, "")`, relying on
|
||||
the user to properly set the `LANG` environment variable. notcurses will
|
||||
refuse to start if nl_langinfo(3) doesn't indicate UTF-8.
|
||||
|
||||
notcurses_init(3) accepts a `struct notcurses_options` allowing fine-grained
|
||||
control of notcurses behavior, including signal handlers, alternative screens,
|
||||
and overriding the TERM environment variable. A `terminfo` entry appropriate
|
||||
for the actual terminal must be available.
|
||||
|
||||
### Output
|
||||
|
||||
All output is performed on `struct ncplane*`s (see [Ncplanes][] below). Output
|
||||
is not visible until explicitly rendered via notcurses_render(3). It is safe to
|
||||
output from multiple threads. Information on drawing functions is available at
|
||||
notcurses_output(3).
|
||||
|
||||
### Input
|
||||
|
||||
notcurses supports input from keyboards (via `stdin`) and pointing devices (via
|
||||
a broker such as GPM, X, or Wayland). Input is delivered as 32-bit Unicode
|
||||
code points. Synthesized events such as mouse button presses and arrow keys
|
||||
are mapped into Unicode's
|
||||
[Supplementary Private Use Area-B](https://unicode.org/charts/PDF/U100000.pdf).
|
||||
Information on input is available at notcurses_input(3).
|
||||
|
||||
### Ncplanes
|
||||
|
||||
Following initialization, a single ncplane exists, the "standard plane" (see
|
||||
notcurses_stdplane(3)). This plane cannot be destoyed nor manually resized,
|
||||
and is always exactly as large as the screen. Further ncplanes can be created
|
||||
with ncplane_new(3). A total z-ordering always exists on the set of
|
||||
ncplanes, and new ncplanes are placed at the top of the z-buffer. Ncplanes can
|
||||
be larger, smaller, or the same size as the physical screen, and can be placed
|
||||
anywhere relative to it (including entirely off-screen). Ncplanes are made up
|
||||
of cells (see [Cells][] below). Information on ncplanes is available at
|
||||
notcurses_ncplane(3).
|
||||
|
||||
### Cells
|
||||
|
||||
Information on cells is available at notcurses_cell(3).
|
||||
|
||||
### Destruction
|
||||
|
||||
Before exiting, notcurses_stop(3) should be called. In addition to freeing up
|
||||
resources, this is necessary to restore the terminal to a state useful for the
|
||||
shell. By default, notcurses_init(3) installs signal handlers to catch all
|
||||
signals which would normally terminate the process. The new handlers will try
|
||||
to call notcurses_stop(3), and then propagate the received signal to the
|
||||
previous action.
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses-demo(1), notcurses_cell(3), notcurses_init(3), notcurses_input(3),
|
||||
notcurses_ncplane(3), ncplane_new(3), notcurses_output(3), notcurses_render(3),
|
||||
notcurses_stdplane(3), notcurses_stop(3), ncurses(3NCURSES), terminfo(5)
|
||||
112
doc/man/man3/notcurses_cell.3.md
Normal file
112
doc/man/man3/notcurses_cell.3.md
Normal file
@ -0,0 +1,112 @@
|
||||
% notcurses_cell(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
**notcurses_cell**—operations on notcurses cells
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
```c
|
||||
typedef struct cell {
|
||||
uint32_t gcluster;
|
||||
uint32_t attrword;
|
||||
uint64_t channels;
|
||||
} cell;
|
||||
|
||||
#define CELL_TRIVIAL_INITIALIZER \
|
||||
{ .gcluster = '\0', .attrword = 0, .channels = 0, }
|
||||
#define CELL_SIMPLE_INITIALIZER(c) \
|
||||
{ .gcluster = (c), .attrword = 0, .channels = 0, }
|
||||
#define CELL_INITIALIZER(c, a, chan) \
|
||||
{ .gcluster = (c), .attrword = (a), .channels = (chan), }
|
||||
```
|
||||
|
||||
**void cell_init(cell* c);**
|
||||
|
||||
**int cell_load(struct ncplane* n, cell* c, const char* gcluster);**
|
||||
|
||||
**int cell_prime(struct ncplane* n, cell* c, const char *gcluster, uint32_t attr, uint64_t channels);**
|
||||
|
||||
**int cell_duplicate(struct ncplane* n, cell* targ, const cell* c);**
|
||||
|
||||
**void cell_release(struct ncplane* n, cell* c);**
|
||||
|
||||
**void cell_styles_set(cell* c, unsigned stylebits);**
|
||||
|
||||
**unsigned cell_styles(const cell* c);**
|
||||
|
||||
**void cell_styles_on(cell* c, unsigned stylebits);**
|
||||
|
||||
**void cell_styles_off(cell* c, unsigned stylebits);**
|
||||
|
||||
**void cell_set_fg_default(cell* c);**
|
||||
|
||||
**void cell_set_bg_default(cell* c);**
|
||||
|
||||
**int cell_set_fg_alpha(cell* c, int alpha);**
|
||||
|
||||
**int cell_set_bg_alpha(cell* c, int alpha);**
|
||||
|
||||
**bool cell_double_wide_p(const cell* c);**
|
||||
|
||||
**bool cell_simple_p(const cell* c);**
|
||||
|
||||
**const char* cell_extended_gcluster(const struct ncplane* n, const cell* c);**
|
||||
|
||||
**bool cell_noforeground_p(const cell* c);**
|
||||
|
||||
**bool cell_nobackground_p(const struct ncplane* n, const cell* c);**
|
||||
|
||||
**int cell_load_simple(struct ncplane* n, cell* c, char ch);**
|
||||
|
||||
**uint32_t cell_egc_idx(const cell* c);**
|
||||
|
||||
**unsigned cell_bchannel(const cell* cl);**
|
||||
|
||||
**unsigned cell_fchannel(const cell* cl);**
|
||||
|
||||
**uint64_t cell_set_bchannel(cell* cl, uint32_t channel);**
|
||||
|
||||
**uint64_t cell_set_fchannel(cell* cl, uint32_t channel);**
|
||||
|
||||
**uint64_t cell_blend_fchannel(cell* cl, unsigned channel);**
|
||||
|
||||
**uint64_t cell_blend_bchannel(cell* cl, unsigned channel);**
|
||||
|
||||
**unsigned cell_fg(const cell* cl);**
|
||||
|
||||
**unsigned cell_bg(const cell* cl);**
|
||||
|
||||
**unsigned cell_fg_alpha(const cell* cl);**
|
||||
|
||||
**unsigned cell_bg_alpha(const cell* cl);**
|
||||
|
||||
**unsigned cell_fg_rgb(const cell* cl, unsigned* r, unsigned* g, unsigned* b);**
|
||||
|
||||
**unsigned cell_bg_rgb(const cell* cl, unsigned* r, unsigned* g, unsigned* b);**
|
||||
|
||||
**int cell_set_fg_rgb(cell* cl, int r, int g, int b);**
|
||||
|
||||
**int cell_set_bg_rgb(cell* cl, int r, int g, int b);**
|
||||
|
||||
**int cell_set_fg(cell* c, uint32_t channel);**
|
||||
|
||||
**int cell_set_bg(cell* c, uint32_t channel);**
|
||||
|
||||
**bool cell_fg_default_p(const cell* cl);**
|
||||
|
||||
**bool cell_bg_default_p(const cell* cl);**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **notcurses_channels(3)**, **notcurses_ncplane(3)**,
|
||||
**notcurses_output(3)**
|
||||
@ -1,107 +0,0 @@
|
||||
notcurses_cell(3) -- operations on notcurses cells
|
||||
==================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
<pre>typedef struct cell {
|
||||
uint32_t gcluster;
|
||||
uint32_t attrword;
|
||||
uint64_t channels;
|
||||
} cell;</pre>
|
||||
|
||||
`#define CELL_TRIVIAL_INITIALIZER { .gcluster = '\0', .attrword = 0, .channels = 0, }`
|
||||
|
||||
`#define CELL_SIMPLE_INITIALIZER(c) { .gcluster = (c), .attrword = 0, .channels = 0, }`
|
||||
|
||||
`#define CELL_INITIALIZER(c, a, chan) { .gcluster = (c), .attrword = (a), .channels = (chan), }`
|
||||
|
||||
`void cell_init(cell* c);`
|
||||
|
||||
`int cell_load(struct ncplane* n, cell* c, const char* gcluster);`
|
||||
|
||||
`int cell_prime(struct ncplane* n, cell* c, const char *gcluster, uint32_t attr, uint64_t channels);`
|
||||
|
||||
`int cell_duplicate(struct ncplane* n, cell* targ, const cell* c);`
|
||||
|
||||
`void cell_release(struct ncplane* n, cell* c);`
|
||||
|
||||
`void cell_styles_set(cell* c, unsigned stylebits);`
|
||||
|
||||
`unsigned cell_styles(const cell* c);`
|
||||
|
||||
`void cell_styles_on(cell* c, unsigned stylebits);`
|
||||
|
||||
`void cell_styles_off(cell* c, unsigned stylebits);`
|
||||
|
||||
`void cell_set_fg_default(cell* c);`
|
||||
|
||||
`void cell_set_bg_default(cell* c);`
|
||||
|
||||
`int cell_set_fg_alpha(cell* c, int alpha);`
|
||||
|
||||
`int cell_set_bg_alpha(cell* c, int alpha);`
|
||||
|
||||
`bool cell_double_wide_p(const cell* c);`
|
||||
|
||||
`bool cell_simple_p(const cell* c);`
|
||||
|
||||
`const char* cell_extended_gcluster(const struct ncplane* n, const cell* c);`
|
||||
|
||||
`bool cell_noforeground_p(const cell* c);`
|
||||
|
||||
`bool cell_nobackground_p(const struct ncplane* n, const cell* c);`
|
||||
|
||||
`int cell_load_simple(struct ncplane* n, cell* c, char ch);`
|
||||
|
||||
`uint32_t cell_egc_idx(const cell* c);`
|
||||
|
||||
`unsigned cell_bchannel(const cell* cl);`
|
||||
|
||||
`unsigned cell_fchannel(const cell* cl);`
|
||||
|
||||
`uint64_t cell_set_bchannel(cell* cl, uint32_t channel);`
|
||||
|
||||
`uint64_t cell_set_fchannel(cell* cl, uint32_t channel);`
|
||||
|
||||
`uint64_t cell_blend_fchannel(cell* cl, unsigned channel);`
|
||||
|
||||
`uint64_t cell_blend_bchannel(cell* cl, unsigned channel);`
|
||||
|
||||
`unsigned cell_fg(const cell* cl);`
|
||||
|
||||
`unsigned cell_bg(const cell* cl);`
|
||||
|
||||
`unsigned cell_fg_alpha(const cell* cl);`
|
||||
|
||||
`unsigned cell_bg_alpha(const cell* cl);`
|
||||
|
||||
`unsigned cell_fg_rgb(const cell* cl, unsigned* r, unsigned* g, unsigned* b);`
|
||||
|
||||
`unsigned cell_bg_rgb(const cell* cl, unsigned* r, unsigned* g, unsigned* b);`
|
||||
|
||||
`int cell_set_fg_rgb(cell* cl, int r, int g, int b);`
|
||||
|
||||
`int cell_set_bg_rgb(cell* cl, int r, int g, int b);`
|
||||
|
||||
`int cell_set_fg(cell* c, uint32_t channel);`
|
||||
|
||||
`int cell_set_bg(cell* c, uint32_t channel);`
|
||||
|
||||
`bool cell_fg_default_p(const cell* cl);`
|
||||
|
||||
`bool cell_bg_default_p(const cell* cl);`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses_channels(3), notcurses_ncplane(3)
|
||||
21
doc/man/man3/notcurses_channels.3.md
Normal file
21
doc/man/man3/notcurses_channels.3.md
Normal file
@ -0,0 +1,21 @@
|
||||
% notcurses_channels(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
**notcurses_channels(3)**—operations on notcurses channels
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **notcurses_cell(3)**, **notcurses_ncplane(3)**,
|
||||
**notcurses_output(3)**
|
||||
@ -1,19 +0,0 @@
|
||||
notcurses_channels(3) -- operations on notcurses channels
|
||||
=========================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses_cell(3), notcurses_ncplane(3)
|
||||
123
doc/man/man3/notcurses_init.3.md
Normal file
123
doc/man/man3/notcurses_init.3.md
Normal file
@ -0,0 +1,123 @@
|
||||
% notcurses_init(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
**notcurses_init**—initialize a notcurses instance
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
```c
|
||||
typedef struct notcurses_options {
|
||||
const char* termtype;
|
||||
bool inhibit_alternate_screen;
|
||||
bool retain_cursor;
|
||||
bool clear_screen_start;
|
||||
bool suppress_banner;
|
||||
bool no_quit_sighandlers;
|
||||
bool no_winch_sighandler;
|
||||
FILE* renderfp;
|
||||
} notcurses_options;
|
||||
```
|
||||
|
||||
**struct notcurses*
|
||||
notcurses_init(const struct notcurses_options* opts, FILE* fp);**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
**notcurses_init** prepares the **FILE** provided as **fp** (which must be
|
||||
attached to a terminal) for cursor-addressable (multiline) mode. The
|
||||
**struct notcurses_option** passed as **opts** controls behavior. Only one
|
||||
instance should be associated with a given terminal at a time, though it is no
|
||||
problem to have multiple instances in a given process. On success, a pointer to
|
||||
a valid **struct notcurses** is returned. **NULL** is returned on failure.
|
||||
Before the process exits, **notcurses_stop(3)** should be called to reset the
|
||||
terminal and free up resources.
|
||||
|
||||
An appropriate **terminfo(5)** entry must exist for the terminal. This entry is
|
||||
usually selected using the value of the **TERM** environment variable (see
|
||||
**getenv(3)**), but a non-**NULL** value for **termtype** will override this. An
|
||||
invalid terminfo specification can lead to reduced performance, reduced
|
||||
display capabilities, and/or display errors. notcurses natively targets
|
||||
24bpp/8bpc RGB color, and it is thus desirable to use a terminal with the
|
||||
**rgb** capability (e.g. xterm's **xterm-direct**).
|
||||
|
||||
If the terminal advertises support for an "alternate screen" via the **smcup**
|
||||
terminfo capability, notcurses will employ it by default. This can be prevented
|
||||
by setting **inhibit_alternate_screen** to **true**. Users tend to have strong
|
||||
opinions regarding the alternate screen, so it's often useful to expose this
|
||||
via a command-line option.
|
||||
|
||||
notcurses furthermore hides the cursor by default, but **retain_cursor** can
|
||||
prevent this (the cursor can be dynamically enabled or disabled during
|
||||
execution via **notcurses_cursor_enable(3)** and **notcurses_cursor_disable(3)**).
|
||||
|
||||
If **clear_screen_start** is set to **true**, the screen will be cleared as part of
|
||||
**notcurses_init**. Otherwise, whatever's on the screen at entry will remain
|
||||
there until changed.
|
||||
|
||||
**notcurses_init** typically emits some diagnostics at startup, including version
|
||||
information and some details of the configured terminal. This can be inhibited
|
||||
with **suppress_banner**. This will also inhibit the performance summary normally
|
||||
printed by **notcurses_stop(3)**.
|
||||
|
||||
## Fatal signals
|
||||
|
||||
It is important to reset the terminal before exiting, whether terminating due
|
||||
to intended operation or a received signal. This is usually accomplished by
|
||||
explicitly calling **notcurses_stop(3)** during shutdown. For convenience, notcurses
|
||||
by default installs signal handlers for various signals typically resulting in
|
||||
process termination (see **signal(7)**). These signal handlers call
|
||||
notcurses_stop(3) for each **struct notcurses** in the process, and then propagate
|
||||
the signal to any previously-configured handler. These handlers are disabled
|
||||
upon entry to **notcurses_stop(3)**.
|
||||
|
||||
To prevent signal handler registration, set **no_quit_sighandlers** to **true**.
|
||||
No means is provided to selectively register fatal signal handlers. If this is
|
||||
done, the caller ought be sure to effect similar functionality themselves.
|
||||
|
||||
## Resize events
|
||||
|
||||
**SIGWINCH** (SIGnal WINdow CHange) is delivered to the process when the terminal
|
||||
is resized. The default action is to ignore it (**SIG_IGN**). notcurses installs
|
||||
a handler for this signal. The handler causes notcurses to update its idea of
|
||||
the terminal's size using **TIOCGWINSZ** (see **ioctl_tty(2)**), and generates an
|
||||
**NCKEY_RESIZE** input event (see **notcurses_input(3)**. This signal handler can be
|
||||
inhibited by setting **no_winch_sighandler** to **true**. If this is done, the
|
||||
caller should probably watch for the signal, and invoke **notcurses_resize()**
|
||||
upon its receipt.
|
||||
|
||||
A resize event does not invalidate any references returned earlier by
|
||||
notcurses. The content of any new screen area is undefined until the next call
|
||||
to notcurses_render(3), unless **clear_screen_start** is set **true**, in which
|
||||
case new area is cleared. This is true even if an existing **struct ncplane**
|
||||
(see **notcurses_ncplane(3)**) overlaps the new area, since the signal could
|
||||
arrive while the ncplanes are being modified. Signal handlers are quite
|
||||
restricted as to what actions they can perform, so minimal work is performed in
|
||||
the handler proper.
|
||||
|
||||
Thus, in the absence of **no_winch_sighandler**, **SIGWINCH** results in:
|
||||
|
||||
* interruption of some thread to process the signal
|
||||
* a **TIOCGWINSZ** **ioctl** to retrieve the new screen size
|
||||
* queuing of a **NCKEY_RESIZE** input event (if there is space in the queue)
|
||||
* blanking of the new screen area (if **clear_screen_start** is set)
|
||||
|
||||
Upon the next call to **notcurses_render(3)** or **notcurses_resize(3)**, the standard
|
||||
plane (see **notcurses_stdplane(3)**) will be resized to the new screen size. The
|
||||
next **notcurses_render(3)** call will function as expected across the new screen
|
||||
geometry.
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
**NULL** is returned on failure. Otherwise, the return value points at a valid
|
||||
**struct notcurses**, which can be used until it is provided to **notcurses_stop(3)**.
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**getenv(3)**, **termios(3)**, **notcurses(3)**, **notcurses_input(3)**,
|
||||
**notcurses_ncplane(3)**, **notcurses_render(3)**, **notcurses_stop(3)**,
|
||||
**terminfo(5)**, **signal(7)**
|
||||
@ -1,119 +0,0 @@
|
||||
notcurses_init(3) -- initialize a notcurses instance
|
||||
====================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
<pre>typedef struct notcurses_options {
|
||||
const char* termtype;
|
||||
bool inhibit_alternate_screen;
|
||||
bool retain_cursor;
|
||||
bool clear_screen_start;
|
||||
bool suppress_banner;
|
||||
bool no_quit_sighandlers;
|
||||
bool no_winch_sighandler;
|
||||
FILE* renderfp;
|
||||
} notcurses_options;</pre>
|
||||
|
||||
`struct notcurses*
|
||||
notcurses_init(const struct notcurses_options* opts, FILE* fp);`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
`notcurses_init` prepares the `FILE*` provided as `fp` (which must be attached
|
||||
to a terminal) for cursor-addressable (multiline) mode. The `struct
|
||||
notcurses_option` passed as `opts` controls behavior. Only one instance should
|
||||
be associated with a given terminal at a time, though it is no problem to have
|
||||
multiple instances in a given process. On success, a pointer to a valid `struct
|
||||
notcurses` is returned. `NULL` is returned on failure. Before the process exits,
|
||||
notcurses_stop(3) should be called to reset the terminal and free up
|
||||
resources.
|
||||
|
||||
An appropriate terminfo(5) entry must exist for the terminal. This entry is
|
||||
usually selected using the value of the `TERM` environment variable (see
|
||||
getenv(3)), but a non-`NULL` value for `termtype` will override this. An
|
||||
invalid terminfo specification can lead to reduced performance, reduced
|
||||
display capabilities, and/or display errors. notcurses natively targets
|
||||
24bpp/8bpc RGB color, and it is thus desirable to use a terminal with the
|
||||
`rgb` capability (e.g. xterm's `xterm-direct`).
|
||||
|
||||
If the terminal advertises support for an "alternate screen" via the `smcup`
|
||||
terminfo capability, notcurses will employ it by default. This can be prevented
|
||||
by setting `inhibit_alternate_screen` to `true`. Users tend to have strong
|
||||
opinions regarding the alternate screen, so it's often useful to expose this
|
||||
via a command-line option.
|
||||
|
||||
notcurses furthermore hides the cursor by default, but `retain_cursor` can
|
||||
prevent this (the cursor can be dynamically enabled or disabled during
|
||||
execution via notcurses_cursor_enable(3) and notcurses_cursor_disable(3)).
|
||||
|
||||
If `clear_screen_start` is set to `true`, the screen will be cleared as part of
|
||||
`notcurses_init`. Otherwise, whatever's on the screen at entry will remain
|
||||
there until changed.
|
||||
|
||||
`notcurses_init` typically emits some diagnostics at startup, including version
|
||||
information and some details of the configured terminal. This can be inhibited
|
||||
with `suppress_banner`. This will also inhibit the performance summary normally
|
||||
printed by notcurses_stop(3).
|
||||
|
||||
### Fatal signals
|
||||
|
||||
It is important to reset the terminal before exiting, whether terminating due
|
||||
to intended operation or a received signal. This is usually accomplished by
|
||||
explicitly calling notcurses_stop(3) during shutdown. For convenience, notcurses
|
||||
by default installs signal handlers for various signals typically resulting in
|
||||
process termination (see `signal(7)`). These signal handlers call
|
||||
notcurses_stop(3) for each `struct notcurses` in the process, and then propagate
|
||||
the signal to any previously-configured handler. These handlers are disabled
|
||||
upon entry to notcurses_stop(3).
|
||||
|
||||
To prevent signal handler registration, set `no_quit_sighandlers` to `true`.
|
||||
No means is provided to selectively register fatal signal handlers. If this is
|
||||
done, the caller ought be sure to effect similar functionality themselves.
|
||||
|
||||
### Resize events
|
||||
|
||||
`SIGWINCH` (SIGnal WINdow CHange) is delivered to the process when the terminal
|
||||
is resized. The default action is to ignore it (`SIG_IGN`). notcurses installs
|
||||
a handler for this signal. The handler causes notcurses to update its idea of
|
||||
the terminal's size using `TIOCGWINSZ` (see ioctl_tty(2)), and generates an
|
||||
`NCKEY_RESIZE` input event (see notcurses_input(3). This signal handler can be
|
||||
inhibited by setting `no_winch_sighandler` to `true`. If this is done, the
|
||||
caller should probably watch for the signal, and invoke `notcurses_resize()`
|
||||
upon its receipt.
|
||||
|
||||
A resize event does not invalidate any references returned earlier by
|
||||
notcurses. The content of any new screen area is undefined until the next call
|
||||
to notcurses_render(3), unless `clear_screen_start` is set `true`, in which
|
||||
case new area is cleared. This is true even if an existing `struct ncplane`
|
||||
(see notcurses_ncplane(3)) overlaps the new area, since the signal could
|
||||
arrive while the ncplanes are being modified. Signal handlers are quite
|
||||
restricted as to what actions they can perform, so minimal work is perfomed in
|
||||
the handler proper.
|
||||
|
||||
Thus, in the absence of `no_winch_sighandler`, `SIGWINCH` results in:
|
||||
|
||||
* interruption of some thread to process the signal
|
||||
* a `TIOCGWINSZ` `ioctl` to retrieve the new screen size
|
||||
* queuing of a `NCKEY_RESIZE` input event (if there is space in the queue)
|
||||
* blanking of the new screen area (if `clear_screen_start` is set)
|
||||
|
||||
Upon the next call to notcurses_render(3) or notcurses_resize(3), the standard
|
||||
plane (see notcurses_stdplane(3)) will be resized to the new screen size. The
|
||||
next notcurses_render(3) call will function as expected across the new screen
|
||||
geometry.
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
`NULL` is returned on failure. Otherwise, the return value points at a valid
|
||||
`struct notcurses`, which can be used until it is provided to notcurses_stop(3).
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
getenv(3), termios(3), notcurses(3), notcurses_input(3), notcurses_ncplane(3),
|
||||
notcurses_render(3), notcurses_stop(3), terminfo(5), signal(7)
|
||||
43
doc/man/man3/notcurses_input.3.md
Normal file
43
doc/man/man3/notcurses_input.3.md
Normal file
@ -0,0 +1,43 @@
|
||||
% notcurses_input(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
**notcurses_input**—input via notcurses
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
#include <notcurses.h>**
|
||||
|
||||
```c
|
||||
typedef struct ncinput {
|
||||
char32_t id; // Unicode codepoint
|
||||
int y; // Y cell coordinate of event, -1 for undefined
|
||||
int x; // X cell coordinate of event, -1 for undefined
|
||||
bool alt; // Was Alt held during the event?
|
||||
bool shift; // Was Shift held during the event?
|
||||
bool ctrl; // Was Ctrl held during the event?
|
||||
} ncinput;
|
||||
```
|
||||
|
||||
**bool nckey_mouse_p(char32_t r);**
|
||||
|
||||
**char32_t notcurses_getc(struct notcurses* n, const struct timespec* ts, sigset_t* sigmask, ncinput* ni);**
|
||||
|
||||
**char32_t notcurses_getc_nblock(struct notcurses* n, ncinput* ni);**
|
||||
|
||||
**char32_t notcurses_getc_blocking(struct notcurses* n, ncinput* ni);**
|
||||
|
||||
**int notcurses_mouse_enable(struct notcurses* n);**
|
||||
|
||||
**int notcurses_mouse_disable(struct notcurses* n);**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **poll(2)**, **unicode(7)**
|
||||
@ -1,40 +0,0 @@
|
||||
notcurses_input(3) -- input via notcurses
|
||||
=========================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
<pre>typedef struct ncinput {
|
||||
char32_t id; // Unicode codepoint
|
||||
int y; // Y cell coordinate of event, -1 for undefined
|
||||
int x; // X cell coordinate of event, -1 for undefined
|
||||
bool alt; // Was Alt held during the event?
|
||||
bool shift; // Was Shift held during the event?
|
||||
bool ctrl; // Was Ctrl held during the event?
|
||||
} ncinput;</pre>
|
||||
|
||||
`bool nckey_mouse_p(char32_t r);`
|
||||
|
||||
`char32_t notcurses_getc(struct notcurses* n, const struct timespec* ts, sigset_t* sigmask, ncinput* ni);`
|
||||
|
||||
`char32_t notcurses_getc_nblock(struct notcurses* n, ncinput* ni);`
|
||||
|
||||
`char32_t notcurses_getc_blocking(struct notcurses* n, ncinput* ni);`
|
||||
|
||||
`int notcurses_mouse_enable(struct notcurses* n);`
|
||||
|
||||
`int notcurses_mouse_disable(struct notcurses* n);`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses(3), poll(2), unicode(7)
|
||||
21
doc/man/man3/notcurses_lines.3.md
Normal file
21
doc/man/man3/notcurses_lines.3.md
Normal file
@ -0,0 +1,21 @@
|
||||
% notcurses_lines(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
**notcurses_lines**—operations on lines and boxes
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **notcurses_cell(3)**, **notcurses_ncplane(3)**
|
||||
@ -1,19 +0,0 @@
|
||||
notcurses_lines(3) -- operations on lines and boxes
|
||||
===================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses_cell(3), notcurses_lines(3), notcurses_ncplane(3)
|
||||
89
doc/man/man3/notcurses_ncplane.3.md
Normal file
89
doc/man/man3/notcurses_ncplane.3.md
Normal file
@ -0,0 +1,89 @@
|
||||
% notcurses_ncplane(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
**notcurses_ncplane**—operations on notcurses planes
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
**struct ncplane* ncplane_new(struct notcurses* nc, int rows, int cols, int yoff, int xoff, void* opaque);**
|
||||
|
||||
**struct ncplane* ncplane_aligned(struct ncplane* n, int rows, int cols, int yoff, ncalign_e align, void* opaque);**
|
||||
|
||||
**int ncplane_resize(struct ncplane* n, int keepy, int keepx, int keepleny, int keeplenx, int yoff, int xoff, int ylen, int xlen);**
|
||||
|
||||
**int ncplane_move_yx(struct ncplane* n, int y, int x);**
|
||||
|
||||
**void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict x);**
|
||||
|
||||
**int ncplane_set_default(struct ncplane* ncp, const cell* c);**
|
||||
|
||||
**int ncplane_default(struct ncplane* ncp, cell* c);**
|
||||
|
||||
**int ncplane_destroy(struct ncplane* ncp);**
|
||||
|
||||
**int ncplane_move_top(struct ncplane* n);**
|
||||
|
||||
**int ncplane_move_bottom(struct ncplane* n);**
|
||||
|
||||
**int ncplane_move_above(struct ncplane* n, struct ncplane* above);**
|
||||
|
||||
**int ncplane_move_below(struct ncplane* n, struct ncplane* below);**
|
||||
|
||||
**struct ncplane* ncplane_below(struct ncplane* n);**
|
||||
|
||||
**int ncplane_at_cursor(struct ncplane* n, cell* c);**
|
||||
|
||||
**int ncplane_at_yx(struct ncplane* n, int y, int x, cell* c);**
|
||||
|
||||
**void* ncplane_set_userptr(struct ncplane* n, void* opaque);**
|
||||
|
||||
**void* ncplane_userptr(struct ncplane* n);**
|
||||
|
||||
**const void* ncplane_userptr_const(const struct ncplane* n);**
|
||||
|
||||
**void ncplane_dim_yx(const struct ncplane* n, int* restrict rows, int* restrict cols);**
|
||||
|
||||
**int ncplane_cursor_move_yx(struct ncplane* n, int y, int x);**
|
||||
|
||||
**void ncplane_cursor_yx(const struct ncplane* n, int* restrict y, int* restrict x);**
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
Ncplanes are the fundamental drawing object of notcurses. All output functions
|
||||
take a **struct ncplane*** as an argument. They can be any size, and placed
|
||||
anywhere. In addition to its framebuffer--a rectilinear matrix of cells
|
||||
(see **notcurses_cell(3)**)--an ncplane is defined by:
|
||||
|
||||
* a base cell, used for any cell on the plane without a glyph,
|
||||
* the egcpool backing its cells,
|
||||
* a current cursor location,
|
||||
* a current style, foreground channel, and background channel,
|
||||
* its geometry,
|
||||
* a configured user pointer,
|
||||
* its position relative to the visible plane, and
|
||||
* its z-index.
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
**ncplane_new(3)** and **ncplane_aligned(3)** both return a new **struct ncplane**, or
|
||||
**NULL** on failure.
|
||||
|
||||
**ncplane_userptr(3)** and **ncplane_userptr_const(3)** both return the configured user
|
||||
pointer for the ncplane. They cannot fail.
|
||||
|
||||
**ncplane_below(3)** returns the plane below the specified ncplane. If the provided
|
||||
plane is the bottommost plane, NULL is returned. It cannot fail.
|
||||
|
||||
Functions returning **int** return 0 on success, and non-zero on error.
|
||||
|
||||
All other functions either cannot fail (and return **void**).
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **notcurses_cell(3)**, **notcurses_output(3)**,
|
||||
**notcurses_stdplane(3)**
|
||||
@ -1,87 +0,0 @@
|
||||
notcurses_ncplane(3) -- operations on notcurses planes
|
||||
======================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
`struct ncplane* ncplane_new(struct notcurses* nc, int rows, int cols, int yoff, int xoff, void* opaque);`
|
||||
|
||||
`struct ncplane* ncplane_aligned(struct ncplane* n, int rows, int cols, int yoff, ncalign_e align, void* opaque);`
|
||||
|
||||
`int ncplane_resize(struct ncplane* n, int keepy, int keepx, int keepleny, int keeplenx, int yoff, int xoff, int ylen, int xlen);`
|
||||
|
||||
`int ncplane_move_yx(struct ncplane* n, int y, int x);`
|
||||
|
||||
`void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict x);`
|
||||
|
||||
`int ncplane_set_default(struct ncplane* ncp, const cell* c);`
|
||||
|
||||
`int ncplane_default(struct ncplane* ncp, cell* c);`
|
||||
|
||||
`int ncplane_destroy(struct ncplane* ncp);`
|
||||
|
||||
`int ncplane_move_top(struct ncplane* n);`
|
||||
|
||||
`int ncplane_move_bottom(struct ncplane* n);`
|
||||
|
||||
`int ncplane_move_above(struct ncplane* n, struct ncplane* above);`
|
||||
|
||||
`int ncplane_move_below(struct ncplane* n, struct ncplane* below);`
|
||||
|
||||
`struct ncplane* ncplane_below(struct ncplane* n);`
|
||||
|
||||
`int ncplane_at_cursor(struct ncplane* n, cell* c);`
|
||||
|
||||
`int ncplane_at_yx(struct ncplane* n, int y, int x, cell* c);`
|
||||
|
||||
`void* ncplane_set_userptr(struct ncplane* n, void* opaque);`
|
||||
|
||||
`void* ncplane_userptr(struct ncplane* n);`
|
||||
|
||||
`const void* ncplane_userptr_const(const struct ncplane* n);`
|
||||
|
||||
`void ncplane_dim_yx(const struct ncplane* n, int* restrict rows, int* restrict cols);`
|
||||
|
||||
`int ncplane_cursor_move_yx(struct ncplane* n, int y, int x);`
|
||||
|
||||
`void ncplane_cursor_yx(const struct ncplane* n, int* restrict y, int* restrict x);`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
Ncplanes are the fundamental drawing object of notcurses. All output functions
|
||||
take a `struct ncplane*` as an argument. They can be any size, and placed
|
||||
anywhere. In addition to its framebuffer--a rectilinear matrix of cells
|
||||
(see notcurses_cell(3))--an ncplane is defined by:
|
||||
|
||||
* a base cell, used for any cell on the plane without a glyph,
|
||||
* the egcpool backing its cells,
|
||||
* a current cursor location,
|
||||
* a current style, foreground channel, and background channel,
|
||||
* its geometry,
|
||||
* a configured user pointer,
|
||||
* its position relative to the visible plane, and
|
||||
* its z-index.
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
ncplane_new(3) and ncplane_aligned(3) both return a new `struct ncplane*`, or
|
||||
`NULL` on failure.
|
||||
|
||||
ncplane_userptr(3) and ncplane_userptr_const(3) both return the configured user
|
||||
pointer for the ncplane. They cannot fail.
|
||||
|
||||
ncplane_below(3) returns the plane below the specified ncplane. If the provided
|
||||
plane is the bottommost plane, NULL is returned. It cannot fail.
|
||||
|
||||
Functions returning `int` return 0 on success, and non-zero on error.
|
||||
|
||||
All other functions either cannot fail (and return `void`).
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses_cell(3), notcurses_output(3), notcurses_stdplane(3)
|
||||
20
doc/man/man3/notcurses_ncvisual.3.md
Normal file
20
doc/man/man3/notcurses_ncvisual.3.md
Normal file
@ -0,0 +1,20 @@
|
||||
% notcurses_ncvisual(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
**notcurses_ncvisual**—notcurses multimedia
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **notcurses_ncplane(3)**
|
||||
@ -1,19 +0,0 @@
|
||||
notcurses_ncvisual(3) -- notcurses multimedia
|
||||
=============================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses_ncplane(3)
|
||||
20
doc/man/man3/notcurses_output.3.md
Normal file
20
doc/man/man3/notcurses_output.3.md
Normal file
@ -0,0 +1,20 @@
|
||||
% notcurses_output(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
notcurses_output—output to ncplanes
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **notcurses_cell(3)**, **notcurses_ncplane(3)**
|
||||
@ -1,19 +0,0 @@
|
||||
notcurses_output(3) -- output to ncplanes
|
||||
=========================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses_cell(3), notcurses_ncplane(3)
|
||||
79
doc/man/man3/notcurses_render.3.md
Normal file
79
doc/man/man3/notcurses_render.3.md
Normal file
@ -0,0 +1,79 @@
|
||||
% notcurses_render(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
notcurses_render—sync the physical display to the virtual ncplanes
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
**int notcurses_render(struct notcurses* nc);**
|
||||
|
||||
**char* notcurses_at_yx(struct notcurses* nc, int yoff, int xoff, cell* c);**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
**notcurses_render** syncs the physical display to the context's prepared
|
||||
ncplanes. It is necessary to call **notcurses_render** to generate any visible
|
||||
output; the various notcurses_output(3) calls only draw to the virtual
|
||||
ncplanes. Most of the notcurses statistics are updated as a result of a
|
||||
render (see notcurses_stats(3)).
|
||||
|
||||
A render operation consists of two logical phases: generation of the rendered
|
||||
scene, and blitting this scene to the terminal (these two phases might actually
|
||||
be interleaved, streaming the output as it is rendered). All ncplanes are
|
||||
locked while generating the frame. Frame generation requires determining an
|
||||
extended grapheme cluster, foreground color, background color, and style for
|
||||
each cell of the physical terminal. Writing the scene requires synthesizing
|
||||
a set of UTF-8-encoded characters and escape codes appropriate for the terminal
|
||||
(relying on terminfo(5)), and writing this sequence to the output **FILE***. If
|
||||
the **renderfp** value was not NULL in the original call to notcurses_init(3),
|
||||
the frame will be written to that **FILE*** as well. This write does not affect
|
||||
statistics.
|
||||
|
||||
Each cell can be rendered in isolation, though synthesis of the stream carries
|
||||
dependencies between cells.
|
||||
|
||||
## Cell rendering algorithm
|
||||
|
||||
Recall that there is a total ordering on the N ncplanes, and that the standard
|
||||
plane always exists, with geometry equal to the physical screen. Each cell of
|
||||
the physical screen is thus intersected by some totally ordered subset of
|
||||
planes **P0**, **P1**...**Pi**, where 0 < **i** ≤ **N**. At each cell, rendering starts at
|
||||
the topmost intersecting plane **P0**. The algorithm descends until either:
|
||||
|
||||
* it has locked in an extended grapheme cluster, and fore/background colors, or
|
||||
* all **i** planes have been examined
|
||||
|
||||
At each plane **P**, we consider a cell **C**. This cell is the intersecting cell,
|
||||
unless that cell has no EGC. In that case, **C** is the plane's default cell.
|
||||
|
||||
* If we have not yet determined an EGC, and **C** has a non-zero EGC, use the EGC and style of **C**.
|
||||
* If we have not yet locked in a foreground color, and **C** is not foreground-transparent, use the foreground color of **C** (see [BUGS][] below). If **C** is **CELL_ALPHA_OPAQUE**, lock the color in.
|
||||
* If we have not yet locked in a background color, and **C** is not background-transparent, use the background color of **C** (see [BUGS][] below). If **C** is **CELL_ALPHA_OPAQUE**, lock the color in.
|
||||
|
||||
If the algorithm concludes without an EGC, the cell is rendered with no glyph
|
||||
and a default background. If the algorithm concludes without a color locked in,
|
||||
the color as computed thus far is used.
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
On success, 0 is returned. On failure, a non-zero value is returned. A success
|
||||
will result in the **renders** stat being increased by 1. A failure will result
|
||||
in the **failed_renders** stat being increased by 1.
|
||||
|
||||
# BUGS
|
||||
|
||||
In addition to the RGB colors, it is possible to use the "default foreground color"
|
||||
and "default background color" inherited from the terminal. Since
|
||||
notcurses doesn't know what these colors are, they are not considered for
|
||||
purposes of color blending.
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **notcurses_cell(3)**, **notcurses_ncplane(3)**,
|
||||
**notcurses_output(3)**, **notcurses_stats(3)**, **console_codes(4)**,
|
||||
**utf-8(7)**
|
||||
@ -1,77 +0,0 @@
|
||||
notcurses_render(3) -- sync the physical display to virtual ncplanes
|
||||
====================================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
`int notcurses_render(struct notcurses* nc);`
|
||||
|
||||
`char* notcurses_at_yx(struct notcurses* nc, int yoff, int xoff, cell* c);`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
`notcurses_render` syncs the physical display to the context's prepared
|
||||
ncplanes. It is necessary to call `notcurses_render` to generate any visible
|
||||
output; the various notcurses_output(3) calls only draw to the virtual
|
||||
ncplanes. Most of the notcurses statistics are updated as a result of a
|
||||
render (see notcurses_stats(3)).
|
||||
|
||||
A render operation consists of two logical phases: generation of the rendered
|
||||
scene, and blitting this scene to the terminal (these two phases might actually
|
||||
be interleaved, streaming the output as it is rendered). All ncplanes are
|
||||
locked while generating the frame. Frame generation requires determining an
|
||||
extended grapheme cluster, foreground color, background color, and style for
|
||||
each cell of the physical terminal. Writing the scene requires synthesizing
|
||||
a set of UTF-8-encoded characters and escape codes appropriate for the terminal
|
||||
(relying on terminfo(5)), and writing this sequence to the output `FILE*`. If
|
||||
the `renderfp` value was not NULL in the original call to notcurses_init(3),
|
||||
the frame will be written to that `FILE*` as well. This write does not affect
|
||||
statistics.
|
||||
|
||||
Each cell can be rendered in isolation, though synthesis of the stream carries
|
||||
dependencies between cells.
|
||||
|
||||
### Cell rendering algorithm
|
||||
|
||||
Recall that there is a total ordering on the N ncplanes, and that the standard
|
||||
plane always exists, with geometry equal to the physical screen. Each cell of
|
||||
the physical screen is thus intersected by some totally ordered subset of
|
||||
planes `P0`, `P1`...`Pi`, where 0 < `i` ≤ `N`. At each cell, rendering starts at
|
||||
the topmost intersecting plane `P0`. The algorithm descends until either:
|
||||
|
||||
* it has locked in an extended grapheme cluster, and fore/background colors, or
|
||||
* all `i` planes have been examined
|
||||
|
||||
At each plane `P`, we consider a cell `C`. This cell is the intersecting cell,
|
||||
unless that cell has no EGC. In that case, `C` is the plane's default cell.
|
||||
|
||||
* If we have not yet determined an EGC, and `C` has a non-zero EGC, use the EGC and style of `C`.
|
||||
* If we have not yet locked in a foreground color, and `C` is not foreground-transparent, use the foreground color of `C` (see [BUGS][] below). If `C` is `CELL_ALPHA_OPAQUE`, lock the color in.
|
||||
* If we have not yet locked in a background color, and `C` is not background-transparent, use the background color of `C` (see [BUGS][] below). If `C` is `CELL_ALPHA_OPAQUE`, lock the color in.
|
||||
|
||||
If the algorithm concludes without an EGC, the cell is rendered with no glyph
|
||||
and a default background. If the algorithm concludes without a color locked in,
|
||||
the color as computed thus far is used.
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
On success, 0 is returned. On failure, a non-zero value is returned. A success
|
||||
will result in the `renders` stat being increased by 1. A failure will result
|
||||
in the `failed_renders` stat being increased by 1.
|
||||
|
||||
## BUGS
|
||||
|
||||
In addition to the RGB colors, it is possible to use the "default foreground color"
|
||||
and "default background color" inherited from the terminal. Since
|
||||
notcurses doesn't know what these colors are, they are not considered for
|
||||
purposes of color blending.
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses_cell(3), notcurses_ncplane(3), notcurses_output(3),
|
||||
notcurses_stats(3), console_codes(4), utf-8(7)
|
||||
@ -1,11 +1,17 @@
|
||||
notcurses_stats(3) -- notcurses runtime statistics
|
||||
==================================================
|
||||
% notcurses_stats(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
## SYNOPSIS
|
||||
# NAME
|
||||
|
||||
`#include <notcurses.h>`
|
||||
notcurses_stats—notcurses runtime statistics
|
||||
|
||||
<pre>typedef struct ncstats {
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
```c
|
||||
typedef struct ncstats {
|
||||
uint64_t renders; // number of successful renders
|
||||
uint64_t failed_renders; // aborted renders, should be 0
|
||||
uint64_t render_bytes; // bytes emitted to ttyfp
|
||||
@ -23,27 +29,28 @@ notcurses_stats(3) -- notcurses runtime statistics
|
||||
uint64_t bgemissions; // RGB bg emissions
|
||||
uint64_t defaultelisions; // default color was emitted
|
||||
uint64_t defaultemissions; // default color was elided
|
||||
} ncstats;</pre>
|
||||
} ncstats;
|
||||
```
|
||||
|
||||
`void notcurses_stats(struct notcurses* nc, ncstats* stats);`
|
||||
**void notcurses_stats(struct notcurses* nc, ncstats* stats);**
|
||||
|
||||
`void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);`
|
||||
**void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);**
|
||||
|
||||
## DESCRIPTION
|
||||
# DESCRIPTION
|
||||
|
||||
`notcurses_stats` acquires an atomic snapshot of statistics, primarily
|
||||
related to notcurses_render(3). `notcurses_reset_stats` does the same, but
|
||||
also resets all cumulative stats (immediate stats such as `fbbytes` are not
|
||||
**notcurses_stats** acquires an atomic snapshot of statistics, primarily
|
||||
related to notcurses_render(3). **notcurses_reset_stats** does the same, but
|
||||
also resets all cumulative stats (immediate stats such as **fbbytes** are not
|
||||
reset).
|
||||
|
||||
## RETURN VALUES
|
||||
# NOTES
|
||||
|
||||
Unsuccessful render operations do not contribute to the render timing stats.
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
Neither of these functions can fail. Neither returns any value.
|
||||
|
||||
## AUTHOR
|
||||
# SEE ALSO
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses_render(3)
|
||||
**notcurses(3)**, **notcurses_render(3)**
|
||||
37
doc/man/man3/notcurses_stdplane.3.md
Normal file
37
doc/man/man3/notcurses_stdplane.3.md
Normal file
@ -0,0 +1,37 @@
|
||||
% notcurses_stdplane(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
**notcurses_stdplane**—acquire the standard ncplane
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
**struct ncplane*
|
||||
notcurses_stdplane(struct notcurses* nc);**
|
||||
|
||||
**const struct ncplane*
|
||||
notcurses_const_stdplane(const struct notcurses* nc);**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
**notcurses_stdplane** returns a handle to the standard ncplane for the context
|
||||
**nc**. The standard plane always exists, and is always the same size as the
|
||||
screen. It is an error to call **ncplane_destroy(3)**, **ncplane_resize(3)**,
|
||||
or **ncplane_move(3)** on the standard plane, though it can be freely moved
|
||||
along the z-axis.
|
||||
|
||||
A resize event does not invalidate this reference; it can be used until
|
||||
**notcurses_stop(3)** is called on **nc**.
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
These functions cannot fail when provided a valid **struct notcurses**. They
|
||||
will always return a valid pointer to the standard plane.
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **notcurses_ncplane(3)**, **notcurses_stop(3)**
|
||||
@ -1,36 +0,0 @@
|
||||
notcurses_stdplane(3) -- acquire the standard ncplane
|
||||
=====================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
`struct ncplane*
|
||||
notcurses_stdplane(struct notcurses* nc);`
|
||||
|
||||
`const struct ncplane*
|
||||
notcurses_const_stdplane(const struct notcurses* nc);`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
`notcurses_stdplane` returns a handle to the standard ncplane for the context
|
||||
`nc`. The standard plane always exists, and is always the same size as the
|
||||
screen. It is an error to call `ncplane_destroy(3)`, `ncplane_resize(3)`, or
|
||||
`ncplane_move(3)` on the standard plane, though it can be freely moved along
|
||||
the z-axis.
|
||||
|
||||
A resize event does not invalidate this reference; it can be used until
|
||||
`notcurses_stop(3)` is called on `nc`.
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
These functions cannot fail when provided a valid `struct notcurses*`. They
|
||||
will always return a valid pointer to the standard plane.
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses_ncplane(3), notcurses_stop(3)
|
||||
34
doc/man/man3/notcurses_stop.3.md
Normal file
34
doc/man/man3/notcurses_stop.3.md
Normal file
@ -0,0 +1,34 @@
|
||||
% notcurses_stop(3)
|
||||
% nick black <nickblack@linux.com>
|
||||
% v0.9.9
|
||||
|
||||
# NAME
|
||||
|
||||
notcurses_stop—free up resources and restore initial terminal state
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**#include <notcurses.h>**
|
||||
|
||||
**int notcurses_stop(struct notcurses* nc);**
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
**notcurses_stop** frees up any resources associated with the
|
||||
**struct notcurses** provided as **nc**, and attempts to restore the terminal to its
|
||||
state prior to calling notcurses_init(3). It also unregisters any signal
|
||||
handlers put into place by notcurses_init(3). **nc** must not be used following
|
||||
the call.
|
||||
|
||||
# NOTES
|
||||
|
||||
Behavior is undefined if other threads are working with **nc** when or after
|
||||
this function is called. It is unlikely to be good.
|
||||
|
||||
# RETURN VALUES
|
||||
|
||||
On success, 0 is returned. Otherwise, a negative value is returned.
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**notcurses(3)**, **notcurses_init(3)**
|
||||
@ -1,27 +0,0 @@
|
||||
notcurses_stop(3) -- free up notcurses and restore the console
|
||||
==============================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
`#include <notcurses.h>`
|
||||
|
||||
`int notcurses_stop(struct notcurses* nc);`
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
`notcurses_stop` frees up any resources associated with the `struct notcurses*`
|
||||
provided as `nc`, and attempts to restore the terminal to its state prior to
|
||||
calling notcurses_init(3). It also unregisters any signal handlers put into
|
||||
place by notcurses_init(3). `nc` must not be used following the call.
|
||||
|
||||
## RETURN VALUES
|
||||
|
||||
On success, 0 is returned. Otherwise, a negative value is returned.
|
||||
|
||||
## AUTHOR
|
||||
|
||||
Nick Black <nickblack@linux.com>
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
notcurses(3), notcurses_init(3)
|
||||
Loading…
x
Reference in New Issue
Block a user