Built-in Hooks

subscribe.addgroup(func)

Called when group is added

Arguments

  • name of new group

subscribe.changegroup(func)

Called whenever a group change occurs

Arguments

None

subscribe.client_focus(func)

Called whenever focus moves to a client window

Arguments

  • Window object of the new focus.

subscribe.client_killed(func)

Called after a client has been unmanaged

Arguments

  • Window object of the killed window.

subscribe.client_managed(func)

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

subscribe.client_mouse_enter(func)

Called when the mouse enters a client

Arguments

  • Window of window entered

subscribe.client_name_updated(func)

Called when the client name changes

Arguments

  • Window of client with updated name

subscribe.client_new(func)

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

Examples

@libqtile.hook.subscribe.client_new
def func(c):
    if c.name == "xterm":
        c.togroup("a")
    elif c.name == "dzen":
        c.static(0)
subscribe.client_urgent_hint_changed(func)

Called when the client urgent hint changes

Arguments

  • Window of client with hint change

subscribe.current_screen_change(func)

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

Arguments

None

subscribe.delgroup(func)

Called when group is deleted

Arguments

  • name of deleted group

subscribe.enter_chord(func)

Called when key chord begins

Arguments

  • name of chord(mode)

subscribe.float_change(func)

Called when a change in float state is made

Arguments

None

subscribe.focus_change(func)

Called when focus is changed, including moving focus between groups or when focus is lost completely

Arguments

None

subscribe.group_window_add(func)

Called when a new window is added to a group

Arguments

  • Group receiving the new window

  • Window added to the group

subscribe.layout_change(func)

Called on layout change

Arguments

  • layout object for new layout

  • group object on which layout is changed

subscribe.leave_chord(func)

Called when key chord ends

Arguments

None

subscribe.net_wm_icon_change(func)

Called on _NET_WM_ICON chance

Arguments

  • Window of client with changed icon

subscribe.restart(func)

Called before qtile is restarted

Arguments

None

subscribe.resume(func)

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

subscribe.screen_change(func)

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

Arguments

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

subscribe.screens_reconfigured(func)

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

Arguments

None

subscribe.selection_change(func)

Called on selection change

Arguments

  • name of the selection

  • dictionary describing selection, containing owner and selection as keys

subscribe.selection_notify(func)

Called on selection notify

Arguments

  • name of the selection

  • dictionary describing selection, containing owner and selection as keys

subscribe.setgroup(func)

Called when group is changed

Arguments

None

subscribe.shutdown(func)

Called before qtile is shutdown

Arguments

None

subscribe.startup(func)

Called when qtile is started

Arguments

None

subscribe.startup_complete(func)

Called when qtile is started after all resources initialized

Arguments

None

subscribe.startup_once(func)

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