## 16 Hooks ¶

StumpWM exports a number of hooks you can use to add customizations; like hooks in Emacs, you add to a hook with the `add-hook` function. For example:

    (stumpwm:add-hook 'stumpwm:*new-window-hook* 'my-new-window-custos)

adds your `my-new-window-custos` function to the list of functions called when a new window appears.

Macro: add-hook hook fn ¶

  Add function to the hook-variable. For example, to display a message whenever you switch frames:

      (defun my-rad-fn (to-frame from-frame)
        (stumpwm:message "Mustard!"))

      (stumpwm:add-hook stumpwm:*focus-frame-hook* 'my-rad-fn)

Macro: remove-hook hook fn ¶

  Remove the specified function from the hook.

Macro: remove-all-hooks hook ¶

  Remove all functions from a hook

Function: run-hook hook ¶

  Call each function in HOOK.

Function: run-hook-with-args hook &rest args ¶

  Call each function in HOOK and pass args to it.

The following hooks are available:

Hook: *new-window-hook* ¶

  A hook called whenever a window is added to the window list. This includes a genuinely new window as well as bringing a withdrawn window back into the window list. Called with the window as an argument.

Hook: *destroy-window-hook* ¶

  A hook called whenever a window is destroyed or withdrawn. Called with the window as an argument.

Hook: *focus-window-hook* ¶

  A hook called when a window is given focus. It is called with 2 arguments: the current window and the last window (could be nil).

Hook: *place-window-hook* ¶

  A hook called whenever a window is placed by rule. Arguments are window, group and frame.

Hook: *start-hook* ¶

  A hook called when stumpwm starts.

Hook: *internal-loop-hook* ¶

  A hook called inside stumpwm’s inner loop.

Hook: *focus-frame-hook* ¶

  A hook called when a frame is given focus. The hook functions are called with 2 arguments: the current frame and the last frame.

Hook: *new-frame-hook* ¶

  A hook called when a new frame is created. The hook is called with the frame as an argument.

Hook: *message-hook* ¶

  A hook called whenever stumpwm displays a message. The hook function is passed any number of arguments. Each argument is a line of text.

Hook: *top-level-error-hook* ¶

  Called when a top level error occurs. Note that this hook is run before the error is dealt with according to *top-level-error-action*.

Hook: *focus-group-hook* ¶

  A hook called whenever stumpwm switches groups. It is called with 2 arguments: the current group and the last group.

Hook: *hooks-enabled-p* ¶

  Controls whether hooks will actually run or not

Hook: *remove-split-hook* ¶

  A hook called when a split is removed. the hook is called with the current frame and removed frame as arguments.

Hook: *key-press-hook* ¶

  A hook called whenever a key under *top-map* is pressed. It is called with 3 argument: the key, the (possibly incomplete) key sequence it is a part of, and command value bound to the key.

Hook: *root-click-hook* ¶

  A hook called whenever there is a mouse click on the root window. Called with 4 arguments, the screen containing the root window, the button clicked, and the x and y of the pointer.

Hook: *click-hook* ¶

  A hook called whenever there is a mouse click. Called with 4 arguments, the screen containing the window (or nil if there isn’t one), the button clicked, and the x and y of the pointer.

Hook: *mode-line-click-hook* ¶

  Called whenever the mode-line is clicked. It is called with 4 arguments, the mode-line, the button clicked, and the x and y of the pointer.

Hook: *urgent-window-hook* ¶

  A hook called whenever a window sets the property indicating that it demands the user’s attention. Called with the window as an argument.

Hook: *event-processing-hook* ¶

  A hook called inside stumpwm’s inner loop, before the default event processing takes place. This hook is run inside (with-event-queue ...).

Hook: *pre-command-hook* ¶

  Called before a command is called. It is called with 1 argument: the command as a symbol.

Hook: *post-command-hook* ¶

  Called after a command is called. It is called with 1 argument: the command as a symbol.

Hook: *menu-selection-hook* ¶

  Called after an item is selected in the windows menu. It is called with 1 argument: the menu.

Hook: *new-head-hook* ¶

  A hook called whenever a head is added. It is called with 2 arguments: the new head and the current screen.

Hook: *command-mode-end-hook* ¶

  A hook called whenever command mode is ended.

Hook: *command-mode-start-hook* ¶

  A hook called whenever command mode is started.

Hook: *destroy-mode-line-hook* ¶

  Called whenever the mode-line is destroyed. It is called with argument, the mode-line

Hook: *quit-hook* ¶

  A hook called when stumpwm quits.

Hook: *restart-hook* ¶

  A hook called when stumpwm restarts.

Hook: *selection-notify-hook* ¶

  Called after a :selection-notify event is processed. It is called with 1 argument: the selection as a string.

Hook: *split-frame-hook* ¶

  A hook called when a frame is split. the hook is called with the old frame (window is removed), and two new frames as arguments.