doc/lispref/hooks.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Emacs Lisp Reference Manual.
   3 @c Copyright (C) 1990-1993, 1998, 2001-2018 Free Software Foundation,
   4 @c Inc.
   5 @c See the file elisp.texi for copying conditions.
   6 @node Standard Hooks
   7 @appendix Standard Hooks
   8 @cindex standard hooks
   9 @cindex hook variables, list of
  10
  11 The following is a list of some hook variables that let you provide
  12 functions to be called from within Emacs on suitable occasions.
  13
  14 Most of these variables have names ending with @samp{-hook}.  They are
  15 @dfn{normal hooks}, run by means of @code{run-hooks}.  The value of such
  16 a hook is a list of functions; the functions are called with no
  17 arguments and their values are completely ignored.  The recommended way
  18 to put a new function on such a hook is to call @code{add-hook}.
  19 @xref{Hooks}, for more information about using hooks.
  20
  21 The variables whose names end in @samp{-functions} are usually @dfn{abnormal
  22 hooks} (some old code may also use the deprecated @samp{-hooks} suffix); their
  23 values are lists of functions, but these functions are called in a special way
  24 (they are passed arguments, or their return values are used).  The variables
  25 whose names end in @samp{-function} have single functions as their values.
  26
  27 This is not an exhaustive list, it only covers the more general hooks.
  28 For example, every major mode defines a hook named
  29 @samp{@var{modename}-mode-hook}.  The major mode command runs this
  30 normal hook with @code{run-mode-hooks} as the very last thing it does.
  31 @xref{Mode Hooks}.  Most minor modes have mode hooks too.
  32
  33 A special feature allows you to specify expressions to evaluate if and
  34 when a file is loaded (@pxref{Hooks for Loading}).  That feature is
  35 not exactly a hook, but does a similar job.
  36
  37 @c We need to xref to where each hook is documented or else document it here.
  38 @c Add vindex for anything not indexed elsewhere.
  39 @c This list is in alphabetical order, grouped by topic.
  40 @c TODO It should probably be more thoroughly ordered by topic.
  41
  42 @table @code
  43 @item activate-mark-hook
  44 @itemx deactivate-mark-hook
  45 @xref{The Mark}.
  46
  47 @item after-change-functions
  48 @itemx before-change-functions
  49 @itemx first-change-hook
  50 @xref{Change Hooks}.
  51
  52 @item after-change-major-mode-hook
  53 @itemx change-major-mode-after-body-hook
  54 @xref{Mode Hooks}.
  55
  56 @item after-init-hook
  57 @itemx before-init-hook
  58 @itemx emacs-startup-hook
  59 @itemx window-setup-hook
  60 @xref{Init File}.
  61
  62 @item after-insert-file-functions
  63 @itemx write-region-annotate-functions
  64 @itemx write-region-post-annotation-function
  65 @xref{Format Conversion}.
  66
  67 @item after-make-frame-functions
  68 @itemx before-make-frame-hook
  69 @xref{Creating Frames}.
  70
  71 @c Not general enough?
  72 @ignore
  73 @item after-revert-hook
  74 @itemx before-revert-hook
  75 @itemx buffer-stale-function
  76 @itemx revert-buffer-function
  77 @itemx revert-buffer-insert-file-contents-function
  78 @xref{Reverting}.
  79 @end ignore
  80
  81 @item after-save-hook
  82 @itemx before-save-hook
  83 @itemx write-contents-functions
  84 @itemx write-file-functions
  85 @xref{Saving Buffers}.
  86
  87 @item after-setting-font-hook
  88 @vindex after-setting-font-hook
  89 Hook run after a frame's font changes.
  90
  91 @item auto-save-hook
  92 @xref{Auto-Saving}.
  93
  94 @item before-hack-local-variables-hook
  95 @itemx hack-local-variables-hook
  96 @xref{File Local Variables}.
  97
  98 @item buffer-access-fontify-functions
  99 @xref{Lazy Properties}.
 100
 101 @item buffer-list-update-hook
 102 @vindex buffer-list-update-hook
 103 Hook run when the buffer list changes (@pxref{Buffer List}).
 104
 105 @item buffer-quit-function
 106 @vindex buffer-quit-function
 107 Function to call to quit the current buffer.
 108
 109 @item change-major-mode-hook
 110 @xref{Creating Buffer-Local}.
 111
 112 @item command-line-functions
 113 @xref{Command-Line Arguments}.
 114
 115 @item delayed-warnings-hook
 116 @vindex delayed-warnings-hook
 117 The command loop runs this soon after @code{post-command-hook} (q.v.).
 118
 119 @item focus-in-hook
 120 @vindex focus-in-hook
 121 @itemx focus-out-hook
 122 @vindex focus-out-hook
 123 @xref{Input Focus}.
 124
 125 @item delete-frame-functions
 126 @xref{Deleting Frames}.
 127
 128 @item delete-terminal-functions
 129 @xref{Multiple Terminals}.
 130
 131 @item pop-up-frame-function
 132 @itemx split-window-preferred-function
 133 @xref{Choosing Window Options}.
 134
 135 @item echo-area-clear-hook
 136 @xref{Echo Area Customization}.
 137
 138 @item find-file-hook
 139 @itemx find-file-not-found-functions
 140 @xref{Visiting Functions}.
 141
 142 @item font-lock-extend-after-change-region-function
 143 @xref{Region to Refontify}.
 144
 145 @item font-lock-extend-region-functions
 146 @xref{Multiline Font Lock}.
 147
 148 @item font-lock-fontify-buffer-function
 149 @itemx font-lock-fontify-region-function
 150 @itemx font-lock-mark-block-function
 151 @itemx font-lock-unfontify-buffer-function
 152 @itemx font-lock-unfontify-region-function
 153 @xref{Other Font Lock Variables}.
 154
 155 @item fontification-functions
 156 @xref{Auto Faces,, Automatic Face Assignment}.
 157
 158 @item frame-auto-hide-function
 159 @xref{Quitting Windows}.
 160
 161 @item kill-buffer-hook
 162 @itemx kill-buffer-query-functions
 163 @xref{Killing Buffers}.
 164
 165 @item kill-emacs-hook
 166 @itemx kill-emacs-query-functions
 167 @xref{Killing Emacs}.
 168
 169 @item menu-bar-update-hook
 170 @xref{Menu Bar}.
 171
 172 @item minibuffer-setup-hook
 173 @itemx minibuffer-exit-hook
 174 @xref{Minibuffer Misc}.
 175
 176 @item mouse-leave-buffer-hook
 177 @vindex mouse-leave-buffer-hook
 178 Hook run when about to switch windows with a mouse command.
 179
 180 @item mouse-position-function
 181 @xref{Mouse Position}.
 182
 183 @item prefix-command-echo-keystrokes-functions
 184 @vindex prefix-command-echo-keystrokes-functions
 185 An abnormal hook run by prefix commands (such as @kbd{C-u}) which
 186 should return a string describing the current prefix state.  For
 187 example, @kbd{C-u} produces @samp{C-u-} and @samp{C-u 1 2 3-}.  Each
 188 hook function is called with no arguments and should return a string
 189 describing the current prefix state, or @code{nil} if there's no
 190 prefix state.  @xref{Prefix Command Arguments}.
 191
 192 @item prefix-command-preserve-state-hook
 193 @vindex prefix-command-preserve-state-hook
 194 Hook run when a prefix command needs to preserve the prefix by passing
 195 the current prefix command state to the next command.  For example,
 196 @kbd{C-u} needs to pass the state to the next command when the user
 197 types @kbd{C-u -} or follows @kbd{C-u} with a digit.
 198
 199 @item pre-redisplay-functions
 200 Hook run in each window just before redisplaying it.  @xref{Forcing
 201 Redisplay}.
 202
 203 @item post-command-hook
 204 @itemx pre-command-hook
 205 @xref{Command Overview}.
 206
 207 @item post-gc-hook
 208 @xref{Garbage Collection}.
 209
 210 @item post-self-insert-hook
 211 @xref{Keymaps and Minor Modes}.
 212
 213 @ignore
 214 @item prog-mode-hook
 215 @itemx special-mode-hook
 216 @vindex special-mode-hook
 217 @xref{Basic Major Modes}.
 218 @end ignore
 219
 220 @item suspend-hook
 221 @itemx suspend-resume-hook
 222 @itemx suspend-tty-functions
 223 @itemx resume-tty-functions
 224 @xref{Suspending Emacs}.
 225
 226 @item syntax-begin-function
 227 @itemx syntax-propertize-extend-region-functions
 228 @itemx syntax-propertize-function
 229 @itemx font-lock-syntactic-face-function
 230 @xref{Syntactic Font Lock}.  @xref{Syntax Properties}.
 231
 232 @item temp-buffer-setup-hook
 233 @itemx temp-buffer-show-function
 234 @itemx temp-buffer-show-hook
 235 @xref{Temporary Displays}.
 236
 237 @item tty-setup-hook
 238 @xref{Terminal-Specific}.
 239
 240 @item window-configuration-change-hook
 241 @itemx window-scroll-functions
 242 @itemx window-size-change-functions
 243 @xref{Window Hooks}.
 244 @end table
 245
 246 @ignore
 247 Some -hook, -function, -functions from preloaded Lisp or C files that
 248 I thought did not need to be mentioned here:
 249
 250 Lisp:
 251 after-load-functions
 252 auto-coding-functions
 253 choose-completion-string-functions
 254 completing-read-function
 255 completion-annotate-function
 256 completion-at-point-functions
 257 completion-list-insert-choice-function
 258 deactivate-current-input-method-function
 259 describe-current-input-method-function
 260 font-lock-function
 261 menu-bar-select-buffer-function
 262 read-file-name-function
 263 replace-re-search-function
 264 replace-search-function
 265 yank-undo-function
 266
 267 C hooks:
 268 kbd-macro-termination-hook
 269 signal-hook-function
 270
 271 C functions:
 272 redisplay-end-trigger-functions
 273 x-lost-selection-functions
 274 x-sent-selection-functions
 275
 276 C function:
 277 auto-composition-function
 278 auto-fill-function
 279 command-error-function
 280 compose-chars-after-function
 281 composition-function-table
 282 deferred-action-function
 283 input-method-function
 284 load-read-function
 285 load-source-file-function
 286 read-buffer-function
 287 ring-bell-function
 288 select-safe-coding-system-function
 289 set-auto-coding-function
 290 show-help-function
 291 signal-hook-function
 292 undo-outer-limit-function
 293
 294 @end ignore