Mouse Events

Mouse Events

Conky has support for handling mouse events when compiled with MOUSE_EVENTS option. Given the nature of the feature, support varies between X11 and Wayland implementations (see differences).

In order to use the mouse events, add a lua_mouse_hook to your conky.conf file:

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

In the example above, my_event_handler is a name of a function that will receive mouse event information. The hook function should take in a single parameter (a table containing event information), and return a boolean to tell conky whether the event was consumed.

A minimal example of how it should look is:

-- ~/.config/conky/conky.lua
function my_event_handler(event)
  return false
end

NOTE: The hook should be defined in lua file specified by the lua_load property.

This hook will get called for all mouse events and the event table will contain all information about the event that was captured. An example of a hook that prints out all the event information can be found in the original PR. The first argument doesn't have to be called event (only position matters) but this article will refer to it as event for consistency and brevity.

Mouse event table

Event table will always contain a type field to indicate the type of event that was captured. Following events types are supported:

• button_down - called when a mouse button is clicked
• button_up - called when a mouse button is released
• button_scroll - called on scroll action
• mouse_move - called when the pointer is being moved over conky window (or background)
• mouse_enter - called when the pointer enters conky window
• mouse_leave - called when the pointer leaves conky window

If your hook function is long and performs a lot of work, consider returning early for the event types you don't need. The hook will be called a lot of times as mouse_move events are triggered for very small movements (few pixels).

Based on the event type, the event can contain multiple other fields which are noted in the following sections. If you're handling a lot of different events in different manner, it might be convenient to separate each into a function and then call the appropriate function from the hook.

Common fields

These event fields are common to all events.

• x - window-relative cursor x position
• y - window-relative cursor y position
• x_abs - display-relative cursor x position
• y_abs - display-relative cursor y position
• time - milliseconds since epoch

Mouse button

When the event.type is button_down, button_up, the event table contains a button field indicating which mouse button was pressed.

Value of event.button is input library dependent, but common values are:

• Left button: 1
• Right button: 2
• Middle button: 3

You'll have to test out your own specific build and hardware configuration if you'd like to use other button keys.

Modifiers

When the event.type is button_down, button_up or button_scroll, the event table contains a mods entry which is a nested table containing information on held down modifier buttons (e.g. Ctrl, Shift).

The following modifiers are supported by X11:

• shift - Shift
• lock
• control - Ctrl
• mod1 - ⊞ Win or ⌘ Cmd
• num_lock - Num Lock
• mod3
• mod4
• mod5
• mouse_left - indicates the left mouse button is held (as well)
• mouse_right - indicates the right mouse button is held (as well)
• mouse_middle - indicates the middle mouse button (scroll wheel) is held (as well)
• scroll_up - indicates upward scroll direction
• scroll_down - indicates downward scroll direction

NOTE: Some modifier keys aren't annotated as there's no documentation specifying their meaning/purpose or how they map to the keyboard. Feel free to improve this section if you know what they are.

Scroll direction

When the event.type is button_scroll, a direction field is provided in the event table. The value of the direction is either an up or down string indicating corresponding scroll direction.

NOTE: There's no scroll delta as scroll distance isn't supported by Xorg. Handle scroll amount manually.

Computing movement delta for mouse_move

Movement delta computation isn't handled by conky, but it can be done by declaring a previous position variable in your configuration and then computing the distance between previous event.x/event.y and the current.

Implementation differences

This section describes differences in how mouse events behave between different backends.

X11

When own_window_type is "desktop", mouse events won't be reported by conky as trying to listen for them on desktop causes a crash on most WMs because only one X11 client can listen for ButtonPress events. Use any other window type that works well for your WM (see Window Configuration section).

Wayland

Keyboard modifiers aren't reported by the Wayland implementation. This is due to the fact that in order to support that feature, keyboard events have to be fully processed (including keyboard layouts). Keyboard modifiers on X11 are already contained in mouse events, on Wayland that requires special handling.