Skip to content

Using Lua scripts (Part 02): Displaying stuff in conky

lasers edited this page Jan 5, 2019 · 3 revisions

ii. Displaying stuff in conky

so we have a blank main function we can set up our conkyrc to point to the script location with lua_load and we can activate the main function through lua_draw_hook

BUT we need something inside our lua function for conky to show!

what can lua display in conky? really 1 of 2 things

  • text
  • graphics such things as:
    • lines
    • boxes
    • bars
    • circles
    • etc

lets look at how to get text onto the screen first, any plain text within the lua script must be contained within quotes "plain text" you can set strings to contain plain text like so

text="hello world"
print (text) --> hello world (in terminal)

i like to do things in a "modular" way that is set everything to strings, then use those strings within the code I find this is easier to keep track of variables but is not necessary

so i want to display the text "hello world" in conky... here are the lines to do it

text="hello world"
cairo_select_font_face (cr, font, font_slant, font_face);
cairo_set_font_size (cr, font_size)
cairo_set_source_rgba (cr,red,green,blue,alpha)
cairo_move_to (cr,xpos,ypos)
cairo_show_text (cr,text)
cairo_stroke (cr)

you can see i set anything that might change to strings first, then used the strings within the code but it would work exactly the same way like this

cairo_select_font_face (cr, "mono", CAIRO_FONT_SLANT_NORMAL, CAIRO_FONT_WEIGHT_NORMAL);
cairo_set_font_size (cr, 12)
cairo_set_source_rgba (cr,1,1,1,1)
cairo_move_to (cr,100,100)
cairo_show_text (cr,"hello world")
cairo_stroke (cr)

with all the settings typed directly into the code.

NOTEwhen i write lua scripts i usually stick to having one line do one things but you don't have to you can use a semi colon ; to separate operations on the same line for example

cairo_move_to (cr,100,100);cairo_show_text (cr,"hello world");cairo_stroke (cr)

but i find that this can make things harder to navigate when looking back through the script to track down an error for example

using either of the above code examples we are going to:

  • print "hello world"
  • in white
  • using the mono font
  • at font size 12
  • at coordinates 100,100
  • normal face and slant (ie not bold or italic)

but lets look closer at what and how those things are set.

font names must be set within quotes but note in the first example, once the font has been set to a string, the string itself is called without quotes

the same goes for plain text which must also be in quotes

numbers do not require quotes as for font_size

another thing to note is how i have set my strings xpos,ypos=100,100 i have set 2 different strings in the same line by using commas to separate them this is exactly the same as writing


the same goes for setting the color red,green,blua,alpha=1,1,1,1 is the same as


either way is just as good

NOTE if you are thinking of later on making a setup section in a different area of the script (at the top most likely) then you will have to use the string setting method and you might also want to make your string names unique

if you remember, strings with the same names simply overwrite each other base on where they appear in the script so go for text_1="hello world" instead of simply text="hello world"

x and y when it comes to setting x and y values for text, the point you set will be the coordinates of the bottom left corner of the text and is set relative to the top and left edges of the conky window

so x,y=100,100 will move 100 pixels down from the top of the window, 100 pixels across from the left then it will display the text above and to the right of that point

color lua requires values for red green blue and alpha these values are all in the range of 0 to 1

So how do you get your values?

in many script, you may see a separate function to turn hexadecimal color codes into rgba values I'll discuss other function in a separate part of the guide so for now lets look at the direct way.

For example, you can open up gimp and use it to get a color you like:

here i have picked an orangey color and you can see in the window the various values for the color for this purpose look at the RGB values R = 246 G = 155 B = 11 these are almost the values we want, but instead of being between 0 and 1 they are between 0 and 255

one of the advantages of script is that you can do calculations, and in lua you can set a string to be the result of a calculation so we can set something like this to get our values in the correct range (0 to 1)


alpha is a little different, simply an alpha of 0 is fully transparent, ie you wont see anything and an alpha of 1 == fully opaque, so set whatever value you want

finally for font_face and font_slant


these do not need to be set within quotes face can be NORMAL or BOLD slant can be NORMAL or ITALIC

EXAMPLE we want to display our cpu usage percent in conky via a lua script to showcpu usage: 23% (or whatever cpu% is at the time)

  1. we use conky_parse to get the cpu number remember that the string names i am using are just my examples, you can call them whatever

but our string "cpu_perc" is only the number value from conky, we need to add the other parts

there are several ways to do this but probably easiest is to "stitch together" (or concatenate to be technical) the various elements we need. Like this:

cpu_text="cpu usage: "..cpu_perc.."%"

we are stitching some plain text "cpu usage: " to the string that contains the cpu value we want (cpu_perc) and ending with some more plain text "%" the use of a double period is how we put these elements together

NOTE say you only wanted the number followed by the percent you would do it like this


there are more complex ways to use text but again for later

You can’t perform that action at this time.