conky-awesome is a framework for making awesome widgets displaying system information from conky
conky-awesome provides some optional keybindings to manange conky's own
X-window, but you can also run conky-awesome headless by configuring conky
with out_to_x = false and only have it update your widgets.
- conky
- awesome with dbus support
- lua bindings to dbus
Clone this repo to ~/.config/awesome/conky
conky.config = {
.....
lua_load = "~/.config/awesome/conky/conky-dbus.lua",
lua_draw_hook_pre = "conky_update_awesome",
}
local conky = require("conky")
This is all that is required to have conky start at launch. Restarting awesome will not spawn additional conky clients.
To launch conky with custom options, i.e. a different conkyrc:
conky.options = "-c ~/.conky/my_special_conkyrc"
The conky client's own window defaults to being behind all other windows.
Bind keys for raising the client window on top.
globalkeys = awful.util.table.join(
awful.key( .....
.....
conky.show_key("F12"), -- conky window on top while held
conky.toggle_key("F12"), { modkey }) -- toggle conky on top
)
Both functions have this signature:
(keystring, [ modifier table ])
You can also provide functions to call when the window is raised and lowered
conky.raise = function(c) c.opacity = 1.0 end
conky.lower = function(c) c.opacity = 0.4 end
If you are running conky with a non-standard window class, by setting
own_window_class in conkyrc, you must also set this in rc.lua for
the keybindings to work:
conky.class = "MyClass"
To set properties for the client window (defaults shown):
conky.properties = {
floating = true,
sticky = true,
ontop = false,
skip_taskbar = true,
below = true,
focusable = true,
titlebars_enabled = false,
}
For these properties to apply properly when awesome is started and restarted,
the following must be added to the Rules section in awesome/rc.lua:
awful.rules.rules = {
....
conky.rules()
}
Extra properties may be provided to be applied on launch, as per awful.rules:
awful.rules.rules = {
....
conky.rules({ properties = { tag = "3" }, callback = function(c) ... end })
}
Conky widget declaration:
{
icon = <string>, -- image filename
label = <string>, -- text for a label
conky = <string>, -- the string conky evaluates with conky_parse()
background = <table>, -- background properties table
updater = <function>, -- custom updater function
buttons = <table>, -- buttons to connect to the widget
signals = <table>, -- signals to connect to the widget
tooltip = <table>, -- tooltip for the widget
<wibox property> = <value> -- properties for the widgets
{ -- any number of child widgets:
<conky declaration>, -- nested conky widget declarations
<canned conky widget>, -- premade widgets from .config/awesome/conky/widgets
<any widget> -- to place other widgets in-between conky widgets
}
}
A conky widget consists of up to four subwidgets, all optional:
icondeclares a wibox.widget.imagebox instancelabeldeclares a wibox.widget.textbox instanceconkydeclares a wibox.widget.textbox instancebackgrounddeclares a wibox.container.background instance
Simply declaring a string to be evaluated by conky:
s.mywibox:setup {
.....
conky.widget({ conky = "CPU: ${cpu0}% MEM: ${memperc}% GPU: ${hwmon 0 temp 1}" }),
....
}
Simple example with an icon and a text label:
conky.widget({
icon = "my_neat_cpu_icon.png",
label = "CPU:",
conky = "${cpu0}"
})
Setting wibox properties individually for subwidgets:
conky.widget({
label = "CPU:",
conky = "${cpu}",
-- properties for the background wibox
background = { bg = "red" },
-- properties for the label wibox
labelbox = { font = "Font for Label" },
-- properties for the conky wibox
conkybox = { force_width = 30, align = "right" },
-- properties for the icon wibox
iconbox = { opacity = 0.8 },
})
Child widgets inherit properties from their parents.
Any number of child widgets can be declared, and will be placed to the right of its parent.
conky.widget({
font = "My Neat Font",
label = "CPU:",
conky = "${hwmon 1 temp 1}", -- cpu temp
{ -- child widget 1 inherits "My Neat Font"
label = "Core 1:",
{ conky = "${cpu1}" }, -- as does the grandchildren
{ conky = "${cpu2}" },
},
{ -- child widget 2 inherits "My Neat Font"
label = "Core 2:",
{ conky = "${cpu3}" }, -- as does the grandchildren
{ conky = "${cpu4}" },
},
....
{
font = "Font for Ram" -- different font for RAM child widget
label = "RAM:"
conky = "${memperc}"
}
})
Child widgets inherit subwidget properties from their parent.
conky.widget({
label = "Parent",
background = { bg = "black" },
labelbox = { force_width = 30 },
{
label = "Child",
labelbox = { align = "right" },
{
-- this widget has a black background,
-- and a left-aligned label widget 30 pixels wide
label = "GrandChild",
labelbox = { align = "left" },
}
}
})
To change the widget based on updates from conky, provide an updater function with the following signature:
function updater(conky_update, conky_wibox, icon_wibox, label_wibox, background)
Where conky_update is the update from conky, and the rest are the subwidget
wiboxes.
A CPU widget that changes its background color to red if the load goes above 80%:
conky.widget({
label = "CPU:",
conky = "${cpu0}",
background = { bg = "grey" },
updater = function(conky_update, conky_wibox, _, _, background)
conky_wibox:set_text(conky_update)
if tonumber(conky_update) > 80 then
background.bg = "red"
else
background.bg = "grey"
end
end
})
Providing a table of button declarations allows you to change the widget based on button pressed.
A CPU widget that changes its background color to blue while the user holds CTRL and :
conky.widget({
label = "CPU:",
conky = "${cpu0}",
background = { bg = "red" },
buttons = {
{ -- declaration of single button
{ "Control" }, -- table of modifiers
1, -- key, here <mouse1>
function(conkybox, iconbox, labelbox, background) -- function for
background.bg = "blue" -- button press
end,
function(conkybox, iconbox, labelbox, background) -- (optional) function
background.bg = "red" -- for button release
end
},
... -- more button declarations
}
})
Providing a table of signals and conky-awesome connects them for you.
A CPU widget showing the load on all four cores while the mouse hovers over it:
local cpu_widget = (function()
local conkyb = { -- properties are not passed to
forced_width = 30, -- already built child widgets, so
align = "right", -- shared properties are declared here
}
local cores = conky.widget({ -- building the widget here to close
conkybox = conkyb, -- up in signal functions below
{ conky = "${cpu 1}%" },
{ conky = "${cpu 2}%" },
{ conky = "${cpu 3}%" },
{ conky = "${cpu 4}%" },
})
cores.visible = false -- widget starts out with cores hidden
return { -- widget declaration
conkybox = conkyb, -- shared properties
conky = "${cpu 0}%", -- total load %
signals = {
['mouse::enter'] = function(conkybox, iconbox, labelbox, background)
cores.visible = true -- on hover, show cores and hide
conkybox.visible = false -- total load
end,
['mouse::leave'] = function(conkybox, iconbox, labelbox, background)
cores.visible = false -- reset when mouse leaves
conkybox.visible = true
end,
},
cores,
}
end)()
Simply a table to pass to awful.tooltip().
A simple 24 hour clock with a date tooltip:
conky.widget({
conky = "${time %R}",
conkybox = { align = "center" },
tooltip = {
timer_function = function() return os.date("%A %B %d %Y") end,
}
})
Canned widgets, located in awesome/conky/widgets/, can be included by providing
its filename, without the lua extension, in place of any widget declaration.
conky.widget({
conky = "CPU: ${cpu0}"
{
"battery" -- battery widget, from widgets/battery.lua
}
})
Canned widgets can be configured as follows:
conky.config.<widget> = { <option> = <value> }
To make a canned widget, have the module return a constructor function that takes a table of options and returns a widget declaration. The top of the file should contain a comment describing use and configuration.
-- usage
--[[
Description and instructions goes here
--]]
return function(options)
-- apply options
return {
-- declare widget
}
end
Please contribute if you make anything cool or useful.
Mixins, located in awesome/conky/mixins/, are for extending a widget
declaration with common functionality. Below the keep-max mixin extends
the CPU widget declaration with functionality that tracks and displays both
the current and highest value, in this case CPU core temperature.
conky.widget({
conky.mixin("keep-max", {
icon = beautiful["icon-hardware-cpu"],
conky = "${hwmon temp 2} ${hwmon 3 temp 3}",
{
conky = ${cpu 0}% ",
}
})
})
Any number of mixins may be provided, and they are applied in order to the provided declaration.
conky.mixin("keep-max", "alert-on", ..., <widget declaration>)
To make a mixin, have the module return a constructor function that takes a widget declaration to extend. The top of the file should contain a comment describing use and configuration.
-- usage
--[[
Description and instructions goes here
--]]
return function(widget_decl)
<define stuff>
<extend widget>
return widget_decl
end
If you change your .conkyrc while conky is running, conky will restart itself
but appears to not be reloading its lua files. Conky will complain about
conky_update_awesome being nil. Simply kill the process and start conky
manually.
If you start a nested awesome in Xephyr, you will need to start it in a
separate dbus session. You can do this by starting the nested awesome with
dbus-launch awesome