Built-in Hooks¶
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}")
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")
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")
client_killed()
Called after a client has been unmanaged
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")
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")
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}")
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}"
)
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.
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)
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"
)
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.")
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}")
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.")
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.")
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.")
group_window_add()
Called when a new window is added to a group
Arguments
* `Group` receiving the new window
* `Window` added to the group
Example:
from libqtile import hook
from libqtile.utils import send_notification
@hook.subscribe.group_window_add
def group_window_add(group, window):
send_notification("qtile", f"Window {window.name} added to {group.name}")
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}"
)
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")
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")
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...")
resume()
Called when system wakes up from sleep, suspend or hibernate.
Relies on systemd's inhibitor dbus interface, via the dbus-next package.
Note: the hook is not fired when resuming from shutdown/reboot events. Use the "startup" hooks for those scenarios.
Arguments
None
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.")
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.")
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."
)
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."
)
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")
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])
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")
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")
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])
suspend()
Called when system is about to sleep, suspend or hibernate.
Relies on systemd's inhibitor dbus interface, via the dbus-next 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")
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.