mirror of
https://github.com/dankamongmen/notcurses
synced 2025-03-12 18:49:03 -04:00
57 lines
2.3 KiB
Markdown
57 lines
2.3 KiB
Markdown
notcurses(3notcurses) -- 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(3notcurses)` 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 [Initialization][]).
|
|
|
|
### Initialization
|
|
|
|
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` 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.
|
|
|
|
### Shutdown
|
|
|
|
Before exiting, `notcurses_stop(3notcurses)` 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` installs signal handlers to
|
|
catch all signals which would normally terminate the process. The new handlers
|
|
will try to call `notcurses_stop`, and then propagate the received signal to
|
|
the previous action.
|
|
|
|
## AUTHORS
|
|
|
|
Nick Black <nickblack@linux.com>
|
|
|
|
## SEE ALSO
|
|
|
|
notcurses-demo(1), notcurses_init(3notcurses), notcurses_stop(3notcurses),
|
|
ncurses(3NCURSES), terminfo(5)
|