# Colors

Colors for EDM displays are specified in "colors.list". The default location is /etc but may be overridden with the environment variable EDMFILES.

## RGB Values, Indices and Names

Most widgets have more than one color: foreground, background, border, shadow, ... There are several ways to address such a color:

- RGB
  The triple of RGB values, that is the intensity of red, green and blue, defines what a color actually looks like on the screen. Each intensity is an integer from 0 up to a configurable limit, e.g. 255.
- Name
  A string for the color. This name can be based on the meaning of the color, e.g. "background=RGB(0, 0, 255)" or describe how the color looks as in "red=RGB(255, 0, 0)". Note that noone prevents you from calling the RGB(255, 0, 0) "green": For EDM, the color name is an arbitrary string.
- Palette, Index
  EDM puts all the defined colors into a palette. The colors in there are indexed beginning with zero.

The colors.list file defines the palette, the relationship between names, indices and actual RGB values. Originally, all widgets stored the palette index in the display file. Some widgets do now store the name in the display file.

## Syntax for "colors.list"

Example colors.list for version 3.0.0:

    3 0 0

    # The first line has to be a version number:
    #   <Major version> <Minor version> <Release>
    # No comments are allowed before that first line

    # blank lines or comments after "#" allowed
    # decimal or hex numbers are allowed

    # Number to use for maximum RGB intensity
    max=256     # for 8 bit, use max=0x10000 for 16 bit

    columns=10  # number of columns for color palette

    # Static colors:
    # "static" name { R G B }
    #
    # The first color has index 0, the second color
    # has index 1 and so on
    static black { 0 0 0 }
    static white { 0xff, 0xff, 0xff } # commas are optional
    static "lt grey" { 240 240 240 }  # if name has whitespace, must quote
    static "lt wheat" { 240 240 210 }
    static red { 255 0 0 }            # index 4
    static green { 0 255 0 }          # index 5

When configuring a widget, the color can be selected by name or picked from a dialog displaying the whole color palette.
Note: Since many widgets save the color as an index, care must be taken when rearranging the color file.

### Color Rules

Color rules may follow the static color definitions:

    rule Rainbow
    {
      <0        : red
      >0        : green
      default   : black
    }

This color will change, depending on the Color Value, from green for positive value over black for zero into red for negative values. The Color Value is provided by the widget. For most widgets it will be the current value of the readback or control PV, some widgets might allow for a separate "Color PV" that can be different from the main PV.

Another example:

    # Rule entries can be exact values,
    # comparisons and boolean combinations.
    # Conditions to be joined to enhance readability:
    rule rule1 {    # comment
      11            : ||
      12            : ||
      13            : red
      14            : blue
      15            : green
      <2 || >4      : &&
      <7 || >9      : forest
      default       : black
    }

### Alarms

Some widgets have an "alarm" checkbox, they reflect the alarm state of the PV via colors, configured like this:

    alarm {
      disconnected : "Disconn/Invalid"
      invalid      : "Disconn/Invalid"
      minor        : "Monitor: MINOR"
      major        : "Monitor: MAJOR"
      noalarm      : "Monitor: NORMAL"
     }

The specification for the no alarm state may either be a valid color name or "*". In the latter case, the object's foreground color determine the non-alarm color.

### Menu Map

Per default, all static and rule-based colors are displayed in a list box, ordered by appearance in colors.list. This syntax allows for displaying a limited subset in a specific order:

    menumap {
      black
      "light grey"
      red
      forest
      "blink green"
    }

If this option is used, all color names must be explicitly included in the list (if they are to appear in the menu).

### API

Refer to lib/color_pkg.h.