« Back to Product

Documentation

Send feedback!

SetValueColor

 bool SetValueColor (int $VariableID, int $ColorValue)

Parameters

VariableID

ID of the variable
ColorValue

Color in the format 0xRRGGBB

Returns

If the function succeeds, it returns TRUE, otherwise FALSE.

Description

The function sets the content of the variable with the ID VariableID to the color ColorValue in the format 0xRRGGBB. The color is stored according to the variable:

  • Integer variables receive ColorValue unchanged. The presentation is not checked.
  • String variables must use the presentation Color. ColorValue is converted according to the parameter ENCODING of the presentation and stored as JSON object. Only the lower 24 bits of ColorValue are evaluated.
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. For CMYK, HSV, HSL and xy the conversion results in floating point numbers.

Like SetValue, only the value of the variable is written; no action is executed, so the device is not switched. Use RequestActionColor for that.

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" and leaves the variable unchanged; for variables of type Boolean or Float with "Invalid Variable Type". If the variable is read-only (e.g. a status variable of a module), the function fails with "Variable is marked as read-only and cannot be changed".

See also GetValueColor.

Example

// Set orange
SetValueColor(12345, 0xFF8000);

// For a string variable with the presentation Color and the encoding RGB
echo GetValue(12345);
// returns: {"b":0,"g":128,"r":255}
Any questions?