29.20 Text Terminal Colors

Emacs can display color on text-only terminals, starting with version 21. These terminals support only a small number of colors, and the computer uses small integers to select colors on the terminal. This means that the computer cannot reliably tell what the selected color looks like; instead, you have to inform your application which small integers correspond to which colors. However, Emacs does know the standard set of colors and will try to use them automatically.

Several of these functions use or return rgb values. An rgb value is a list of three integers, which give the amount of red, the amount of green, and the amount of blue. Each integer ranges in principle from 0 to 65535, but in practice the largest value used is 65280.

These functions accept a display (either a frame or the name of a terminal) as an optional argument. We hope in the future to make Emacs support more than one text-only terminal at one time; then this argument will specify which terminal to operate on (the default being the selected frame's terminal; see section 29.9 Input Focus). At present, though, the display argument has no effect.

Function: tty-color-define name number &optional rgb display

This function associates the color name name with color number number on the terminal.

The optional argument rgb, if specified, is an rgb value; it says what the color actually looks like. If you do not specify rgb, then this color cannot be used by tty-color-approximate to approximate other colors, because Emacs does not know what it looks like.

Function: tty-color-clear &optional display

This function clears the table of defined colors for a text-only terminal.

Function: tty-color-alist &optional display

This function returns an alist recording the known colors supported by a text-only terminal.

Each element has the form (name number . rgb) or (name number). Here, name is the color name, number is the number used to specify it to the terminal. If present, rgb is an rgb value that says what the color actually looks like.

Function: tty-color-approximate rgb &optional display

This function finds the closest color, among the known colors supported for display, to that described by the rgb value rgb.

Function: tty-color-translate color &optional display

This function finds the closest color to color among the known colors supported for display. If the name color is not defined, the value is nil.

color can be an X-style "#xxxyyyzzz" specification instead of an actual name. The format "RGB:xx/yy/zz" is also supported.