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

ii. Displaying stuff in Conky

NOTE: The following examples require your conky.cfg file to have the following settings at a minimum:

conky.config =
{
  minimum_height = 200,
  minimum_width = 200,
  own_window = true,
  own_window_class = 'Conky',
  own_window_type = 'normal',
  own_window_transparent = false,
}
conky.text = [[
]]

So now we have a blank conky window and a blank main function. We can set up our conky.conf 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 one of two things:

• text
• graphics, things like:
  • 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, like this: "plain text". For example:

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

The "-->" is not part of Lua syntax. It is a comment (--) made into an arrow to show what is printed when you run the script.

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 makes it easier to keep track of variables.

Here is a way to display "hello world" in Conky:

font = "Mono"
font_size = 12
text = "hello world"
xpos, ypos = 100, 100
red, green, blue, alpha = 1, 1, 1, 1
font_slant = CAIRO_FONT_SLANT_NORMAL
font_face = CAIRO_FONT_WEIGHT_NORMAL

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)

NOTE: when I write Lua scripts I usually stick to one statement per line but you can use a semicolon (;) to separate operations on the same line:

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 -- when error-hunting, 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 once the font has been set to a string, the string itself is called without quotes.

The same goes for any plain text.

Numbers, like the value of font_size, do not require quotes.

Another thing to note is the line xpos, ypos = 100, 100. This is a way to set multiple variables at once. It's the same was writing:

xpos = 100
ypos = 100

I do the same thing when I set the colour. red, green, blua, alpha = 1, 1, 1, 1 is the same as

red=1
green=1
blua=1
alpha=1

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 based on where they appear in the script, so go for, for example, text_1 = "hello world" instead of 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 that are in the range of 0 and 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. 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):

red = 246 / 255
green = 155 / 255
blue = 11 / 255

Alpha is a little different: 0 is fully transparent (ie you wont see anything) and 1 is fully opaque, so set whatever value you want.

Finally for font_face and font_slant:

font_slant = CAIRO_FONT_SLANT_NORMAL
font_face = CAIRO_FONT_WEIGHT_NORMAL

These do not need to be set within quotes. Face can be NORMAL or BOLD. Slant can be NORMAL or ITALIC.

EXAMPLE. Let's say we want to display our percentage CPU usage in Conky using a Lua script. We will display in in the format cpu usage: 23% (or whatever the cpu% is at that time.

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 you want.

cpu_perc = conky_parse ("${cpu}")

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 -- Lua's "concatenation operator".

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

cpu_text = cpu_perc .. "%"

There are more complex ways to use text but again for later.