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++, which currently only compiles against Lua 5.1.

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

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

NOTE: In order 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 particular instance of Conky.

conky_build_info

A string containing the build info for this particular instance of Conky, 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 instance of Conky.

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.