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.circles

Circular meters for Corky.

Loading the module:

#: include, corky.circles

Adding a circular meter:

Note: This is only one line in the actual configuration. Do not add the line break!

#: circle, <name>, <value>, <x>, <y>, <radius>, <width>, <start>, <angle>, <fcol>
   [, <bcol>[, <scale>[, <scol>[, <min>[, <max>[, <hook>]]]]]]

Parameters:

<name>

• The name of the meter, may be any arbitrary string. It is currently not used and may be left empty. Multiple meters with the same name are allowed.

<value>

• The value to display, e.g. ${cpu cpu1} for a circular meter showing the current CPU usage of the first CPU. The value will be retrieved using the corky.cache module's percent() function. To get correct values, it is necessary to manually add the value to the cache and define its minimum and maximum value (either in a Lua script using set() or using the cache directive in the configuration file), even if the value itself is already a percentage (like ${cpu cpu1})! Please see the corky.cache module for more details.

<x>

• The X coordinate of the circle's center. Must be a valid integer greater than or equal to 0.

<y>

• The Y coordinate of the circle's center. Must be a valid integer greater than or equal to 0.

<radius>

• The radius of the circle. Must be a valid integer greater than 0.

<width>

• The width of the meter. Must be a valid integer greater than 0.

<start>

• The start angle: the angle where a value of 0% (or the <min> value) is located, in degrees. Must be a valid number greater than or equal to 0 and less than 360. An angle of 0 is in the direction of the positive X axis, the angle increases in clockwise direction.

<angle>

• The total angle of the meter, in degrees. This must be a valid number between -360 and 360 (inclusive). It must not be 0. The meter will be drawn in clockwise direction for positive values, and counter-clockwise for negative values.

<fcol>

• The foreground color, i.e. the color used to draw the meter from 0% (or the <min> value) to the value. The corky.dcolors module will be used to resolve the color, so any named color (see corky.colors), fixed dynamic color or gradient color (see corky.dcolors) may be used, or a 0x<AARRGGBB> value (or in fact any valid number between 0 and 0xffffffff, see the colors module) may be used directly.

• Note: There will be no gradient displayed on the meter, i.e. the foreground color will be one color across the length of the meter. The gradient (or fixed dynamic color), if one is used, will just be used to calculate this one color based on the value. If dynamic colors are used, the threshold values must be specified in percent. See corky.dcolors for more details.

<bcol>

• Optional. The background color. If specified, the part of the meter between the value and the 100% position (or the <max> value) will be filled with this color. The same notes as for the foreground color apply, please see above.

<scale>

• Optional. The name of a list of scale positions. See the corky.lists module on how to define a list. If this is specified, the list must contain an arbitrary number of numeric values between 0 and 100 (inclusive), in ascending order. These values specify the positions (in percent) of scale marks to be drawn over the meter. To enable these marks, the parameter <scol> has to be specified, too.

<scol>

• Optional. The color for the scale marks. The same notes as for the foreground color apply, see above. Note that the <scale> has to be a valid list as described above for marks to be drawn.

<min>

• Optional. The minimum value in percent, defaults to 0 if not specified.

<max>

• Optional. The maximum value in percent, defaults to 100 if not specified.

<hook>

• Optional. Specifies when to draw the circle. It must be either "pre" (to draw it during the pre-draw hook) or "post" (to draw it during the post-draw hook). The default value is "post".

Examples:

Display the (total) CPU usage. Colors are defined using the color (see corky.colors) and dcolor (see corky.dcolors) directives, and scale marks will be shown in 10% steps.

Note that optional values at the end may be left out completely, while the optional name of the meter may be left empty, but the (empty) field itself has to be included!

#: cache, ${cpu}, 1, 0, 100

#: color,  black, 0x000000
#: color,  grey,  0x444444
#: dcolor, fg,    0x00ff00, 50, 0xffff00, 0xff0000

#: list, scale, 0, 10, 20, 30, 40, 50, 60, 70, 80, 90

#: circle,, ${cpu}, 100, 100, 50, 10, 270, +360, fg, grey, scale, black

Display the (total) CPU usage using two circular meters:

#: cache, ${cpu}, 1, 0, 100

#: circle,, ${cpu}, 70, 250, 50, 10, 90, +180, 0xff0000, 0x444444,,,  0,  50
#: circle,, ${cpu}, 70, 250, 37, 10, 90, +180, 0xff0000, 0x444444,,, 50, 100

This example will display two circular meters for the CPU usage. Values between 0% and 50% will be shown in the first meter, i.e. if the CPU usage is 25%, the first meter will display a 50% value, while the second meter will show 0%. Values between 50% and 100% will be shown in the second meter, i.e. for a CPU usage of 75% the first meter will show a 100% value, and the second meter will show a 50% value.

If you want to use scale marks on the meters, note that these are defined per meter. If in the example above a list containing a single value of 50 is specified as <scale> parameter, a scale mark at the 50% position of both meters will be drawn (i.e. at the 25% and 75% CPU usage positions)!

Info:

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

Functions

add (...)	Add a circular meter.
arc (x, y, radius, width, start, angle, p, fcol[, bcol[, scale[, scol]]])	Draw a circular meter.

Local Functions

draw (hook)	Draw the meters.
config_handler (setting)	Configuration handler for circle settings.

Local Tables

circles

Stores the defined meters.

Functions

add (...) line 209

Add a circular meter.

The parameters are the same as the parameters for the configuration directive, in the same order. Please see above for more details.

This function will add the new meter to the list of meters, it will not draw it!

Parameters:

• ...
  • name: (string) Name of the meter.
  • value: (string) Value of the meter.
  • x: (int) X coordinate of the center (x >= 0).
  • y: (int) Y coordinate of the center (y >= 0).
  • radius: (int) The radius of the circle (radius > 0).
  • width: (int) The width of the meter (width > 0).
  • start: (number) The start angle, in degrees (0 <= start < 360).
  • angle: (number) The total angle, in degrees (-360 <= angle <= 360 and angle ~= 0).
  • fcol: The foreground color, uses corky.dcolors to get the actual color.
  • bcol: The background color, uses corky.dcolors to get the actual color. (optional)
  • scale: (string) Name of a list with scale mark positions, see corky.lists. (optional)
  • scol: Scale color, uses corky.dcolors to get the actual color. (optional)
  • min: (number) Minimum value for the meter (0 <= min < 100). (optional)
  • max: (number) Maximum value for the meter (0 < max <= 100). (optional)
  • hook: (string) When to draw the meter (either "pre" or "post"). (optional)

Returns:

1. bool Returns true if the meter could be added, false in case of any error.

arc (x, y, radius, width, start, angle, p, fcol[, bcol[, scale[, scol]]]) line 294

Draw a circular meter.

Note: This function assumes that corky.cairo.init() has been called and a valid surface and context are available!

Parameters:

• x int X coordinate of the circle's center.
• y int Y coordinate of the circle's center.
• radius int The radius of the circle.
• width int The width of the meter.
• start number The start angle, in degrees.
• angle number The total angle, in degrees.
• p number The percent value, relative to the meter.
• fcol table The foreground color, as { r, g, b, a }, all values between 0 and 1 (inclusive).
• bcol table The background color, as { r, g, b, a }, all values between 0 and 1 (inclusive). (optional)
• scale table Array containing the scale mark positions, in percent. (optional)
• scol table The scale marks' color, as { r, g, b, a }, all values between 0 and 1 (inclusive). (optional)

Local Functions

draw (hook) line 366

Draw the meters.

Parameters:

• hook string Which meters to draw, either "pre" or "post".

config_handler (setting) line 401

Configuration handler for circle settings.

This handler will be called automatically for every circle 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

circles line 171

Stores the defined meters.

The keys are the meter names, the values are arrays containing tables with the meter data defined under that name, in the order they are added. The meter data tables contain the following keys: value, x, y, radius, width, start, angle, fcol, bcol, scale, scol, min, max, hook. The scale will already be resolved to the appropriate list, all colors will be strings (or numbers) and will be resolved at runtime to allow for dynamic colors.