Idle events

Qtile supports idle events natively on both the X11 and Wayland backends. Custom actions can be triggered after a specified period of inactivity. In addition, users can define rules to prevent idle timers from activating (e.g. when a video player is fullscreened.).

The Wayland backend includes support for the ext_idle_notifier_v1 and zwp_idle_inhibit_manager_v1 protocols. This means clients like swayidle are supported by qtile.

Note

If an inhibitor prevents a timer from firing, the timer will not be fired if the inhibitor is removed and the system is still in an idle state. Similarly, a resume action will not be fired when exiting the idle state if there was an active inhibitor when the timeout period was completed.

Idle timers

Timers are defined in the idle_timers section of the config file. This should be a list of IdleTimer objects.

from libqtile.config import IdleTimer
from libqtile.lazy import lazy

idle_timers = [
   IdleTimer(300, action=lazy.spawn("/path/to/screen_dimmer.sh"), resume=lazy.spawn("/path/to/restore_screen.sh")),
   IdleTimer(900, action=lazy.spawn("/path/to/screen_off.sh"))
]

IdleTimer

class libqtile.config.IdleTimer(timeout: int, action: IdleAction = None, resume: IdleAction = None, respect_inhibitor: bool = True)

Creates a timer that will trigger an action when the system has been idle for a specified amount of time. An action can also be triggered when user input has been detected (NB this will only fire if the idle time is greater or equal to the specified timeout).

IdleNotifier takes the following arguments:

• timeout: (int) timeout in seconds

• action: (callable or LazyCall) the action to run when the timeout period is met (optional).

• resume: (callable or LazyCall) the action run when user input is detected (optional).

• respect_inhibitor: (boolean) whether the action should be fired if there is an active idle inhibitor

  (default True).

action and resume can also take coroutines so that the actions are run asynchronously.

At least one of action and resume must be set.

Idle inhibitors

An active idle inhibitor will prevent a timer action being triggered. Users can define rules for inhibitors in the idle_inhibitors section of the config file. This is a list of IdleInhibitor objects. Each inhibitor defines a Match to check whether the rule should apply to a window. There is also a setting to determine what state the window must be in to activate the inhibitor.

from libqtile.config import IdleInhibitor, Match
from libqtile.lazy import lazy

idle_inhibitors = [
   IdleInhibitor(match=Match(wm_class="vlc"), when="fullscreen"),
]

IdleInhibitor

class libqtile.config.IdleInhibitor(match: _Match | None = None, when: Literal['focus' | 'fullscreen' | 'visible' | 'open'] = 'open')

Create rules for when the compositor should not go into an idle state.

IdleInhibitor take two arguments:

• match: a Match object to define which windows the rule should apply to. If unset, it will apply to all windows.

  Note: qtile evaluates whether a rule matches a window once, when the window is first created.

• when: one of the following strings:

• "focus" (default): Inhibitor is active when the matching window is the currently focused window

• "fullscreen": Inhibitor is active when the matching window is fullscreen

• "visible": Inhibitor is active when the matching window is visible on any screen

  (still applies if window is completely covered by a floating window)

• "open": Inhibitor is active when the matching window is open (even if hidden)