General description

This PR adds a lua_mouse_hook to Lua config script as suggested in issue #938. I remembered wanting click events in conky before, and I wanted them again, this time I understood C & C++ a bit more so I decided to implement it.

Instead of defining 6 different hooks, I opted for creating just one and passing the relevant data in a table as an argument. Hopefully, this table stuff doesn't break any guidelines. This also means that lua_mouse_hook is not adjustable by context (can't pass custom arguments), but mouse action handling is generally very case-specific so that shouldn't be a problem.

I added a custom build flag which means this can be turned off completely if not wanted. There is some code outside of #ifdef, but it will be optimized away by most compilers as it's very trivial (declaring a variable that never changes). I can wrap it if needed.

List of events handled by the lua_mouse_hook

• button_down - called when a mouse button is clicked
• button_up - called when a mouse button is released
• button_scroll - called on scroll action (X handles it the same way as button clicks)
• mouse_move - called when the pointer is being dragged across conky window
• mouse_enter - called when the pointer enters conky window
• mouse_leave - called when the pointer leaves conky window

Users are supposed to handle the events by reading event.type string and putting logic into appropriate if-clauses - where event is the name of the first (and only) function argument and value is one of the event names from the above list. If there is an error with code, event.type == "err".

Users can return true to signal conky that the event has been "consumed" and shouldn't be passed to the root window. If nothing is returned, false is assumed which pushes the event through.

Depending on event type, different data is appended to the event table:

Move event

event table has following keys:

• x - window-relative cursor x position (int)
• y - window-relative cursor y position (int)
• x_abs - display-relative cursor x position (int)
• y_abs - display-relative cursor y position (int)
• time - time in ms provided by Xlib (ulong)

Button press and release event

event table has all move event entries and additionally:

• mods - table of buttons and modifier keys being held (name to bool map)
  • shift
  • lock
  • control
  • mod1
  • num_lock
  • mod3
  • mod4
  • mod5
  • mouse_left
  • mouse_right
  • mouse_middle
  • scroll_up
  • scroll_down
• button - number of the button being pressed/released (int)
  • Left button: 1
  • Right button: 2
  • Middle button: 3

Scroll event

Same as button press and release event but instead of the button field, a direction field is provided, holding either up or down string value - depending on scroll direction.

Mouse enter/leave event

Called when the mouse enters or leaves conky window area. This might be useful for "turning off" "buttons" when the user drags their mouse outside the window while holding the mouse button pressed. event fields are the same as in the movement event.

Problems

• When own_window_type property is set to desktop or override, no mouse_events are being handled as making any changes to events root window listens to caused a crash while I was initially trying to get the code to work. This sadly means that users with some WMs/DEs won't be able to use mouse events at all (for instance me, bspwm). I also tested this on XFCE where all other mounting options worked fine (again, didn't modify the root window). On bspwm anything other than desktop and override make conky render as a window. Sudo didn't prevent crashing.
• I wasn't able to test mods scroll_up and scroll_down, they might represent 2 extra buttons on some mice but I believe scrolling is more likely as they're named the same as scrolling actions in Xlib docs. I don't have a mouse with 5 buttons, so I can't test it as scrolling is really hard to capture from my experience.

Screenshots

Sadly I haven't gotten into Cairo yet, so all of these are pretty technical.

Imgur post containing images below.

Errors you see in VSCode navigation are because my environment isn't configured, wouldn't be able to compile and run it if they were actual errors.

Lua script using all provided options

I used this script for the above images. I fixed it a bit here because the 'mods' section had the wrong indentation for first item (extra '\t').

function echo (what)
    os.execute("echo -n '" .. what .. "'")
end

local function print_mods (mods)
    echo("mods:\n")
    for k,v in pairs(mods) do
        if (v) then
            echo("\t- " .. k .. "\n")
        end
    end
end

function conky_mouse (event)
    if (event.type ~= "mouse_move") then
        echo("type: " .. event.type .. ",\n")
    end
    
    if (event.type == "button_down") then
        echo("x: " .. tostring(event.x) .. ", ")
        echo("y: " .. tostring(event.y) .. ", ")
        echo("x_abs: " .. tostring(event.x_abs) .. ", ")
        echo("y_abs: " .. tostring(event.y_abs) .. ",\n")
        echo("time: " .. tostring(event.time) .. ",\n")
        print_mods(event.mods)
        echo("button: " .. tostring(event.button) .. "\n")
    elseif (event.type == "button_up") then
        echo("x: " .. tostring(event.x) .. ", ")
        echo("y: " .. tostring(event.y) .. ", ")
        echo("x_abs: " .. tostring(event.x_abs) .. ", ")
        echo("y_abs: " .. tostring(event.y_abs) .. ",\n")
        echo("time: " .. tostring(event.time) .. "\n")
        print_mods(event.mods)
        echo("button: " .. tostring(event.button) .. "\n")
    elseif (event.type == "mouse_scroll") then
        echo("x: " .. tostring(event.x) .. ", ")
        echo("y: " .. tostring(event.y) .. ", ")
        echo("x_abs: " .. tostring(event.x_abs) .. ", ")
        echo("y_abs: " .. tostring(event.y_abs) .. ",\n")
        echo("time: " .. tostring(event.time) .. ",\n")
        print_mods(event.mods)
        echo("direction: " .. tostring(event.direction) .. "\n")
    elseif (event.type == "mouse_move") then
        -- This will spam out everything else
        echo("x: " .. tostring(event.x) .. ", ")
        echo("y: " .. tostring(event.y) .. ", ")
        echo("x_abs: " .. tostring(event.x_abs) .. ", ")
        echo("y_abs: " .. tostring(event.y_abs) .. ",\n")
        echo("time: " .. tostring(event.time) .. ",\n")
        print_mods(event.mods)
    elseif (event.type == "mouse_enter") then
        echo("x: " .. tostring(event.x) .. ", ")
        echo("y: " .. tostring(event.y) .. ", ")
        echo("x_abs: " .. tostring(event.x_abs) .. ", ")
        echo("y_abs: " .. tostring(event.y_abs) .. ",\n")
        echo("time: " .. tostring(event.time) .. "\n")
    elseif (event.type == "mouse_leave") then
        echo("x: " .. tostring(event.x) .. ", ")
        echo("y: " .. tostring(event.y) .. ", ")
        echo("x_abs: " .. tostring(event.x_abs) .. ", ")
        echo("y_abs: " .. tostring(event.y_abs) .. ",\n")
        echo("time: " .. tostring(event.time) .. "\n")
    elseif (event.type == "err") then
        echo("This currently can't happen.")
    end
    return false
end

Notes

I have a few additional thoughts and concerns:

• Mouse movement event is being called very frequently, I'm not familiar with Lua enough to know for sure whether this would slow conky down or not. This event should maybe be separated into it's own hook just so that users have the option of ignoring only that event. Or maybe a mask option can be provided to select exactly the events they want to receive. Other events don't really need to be controlled from C++ code as they aren't being called that often (on average even less than some of the other hooks).
• Keyboard events can easily be added in a similar fashion to these. Someone is likely to ask for those too. But they have the problem of requiring conky to capture ALL keyboard events, detect mouse position, query entire window tree form X, calculate where the mouse is and then finally handle them or pass them through to the appropriate window at which point conky becomes more like a WM than what it's supposed to be. I suggest they're not added.
• In screenshots above conky is being displayed over VSCode because it doesn't work on bspwm unless it's drawn on root window (which disables mouse events). I noticed it captures all events as a normal window and doesn't pass them through. Also, upon grabbing the pointer it also seems to grab the keyboard or something because I had to switch to another desktop and go back to be able to type anything into VSCode. SIGTERM keybind seemed to send it to VSCode, so I know it was focused. This might be a bug. Also, it's worth considering the possibility of drawing conky over the windows instead of below.