Add mixins and keep-max mixin

README.md

@@ -1,10 +1,14 @@
 # Conky widgets for Awesome WM 4.0
 
-conky-awesome lets you make widgets displaying system information from [conky](https://github.com/brndnmtthws/conky)
+`conky-awesome` is a framework for making [awesome](https://awesomewm.org) widgets displaying system information from [conky](https://github.com/brndnmtthws/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.
 
 ## Requirements
+* conky
 * awesome with dbus support
-* conky with X support
 * [lua bindings to dbus](https://github.com/daurnimator/ldbus)
 
 ## Installation
@@ -246,9 +250,15 @@ 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:
+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 {
@@ -259,15 +269,53 @@ end
 
 Please contribute if you make anything cool or useful.
 
+### Mixins
+
+Mixins, located in `awesome/conky/mixins/`, are for extending 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
+```
+
 ## Caveats and Gotchas
 
 ### Conky
 
-Conky only runs its lua scripts when the `out_to_x` setting is `true`.
-Furthermore, in versions `>=1.10` conky will halt its loop if its window
-isn't on the current desktop/tag. This consequently halts the updating of the
-widget.
-
 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

init.lua

@@ -62,7 +62,7 @@ local widget = { -- for the widget that awesome draws
  -- for declaring subwidget properties
  SUBW_DECL = Set({ "conkybox", "iconbox", "labelbox", "background" }),
  -- for declaring a conky widget
- CONKY_DECL = Set({ "conky", "icon", "label", "updater" }),
+ CONKY_DECL = Set({ "conky", "icon", "label", "updater", "buttons" }),
 }
 local updater = {} -- for updating the widget
 local window = {} -- for conky's own window
@@ -132,7 +132,13 @@ function public.toggle_key(key, mod) -- {{{2
  { description = "toggle conky window on top", group = "conky" })
 end
 
-
+function public.mixin(...) -- {{{2
+ local root = arg[#arg]
+ for i = 1, #arg - 1 do
+ root = require("conky/mixins/" .. arg[i])(root)
+ end
+ return root
+end
 
 -- WIDGET -- {{{1
 function widget.make(raw) -- {{{2
@@ -158,20 +164,44 @@ function widget.make(raw) -- {{{2
  widget.apply_properties(raw, background, "background")
  end
 
+ local conkybox = nil
  if raw.conky then
- local conkybox = wibox.widget.textbox("")
+ conkybox = wibox.widget.textbox("")
  widget.apply_properties(raw, conkybox, "conkybox")
  layout:add(conkybox)
 
  updater.add_string(raw.conky)
  updater.add(conkybox, iconbox, labelbox, background, raw.updater)
  end
 
+ local root = nil
  if raw.background then
- return wibox.layout.fixed.horizontal(background)
+ root = wibox.layout.fixed.horizontal(background)
  else
- return layout
+ root = layout
  end
+
+ if raw.buttons then
+ local buttons = {}
+ for _, button in ipairs(raw.buttons) do
+ local mod = button[1]
+ local button_num = button[2]
+ local func = button[3]
+
+ buttons = awful.util.table.join(buttons,
+ awful.button(mod, button_num, function()
+ local conkybox = conkybox
+ local iconbox = iconbox
+ local labelbox = labelbox
+ local background = background
+ func(conkybox, iconbox, labelbox, background)
+ end)
+ )
+ end
+ root:buttons(buttons)
+ end
+
+ return root
 end
 
 function widget.inherit_properties(child, parent) -- {{{2

mixins/keep-max.lua

@@ -0,0 +1,106 @@
+-- usage {{{1
+--[[
+
+This mixin provides an update function that:
+ - Splits the update on spaces, and finds the highest value
+ - Displays the current highest and (optionally) historically highest value
+ - Clicking the widget resets and toggles the historical max being displayed
+
+Widget declaration with the extra options:
+
+conky.mixin("keep-max", {
+ <usual widget declaration>
+
+ show_max = false, -- don't display max by default
+ format = "%s°", -- format for conkybox without max
+ max_format = "%s(%s)°", -- format for conkybox with max
+ conkybox = {
+ forced_width = 40, -- width when not showing max
+ max_forced_width = 60, -- width when showing max
+ align = "center",
+ }
+}),
+
+--]]
+
+-- constructor {{{1
+return function(raw_widget)
+ -- init {{{2
+ local defaults = {
+ show_max = false,
+ max_format = "%s(%s)°",
+ format = "%s°",
+ conkybox = {
+ forced_width = 40,
+ max_forced_width = 60,
+ align = "center",
+ }
+ }
+
+ local raw = raw_widget
+
+ for k, v in pairs(defaults) do
+ if k == "conkybox" then
+ if raw.conkybox == nil then raw.conkybox = {} end
+ for _k, _v in pairs(v) do
+ raw.conkybox[_k] = raw.conkybox[_k] or _v
+ end
+ else
+ raw[k] = raw[k] or v
+ end
+ end
+
+ local max = 0
+ local last_update = nil
+
+ local show_max = raw.show_max
+ local forced_width = raw.conkybox.forced_width
+ local max_forced_width = raw.conkybox.max_forced_width
+
+ if show_max then
+ raw.conkybox.forced_width = max_forced_width
+ end
+
+ -- widget updater {{{2
+ local function updater(update, textbox, _)
+ last_update = update
+ local current_max = 0
+ for value in string.gmatch(update, "%S+") do
+ local num = tonumber(value) or 0
+ if num > current_max then
+ current_max = num
+ end
+ end
+
+ if current_max > max then
+ max = current_max
+ end
+
+ if show_max then
+ textbox:set_text(string.format(defaults.max_format, current_max, max))
+ else
+ textbox:set_text(string.format(defaults.format, current_max))
+ end
+ end
+
+ -- toggle function for button binding {{{2
+ local function toggle(conkybox, _)
+ max = 0
+ show_max = not show_max
+ if show_max then
+ conkybox:set_forced_width(max_forced_width)
+ else
+ conkybox:set_forced_width(forced_width)
+ end
+ updater(last_update, conkybox)
+ end
+
+ -- update raw widget {{{2
+
+ raw.updater = updater
+ raw.buttons = {
+ { { }, 1, toggle },
+ }
+
+ return raw
+end