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, conky_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 conky_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 or 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.

Additionally, event.button_code field provides numeric event codes of pressed buttons which allows checking for other mouse buttons, though buttons other than the ones listed in this section 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

These values depend on xkb configuration, they're assuming the defaults, but those can be changed.

On Wayland this table is always empty as Wayland doesn't provide modifier key information with events and they require special handling.

Movement delta

Mouse move events also have a move_delta, and move_delta_x, move_delta_y values which contain information about movement delta. (NYI)

Scroll information

When the event.type is button_scroll, a direction field is provided in the event table.

The value of the direction can be one of following strings: up, down, left or right.
Scroll events also have a scroll_delta, and scroll_delta_x, scroll_delta_y values which contain information about scroll amount and direction. (NYI)

NOTE: Scroll delta is always in range -1 to 1 if BUILD_XINPUT is disabled.

Fixing quirks

X11

On X11, some devices might have unexpected valuator indices or produce incorrect information about whether motion events are relative or absolute.

The first manifests as cursor motion behaving as if it were scroll, and vice versa. This can be fixed by setting conky specific xinput properties for that device:

xinput set-prop "My Mouse Device" --type=atom "ConkyValuatorMoveX" "0"
xinput set-prop "My Mouse Device" --type=atom "ConkyValuatorMoveY" "1"
xinput set-prop "My Mouse Device" --type=atom "ConkyValuatorScrollX" "2"
xinput set-prop "My Mouse Device" --type=atom "ConkyValuatorScrollY" "3"

To find your device name or id number (id is easier to use), use xinput list command. To figure out correct valuator indices, use xinput list "My Mouse Device" command and check the valuator names. Movement valuators are commonly labeled "Rel X" and "Rel Y", while scroll ones are called "Rel Horiz Scroll" and "Rel Vert Scroll". Those labels might be different for your device. If you're not sure (or the labels are blank/missing), you can use xinput test-xi2 command and observe generated events when you move your cursor and scroll for information. Note that scroll events also generate button events (backwards compatibility reasons), so you might need to check last 3/4 events.

The second issue manifests as forwarding behaving as if you're constantly scrolling the same direction, and (more clearly) reported event values being wrong. To fix this, set the following properties:

xinput set-prop "My Mouse Device" --type=atom "ConkyValuatorScrollMode" "relative"   
xinput set-prop "My Mouse Device" --type=atom "ConkyValuatorMoveMode" "relative"

You can add those commands to your .xinitrc file in order to make them persist between sessions.

Implementation differences

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

X11

If BUILD_XINPUT flag is disabled and own_window_type is "desktop", mouse events won't be reported by conky.

BUILD_XINPUT build flag is required (which requires libXi) for better mouse_enter & mouse_leave event tracking at the cost of additional CPU usage as it's processing mouse events outside conky as well (and manually checking for cursor overlap).

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 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.