DOCSEARCHbyAlgolia
Submit Docs

ncurses Documentation

repository·master·Indexed 20 days ago

https://github.com/mirror/ncurses

A comprehensive library for terminal-based user interfaces providing the curses API along with panel, menu, and form libraries. Includes documentation for the C++ interface and its class hierarchy (NCursesWindow, NCursesPanel, NCursesMenu, NCursesForm), Ada95 bindings, and utilities such as clear and tabs. Covers terminfo storage configurations, the ncurses6 screen dump file format, and legacy binary formats.

Tokens
9.5K
Snippets
24
Records
53
Agent score
67%

What's inside ncurses

  1. Overview of ncurses base modules

    master

    The functions located in the base/ directory of ncurses constitute the generic, device-independent modules of the library. These modules provide core functionality that is not tied to specific terminal types.

    Developer Note: When working with or extending these modules, they are designed to be decoupled from terminal-specific data. As a rule, these modules should not depend directly on term.h references or associated terminfo functions and variables.

  2. Overview of the ncurses trace directory

    master

    The trace directory contains files that provide tracing support for both the terminfo and ncurses libraries.

    Important Note on Compilation: Most tracing functions are only available and linked if the libraries are explicitly compiled with the TRACE macro defined.

  3. Overview of ncurses

    master
    ncurses is a library that provides a terminal-independent way to create text-based user interfaces. It allows developers to control terminal capabilities such as cursor movement, color, and window management across different terminal types. For detailed discussions on the internal implementation and package architecture, refer to hackguide.html located in the doc/html directory of the repository.

  4. Overview of the tinfo library

    master

    The tinfo directory contains the files necessary to support the terminfo database and provide interfaces for ncurses. The tinfo library serves two primary purposes:

    1. Terminfo Database Support: It provides the underlying data and logic for managing terminal information.
    2. ncurses Interface: It provides the low-level interfaces used by ncurses.

    While tinfo can be built as a standalone, lower-level library, it is typically bundled with ncurses.

  5. Overview of ncurses libraries and components

    master

    ncurses is a collection of libraries and utilities for terminal handling and text-based user interfaces. A full installation typically includes several libraries, utilities, and a terminal description database.

    Core Libraries

    • ncurses: Implements the standard curses API.
    • panel: Implements clones of the SVr4 panel API.
    • menu: Implements clones of the SVr4 menu API.
    • form: Implements clones of the SVr4 forms API.

    Library Variants

    Depending on your configuration, library names will change:

    • Wide-character support: If configured with --enable-widec, a w is appended to the library names (e.g., libncursesw.a). These support wide-characters (e.g., via UTF-8 locale). The header files are compatible with non-wide configurations, but the wide-character libraries are not binary-compatible with the non-wide versions.
    • Reentrancy: If configured with --enable-reentrant, a t is appended to the library names (e.g., libncursest.a). This provides a different binary interface that makes the ncurses interface more "opaque."
    • Debug/Profiling:
      • _g suffix (e.g., libncurses_g.a): Debug and trace code enabled.
      • _p suffix (e.g., libncurses_p.a): Profiling enabled.

  6. Use the C++ interface to ncurses routines

    master

    The ncurses C++ interface provides a set of classes designed to simplify writing terminal-based applications. Instead of using raw C functions, you can use object-oriented classes that encapsulate window-specific operations.

    Key benefits include:

    • Simplified Window Management: Window-specific functions are encapsulated within window objects. Function overloading is used to provide a narrower, cleaner interface (e.g., combining printw and mvprintw into a single overloaded method).
    • Type Safety: The interface replaces many #define macros from curses.h with inline functions, enabling strict type checking of arguments and reducing identifier collisions.
    • Integrated Color Support: Color support is built into the base class, allowing any derived class (like Panels, Menus, or Forms) to use color seamlessly alongside monochrome windows.
    • Package Integration: The interface provides native support for the panels, menu, and form libraries through a class hierarchy.

    To learn how to use these classes, refer to the example programs provided in the repository, as formal documentation is currently limited.

  7. Understand terminfo entry naming and structure

    master

    When using infocmp, the output follows the terminfo(n) format. The first line of a description contains the names by which terminfo identifies the terminal, separated by pipe-bar (|) characters, with the last field terminated by a comma.

    • Primary Name: The first name field. This is the name you should use when setting the TERM environment variable.
    • Aliases: Names between the first and last fields are aliases (often historical names) used for compatibility.
    • Description: The last name field is a description of the terminal type (may contain spaces).

  8. How to use extended key-definitions

    master

    Terminals often send distinct strings for combinations of modified special keys (e.g., Shift + F1). Since the standard set of 60 function keys is insufficient, ncurses uses an extended naming convention based on xterm(1).

    1. Naming Convention

    Extended keys use a base name (starting with k) followed by a suffix representing the modifier.

    Base Names:

    • kDC: special form of kdch1 (delete character)
    • kDN: special form of kcud1 (cursor down)
    • kEND: special form of kend (End)
    • kHOM: special form of khome (Home)
    • kLFT: special form of kcub1 (cursor-left)
    • kNXT: special form of knext (Next/Page-Down)
    • kPRV: special form of kprev (Prev/Page-Up)
    • kRIT: special form of kcuf1 (cursor-right)
    • kUP: special form of kcuu1 (cursor-up)

    Modifier Suffixes:

    SuffixModifier
    2Shift
    3Alt
    4Shift + Alt
    5Control
    6Shift + Control
    7Alt + Control
    8Shift + Alt + Control
    9Meta
    10Meta + Shift
    11Meta + Alt
    12Meta + Alt + Shift
    13Meta + Ctrl
    14Meta + Ctrl + Shift
    15Meta + Ctrl + Alt
    16Meta + Ctrl + Alt + Shift

  9. Check for event-watching support via NCURSES_EVENT_VERSION

    master
    To determine if the ncurses installation supports the event-watching extension, check if the macro NCURSES_EVENT_VERSION is defined during compilation. If this symbol is not defined (for example, on BeOS), the event-watching API is not available.

  10. Understand the C++ class hierarchy for windows, panels, and menus

    master

    The C++ interface uses an inheritance hierarchy to allow complex UI elements to share core functionality like color support and window management. This structure allows you to build sophisticated interfaces using windows, panels, menus, and forms.

    Class Hierarchy:

    • NCursesWindow: The base class providing core window functionality and color support.
      • NCursesPanel: Derived from NCursesWindow; provides support for the ncurses panels library.
        • NCursesMenu: Derived from NCursesPanel; provides support for the ncurses menu library.
        • NCursesForm: Derived from NCursesPanel; provides support for the ncurses form library.

    Note: The NCursesColorWindow class is also available for compatibility with older implementations, but it is recommended to use the base NCursesWindow for modern color support.

  11. Understand ncurses terminal requirements

    master

    For ncurses to function correctly, two environmental requirements must be met:

    1. TERM Environment Variable: The TERM variable must be set to your terminal type (e.g., xterm, vt100). This is typically handled by the OS or getty(1), but can be manually overridden in your shell profile.
    2. Terminal Database: ncurses requires a database of terminal capabilities. It prefers the binary terminfo hierarchy (typically under /usr/lib/terminfo), but can fall back to the older flat-file termcap format (/etc/termcap) if configured with --enable-termcap.

  12. Extended Number Format (ncurses 6.1+)

    master

    To support capabilities requiring more than 16-bit signed integers, ncurses 6.1 introduced an extended number format.

    Key changes:

    • Uses a different magic number (octal 01036).
    • Changes the numbers array type from signed 16-bit integers to signed 32-bit integers.

    While the library uses an internal TERMTYPE2 structure to handle these larger numbers, it maintains compatibility by presenting the same TERMTYPE structure to legacy applications (though legacy callers will not be able to access the extended 32-bit values).