DOCSEARCHbyAlgolia
Submit Docs

Notcurses Documentation

repository·master·Indexed 26 days ago

https://github.com/dankamongmen/notcurses

A high-performance library for creating advanced, multimedia-capable Terminal User Interfaces (TUIs) on modern terminal emulators. It supports 24-bit color, Unicode, bitmapped graphics (Sixel, Kitty, Linux framebuffer), and multimedia (images, video). The project includes a C library, C++ bindings, and CFFI-based Python bindings, along with utilities like ncls, ncplayer, and notcurses-info.

Tokens
35.8K
Snippets
36
Records
230
Agent score
88%

What's inside Notcurses

  1. Overview of Notcurses

    master

    Notcurses is a high-performance library for creating complex Terminal User Interfaces (TUIs) on modern terminal emulators. Unlike NCURSES, it is designed to maximize terminal capabilities, including 24-bit color, Unicode (Extended Grapheme Clusters), multimedia (images, video), and bitmapped graphics (Sixel, Kitty, Linux framebuffer).

    Key features include:

    • Thread safety and efficient parallel programming support.
    • Native support for the Universal Character Set (Unicode).
    • High-performance 'TUI mode' for full-screen apps and 'CLI mode' for scrolling shell utilities.
    • Support for unambiguous keyboard protocols.
    • Apache2 license.

  2. Overview of Notcurses Python bindings

    master

    The notcurses Python package provides CFFI-based bindings for the Notcurses C library. Notcurses is used to build complex, vibrant textual user interfaces (TUIs) on modern terminal emulators.

    Note: These Python bindings do not offer complete coverage of the full Notcurses C API.

  4. Use the ncselector widget for item selection

    master
    The ncselector is a high-level widget used to present a list of items and facilitate the selection of zero or one item from that list. It can handle dynamic item sets and provides built-in support for common input controls like arrow keys, PageUp/PageDown, and mouse scrolling when input is offered via ncselector_offer_input.

  5. Understand and manage ncplanes

    master

    An ncplane is the fundamental drawing object in Notcurses. It acts as a framebuffer of nccells and can be sized and positioned anywhere.

    Key Characteristics:

    • Hierarchy: Planes can be bound to other planes. If a parent plane moves, all its bound planes move with it. When a plane is destroyed, all its bound descendants are also destroyed.
    • Coordinate Systems: If a plane is bound to another, its x and y coordinates are relative to the parent plane.
    • Base Cells: Every plane has a base nccell. When rendering, any cell without a specific glyph uses the base cell's attributes. ncplane_erase does not affect the base cell.
    • Concurrency: It is an error for two threads to concurrently mutate a single ncplane. However, multiple threads may safely output to different ncplanes simultaneously, or multiple threads may read from the same ncplane if no rendering is taking place.

  6. Understand design differences between Notcurses and NCURSES

    master

    If you are coming from an NCURSES background, be aware of these fundamental architectural differences in Notcurses:

    • Z-Buffer vs Panels: There is no PANEL type. All drawable surfaces are ordered along a z-axis. There is no update_panels() equivalent.
    • Scrolling: Scrolling is disabled by default and cannot be globally enabled (use Direct Mode instead).
    • Character Representation: Instead of cchar_t (fixed-size wchar_t array), Notcurses uses nccell, which supports arbitrary-length UTF-8 encoded extended grapheme clusters (ASCII or Unicode).
    • Cursor & Input: The cursor is disabled by default (if civis is supported). Echoing is disabled by default, and cbreak mode is used by default.
    • Colors: Colors are specified as 24-bit RGB components. There are no "color pairs," though indexed palettes are supported.
    • Pads: There is no distinct "pad" concept; all drawable surfaces can exceed the display size (equivalent to NCURSES WINDOWs created with newpad()).
    • Threading: Notcurses is thread-safe. Multiple threads can concurrently mutate different ncplanes.
    • Environment: Notcurses does not interact with LINES or COLUMNS environment variables.
    • Missing Features: Notcurses does not support soft labels (slk_init), subwindows that share memory with parents, curs_util functions (like putwin/getwin), or NCURSES tracing.

  7. Understand Notcurses piles and rendering

    master

    Piles are collections of ncplanes that are independent for rendering and thread-safety.

    Key behaviors:

    • Concurrency: Arbitrary concurrent actions can be safely performed on distinct piles.
    • Rasterization: While piles are independent, only one pile can be rasterized (written to the display) at a time.
    • Composition: Piles do not compose; rasterizing a pile destroys any overlapping material from other piles.
    • Lifecycle: A pile is created via ncpile_create, ncvisual_blit (with a NULL target), or ncplane_reparent. A pile is destroyed when its last ncplane is destroyed or reparented elsewhere.

  8. Understand the Rendering and Rasterization Pipeline

    master

    Notcurses decouples rendering from rasterization to support concurrency and efficiency.

    • Rendering: Operates on a 'pile' (a collection of planes). Multiple piles can be rendered concurrently. Rendering produces a rendered frame.
    • Rasterization: Operates on a single pile, the last frame, and the screen. Concurrent rasterizations are illegal and will result in an error. Rasterization takes the rendered frame and produces a buffer for writeout.
    • Writeout: A blocking process that writes the rasterized buffer to the output descriptor. It is relative to the 'last frame' and only updates damaged cells to optimize performance.

    Critical Constraint: A pile must not be mutated between the rendering and rasterization phases, as this can invalidate Extended Grapheme Cluster (EGC) references used during the process.

  9. Sync the physical display to a virtual pile

    master

    To make changes drawn to ncplanes visible on the terminal, you must perform a render and rasterization. Drawing functions only modify the virtual planes; they do not update the physical screen.

    Use notcurses_render for a simple, exclusive blocking call that performs both rendering and rasterization on the standard plane. Alternatively, for more granular control over specific piles, use ncpile_render followed by ncpile_rasterize.

    Important Safety Note: While a render operation is in progress, you must not call any other functions modifying the same pile. You may access the pile, but do not modify it until the call returns.

  10. Install build dependencies for APT (Debian/Ubuntu)

    master

    To build Notcurses from source on Debian-based systems, install the following dependencies.

    Core build dependencies: apt-get install build-essential cmake doctest-dev libavdevice-dev libdeflate-dev libgpm-dev libncurses-dev libqrcodegen-dev libswscale-dev libunistring-dev pandoc pkg-config

    Customization notes:

    • No multimedia: Omit libavdevice-dev.
    • No QR codes: Omit libqrcodegen-dev.
    • Use zlib instead of libdeflate: Omit libdeflate-dev and build with -DUSE_DEFLATE=off.

    Python wrappers: If you intend to build the Python wrappers, also install: apt-get install python3-cffi python3-dev python3-pypandoc python3-setuptools

    apt-get install build-essential cmake doctest-dev libavdevice-dev libdeflate-dev libgpm-dev libncurses-dev libqrcodegen-dev libswscale-dev libunistring-dev pandoc pkg-config

  11. Use libnotcurses-core for minimal linkage

    master

    If your application does not require the multimedia capabilities of Notcurses, you can link directly to libnotcurses-core instead of libnotcurses. This reduces the dependency burden of your binary.

    When using libnotcurses-core, you must use the core-specific initialization functions instead of the standard ones to avoid linking errors or unnecessary dependencies.

  12. Configure Notcurses for MSYS2/Cygwin

    master

    Notcurses requires the Windows ConPTY layer.

    • Cygwin: Available by default since version 3.2.0.
    • MSYS: Disabled by default. To enable it, launch mintty with the -P on argument, or export MSYS=enable_pcon before launching it.