Lua

APIs

APIs are functions you can call in your Lua scripts to interact with Conky. See man -P "less -p 'LUA API'" conky for a complete list of Conky Lua APIs.

Information

Since 1.7.1, Conky features built-in Lua support. Lua is a "lightweight, reflective, imperative and functional programming language, designed as a scripting language with extensible semantics as a primary goal" which makes it ideal for integration into Conky. Together with the Cairo, RSVG and Imlib2 libraries (use build flags: BUILD_LUA_CAIRO, BUILD_LUA_RSVG, BUILD_LUA_IMLIB2) this allows for almost infinite possibilities. You can draw whatever you want, implement your own graphs, process data, ... To check if your conky installations supports these Lua libraries use conky -v. You can use any variable from conky within Lua but you can also pass them to a Lua function when you call it in conky.

conky.config = {
    lua_load = '~/.conky/Test/cpu_graph.lua',
    lua_draw_hook_pre = 'main_graph',
};

This will load the Lua file cpu_graph.lua and call the Lua function conky_main_graph before it updates the text section of the config. For safety all the functions you want to be callable from within conky must start with conky_ this prefix must not be added when calling your Lua function from your conky configuration (see the example). You can load multiple scripts separated by spaces.

You can load multiple scripts, just make sure the conky_ functions within the Lua scripts have a unique name. Do you want to get started? See Lua Tutorial.

Tips and Tricks

• Always use local variables, even if they are not in a function (except if you know what you are doing).

• Always destroy used cairo resources, eg cairo_xlib_surface_create, cairo_create, cairo_pattern_create_radial, ... as otherwise these will cause memory leaks!

• When you encounter small visual "off-by-one" errors using cairo this might be caused by the anti-aliasing which is used by default. This draws outside the area you have defined and may cause unwanted overlapping. The anti-aliasing can be turned of by using cairo_set_antialias(cr, CAIRO_ANTIALIAS_NONE).

• [Technical] For optimal Cairo performance you are more likely to obtain good performance when using a loop to, for example, draw 100 boxes, 100 circles and 100 triangles each by a separated for loop (followed by a fill) than to make a single for loop and interleave them (1 rectangle, circle and triangle at a time 100 times). This is because window drawing happens on the GPU while calculations happen on the CPU. To avoid waiting on synchronisation mixing calculations and drawings is generally a good idea (the 100 rectangles can be filled by the GPU while the 100 circles are calculated by the CPU).

• [Technical] Some events may trigger extra calls to the lua_draw_hook_pre/post hooks, eg. while dragging a window or when Conky windows overlap. This may be an issue if you want to store values every time conky updates since your lua script may be called more often and thus logging too much data. A work around is using the following function to draw, note this will only work with an update_interval >= 1 because the os.time() is only accurate up to 1 second.

-- Setup Global Variables
if tonumber(conky_parse('${updates}')) < 2 then --# don't reset these global
variables when changes are made to the lua script
    -- initialize previous epoch (use to prevent graph tables from being
    -- screwed up when other windows are moved across the conky window)
    previousEpoch = os.time()
end

function conky_main() --# main function controls everything else
    local newEpoch = os.time()

    if previousEpoch < newEpoch then
        -- "Collect Data in Global Variables Here"
    end
    if previousEpoch < newEpoch then
        previousEpoch = newEpoch
    else
        print("Error: epoch check warning old:" .. previousEpoch .. " new:" .. newEpoch)
    end
end

Sites

• Mr.Peachy
• wlourf
• TeoBigusGeekus Weather
• Mr.Peachy HOW TO Lua
• Conky Archive
• Collection of python scripts for Conky: Conky Companions (abandoned)