{"id":13464612,"url":"https://github.com/dankamongmen/notcurses","last_synced_at":"2025-10-19T12:47:34.834Z","repository":{"id":38186304,"uuid":"222187361","full_name":"dankamongmen/notcurses","owner":"dankamongmen","description":"blingful character graphics/TUI library. definitely not curses.","archived":false,"fork":false,"pushed_at":"2025-05-13T06:56:01.000Z","size":108155,"stargazers_count":3890,"open_issues_count":293,"forks_count":125,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-05-13T07:42:53.383Z","etag":null,"topics":["c","cli","ncurses","terminal","terminal-emulators"],"latest_commit_sha":null,"homepage":"https://nick-black.com/dankwiki/index.php/Notcurses","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dankamongmen.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"dankamongmen"}},"created_at":"2019-11-17T02:38:24.000Z","updated_at":"2025-05-13T06:56:10.000Z","dependencies_parsed_at":"2024-03-23T11:22:03.004Z","dependency_job_id":"dc762c88-7204-4728-9021-89f989a7bcbf","html_url":"https://github.com/dankamongmen/notcurses","commit_stats":{"total_commits":8261,"total_committers":41,"mean_commits":201.4878048780488,"dds":0.07747246096114269,"last_synced_commit":"3c7dcd951e75b0061c3523abd112dd217a1af863"},"previous_names":[],"tags_count":145,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankamongmen%2Fnotcurses","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankamongmen%2Fnotcurses/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankamongmen%2Fnotcurses/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankamongmen%2Fnotcurses/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dankamongmen","download_url":"https://codeload.github.com/dankamongmen/notcurses/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253900315,"owners_count":21981259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cli","ncurses","terminal","terminal-emulators"],"created_at":"2024-07-31T14:00:47.388Z","updated_at":"2025-10-19T12:47:34.807Z","avatar_url":"https://github.com/dankamongmen.png","language":"C","readme":"# Notcurses: blingful TUIs and character graphics\n\n**What it is**: a library facilitating complex TUIs on modern terminal\nemulators, supporting vivid colors, multimedia, threads, and Unicode to the\nmaximum degree possible. [Things](https://www.youtube.com/watch?v=dcjkezf1ARY) can be done with\nNotcurses that simply can't be done with NCURSES. It is furthermore\nfast as shit. **What it is not**: a source-compatible X/Open Curses implementation, nor a\nreplacement for NCURSES on existing systems.\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://www.youtube.com/watch?v=dcjkezf1ARY\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/dankamongmen/notcurses/gh-pages/notcurses-logo.png\" alt=\"setting the standard (hype video)\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nfor more information, see [dankwiki](https://nick-black.com/dankwiki/index.php/Notcurses)\nand the [man pages](https://notcurses.com). in addition, there is\n[Doxygen](https://notcurses.com/html/) output.\ni wrote a coherent [guidebook](https://nick-black.com/htp-notcurses.pdf), which is available for\nfree download (or [paperback purchase](https://amazon.com/dp/B086PNVNC9)).\n\ni've not yet added many documented examples, but [src/poc/](https://github.com/dankamongmen/notcurses/tree/master/src/poc)\nand [src/pocpp/](https://github.com/dankamongmen/notcurses/tree/master/src/pocpp)\ncontain many small C and C++ programs respectively. `notcurses-demo` covers\nmost of the functionality of Notcurses.\n\n**If you're running Notcurses applications in a Docker, please consult\n\"[Environment notes](#environment-notes)\" below.**\n\n\u003ca href=\"https://repology.org/project/notcurses/versions\"\u003e\n\u003cimg src=\"https://repology.org/badge/vertical-allrepos/notcurses.svg\" alt=\"Packaging status\" align=\"right\"\u003e\n\u003c/a\u003e\n\n![Linux](https://img.shields.io/badge/-Linux-grey?logo=linux)\n![FreeBSD](https://img.shields.io/badge/-FreeBSD-grey?logo=freebsd)\n![Windows](https://img.shields.io/badge/-Windows-grey?logo=windows)\n![macOS](https://img.shields.io/badge/-macOS-grey?logo=macos)\n\n[![Linux](https://github.com/dankamongmen/notcurses/actions/workflows/ubuntu_test.yml/badge.svg?branch=master)](https://github.com/dankamongmen/notcurses/actions/workflows/ubuntu_test.yml?query=branch%3Amaster)\n[![macOS](https://github.com/dankamongmen/notcurses/actions/workflows/macos_test.yml/badge.svg?branch=master)](https://github.com/dankamongmen/notcurses/actions/workflows/macos_test.yml?query=branch%3Amaster)\n[![Windows](https://github.com/dankamongmen/notcurses/actions/workflows/windows_test.yml/badge.svg?branch=master)](https://github.com/dankamongmen/notcurses/actions/workflows/windows_test.yml?query=branch%3Amaster)\n\n[![pypi_version](https://img.shields.io/pypi/v/notcurses?label=pypi)](https://pypi.org/project/notcurses)\n[![crates.io](https://img.shields.io/crates/v/libnotcurses-sys.svg)](https://crates.io/crates/libnotcurses-sys)\n\n[![Matrix](https://img.shields.io/matrix/notcursesdev:matrix.org?label=matrixchat)](https://app.element.io/#/room/#notcursesdev:matrix.org)\n[![Sponsor](https://img.shields.io/badge/-Sponsor-red?logo=github)](https://github.com/sponsors/dankamongmen)\n\n## Introduction\n\nNotcurses abandons the X/Open Curses API bundled as part of the Single UNIX\nSpecification. For some necessary background, consult Thomas E. Dickey's\nsuperb and authoritative [NCURSES FAQ](https://invisible-island.net/ncurses/ncurses.faq.html#xterm_16MegaColors).\nAs such, Notcurses is not a drop-in Curses replacement.\n\nWherever possible, Notcurses makes use of the Terminfo library shipped with\nNCURSES, benefiting greatly from its portability and thoroughness.\n\nNotcurses opens up advanced functionality for the interactive user on\nworkstations, phones, laptops, and tablets, possibly at the expense of e.g.\nsome industrial and retail terminals. Fundamentally, Curses assumes the minimum\nand allows you (with effort) to step up, whereas Notcurses assumes the maximum\nand steps down (by itself) when necessary. The latter approach probably breaks\non some older hardware, but the former approach results in new software looking\nlike old hardware.\n\nWhy use this non-standard library?\n\n* Thread safety, and efficient use in parallel programs, has been a design\n  consideration from the beginning.\n\n* A more orderly surface than that codified by X/Open: Exported identifiers are\n  prefixed to avoid common namespace collisions. Where reasonable,\n  `static inline` header-only code is used. This facilitates compiler\n  optimizations, and reduces loader time. Notcurses can be built without its\n  multimedia functionality, requiring a significantly lesser set of dependencies.\n\n* All APIs natively support the Universal Character Set (Unicode). The `nccell`\n  API is based around Unicode's [Extended Grapheme Cluster](https://unicode.org/reports/tr29/) concept.\n\n* Visual features including images, fonts, video, high-contrast text, sprites,\n  and transparent regions. All APIs natively support 24-bit color, quantized\n  down as necessary for the terminal.\n\n* Portable support for bitmapped graphics, using Sixel, Kitty,\n  and even the Linux framebuffer console.\n\n* Support for unambiguous [keyboard protocols](https://sw.kovidgoyal.net/kitty/keyboard-protocol/).\n\n* \"TUI mode\" facilitates high-performance, non-scrolling, full-screen\n  applications. \"CLI mode\" supports scrolling output for shell utilities,\n  but with the full power of Notcurses.\n\n* It's Apache2-licensed in its entirety, as opposed to the\n  [drama in several acts](https://invisible-island.net/ncurses/ncurses-license.html)\n  that is the NCURSES license (the latter is [summarized](https://invisible-island.net/ncurses/ncurses-license.html#issues_freer)\n  as \"a restatement of MIT-X11\").\n\nMuch of the above can be had with NCURSES, but they're not what NCURSES was\n*designed* for. On the other hand, if you're targeting industrial or critical\napplications, or wish to benefit from time-tested reliability and\nportability, you should by all means use that fine library.\n\n## Requirements\n\nMinimum versions generally indicate the oldest version I've tested with; it\nmay well be possible to use still older versions. Let me know of any successes!\n\n* (build) CMake 3.21.0+ and a C17 compiler\n* (OPTIONAL) (OpenImageIO, testing, C++ bindings): A C++17 compiler\n* (build+runtime) From [NCURSES](https://invisible-island.net/ncurses/announce.html): terminfo 6.1+\n* (build+runtime) GNU [libunistring](https://www.gnu.org/software/libunistring/) 0.9.10+\n* (OPTIONAL) (build+runtime) [libgpm](https://www.nico.schottelius.org/software/gpm/) 1.20+\n* (OPTIONAL) (build+runtime) From QR-Code-generator: [libqrcodegen](https://github.com/nayuki/QR-Code-generator) 1.5.0+\n* (OPTIONAL) (build+runtime) From [FFmpeg](https://www.ffmpeg.org/): libswscale 5.0+, libavformat 57.0+, libavutil 56.0+, libavdevice 57.0+\n* (OPTIONAL) (build+runtime) [OpenImageIO](https://github.com/OpenImageIO/oiio) 2.15.0+, requires C++\n* (OPTIONAL) (testing) [Doctest](https://github.com/onqtam/doctest) 2.3.5+\n* (OPTIONAL) (documentation) [pandoc](https://pandoc.org/index.html) 1.19.2+\n* (OPTIONAL) (python bindings): Python 3.7+, [CFFI](https://pypi.org/project/cffi/) 1.13.2+, [pypandoc](https://pypi.org/project/pypandoc/) 1.5+\n* (runtime) Linux 2.6+, FreeBSD 11+, DragonFly BSD 5.9+, Windows 10 v1093+, or macOS 11.4+\n\nMore information on building and installation is available in [INSTALL.md](INSTALL.md).\n\n### Wrappers\n\nIf you wish to use a language other than C to work with Notcurses, numerous\nwrappers are available. Several are included in this repository, while\nothers are external.\n\n| Language | Lead(s)                       | Repository |\n| -------- | ----------------------------- | ---------- |\n| Ada      | Jeremy Grosser                | [JeremyGrosser/notcursesada](https://github.com/JeremyGrosser/notcursesada) |\n| C++      | Marek Habersack, nick black   | internal   |\n| Dart     | Nelson Fernandez              | [kascote/dart_notcurses](https://github.com/kascote/dart_notcurses) |\n| Julia    | Dheepak Krishnamurthy         | [kdheepak/Notcurses.jl](https://github.com/kdheepak/Notcurses.jl) |\n| Nim      | Michael S. Bradley, Jr.       | [michaelsbradleyjr/nim-notcurses](https://github.com/michaelsbradleyjr/nim-notcurses) |\n| Python   | nick black                    | internal   |\n| Python   | igo95862                      | internal   |\n| Rust     | José Luis Cruz                | [dankamongmen/libnotcurses-sys](https://github.com/dankamongmen/libnotcurses-sys) |\n| Zig      | Jakub Dundalek                | [dundalek/notcurses-zig-example](https://github.com/dundalek/notcurses-zig-example) |\n\n## Included tools\n\nNine executables are installed as part of Notcurses:\n* `ncls`: an `ls` that displays multimedia in the terminal\n* `ncneofetch`: a [neofetch](https://github.com/dylanaraps/neofetch) ripoff\n* `ncplayer`: renders visual media (images/videos)\n* `nctetris`: a tetris clone\n* `notcurses-demo`: some demonstration code\n* `notcurses-info`: detect and print terminal capabilities/diagnostics\n* `notcurses-input`: decode and print keypresses\n* `notcurses-tester`: unit testing\n* `tfman`: a swank manual browser\n\nTo run `notcurses-demo` from a checkout, provide the `data` directory via\nthe `-p` argument. Demos requiring data files will otherwise abort. The base\ndelay used in `notcurses-demo` can be changed with `-d`, accepting a\nfloating-point multiplier. Values less than 1 will speed up the demo, while\nvalues greater than 1 will slow it down.\n\n`notcurses-tester` likewise requires that `data`, populated with the necessary\ndata files, be specified with `-p`. It can be run by itself, or via `make test`.\n\n## Documentation\n\nWith `-DUSE_PANDOC=on` (the default), a full set of man pages and XHTML\nwill be built from `doc/man`. The following Markdown documentation is included\ndirectly:\n\n* Per-release [News](NEWS.md) for packagers, developers, and users.\n* The `TERM` environment variable and [various terminal emulators](TERMINALS.md).\n* Notes on [contributing](CONTRIBUTING.md) and [hacking](doc/HACKING.md).\n* There's a semi-complete [reference guide](USAGE.md).\n* A list of [other TUI libraries](doc/OTHERS.md).\n* Abbreviated [history](doc/HISTORY.md) and thanks.\n* [Differences from](doc/CURSES.md) Curses and adapting Curses programs.\n\nIf you (understandably) want to avoid the large Pandoc stack, but still enjoy\nmanual pages, I publish a tarball with generated man/XHTML along with\neach release. Download it, and install the contents as you deem fit.\n\n## Environment notes\n\n* If your `TERM` variable is wrong, or that terminfo definition is out-of-date,\n  you're going to have a very bad time. Use *only* `TERM` values appropriate\n  for your terminal. If this variable is undefined, or Notcurses can't load the\n  specified Terminfo entry, it will refuse to start, and you will\n  [not be going to space today](https://xkcd.com/1133/).\n\n* Notcurses queries the terminal on startup, enabling some advanced features\n  based on the determined terminal (and even version). Basic capabilities,\n  however, are taken from Terminfo. So if you have, say, Kitty, but\n  `TERM=vt100`, you're going to be able to draw RGBA bitmap graphics (despite\n  such things being but a dream for a VT100), but *unable* to use the alternate\n  screen (despite it being supported by every Kitty version). So `TERM` and an\n  up-to-date Terminfo database remain important.\n\n* Ensure your `LANG` environment variable is set to a UTF8-encoded locale, and\n  that this locale has been generated. This usually means\n  `\"[language]_[Countrycode].UTF-8\"`, i.e. `en_US.UTF-8`. The first part\n  (`en_US`) ought exist as a directory or symlink in `/usr/share/locales`.\n  This usually requires editing `/etc/locale.gen` and running `locale-gen`.\n  On Debian systems, this can be accomplished with `dpkg-reconfigure locales`,\n  and enabling the desired locale. The default locale is stored somewhere like\n  `/etc/default/locale`.\n\n* If your terminal has an option about default interpretation of \"ambiguous-width\n  characters\" (this is actually a technical term from Unicode), ensure it is\n  set to **Wide**, not narrow (if that doesn't work, ensure it is set to\n  **Narrow**, heh).\n\n* If your terminal supports 3x8bit RGB color via `setaf` and `setbf` (most\n  modern terminals), but exports neither the `RGB` nor `Tc` terminfo capability,\n  you can export the `COLORTERM` environment variable as `truecolor` or `24bit`.\n  Note that some terminals accept a 24-bit specification, but map it down to\n  fewer colors. RGB is unconditionally enabled whenever\n  [most modern terminals](TERMINALS.md) are identified.\n\n### Fonts\n\nGlyph width, and indeed whether a glyph can be displayed at all, is dependent\nin part on the font configuration. Ideally, your font configuration has a\nglyph for every Unicode EGC, and each glyph's width matches up with the POSIX\nfunction's `wcswidth()` result for the EGC. If this is not the case, you'll\nlikely get blanks or � (U+FFFD, REPLACEMENT CHARACTER) for missing characters,\nand subsequent characters on the line may be misplaced.\n\nIt is worth knowing that several terminals draw the block characters directly,\nrather than loading them from a font. This is generally desirable. Quadrants,\nsextants, and octants are not the place to demonstrate your design virtuosity.\nTo inspect your environment's rendering of drawing characters, run\n`notcurses-info`. The desired output ought look something like this:\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/dankamongmen/notcurses/gh-pages/notcurses-info.png\" alt=\"notcurses-info can be used to check Unicode drawing\"/\u003e\n\u003c/p\u003e\n\n## FAQs\n\nIf things break or seem otherwise lackluster, **please** consult the\n[Environment Notes](#environment-notes) section! You **need** correct\n`TERM` and `LANG` definitions, and might want `COLORTERM`.\n\n\u003cdetails\u003e\n \u003csummary\u003eCan I use Notcurses in my closed-source program?\u003c/summary\u003e\n Notcurses is licensed under \u003ca href=\"https://www.apache.org/licenses/LICENSE-2.0\"\u003eApache2\u003c/a\u003e,\n a demonstration that I have transcended your petty world of material goods,\n fiat currencies, and closed sources. Implement Microsoft Bob in it. Charge\n rubes for it. Put it in your ballistic missiles so that you have a nice LED\n display of said missile's speed and projected yield; right before impact,\n scroll \"FUCK YOU\" in all the world's languages, and close it out with a smart\n palette fade. Carve the compiled objects onto bricks and mail them to Richard\n Stallman, taunting him through a bullhorn as you do so.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCan I write a CLI program (scrolling, fits in with the shell, etc.)\n   with Notcurses?\u003c/summary\u003e\n   Yes! Use the \u003ccode\u003eNCOPTION_CLI_MODE\u003c/code\u003e flag (an alias for several\n   real flags; see \u003ca href=\"https://notcurses.com/notcurses_init.3.html\"\u003e\u003ccode\u003enotcurses_init(1)\u003c/code\u003e\u003c/a\u003e\n   for more information). You still must explicitly render.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCan I have Notcurses without this huge multimedia stack?\u003c/summary\u003e\n  Again yes! Build with \u003ccode\u003e-DUSE_MULTIMEDIA=none\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCan I build this individual Notcurses program without aforementioned\n  multimedia stack?\u003c/summary\u003e\n  Almost unbelievably, yes! Use \u003ccode\u003enotcurses_core_init()\u003c/code\u003e or\n  \u003ccode\u003encdirect_core_init()\u003c/code\u003e in place of \u003ccode\u003enotcurses_init()\u003c/code\u003e/\n  \u003ccode\u003encdirect_init()\u003c/code\u003e, and link with \u003ccode\u003e-lnotcurses-core\u003c/code\u003e.\n  Your application will likely start a few milliseconds faster;\n  more importantly, it will link against minimal Notcurses installations.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWe're paying by the electron, and have no C++ compiler. Can we still\n  enjoy Notcurses goodness?\u003c/summary\u003e\n  Some of it! You won't be able to build several executables, nor the NCPP C++\n  wrappers, nor can you build with the OpenImageIO multimedia backend (OIIO\n  ships C++ headers). You'll be able to build the main library, though, as\n  well as \u003ccode\u003enotcurses-demo\u003c/code\u003e (and maybe a few other programs).\n  Use \u003ccode\u003e-DUSE_CXX=off\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eDo I want ffmpeg or OpenImageIO?\u003c/summary\u003e\n  While OpenImageIO is a superb library for dealing with single-frame images,\n  its video support is less than perfect (blame me; I've been promising Larry\n  I'd rewrite it for several months), and in any case implemented\n  atop...ffmpeg. ffmpeg is the preferred multimedia backend.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eDoes it work with hardware terminals?\u003c/summary\u003e\n  With the correct \u003ccode\u003eTERM\u003c/code\u003e value, many hardware terminals are\n  supported. In general, if the terminfo database entry indicates mandatory\n  delays, Notcurses will not currently support that terminal properly. It's\n  known that Notcurses can drive the VT320 and VT340, including Sixel graphics\n  on the latter.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhat happens if I try blitting bitmap graphics on a terminal which\n  doesn't support them?\u003c/summary\u003e\n  Notcurses will not make use of bitmap protocols unless the terminal positively\n  indicates support for them, even if \u003ccode\u003eNCBLIT_PIXEL\u003c/code\u003e has been\n  requested. Likewise, sextants (\u003ccode\u003eNCBLIT_3x2\u003c/code\u003e) won't be used without\n  Unicode 13 support, octants (\u003ccode\u003eNCBLIT_4x2\u003c/code\u003e) won't be used without\n  Unicode 16 support, etc. \u003ccode\u003encvisual_blit()\u003c/code\u003e will use the best blitter\n  available, unless \u003ccode\u003eNCVISUAL_OPTION_NODEGRADE\u003c/code\u003e is provided (in\n  which case it will fail).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eNotcurses looks like absolute crap in \u003ccode\u003escreen\u003c/code\u003e.\u003c/summary\u003e\n  \u003ccode\u003escreen\u003c/code\u003e doesn't support RGB colors (at least as of 4.08.00);\n  if you have \u003ccode\u003eCOLORTERM\u003c/code\u003e defined, you'll have a bad time.\n    If you have a \u003ccode\u003escreen\u003c/code\u003e that was compiled with\n    \u003ccode\u003e--enable-colors256\u003c/code\u003e, try exporting\n    \u003ccode\u003eTERM=screen-256color\u003c/code\u003e as opposed to \u003ccode\u003eTERM=screen\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eNotcurses looks like absolute crap in \u003ccode\u003emosh\u003c/code\u003e.\u003c/summary\u003e\n  Yeah it sure does. I'm not yet sure what's up.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eNotcurses looks like absolute crap in Windows Terminal.\u003c/summary\u003e\n  Go to \u003ca href=\"ms-settings:regionlanguage\"\u003eLanguage Setting\u003c/a\u003e, click\n  \"Administrative language settings\", click \"Change system locale\", and check\n  the \"Beta: Use Unicode UTF-8 for worldwide language support\" option. Restart\n  the computer. That ought help a little bit. Try playing with fonts—Cascadia\n  Code and Cascadia Mono both seem to work well (quadrants and Braille both\n  work), whereas Consolas and Courier New both have definite problems.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eI'm getting strange and/or duplicate inputs in Kitty/foot.\u003c/summary\u003e\n  Notcurses supports Kitty's powerful\n  \u003ca href=\"https://sw.kovidgoyal.net/kitty/keyboard-protocol/\"\u003ekeyboard protocol\u003c/a\u003e,\n  which includes things like key release events and modifier keypresses by\n  themselves. This means, among other things, that a program in these terminals\n  will usually immediately get an \u003ccode\u003eNC_ENTER\u003c/code\u003e \u003ccode\u003eNCTYPE_RELEASE\u003c/code\u003e\n  event, and each keypress will typically result in at least two inputs.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhy didn't you just render everything to bitmaps?\u003c/summary\u003e\n  That's not a TUI; it's a slow and inflexible GUI. Many terminal emulators\n  don't support bitmaps. They doesn't work well with mouse selection.\n  Sixels have a limited color palette. With that said, both Sixel and the\n  Kitty bitmap protocol are well-supported.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eMy multithreaded program doesn't see \u003ccode\u003eNCKEY_RESIZE\u003c/code\u003e until\n  I press some other key.\u003c/summary\u003e\n  You've almost certainly failed to mask \u003ccode\u003eSIGWINCH\u003c/code\u003e in some thread,\n  and that thread is receiving the signal instead of the thread which called\n  \u003ccode\u003enotcurses_getc_blocking()\u003c/code\u003e. As a result, the \u003ccode\u003epoll()\u003c/code\u003e\n  is not interrupted. Call \u003ccode\u003epthread_sigmask()\u003c/code\u003e before spawning any\n  threads.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eUsing the C++ wrapper, how can I ensure that the \u003ccode\u003eNotCurses\u003c/code\u003e\n  destructor is run when I return from \u003ccode\u003emain()\u003c/code\u003e?\u003c/summary\u003e\n  As noted in the\n  \u003ca href=\"https://isocpp.org/wiki/faq/dtors#artificial-block-to-control-lifetimes\"\u003e\n  C++ FAQ\u003c/a\u003e, wrap it in an artificial scope (this assumes your\n  \u003ccode\u003eNotCurses\u003c/code\u003e is scoped to \u003ccode\u003emain()\u003c/code\u003e).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow do I hide a plane I want to make visible later?\u003c/summary\u003e\n  In order of least to most performant: move it offscreen using\n  \u003ccode\u003encplane_move_yx()\u003c/code\u003e, move it underneath an opaque plane with\n  \u003ccode\u003encplane_move_below()\u003c/code\u003e, or move it off-pile with\n  \u003ccode\u003encplane_reparent()\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhy isn't there an \u003ccode\u003encplane_box_yx()\u003c/code\u003e? Do you hate\n  orthogonality, you dullard?\u003c/summary\u003e \u003ccode\u003encplane_box()\u003c/code\u003e and friends\n  already have far too many arguments, you monster.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhy doesn't Notcurses support 10- or 16-bit color?\u003c/summary\u003e\n  Notcurses supports 24 bits of color, spread across three eight-bit channels.\n  You presumably mean 10-bit-per-channel color. I needed those six bits for\n  other things. When terminals support it, Notcurses might support it.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eThe name is dumb.\u003c/summary\u003e\n  That's not a question?\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eI'm not finding qrcodegen on BSD, despite having installed\n  \u003ccode\u003egraphics/qr-code-generator\u003c/code\u003e.\u003c/summary\u003e\n  Try \u003ccode\u003ecmake -DCMAKE_REQUIRED_INCLUDES=/usr/local/include\u003c/code\u003e.\n  This is passed by \u003ccode\u003ebsd.port.mk\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eDo you support \u003ca href=\"https://musl.libc.org/\"\u003emusl\u003c/a\u003e?\u003c/summary\u003e\n  I try to! You'll need at least 1.20.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eI only seem to blit in ASCII, and/or can't emit Unicode beyond ASCII\n  in general.\u003c/summary\u003e\n  Your \u003ccode\u003eLANG\u003c/code\u003e environment variable is underdefined or incorrectly\n  defined, or the necessary locale is not present on your machine (it is also\n  possible that you explicitly supplied \u003ccode\u003eNCOPTION_INHIBIT_SETLOCALE\u003c/code\u003e,\n  but never called \u003ccode\u003esetlocale(3)\u003c/code\u003e, in which case don't do that).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eI pretty much always need an \u003ccode\u003encplane\u003c/code\u003e when using a\n  \u003ccode\u003enccell\u003c/code\u003e. Why doesn't the latter hold a pointer to the former?\n  \u003c/summary\u003e\n  Besides the massive redundancy this would entail, \u003ccode\u003enccell\u003c/code\u003e needs to\n  remain as small as possible, and you almost always have the \u003ccode\u003encplane\u003c/code\u003e\n  handy if you've got a reference to a valid \u003ccode\u003enccell\u003c/code\u003e anyway.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n \u003csummary\u003eI ran my Notcurses program under \u003ccode\u003evalgrind\u003c/code\u003e/ASAN, and\n    it shows memory leaks from \u003ccode\u003elibtinfo.so\u003c/code\u003e, what's up with that?\u003c/summary\u003e\n  Yeah, the NCURSES Terminfo leaks memory unless compiled a special,\n  non-standard way (see the NCURSES FAQ). It shouldn't be a substantial amount;\n  you're advised not to worry overmuch about it.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eI ran \u003ccode\u003enotcurses-demo\u003c/code\u003e, but my table numbers don't match\n  the Notcurses banner numbers, you charlatan.\u003c/summary\u003e\n  \u003ccode\u003enotcurses-demo\u003c/code\u003e renders several frames beyond the actual demos.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhen my program exits, I don't have a cursor, or text is invisible,\n  or colors are weird, \u003ci\u003ead nauseam\u003c/i\u003e.\u003c/summary\u003e\n  Ensure you're calling \u003ccode\u003enotcurses_stop()\u003c/code\u003e/\u003ccode\u003encdirect_stop()\u003c/code\u003e\n  on all exit paths, including fatal signals (note that, by default, Notcurses\n  installs handlers for most fatal signals to do exactly this).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow can I use Direct Mode in conjunction with libreadline?\u003c/summary\u003e\n  You can't anymore (you could up until 2.4.1, but the new input system is\n  fundamentally incompatible with it). \u003ccode\u003encdirect_readline()\u003c/code\u003e still exists,\n  though, and now actually works even without libreadline, though it is of\n  course not exactly libreadline. In any case, you'd probably be better off\n  using CLI mode with a \u003ccode\u003encreader\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eSo is Direct Mode deprecated or what?\u003c/summary\u003e\n  It is not currently deprecated, and definitely receives bugfixes. You are\n  probably better served using CLI mode (see above), which came about\n  somewhat late in Notcurses development (the 2.3.x series), but is superior\n  to Direct Mode in pretty much every way. The only reason to use Direct\n  Mode is if you're going to have other programs junking up your display.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eDirect Mode sounds fast! Since it's, like, direct.\u003c/summary\u003e\n  Direct mode is \u003ci\u003esubstantially slower\u003c/i\u003e than rendered mode. Rendered\n  mode assumes it knows what's on the screen, and uses this information to\n  generate optimized sequences of escapes and glyphs. Direct mode writes\n  everything it's told to write. It is furthermore far less capable—all\n  widgets etc. are available only to rendered mode, and will definitely\n  not be extended to Direct Mode.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWill there ever be Java wrappers?\u003c/summary\u003e\n  I should hope not. If you want a Java solution, try @klamonte's\n  \u003ca href=\"https://jexer.sourceforge.io/\"\u003eJexer\u003c/a\u003e. Autumn's a good\n  woman, and thorough. We seem to have neatly partitioned the language\n  space.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eGiven that the glyph channel is initialized as transparent for a\n  plane, shouldn't the foreground and background be initialized as transparent,\n  also?\u003c/summary\u003e\n  Probably (they are instead by default initialized to opaque). This would change\n  some of the most longstanding behavior of Notcurses, though,\n  so it isn't happening.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eI get linker errors when statically linking.\u003c/summary\u003e\n  Are you linking all necessary libraries? Use\n  \u003ccode\u003epkg-config --static --libs notcurses\u003c/code\u003e\n  (or \u003ccode\u003e--libs notcurses-core\u003c/code\u003e) to discover them.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eNotcurses exits immediately in MSYS2/Cygwin.\u003c/summary\u003e\n  Notcurses requires the\n  \u003ca href=\"https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/\"\u003eWindows ConPTY\u003c/a\u003e\n  layer. This is available in Cygwin by default since 3.2.0, but is disabled\n  by default in MSYS. Launch \u003ccode\u003emintty\u003c/code\u003e with \u003ccode\u003e-P on\u003c/code\u003e\n  arguments, or export \u003ccode\u003eMSYS=enable_pcon\u003c/code\u003e before launching it.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCan I avoid manually exporting \u003ccode\u003eCOLORTERM=24bit\u003c/code\u003e\n  everywhere?\u003c/summary\u003e\n  Sure. Add \u003ccode\u003eSendEnv COLORTERM\u003c/code\u003e to \u003ccode\u003e.ssh/config\u003c/code\u003e, and\n  \u003ccode\u003eAcceptEnv COLORTERM\u003c/code\u003e to \u003ccode\u003esshd_config\u003c/code\u003e on the remote\n  server. Yes, this will probably require root on the remote server.\n  Don't blame me, man; I didn't do it.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow about \u003ci\u003earbitrary image manipulation here\u003c/i\u003e functionality?\u003c/summary\u003e\n  I'm not going to beat ImageMagick et al. on image manipulation, but you can\n  load an \u003ccode\u003encvisual\u003c/code\u003e from RGBA memory using\n  \u003ccode\u003encvisual_from_rgba()\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eMy program locks up during initialization. \u003c/summary\u003e\n  Notcurses interrogates the terminal. If the terminal doesn't reply to standard\n  interrogations, file a Notcurses bug, send upstream a patch, or use a different\n  terminal. No known terminal emulators exhibit this behavior.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow can I draw a large plane, and only make a portion of it visible?\u003c/summary\u003e\n  The simplest way is probably to create a plane of the same dimensions immediately above\n  the plane, and keep a region of it transparent, and the rest opaque. If you want the visible\n  area to stay in the same place on the display, but the portion being seen to change, try\n  making a plane twice as large in each dimension as the original plane. Make the desired area\n  transparent, and the rest opaque. Now move the original plane behind this plane so that the\n  desired area lines up with the \u0026ldquo;hole\u0026rdquo;.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhy no \u003ccode\u003eNCSTYLE_REVERSE\u003c/code\u003e?\u003c/summary\u003e\n  It would consume a precious bit. You can use \u003ccode\u003encchannels_reverse()\u003c/code\u003e\n  to correctly invert fore- and background colors.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow do I mix Rendered and Direct mode?\u003c/summary\u003e\n  You really don't want to. You can stream a subprocess to a plane with the\n  \u003ccode\u003encsubproc\u003c/code\u003e widget.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow can I clear the screen on startup in Rendered mode when not using\n  the alternate screen?\u003c/summary\u003e\n  Call \u003ccode\u003enotcurses_refresh()\u003c/code\u003e after \u003ccode\u003enotcurses_init()\u003c/code\u003e\n  returns successfully.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhy do the stats show more Linux framebuffer bitmap bytes written\n  than total bytes written to the terminal? And why don't Linux console\n  graphics work when I ssh?\u003c/summary\u003e\n  Linux framebuffer graphics aren't implemented via terminal writes, but rather\n  writes directly into a memory map. This memory map isn't available on remote\n  machines, and these writes aren't tracked by the standard statistics.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n \u003csummary\u003eWhat is the possessive form of Notcurses?\u003c/summary\u003e\n \u003cb\u003eNotcurses'.\u003c/b\u003e I cite \u003ca href=\"https://en.wikipedia.org/wiki/Garner%27s_Modern_English_Usage\"\u003e\n Garner's Modern English Usage\u003c/a\u003e in its third edition: \"\u003cb\u003ePOSSESSIVES. A. Singular\n Possessives.\u003c/b\u003e…Biblical and Classical names that end with a /zəs/ or /eez/\n sound take only the apostrophe.\" Some ask: is Notcurses then Biblical, or is it\n Classical? Truly, it is both.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eI just want to display a bitmap on my terminal. Your library is\n  complex and stupid. You are simple and stupid.\u003c/summary\u003e\n  If you're willing to call a binary, use \u003ctt\u003encplayer\u003c/tt\u003e to put an image,\n  with desired scaling, anywhere on the screen and call it a day. Otherwise,\n  call \u003ctt\u003enotcurses_init()\u003c/tt\u003e, \u003ctt\u003encvisual_from_file()\u003c/tt\u003e,\n  \u003ctt\u003encvisual_blit()\u003c/tt\u003e, \u003ctt\u003enotcurses_render()\u003c/tt\u003e, and\n  \u003ctt\u003enotcurses_stop()\u003c/tt\u003e. It's not too tough. And thanks—your thoughtful\n  comments and appreciative tone are why I work on Free Software.\n\u003c/details\u003e\n\n## Useful links\n\n* [BiDi in Terminal Emulators](https://terminal-wg.pages.freedesktop.org/bidi/)\n* [The Xterm FAQ](https://invisible-island.net/xterm/xterm.faq.html)\n  * [XTerm Control Sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.pdf)\n* [The NCURSES FAQ](https://invisible-island.net/ncurses/ncurses.faq.html)\n* [ECMA-35 Character Code Structure and Extension Techniques](https://www.ecma-international.org/publications/standards/Ecma-035.htm) (ISO/IEC 2022)\n* [ECMA-43 8-bit Coded Character Set Structure and Rules](https://www.ecma-international.org/publications/standards/Ecma-043.htm)\n* [ECMA-48 Control Functions for Coded Character Sets](https://www.ecma-international.org/publications/standards/Ecma-048.htm) (ISO/IEC 6429)\n* [Unicode 14.0 Full Emoji List](https://unicode.org/emoji/charts/full-emoji-list.html)\n* [Unicode Standard Annex #29 Text Segmentation](http://www.unicode.org/reports/tr29)\n* [Unicode Standard Annex #15 Normalization Forms](https://unicode.org/reports/tr15/)\n* [mintty tips](https://github.com/mintty/mintty/wiki/Tips)\n* [The TTY demystified](http://www.linusakesson.net/programming/tty/)\n* [Dark Corners of Unicode](https://eev.ee/blog/2015/09/12/dark-corners-of-unicode/)\n* [UTF-8 Decoder Capability and Stress Test](https://www.cl.cam.ac.uk/~mgk25/ucs/examples/UTF-8-test.txt)\n* [Emoji: how do you get from U+1F355 to 🍕?](https://meowni.ca/posts/emoji-emoji-emoji/)\n* [Glyph Hell: An introduction to glyphs, as used and defined in the FreeType engine](http://chanae.walon.org/pub/ttf/ttf_glyphs.htm)\n* [Text Rendering Hates You](https://gankra.github.io/blah/text-hates-you/)\n* [Use the UTF-8 code page](https://docs.microsoft.com/en-us/windows/apps/design/globalizing/use-utf8-code-page)\n* My wiki's [Sixel page](https://nick-black.com/dankwiki/index.php?title=Sixel) and Kitty's [extensions](https://sw.kovidgoyal.net/kitty/protocol-extensions.html).\n* Linux man pages: [console_codes(4)](http://man7.org/linux/man-pages/man4/console_codes.4.html), [termios(3)](http://man7.org/linux/man-pages/man3/termios.3.html), [ioctl_tty(2)](http://man7.org/linux/man-pages/man2/ioctl_tty.2.html), [ioctl_console(2)](http://man7.org/linux/man-pages/man2/ioctl_console.2.html)\n* The Microsoft Windows [Console Reference](https://docs.microsoft.com/en-us/windows/console/console-reference)\n* NCURSES man pages: [terminfo(5)](http://man7.org/linux/man-pages/man5/terminfo.5.html), [user_caps(5)](http://man7.org/linux/man-pages/man5/user_caps.5.html)\n\n\u003e “Our fine arts were developed, their types and uses were established, in times\nvery different from the present, by men whose power of action upon things was\ninsignificant in comparison with ours. But the amazing growth of our\ntechniques, the adaptability and precision they have attained, the ideas and\nhabits they are creating, make it a certainty that _profound changes are\nimpending in the ancient craft of the Beautiful_.” —Paul Valéry\n","funding_links":["https://github.com/sponsors/dankamongmen"],"categories":["C","Table of Contents","cli","Program"],"sub_categories":["C/C++"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdankamongmen%2Fnotcurses","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdankamongmen%2Fnotcurses","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdankamongmen%2Fnotcurses/lists"}