« Back to Product

Documentation

Send feedback!

GetValueColor

 int GetValueColor (int $VariableID)

Parameters

VariableID

ID of the variable

Returns

Color value in the format 0xRRGGBB (red, green and blue with 8 bits each)

Description

The function returns the content of the variable with the ID VariableID as color value in the format 0xRRGGBB. This allows reading a color regardless of how it is stored in the variable.

  • Integer variables already contain the color as 0xRRGGBB. Their value is returned unchanged; the presentation is not checked.
  • String variables must use the presentation Color. The value is a JSON object which is converted to RGB according to the parameter ENCODING of the presentation:
ENCODING Constant Encoding JSON value of the string variable Ranges
0 COLOR_ENCODING_RGB RGB {"r": ..., "g": ..., "b": ...} r, g, b: 0 - 255
1 COLOR_ENCODING_CMYK CMYK {"c": ..., "m": ..., "y": ..., "k": ...} c, m, y, k: 0 - 100
2 COLOR_ENCODING_HSV HSV {"h": ..., "s": ..., "v": ...} h: 0 - 360, s, v: 0 - 100
3 COLOR_ENCODING_HSL HSL {"h": ..., "s": ..., "l": ...} h: 0 - 360, s, l: 0 - 100
4 COLOR_ENCODING_XY xy {"x": ..., "y": ...} x, y: position on the CIE chromaticity diagram, 0 - 1

The xy encoding only stores the chromaticity, no brightness. The conversion uses the color space of the presentation (COLOR_SPACE); except for color space 5 (none), the coordinates are limited to the triangle of the color space.

If a string variable does not use the presentation Color, the function fails with "Variable does not use presentation Color". For an unknown encoding it fails with "Invalid Color Encoding", for variables of type Boolean or Float with "Invalid Variable Type". The content of a string variable must be valid JSON with the fields listed above; an empty string causes an error.

The presentation can be read with IPS_GetVariablePresentation and set with IPS_SetVariableCustomPresentation. See also SetValueColor, RequestActionColor and GetValue.

Example

$color = GetValueColor(12345);

// Split the color into its components
$red = ($color >> 16) & 0xFF;
$green = ($color >> 8) & 0xFF;
$blue = $color & 0xFF;

printf("#%06X (R: %d, G: %d, B: %d)", $color, $red, $green, $blue);
// e.g. returns: #FF8000 (R: 255, G: 128, B: 0)
Any questions?