[Documentation]: add an example config for mouse events

[rubyFeedback]

Currently we have an explanation on the wiki how mouse events work and how to get them to work. This article can be found here:

https://github.com/brndnmtthws/conky/wiki/Mouse-Events

Now while it is great to have such an example, I don't want to copy/paste, fiddle around and then end up with things not working. I know ruby fairly well, but not lua, and I don't fully understand what I really should do.

Would it be possible to provide a small example for conky that is intrinsically complete, that is, works out of the box, where ideally these key-events are showcased? This can be super-simple, like a hello world, but just written in a way for people to:

a) just drop it and start it, as-is, without any modification

and

b) have it work for the basic stuff

I believe adding such a minimal example would be super-convenient for other users too; and ideally the wiki article could be expanded to point where this example could be found, perhaps under examples/ or config/ or some such.

I'd love to try this out, but after reading the wiki article, I still am not sure what to do. (I should also point out that it has been quite a long while since I last touched any config for conky, so this adds to my confusion; that's why I'd love a tabula rasa state in this way. Then I can understand how it should work, and adjust it, e. g. also answering things such as "how can I call a function or method in a specific file". Actually, can we even call executables via such actions? Would be nice if the example file could also show this, again, just a minimal example so we can learn the monkey-see-monkey-do way. Thanks for reading!

(Also, it would be nice if we could have generic MACROS so that we could avoid having to use lua, e. g. EXECUTE_FILE /usr/bin/funny_cats.rb - while that may look ugly, I would ideally like to avoid having to use lua altogether.)

[Caellian]

I mean, it could be added, but wiki is already pretty detailed on this and I've checked it several times (by using it after I forgot how to add them).

The original PR contains an example script (as noted in wiki) that uses all provided events with a function that executes echo from shell.

-- ~/.config/conky/conky.lua
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 my_event_handler (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

-- ~/.config/conky/conky.conf

conky.config = {
  -- other options...
  lua_load = "./conky.lua",
  lua_mouse_hook = 'my_event_handler'
}

As for macros, I'm strongly opposed to the idea because lua is far more powerful, will cause less issues, bugs and edge cases, and is just a tiny bit more complicated to use than macros would be. It's far simpler than ruby is if you're not going the OO route which it wasn't really designed for.

[github-actions[bot]]

This issue is stale because it has been open 365 days with no activity. Remove stale label or comment, or this issue will be closed in 30 days.

[Caellian]

not resolved yet