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.

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_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_date

A string containing the build date 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.

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:set(x, y, width, height)

Sets the values of an existing RsvgRectangle.

RsvgRectangle:get()

Gets the values of an existing RsvgRectangle.

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:set(x, y, width, height)

Sets the values of an existing RsvgDimensionData.

RsvgDimensionData:get()

Gets the values of an existing RsvgDimensionData.