Conky – Lua API

Conky features a Lua programming API and also ships with Lua bindings for some useful libraries. Note that the bindings require tolua++.

To use Lua with Conky, first make sure you have a version of Conky with Lua support enabled (conky -v will report this). Conky defines certain global functions and variables that can be accessed from Lua code running inside Conky. Scripts must first be loaded using the lua_load configuration option. You can then call Lua functions through Conky's $lua, $lua_read, and Lua hooks.

Be careful when creating threaded objects through the Lua API. You could end up with a large number of threads running if a thread is created with each iteration.

Note: to accommodate certain features in the Cairo library's API, Conky will export a few additional functions for the creation of certain structures. These are documented below.

RsvgDimensionData:create()

Call this method to return a new RsvgDimensionData structure. A creation function for this structure is not provided by the Rsvg API.

After calling this, you should use tolua.takeownership(rect) on the return value to ensure ownership is passed properly.

RsvgDimensionData:destroy()

Call this method to free memory allocated by RsvgDimensionData:create.

You should call tolua.releaseownership(dd) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(dd)

RsvgDimensionData:get()

Gets the values of an existing RsvgDimensionData.

RsvgDimensionData:set(x, y, width, height)

Sets the values of an existing RsvgDimensionData.

RsvgRectangle:create()

Call this method to return a new RsvgRectangle structure. A creation function for this structure is not provided by the Rsvg API.

After calling this, you should use tolua.takeownership(rect) on the return value to ensure ownership is passed properly.

RsvgRectangle:destroy()

Call this method to free memory allocated by RsvgRectangle:create.

You should call tolua.releaseownership(rect) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(rect)

RsvgRectangle:get()

Gets the values of an existing RsvgRectangle.

RsvgRectangle:set(x, y, width, height)

Sets the values of an existing RsvgRectangle.

cairo_font_extents_t:create()

Call this function to return a new cairo_font_extents_t structure. A creation function for this structure is not provided by the cairo API.

After calling this, you should use tolua.takeownership(cfe) on the return value to ensure ownership is passed properly.

cairo_font_extents_t:destroy(structure)

Call this function to free memory allocated by cairo_font_extents_t:create.

You should call tolua.releaseownership(cfe) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(cfe)

cairo_matrix_t:create()

Call this function to return a new cairo_matrix_t structure. A creation function for this structure is not provided by the cairo API.

After calling this, you should use tolua.takeownership(cm) on the return value to ensure ownership is passed properly.

cairo_matrix_t:destroy(structure)

Call this function to free memory allocated by cairo_matrix_t:create.

You should call tolua.releaseownership(cm) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(cm)

cairo_place_image(file, cr, x, y, width, height, alpha)

Renders an image onto a cairo_t, using imlib2. In some cases using a cairo_t and exact coordinates is more useful.

Argument	Description
file	Path to the image to render.
cr	The `cairo_t` to render to.
x,y	Position to render the image.
width, height	The width and height to draw the image
alpha	The transparency of the image 1.0 is solid 0.0 is fully translucent.

require('cairo_imlib2_helper') in your lua file.

cairo_text_extents_t:create()

Call this function to return a new cairo_text_extents_t structure. A creation function for this structure is not provided by the cairo API.

After calling this, you should use tolua.takeownership(cte) on the return value to ensure ownership is passed properly.

cairo_text_extents_t:destroy(structure)

Call this function to free memory allocated by cairo_text_extents_t:create.

You should call tolua.releaseownership(cte) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(cte)

conky_build_arch

A string containing the build architecture for this Conky instance.

conky_build_info

A string containing build information for this Conky instance, including the version, build date, and architecture.

conky_config

A string containing the path of the current Conky configuration file.

conky_info

This table contains some information about Conky's internal data. The following table describes the values contained:

Key	Value
update_interval	Conky's update interval (in seconds).

conky_parse(string)

This function takes a string that is evaluated as per Conky's TEXT section, and then returns a string with the result.

conky_set_update_interval(number)

Sets Conky's update interval (in seconds) to 'number'.

conky_version

A string containing the version of the current Conky instance.

conky_window

This table contains some information about Conky's window. The following table describes the values contained:

Key	Value
drawable	Window's drawable (Xlib Drawable), requires Lua extras enabled at compile time.
visual	Window's visual (Xlib Visual), requires Lua extras enabled at compile time.
display	Window's display (Xlib Display), requires Lua extras enabled at compile time.
width	Window width (in pixels).
height	Window height (in pixels).
border_inner_margin	Window's inner border margin (in pixels).
border_outer_margin	Window's outer border margin (in pixels).
border_width	Window's border width (in pixels).
text_start_x	The x component of the starting coordinate of text drawing.
text_start_y	The y component of the starting coordinate of text drawing.
text_width	The width of the text drawing region.
text_height	The height of the text drawing region.

NOTE: This table is only defined when X support is enabled.

ret_scale_x,ret_scale_y:cairo_draw_image(file, cs, x, y, scale_x, scale_y)

Renders an image onto a cairo_surface_t, using imlib2. Returns the amount the image was scaled by

Argument	Description
file	Path to the image to render.
cs	The `cairo_surface_t` to render to.
x,y	Position to render the image.
scale_x, scale_y	The amount to scale the image, 1.0 provides no scaling, 2.0 for twice the size and
	0.5 for half size etc. Default value: No Scaling (1.0,1.0)

require('cairo_imlib2_helper') in your lua file.

cairo_text_hp_show(cr, x, y, text, font, font_size, alignment, language, script, direction)

Renders text to a cairo_t using HarfBuzz and FreeType. This provides significantly better text rendering than Cairo's built-in functions.

Argument	Description
cr	The `cairo_t` to render to.
x,y	Position to render the text.
text	The text to render.
font	The name of the font to be used, `Fontconfig` is used to search for the font.
font_size	The font size.
alignment	One of `CAIRO_TEXT_ALIGN_LEFT`, `CAIRO_TEXT_ALIGN_RIGHT`, `CAIRO_TEXT_ALIGN_CENTER`. Default value: `CAIRO_TEXT_ALIGN_LEFT`
language	A string containing a BCP 47 language tag. Default value: `en`
script	A string containing a ISO 15924 script tag. Default value: auto-detect from text
direction	A string representing text direction eg `LTR`, `RTL` or `TTB` Default value: auto-detect from text otherwise `LTR`

width,height:cairo_text_hp_text_size(text, font, font_size, language, script, direction)

Used to calculate how many pixels will be required to render a string with cairo_text_hp_show returns a pair of int's with width and height.

Argument	Description
cr	The `cairo_t` to render to.
text	The text to render.
font	The name of the font to be used, `Fontconfig` is used to search for the font.
font_size	The font size.
language	A string containing a BCP 47 language tag. Default value: `en`
script	A string containing a ISO 15924 script tag. Default value: auto-detect from text
direction	A string representing text direction eg `LTR`, `RTL` or `TTB` Default value: auto-detect from text otherwise `LTR`

cairo_text_hp_delete_fonts()

cairo_text_hp_show and cairo_text_hp_text_size both cache internal font details, this function clears those caches.