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.
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.
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)
Gets the values of an existing RsvgDimensionData.
Sets the values of an existing RsvgDimensionData.
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.
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)
Gets the values of an existing RsvgRectangle.
Sets the values of an existing RsvgRectangle.
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.
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)
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.
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)
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.
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.
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)
A string containing the build architecture for this Conky instance.
A string containing build information for this Conky instance, including the version, build date, and architecture.
A string containing the path of the current Conky configuration file.
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). |
This function takes a string that is evaluated as per Conky's TEXT section, and then returns a string with the result.
Sets Conky's update interval (in seconds) to 'number'.
Returns the current cairo_surface_t for the active display output,
or nil if no graphical surface is available. This is the preferred,
backend-agnostic way to obtain a drawing surface for use with Cairo.
The returned surface is only valid for the current draw cycle. Do not
cache it across frames; call conky_surface() each time your draw
hook is invoked.
Example usage:
require('cairo')
function conky_draw()
local surface = conky_surface()
if not surface then return end
local cr = cairo_create(surface)
-- draw ...
cairo_destroy(cr)
end
A string containing the version of the current Conky instance.
This table contains read-only information about Conky's window. The following table describes the values contained:
| Key | Value |
|---|---|
| drawable | Deprecated. Window's drawable (Xlib Drawable). Use conky_surface() instead. |
| visual | Deprecated. Window's visual (Xlib Visual). Use conky_surface() instead. |
| display | Deprecated. Window's display (Xlib Display). Use conky_surface() instead. |
| width | Window width in layout points (pt; logical). |
| height | Window height in layout points (pt; logical). |
| pixel_size.x | Window width in device pixels (px; physical). |
| pixel_size.y | Window height in device pixels (px; physical). |
| scale | Scaling factor of the buffer (dpi; pixel_size / size). |
| 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 a GUI output is
active. The drawable, visual, and display fields are
X11-specific and deprecated.
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.
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 TTBDefault value: auto-detect from text otherwise LTR |
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 TTBDefault value: auto-detect from text otherwise LTR |
cairo_text_hp_show and cairo_text_hp_text_size both cache internal font details,
this function clears those caches.