Corky

• Index

Contents

• Functions
• Local Functions
• Local Tables

Modules

• corky
• corky.cache
• corky.cairo
• corky.circles
• corky.colors
• corky.config
• corky.conky
• corky.dcolors
• corky.hooks
• corky.include
• corky.lists
• corky.options
• corky.rects
• corky.text
• corky.utils
• corky.validator

Source

• corky.lua
• cache.lua
• cairo.lua
• circles.lua
• colors.lua
• config.lua
• conky.lua
• dcolors.lua
• hooks.lua
• include.lua
• lists.lua
• options.lua
• rects.lua
• text.lua
• utils.lua
• validator.lua

Module corky.dcolors

Dynamic color handling for Corky.

This module may be used to store and retrieve dynamic colors — i.e. colors that change depending on some value.

There are two kinds of dynamic colors supported by this module. In both cases, the color depends on a value, this is usually some value returned by conky_parse(). The two terms used in this documentation are:

• Fixed dynamic colors: If fixed dynamic colors are used, the actual color will be determined by a threshold. Each dynamic color definition may contain an arbitrary number of thresholds, and for each threshold a color is defined in the configuration file. The color assigned to the largest threshold that is smaller than or equal to the value will be used. The color will be the same for all values between two thresholds.
• Gradient colors: If these are used, the configuration file determines a start and a stop color, and the actual color will be determined by interpolating between these two to get the color for a given value.

Loading the module:

#: include, corky.dcolors

Adding a dynamic color:

#: dcolor, <name>, <color>[, <threshold>, <color> […]][, <color>]

The first parameter is the dynamic color's name (an arbitrary, non-empty string), the second parameter the default or start color.

After the first two parameters an arbitrary number (zero or more) of parameters in pairs of two may appear: the <threshold> specifies the value at which the fixed dynamic color will be changed to the following <color>. These thresholds must be in ascending order, i.e. the first threshold value must be less than the second one, which must be less than the third one etc. Arbitrary values may be used as thresholds, depending on the actual value for which the fixed dynamic color should be used.

If after these (zero or more) threshold/color pairs another color is specified, the dynamic color will be used as a gradient. This last color then specifies the stop color of the gradient (the color for a 100% value). In this case, the threshold values must be between 0 and 100. If specified, they will be used to split the gradient into several different gradients (i.e. start color to first threshold color will be used for a value from zero percent to the first threshold, etc.).

The color specifications may either be the usual (hexadecimal, RGB or ARGB format) number, or named colors defined by a color directive (see the corky.colors module). Gradient interpolation will include the alpha value. Using a named color is required if you want to include a color with an alpha value of zero (again, see corky.colors for more details)!

Note: When using a named color it has to be defined before it is used in a dcolor directive! Named colors will be resolved when the configuration is read, changing a named color after that will not change a dynamic color that included it!

Info:

• Copyright: © 2015-2017 Stefan Göbel
• Release: 2017033001
• License: GPLv3
• Author: Stefan Göbel [⌂] [✉]

Functions

set (...)	Add a dynamic color entry, or change an existing entry.
gradient (start, stop, percent)	Get a gradient color.
get (color, value)	Get the color for some value.

Local Functions

config_handler (setting)

Configuration handler for dynamic color settings.

Local Tables

dcolors

Stores the user-defined dynamic colors.

Functions

set (...) line 105

Add a dynamic color entry, or change an existing entry.

The parameters to this function are exactly the same as for the dcolor configuration directive described above:

set (<name>, <color>[, <threshold>, <color> […]][, <color>])

Please see the configuration section above for more details on these parameters.

Parameters:

• ... See above for details about the parameters.

Returns:

1. bool Returns true if the entry could be added or modified, false in case of any error (all parameters will be checked for validity). Note that if an error occurs the dynamic color will not be added, and an existing one by the specified name will not be changed.

gradient (start, stop, percent) line 176

Get a gradient color.

Uses linear interpolation in RGB space between the start and the stop color.

Parameters:

• start table The start color (for a value of 0%) of the gradient, as an array: {<r>,<g>,<b>,<a>}. All values must be floats between 0 and 1 (inclusive).
• stop table The stop color (for a value of 100%) of the gradient, as an array: {<r>,<g>,<b>,<a>}. All values must be floats between 0 and 1 (inclusive).
• percent number The position in the gradient, in percent - a number between 0 and 100 (inclusive).

Returns:

1. table Returns the gradient color at the specified position, as an array: {<r>,<g>,<b>,<a>}. All values will be floats between 0 and 1 (inclusive).

get (color, value) line 205

Get the color for some value.

If no dynamic color by the name specified by the first parameter exists, this function will simply pass this parameter to the colors.get() function and return the result. If a dynamic color exists, this function will determine the requested color based on the supplied value (second parameter) and return it.

Note: The type of dynamic color - a fixed dynamic color or gradient color - will be determined based on the definition of the color, see the configuration section above.

Parameters:

• color The name of the dynamic color entry (assumed to be a fixed color specification if no dynamic color by that name exists).
• value number The value used to select the color from a fixed dynamic color table or a color gradient. For gradients the value has to be a number between 0 and 100 (inclusive). For fixed dynamic colors the value may be any arbitrary number.

Returns:

1. table Returns an array containing the values for the red, green, blue and alpha channels, in that order. All values are floating point numbers between 0 and 1 (inclusive). If an error occurs, nil will be returned instead of the array.

Local Functions

config_handler (setting) line 269

Configuration handler for dynamic color settings.

This handler will be called automatically for every dcolor directive in the configuration file.

Parameters:

• setting table Array containing the configuration directive split into its individual parts.

Returns:

1. bool If successful true, false in case of any error.

See also:

• corky

Local Tables

dcolors line 82

Stores the user-defined dynamic colors.

The keys are the names of the dynamic colors. The values are arrays with the color information, in the same format used in the configuration:

{ <color>[, <threshold>, <color> […]][, <color>] }.