Mouse Events

Mouse Events

Conky has support for handling mouse events when compiled with BUILD_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 containing name of pressed mouse button.

Value of event.button can be:

• left
• right
• middle
• back
• forward

middle button corresponds to mouse wheel press. back and forward are buttons present on some mice that allow quick browser navigation.

event.button_code field provides numeric event codes of pressed buttons which allows checking for other mouse buttons, though they won't be reported in X11.

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.

The following modifiers are supported by X11:

• shift - Shift
• control - Ctrl
• super - ⊞ Win or ⌘ Cmd
• caps_lock - Caps Lock
• num_lock - Num Lock

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.

On Wayland this table is always empty as Wayland doesn't provide modifier key information with events and they have to be handled separately.

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 is false or 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).

Enabling BUILD_XINPUT (which requires libXi) provides much better cursor tracking at the cost of additional CPU usage as it's processing mouse events outside conky as well.

Mouse buttons are limited to the ones described in mouse button section. Reported event codes are inferred from system files so their accuracy is worse than named values (though they should be correctly mapped).

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) and keyboard state managed by the application. Keyboard modifiers on X11 are already contained in mouse events, on Wayland that requires special handling.

Wayland provides event codes for mouse buttons. Reported names are inferred from system files so their accuracy is worse than event codes (though they should be correctly mapped). event.button will be nil for buttons other than the ones listed here - if your mouse has more buttons you can use event.button_code to check for them.