default_colors(3NCURSES)

✨ default_colors — bestie edition ✨

okay so this is a page from the ncurses manual, specifically the library calls corner of it, and it's all about use_default_colors and assume_default_colors. yes those are long names. yes they slay. let's get into it 🫶

---

🌸 NAME 🌸

use_default_colors, assume_default_colors — using your terminal's own default colors in curses 💅

---

🎀 SYNOPSIS 🎀

#include <curses.h>

int use_default_colors(void);
int assume_default_colors(int fg, int bg);

like. two little functions. so much power. 👑

---

🦋 DESCRIPTION 🦋

so use_default_colors and assume_default_colors are extensions to the curses library, meaning they're not vanilla-curses, they're ncurses doing extra credit ✨. You use them with terminals that support ISO 6429 color, or something equivalent. And what those terminals let you do is reset the color back to an unspecified default value — like with SGR 39 or SGR 49. cute, right?

Now here's the thing. Applications that just paint a colored background over the whole entire screen? They're not taking advantage of SGR 39 and SGR 49 at all. Not even a little. But some applications are designed to work with the default background, using colors only for the text. For example — and I love this example — there are several implementations of the ls program that use colors to show different file types or permissions. Those "color ls" programs don't necessarily mess with the background color at all; they typically just use the setaf terminfo capability to set the foreground color. And full-screen applications that use default colors can get that same kind of visual effect. iconic behavior honestly 🌈

So, function number one: use_default_colors tells the curses library to assign the terminal's default foreground/background colors to color number -1. Which means init_pair(x,COLOR_RED,-1) will initialize pair x as red on the default background, and init_pair(x,-1,COLOR_BLUE) will initialize pair x as default foreground on blue. yes the -1 is doing a lot of heavy lifting there. she's the main character 💅

Function number two: assume_default_colors is a refinement — it tells you which colors to paint for color pair 0. And this function recognizes that special color number -1, which denotes the default terminal color.

The following are equivalent, no cap:

use_default_colors();
assume_default_colors(-1,-1);

These are ncurses extensions, periodt. For other curses implementations, color number -1 does not mean anything — just like it doesn't mean anything for ncurses before a successful call of use_default_colors or assume_default_colors. so don't go assuming, bestie 🙈

Other curses implementations also don't let an application modify color pair 0 at all. They assume the background is COLOR_BLACK, but they don't actually ensure that color pair 0 gets painted to match that assumption. (the audacity.) If your application doesn't use either use_default_colors or assume_default_colors, ncurses will paint a white foreground (text) with black background for color pair 0.

---

💖 RETURN VALUE 💖

These functions return the integer ERR if they fail, and OK if they succeed. 🫶

They will fail if either the terminal does not support the orig_pair or orig_colors capability. And if the initialize_pair capability is not found, that causes an error as well. so like. three ways to be told no 😭

---

🌟 NOTES 🌟

Associated with this extension: the init_pair function accepts negative arguments to specify default foreground or background colors. (yes, that's the -1 thing again. she's everywhere.)

use_default_colors was added to support ded. And ded is a full-screen application which uses curses to manage only part of the screen. The bottom portion of the screen — which is of adjustable size — is left uncolored so it can display the results from shell commands. The top portion of the screen colors filenames using a scheme like the "color ls" programs. Attempting to manage the background color of the screen for this application would give unsatisfactory results, for a whole variety of reasons. This extension was devised after noting that color xterm (and similar programs) provides a background color which does not necessarily correspond to any of the ANSI colors. And while a special terminfo entry could be constructed using nine colors, there was no mechanism provided within curses to account for the related orig_pair and back_color_erase capabilities. so they built one. slay 🧚

assume_default_colors was added to solve a different problem: support for applications which would use environment variables and other configuration to bypass curses' notion of the terminal's default colors, setting specific values.

---

👑 PORTABILITY 👑

These routines are specific to ncurses, bestie. They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on them be conditioned using NCURSES_VERSION.

fr fr, wrap that stuff in the version check or you're gonna have a bad time 💀

---

🍓 AUTHORS 🍓

Thomas Dickey (from an analysis of the requirements for color xterm for XFree86 3.1.2C, February 1996).

---

⭐ SEE ALSO ⭐

ded(1), color(3NCURSES)

---

and that's the whole page, babes 💜 this was ncurses 6.6, dated 2024-04-13, and honestly? she ate. go forth and use your terminal's default colors, iykyk 🎀✨