# add-color(2)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

## NAME

add-color - Create a new color
add-color-scheme - Create a new color scheme

## SYNOPSIS

add-color "col-no" "red" "green" "blue"
n add-color-scheme "schemeNum" "fore" "back" "current-fore" "current-back"

"selected-fore" "selected-back"
"current-selected-fore" "current-selected-back"
[ "fm-fore" "fm-back" "fm-cur-fore" "fm-cur-back"
"fm-sel-fore" "fm-sel-back"
"fm-cur-sel-fore" "fm-cur-sel-back" ]

## DESCRIPTION

add-color creates a new color and inserts it into MicroEmacs 2009 colors table, where red, green and blue are the color components and col-no is the MicroEmacs 2009 color table number. The color table contains 256 entries indexed by col-no in the range 0-255.

On some platforms (DOS and UNIX termcap) the number of colors is physically limited by the hardware to less than 256 (typically 16), in this case all 256 colors can be defined and for each created color the closest system color is used.

By default, only color 0 (white) and 1 (black) are defined. Once created, the colors may be used to create color schemes, this is the sole use of colors.

add-color may be used to modify an existing col-no index by re-assignment, the existing color definition is over-written with the new color definition. add-color-scheme creates a color scheme entry used by hilight(2), screen-poke(2), osd(2) and variables such as $global-scheme(5), $buffer-scheme(5), $ml-scheme(5).

The command takes an index number "schemeNum" and eight color values (defined by add-color) alternating between foreground and background colors. The 8 colors represent the 4 color paired states of foreground and background that may appear in a text buffer. The paired states correspond to current and selected lines (or permutations thereof). If an argument n is given to the command then schemeNum is set to a duplicate of the nth scheme, no other arguments are required.

schemeNum is the identifying index that is used to recognize the scheme. By default only two color schemes are defined at initialization, they are a monochrome scheme and inverse scheme with indices 0 and 1 using white as foreground and black as background, selected text is inverted. When defining a color scheme, if an existing schemeNum index is used then that scheme is modified.

The next eight arguments must be given, they specify foreground and background color pairs for the four different situations, as follows:-

Default

Color combination used when none of the following three are applicable.

Current

Color combination used when the text is on the same line as the cursor. It is also used by the $mode-line-scheme(5) for the current window's mode line and for the current selection on an osd(2) dialog.

Selected

Color combination used when the text is in the current selected region, but is not on the current line. Also used by osd for non-current item Hot keys.

Current-selected

Color combination used when the text is on the current line and in the current selected region. Also used by osd for the current item's Hot key.

The following 8 arguments set up fonts and are optional, any missing arguments are defaulted to 0. Each argument is a bitmask indicating which font should be enabled, where each bit is as follows:

`0x01` Enable bold font.
`0x02` Enable italic font.
`0x04` Enable light font.
`0x08` Enable reverse font.
`0x10` Enable underlining.

Normally only the foreground value is used, i.e. the first, third, fifth and seventh values. But screen-poke(2) can be used to draw reversed color scheme in which case the background values are used.

## EXAMPLE

The color palette is typically created at start-up via the configuration file scheme X.emf. These files are not easily read as they are automatically generated via the scheme-editor(3) dialog. A more readable form of "`schemed.emf`" would be as follows:-

    ; Standard colors
    add-color &set .white     0 200 200 200
    add-color &set .black     1 0   0   0
    add-color &set .red       2 200 0   0
    add-color &set .green     3 0   200 0
    add-color &set .yellow    4 200 200 0
    add-color &set .blue      5 0   0   200
    add-color &set .magenta   6 200 0   200
    add-color &set .cyan      7 0   200 200
    ; Light colors
    add-color &set .lwhite    8 255 255 255
    add-color &set .lblack    9 75  75  75
    add-color &set .lred     10 255 0   0
    add-color &set .lgreen   11 0   255 0
    add-color &set .lyellow  12 255 255 0
    add-color &set .lblue    13 0   0   255
    add-color &set .lmagenta 14 255 0   255
    add-color &set .lcyan    15 0   255 255
    ; Selection color
    add-color &set .sel-col  16 91  78  131
    ; Set the required cursor-color
    set-variable $cursor-color .col12
    ; Set up the standard schemes for the text, mode line message line, scroll bar and osd.
    add-color-scheme $global-scheme  .white .black .lwhite .black ...
        ... .white .sel-col .lwhite .sel-col 0 8 1 9 8 0 9 1
    add-color-scheme $ml-scheme  .white .black .lwhite .black ...
        ... .white .sel-col .lwhite .sel-col 0 8 1 9 8 0 9 1
    add-color-scheme $mode-line-scheme  .white .red .lwhite .lred ...
        ... .white .red .lwhite .red 8 0 9 1 0 8 1 9
    add-color-scheme $scroll-bar-scheme .white .lblack .lwhite .lblack ...
        ...  .lblack .white .lblack .lwhite 8 0 9 1 0 8 1 9
        .
        .

## NOTES

Color schemes can be created and altered using the scheme-editor(3) dialog, the created color scheme can then the used from start-up by using the user-setup(3) dialog. Therefore direct use of these commands is largely redundant.

The existence of a color or scheme index is checked as each entry is submitted, therefore any color or scheme used must have been previously been created, otherwise a default value is substituted.

Changing any existing color definitions causes all references to the color from a scheme to adopt the new color.

Changing any existing color-scheme definitions changes the rendered color of any hilight(2) etc., that was using that color-scheme.

A negative color scheme value (i.e. -n) uses the previous 'n'th entry that is defined in the color block. i.e. if current-fore was specified as -2 then it would inherit the fore field color.

Not all UNIX terminals support all the above fonts.

On some telnet packages color is not directly supported and some of the termcap display attributes such as bold and italic are represented by a color (e.g. italic text is shown in green). Using this translation it is possible to achieve reasonable color support on a VT100 terminal - it is a little awkward but is worth while if you have to use this type of connection frequently.

## SEE ALSO

scheme-editor(3), user-setup(3), change-font(2), hilight(2), screen-poke(2), $buffer-hilight(5), $cursor-color(5), $global-scheme(5), $trunc-scheme(5), $ml-scheme(5), $osd-scheme(5), $mode-line-scheme(5), $scroll-bar-scheme(5), $system(5).

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12

</HMTL>