Next: , Previous: , Up: The basic curses library   [Contents][Index]


5.2.13 Color manipulation routines

Curses supports color attributes on terminals with that capability. To use these routines start-color! must be called, usually right after initscr. Colors are always used in pairs (referred to as color-pairs). A color-pair consists of a foreground color (for characters) and a background color (for the blank field on which the characters are displayed). A programmer initializes a color-pair with the routine init-pair!. After it has been initialized, color-pair can be used as a new video attribute.

If a terminal is capable of redefining colors, the programmer can use the routine init-color! to change the definition of a color. The routines has-colors? and can-change-color? return #t or #f, depending on whether the terminal has color capabilities and whether the programmer can change the colors. The routine color-content allows a programmer to extract the amounts of red, green, and blue components in an initialized color. The routine pair-content allows a programmer to find out how a given color-pair is currently defined.

Procedure: start-color!

The start-color! routine requires no arguments. It must be called if the programmer wants to use colors, and before any other color manipulation routine is called. It is good practice to call this routine right after initscr. start-color! initializes eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), and prepares the procedures colors and color-pairs (respectively defining the maximum number of colors and color-pairs the terminal can support). It also restores the colors on the terminal to the values they had when the terminal was just turned on.

The return value is unspecified.

Procedure: colors

Returns the maximum number of colors the terminal can support.

Procedure: color-pairs

Returns the maximum number of color-pairs the terminal can support.

Constant: COLOR_BLACK
Constant: COLOR_RED
Constant: COLOR_GREEN
Constant: COLOR_YELLOW
Constant: COLOR_BLUE
Constant: COLOR_MAGENTA
Constant: COLOR_CYAN
Constant: COLOR_WHITE

These variables contain the color number of the eight default colors.

Procedure: init-color! color red green blue

The init-color! routine changes the definition of a color. It takes four arguments: the number of the color to be changed followed by three RGB values (for the amounts of red, green, and blue components). The value of the first argument must be between 0 and the value returned by the colors procedure. Each of the last three arguments must be a value between 0 and 1000. When init-color! is used, all occurrences of that color on the screen immediately change to the new definition.

It returns #f on failure and #t on success. Failure may indicate that, for the current terminal, the colors cannot be modified.

Procedure: init-pair! color-pair fore-color back-color

The init-pair! routine changes the definition of a color-pair. It takes three arguments: the number of the color-pair to be changed, the fore-ground color number, and the background color number.

The value of the first argument must be between 1 and color-pairs - 1.

The value of the second and third arguments must be between 0 and colors. Color pair 0 is assumed to be white on black, but is actually whatever the terminal implements before color is initialized.

If the color-pair was previously initialized, the screen is refreshed and all occurrences of that color-pair are changed to the new definition.

Color pair 0 is set via the assume-default-colors routine. After use-default-colors has been called, the special color number -1 can be used as fore-color or back-color. Color number -1 is set to contain the default foreground or background color for this screen, which is usually white on black.

It returns #f on failure and #t on success. Failure may indicate an attempt to change a color pair beyond the allow range of color pairs.

Procedure: has-colors?

The has-colors? routine returns #t if the terminal can manipulate colors; otherwise, it returns #f. This routine facilitates writing terminal-independent programs. For example, a programmer can use it to decide whether to use color or some other video attribute.

Procedure: can-change-color?

The can-change-color? routine returns #t if the terminal supports colors and can change their definitions; otherwise, it returns #f.

Procedure: color-content color

The color-content routine returns the intensity of the red, green, and blue (RGB) components in a color. Given color as its argument, it returns a list of three integers indicating the red, green, and blue components in the given color. The value of the color argument must be between 0 and the value returned by the colors procedure. The values returned are between 0 (no component) and 1000 (maximum amount of component).

Procedure: pair-content pair

The pair-content routine allows programmers to find out what colors color-pair pair consists of. The value of pair must be between 1 and color-pairs - 1. It returns a list of two elements: the foreground color number and the background color number. The values are between 0 and the value returned by colors.

Procedure: use-default-colors

This procedure allow routines that use color numbers, like init-pair! to use the special color number -1 to indicate the default color. When -1 is used in lieu of the foreground color, it indicated the default foreground color. When -1 is used as the background color, it indicated the default background color. Thus, it has different meanings depending on the context.

It returns #t if successful or #f is the terminal lacks the capability to set color pair 0.

Procedure: assume-default-colors fg bg

This procedure allow the modification of special color pair 0, which cannot be modified by init-pair!. Color pair 0 is the default foreground and background color for the window.

It returns #t if successful or #f is the terminal lacks the capability to set color pair 0.


Next: , Previous: , Up: The basic curses library   [Contents][Index]