Built-in Hooks

subscribe.addgroup()

Called when a new group is added

Arguments

name of new group

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.addgroup
def group_added(group_name):
    send_notification("qtile", f"New group added: {group_name}")

subscribe.changegroup()

Called whenever a group change occurs.

The following changes will result in this hook being fired: 1) New group added (unlike addgroup, no group name is passed with this hook) 2) Group deleted (unlike delgroup, no group name is passed with this hook) 3) Groups order is changed 4) Group is renamed

Arguments

None

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.changegroup
def change_group():
    send_notification("qtile", "Change group event")

subscribe.client_focus()

Called whenever focus moves to a client window

Arguments

Window object of the new focus.

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.client_focus
def client_focus(client):
    send_notification("qtile", f"{client.name} has been focused")

subscribe.client_killed()

Called after a client has been unmanaged. This hook is not called for internal windows.

Arguments

Window object of the killed window.

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.client_killed
def client_killed(client):
    send_notification("qtile", f"{client.name} has been killed")

subscribe.client_managed()

Called after Qtile starts managing a new client

Called after a window is assigned to a group, or when a window is made static. This hook is not called for internal windows.

Arguments

Window object of the managed window

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.client_managed
def client_managed(client):
    send_notification("qtile", f"{client.name} has been managed by qtile")

subscribe.client_mouse_enter()

Called when the mouse enters a client

Arguments

Window of window entered

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.client_mouse_enter
def client_mouse_enter(client):
    send_notification("qtile", f"Mouse has entered {client.name}")

subscribe.client_name_updated()

Called when the client name changes

Arguments

Window of client with updated name

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.client_name_updated
def client_name_updated(client):
    send_notification(
        "qtile",
        f"Client's has been updated to {client.name}"
    )

subscribe.client_new()

Called before Qtile starts managing a new client

Use this hook to declare windows static, or add them to a group on startup. This hook is not called for internal windows. Use group_window_add for focus decisions.

Arguments

Window object

Example:

from libqtile import hook

@hook.subscribe.client_new
def new_client(client):
    if client.name == "xterm":
        client.togroup("a")
    elif client.name == "dzen":
        client.static(0)

subscribe.client_urgent_hint_changed()

Called when the client urgent hint changes

Arguments

Window of client with hint change

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.client_urgent_hint_changed
def client_urgency_change(client):
    send_notification(
        "qtile",
        f"{client.name} has changed its urgency state"
    )

subscribe.current_screen_change()

Called when the current screen (i.e. the screen with focus) changes

Arguments

None

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.current_screen_change
def screen_change():
    send_notification("qtile", "Current screen change detected.")

subscribe.delgroup()

Called when group is deleted

Arguments

name of deleted group

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.delgroup
def group_deleted(group_name):
    send_notification("qtile", f"Group deleted: {group_name}")

subscribe.enter_chord()

Called when key chord begins

Note: if you only want to use this chord to display the chord name then you should use the Chord widget.

Arguments

name of chord(mode)

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.enter_chord
def enter_chord(chord_name):
    send_notification("qtile", "Started {chord_name} key chord.")

subscribe.float_change()

Called when a change in float state is made (e.g. toggle floating, minimised and fullscreen states)

Arguments

None

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.float_change
def float_change():
    send_notification("qtile", "Window float state changed.")

subscribe.focus_change()

Called when focus is changed, including moving focus between groups or when focus is lost completely (i.e. when a window is closed.)

Arguments

None

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.focus_change
def focus_changed():
    send_notification("qtile", "Focus changed.")

subscribe.group_window_add()

Called when a new window is added to a group

This hook can for example be used for focus decisions.

Arguments

Group receiving the new window

Window added to the group

Example:

from libqtile import hook
from libqtile import qtile

@hook.subscribe.group_window_add
def group_window_add(group, window):
    #disallow focus steals except if there's no focus
    if not qtile.current_window:
        return
    window.can_steal_focus = False

subscribe.group_window_remove()

Called when a window is removed from a group

Arguments

Group removing the window

Window removed from the group

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.group_window_remove
def group_window_remove(group, window):
    send_notification("qtile", f"Window {window.name} removed from {group.name}")

subscribe.layout_change()

Called on layout change event (including when a new group is displayed on the screen)

Arguments

layout object for new layout

group object on which layout is changed

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.layout_change
def layout_change(layout, group):
    send_notification(
        "qtile",
        f"{layout.name} is now on group {group.name}"
    )

subscribe.leave_chord()

Called when key chord ends

Arguments

None

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.leave_chord
ded leave_chord():
    send_notification("qtile", "Key chord exited")

subscribe.net_wm_icon_change()

Called on _NET_WM_ICON change

X11 only. Called when a window notifies that it has changed its icon.

Arguments

Window of client with changed icon

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.net_wm_icon_change
def icon_change(client):
    send_notification("qtile", f"{client.name} has changed its icon")

subscribe.plasma_add_mode()

Used to flag when the add mode of the Plasma layout has changed.

The hooked function should take one argument being the layout object.

subscribe.restart()

Called before qtile is restarted.

This hook fires before qtile restarts but after qtile has checked that it is able to restart (i.e. the config file is valid).

Arguments

None

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.restart
def run_every_startup():
    send_notification("qtile", "Restarting...")

subscribe.resume()

Called when system wakes up from sleep, suspend or hibernate.

Relies on systemd's inhibitor dbus interface, via the dbus-fast package.

Note: the hook is not fired when resuming from shutdown/reboot events. Use the "startup" hooks for those scenarios.

Arguments

None

subscribe.screen_change()

Called when the output configuration is changed (e.g. via randr in X11).

Note

If you have reconfigure_screens = True in your config then qtile will automatically reconfigure your screens when it detects a change to the screen configuration. This hook is fired before that reconfiguration takes place. The screens_reconfigured hook should be used where you want to trigger an event after the reconfiguration.

Arguments

xproto.randr.ScreenChangeNotify event (X11) or None (Wayland).

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.screen_change
def screen_change(event):
    send_notification("qtile", "Screen change detected.")

subscribe.screens_reconfigured()

Called once qtile.reconfigure_screens has completed (e.g. if reconfigure_screens is set to True in your config).

Arguments

None

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.screens_reconfigured
def screen_reconf():
    send_notification("qtile", "Screens have been reconfigured.")

subscribe.selection_change()

Called on selection change

X11 only. Fired when a selection property is changed (e.g. new selection created or existing selection is emptied)

Arguments

name of the selection

dictionary describing selection, containing owner and selection as keys

The selection owner will typically be "PRIMARY" when contents is highlighted and "CLIPBOARD" when contents is actively copied to the clipboard, e.g. with Ctrl + C.

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.selection_change
def selection_change(name, selection):
    send_notification(
        "qtile",
        f"Window {selection['owner']} has changed the {name} selection."
    )

subscribe.selection_notify()

Called on selection notify

X11 only. Fired when a selection is made in a window.

Arguments

name of the selection

dictionary describing selection, containing owner and selection as keys

The selection owner will typically be "PRIMARY" when contents is highlighted and "CLIPBOARD" when contents is actively copied to the clipboard, e.g. with Ctrl + C.

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.selection_notify
def selection_notify(name, selection):
    send_notification(
        "qtile",
        f"Window {selection['owner']} has made a selection in the {name} selection."
    )

subscribe.setgroup()

Called when group is put on screen.

This hook is fired in 3 situations: 1) When the screen changes to a new group 2) When two groups are switched 3) When a screen is focused

Arguments

None

Example:

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.setgroup
def setgroup():
    send_notification("qtile", "Group set")

subscribe.shutdown()

Called before qtile is shutdown.

Using a long-running command in this function will cause the shutdown to be delayed.

This hook is only fired when qtile is shutting down, if you want a command to be run when the system sleeps then you should use the suspend hook instead.

Arguments

None

Example:

import os
import subprocess

from libqtile import hook

@hook.subscribe.shutdown
def autostart:
    script = os.path.expanduser("~/.config/qtile/shutdown.sh")
    subprocess.run([script])

subscribe.startup()

Called when qtile is started. Unlike startup_once, this hook is fired on every start, including restarts.

When restarting, this hook is fired after qtile has restarted but before qtile tries to restore the session to the same state that it was in before the restart.

Arguments

None

Example:

import subprocess

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.startup
def run_every_startup():
    send_notification("qtile", "Startup")

subscribe.startup_complete()

Called when qtile is started after all resources initialized.

This is the same as startup with the only difference being that this hook is fired after the saved state has been restored.

Arguments

None

Example:

import subprocess

from libqtile import hook
from libqtile.utils import send_notification

@hook.subscribe.startup_complete
def run_every_startup():
    send_notification("qtile", "Startup complete")

subscribe.startup_once()

Called when Qtile has started on first start

This hook is called exactly once per session (i.e. not on each lazy.restart()).

Arguments

None

Example:

import os
import subprocess

from libqtile import hook

@hook.subscribe.startup_once
def autostart():
    script = os.path.expanduser("~/.config/qtile/autostart.sh")
    subprocess.run([script])

subscribe.suspend()

Called when system is about to sleep, suspend or hibernate.

Relies on systemd's inhibitor dbus interface, via the dbus-fast package.

When this hook is used, qtile will set an inhibitor that prevent the system from sleeping. The inhibitor is removed as soon as your function exits. You should therefore not use long-running code in this function.

Please note, this inhibitor will also only delay, not block, the computer's ability to sleep. The default delay is 5 seconds. If your function has not completed within that time, the machine will still sleep (see important note below).

You can increase this delay by setting InhibitDelayMaxSec in logind.conf. see: https://www.freedesktop.org/software/systemd/man/logind.conf.html

In addition, closing a laptop lid will ignore inhibitors by default. You can override this by setting LidSwitchIgnoreInhibited=no in /etc/systemd/logind.conf.

Important

The logind service creates an inhibitor by passing a reference to a lock file which must be closed to release the lock. Additional references to the lock may be created if you spawn processes with the subprocess module and these processes are running when the machine tries to suspend. As a result, it is strongly recommended that you launch any processes with qtile.spawn(...) as this will not create additional copies of the lock.

Arguments

None

Example:

from libqtile import hook, qtile

@hook.subscribe.suspend
def lock_on_sleep():
    # Run screen locker
    qtile.spawn("/path/to/screen_locker")

subscribe.user()

Use to create user-defined hooks.

The purpose of these hooks is to allow a hook to be fired by an external application.

Hooked functions can receive arguments but it is up to the application firing the hook to ensure the correct arguments are passed. No checking will be performed by qtile.

Example:

from libqtile import hook
from libqtile.log_utils import logger

@hook.subscribe.user("my_custom_hook")
def hooked_function():
  logger.warning("Custom hook received.")

The external script can then call the hook with the following command:

qtile cmd-obj -o cmd -f fire_user_hook -a my_custom_hook

Note

If the script will be run by a different user then you will need to pass the path to the socket file used by the current process. One way to achieve this is to specify a path for the socket when starting qtile e.g. qtile start -s /tmp/qtile.socket. When firing the hook, you should then call qtile cmd-obj -o cmd -f fire_user_hook -a my_custom_hook -s /tmp/qtile.socket However, the same socket will need to be passed wherever you run qtile cmd-obj or qtile shell.