hooks.texi 8.05 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
Paul Eggert's avatar
Paul Eggert committed
3
@c Copyright (C) 1990-1993, 1998, 2001-2018 Free Software Foundation,
Paul Eggert's avatar
Paul Eggert committed
4
@c Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@node Standard Hooks
Glenn Morris's avatar
Glenn Morris committed
7 8 9 10
@appendix Standard Hooks
@cindex standard hooks
@cindex hook variables, list of

Glenn Morris's avatar
Glenn Morris committed
11
The following is a list of some hook variables that let you provide
Glenn Morris's avatar
Glenn Morris committed
12 13 14 15 16 17 18 19 20
functions to be called from within Emacs on suitable occasions.

Most of these variables have names ending with @samp{-hook}.  They are
@dfn{normal hooks}, run by means of @code{run-hooks}.  The value of such
a hook is a list of functions; the functions are called with no
arguments and their values are completely ignored.  The recommended way
to put a new function on such a hook is to call @code{add-hook}.
@xref{Hooks}, for more information about using hooks.

Stefan Monnier's avatar
Stefan Monnier committed
21 22 23 24 25
The variables whose names end in @samp{-functions} are usually @dfn{abnormal
hooks} (some old code may also use the deprecated @samp{-hooks} suffix); their
values are lists of functions, but these functions are called in a special way
(they are passed arguments, or their return values are used).  The variables
whose names end in @samp{-function} have single functions as their values.
Glenn Morris's avatar
Glenn Morris committed
26

Glenn Morris's avatar
Glenn Morris committed
27 28 29 30 31 32
This is not an exhaustive list, it only covers the more general hooks.
For example, every major mode defines a hook named
@samp{@var{modename}-mode-hook}.  The major mode command runs this
normal hook with @code{run-mode-hooks} as the very last thing it does.
@xref{Mode Hooks}.  Most minor modes have mode hooks too.

33 34 35 36
A special feature allows you to specify expressions to evaluate if and
when a file is loaded (@pxref{Hooks for Loading}).  That feature is
not exactly a hook, but does a similar job.

Glenn Morris's avatar
Glenn Morris committed
37 38 39 40
@c We need to xref to where each hook is documented or else document it here.
@c Add vindex for anything not indexed elsewhere.
@c This list is in alphabetical order, grouped by topic.
@c TODO It should probably be more thoroughly ordered by topic.
Glenn Morris's avatar
Glenn Morris committed
41 42 43

@table @code
@item activate-mark-hook
Glenn Morris's avatar
Glenn Morris committed
44
@itemx deactivate-mark-hook
Glenn Morris's avatar
Glenn Morris committed
45 46 47
@xref{The Mark}.

@item after-change-functions
Glenn Morris's avatar
Glenn Morris committed
48 49
@itemx before-change-functions
@itemx first-change-hook
Glenn Morris's avatar
Glenn Morris committed
50 51 52
@xref{Change Hooks}.

@item after-change-major-mode-hook
Glenn Morris's avatar
Glenn Morris committed
53
@itemx change-major-mode-after-body-hook
Glenn Morris's avatar
Glenn Morris committed
54 55 56
@xref{Mode Hooks}.

@item after-init-hook
Glenn Morris's avatar
Glenn Morris committed
57 58
@itemx before-init-hook
@itemx emacs-startup-hook
59
@itemx window-setup-hook
Glenn Morris's avatar
Glenn Morris committed
60 61 62
@xref{Init File}.

@item after-insert-file-functions
Glenn Morris's avatar
Glenn Morris committed
63 64
@itemx write-region-annotate-functions
@itemx write-region-post-annotation-function
Glenn Morris's avatar
Glenn Morris committed
65 66 67
@xref{Format Conversion}.

@item after-make-frame-functions
Glenn Morris's avatar
Glenn Morris committed
68
@itemx before-make-frame-hook
69
@itemx server-after-make-frame-hook
Glenn Morris's avatar
Glenn Morris committed
70 71
@xref{Creating Frames}.

Glenn Morris's avatar
Glenn Morris committed
72 73
@c Not general enough?
@ignore
Glenn Morris's avatar
Glenn Morris committed
74
@item after-revert-hook
Glenn Morris's avatar
Glenn Morris committed
75 76 77 78
@itemx before-revert-hook
@itemx buffer-stale-function
@itemx revert-buffer-function
@itemx revert-buffer-insert-file-contents-function
Glenn Morris's avatar
Glenn Morris committed
79
@xref{Reverting}.
Glenn Morris's avatar
Glenn Morris committed
80
@end ignore
Glenn Morris's avatar
Glenn Morris committed
81 82

@item after-save-hook
Glenn Morris's avatar
Glenn Morris committed
83 84 85
@itemx before-save-hook
@itemx write-contents-functions
@itemx write-file-functions
Glenn Morris's avatar
Glenn Morris committed
86 87
@xref{Saving Buffers}.

Glenn Morris's avatar
Glenn Morris committed
88 89 90
@item after-setting-font-hook
@vindex after-setting-font-hook
Hook run after a frame's font changes.
Glenn Morris's avatar
Glenn Morris committed
91 92 93 94

@item auto-save-hook
@xref{Auto-Saving}.

95
@item before-hack-local-variables-hook
Glenn Morris's avatar
Glenn Morris committed
96
@itemx hack-local-variables-hook
97 98
@xref{File Local Variables}.

Glenn Morris's avatar
Glenn Morris committed
99 100 101
@item buffer-access-fontify-functions
@xref{Lazy Properties}.

Glenn Morris's avatar
Glenn Morris committed
102 103
@item buffer-list-update-hook
@vindex buffer-list-update-hook
104
Hook run when the buffer list changes (@pxref{Buffer List}).
Glenn Morris's avatar
Glenn Morris committed
105 106 107

@item buffer-quit-function
@vindex buffer-quit-function
Paul Eggert's avatar
Paul Eggert committed
108
Function to call to quit the current buffer.
109

Glenn Morris's avatar
Glenn Morris committed
110 111 112 113 114 115
@item change-major-mode-hook
@xref{Creating Buffer-Local}.

@item command-line-functions
@xref{Command-Line Arguments}.

Glenn Morris's avatar
Glenn Morris committed
116 117 118
@item delayed-warnings-hook
@vindex delayed-warnings-hook
The command loop runs this soon after @code{post-command-hook} (q.v.).
Glenn Morris's avatar
Glenn Morris committed
119

120 121 122 123 124 125
@item focus-in-hook
@vindex focus-in-hook
@itemx focus-out-hook
@vindex focus-out-hook
@xref{Input Focus}.

126
@item delete-frame-functions
Glenn Morris's avatar
Glenn Morris committed
127
@xref{Deleting Frames}.
128 129

@item delete-terminal-functions
Glenn Morris's avatar
Glenn Morris committed
130
@xref{Multiple Terminals}.
131

132
@item pop-up-frame-function
Glenn Morris's avatar
Glenn Morris committed
133 134
@itemx split-window-preferred-function
@xref{Choosing Window Options}.
Glenn Morris's avatar
Glenn Morris committed
135 136 137 138 139

@item echo-area-clear-hook
@xref{Echo Area Customization}.

@item find-file-hook
Glenn Morris's avatar
Glenn Morris committed
140
@itemx find-file-not-found-functions
Glenn Morris's avatar
Glenn Morris committed
141 142
@xref{Visiting Functions}.

Glenn Morris's avatar
Glenn Morris committed
143 144
@item font-lock-extend-after-change-region-function
@xref{Region to Refontify}.
Glenn Morris's avatar
Glenn Morris committed
145

Glenn Morris's avatar
Glenn Morris committed
146 147
@item font-lock-extend-region-functions
@xref{Multiline Font Lock}.
Glenn Morris's avatar
Glenn Morris committed
148 149

@item font-lock-fontify-buffer-function
Glenn Morris's avatar
Glenn Morris committed
150 151 152 153
@itemx font-lock-fontify-region-function
@itemx font-lock-mark-block-function
@itemx font-lock-unfontify-buffer-function
@itemx font-lock-unfontify-region-function
Glenn Morris's avatar
Glenn Morris committed
154 155
@xref{Other Font Lock Variables}.

Glenn Morris's avatar
Glenn Morris committed
156 157
@item fontification-functions
@xref{Auto Faces,, Automatic Face Assignment}.
Glenn Morris's avatar
Glenn Morris committed
158

Glenn Morris's avatar
Glenn Morris committed
159 160
@item frame-auto-hide-function
@xref{Quitting Windows}.
Glenn Morris's avatar
Glenn Morris committed
161 162

@item kill-buffer-hook
Glenn Morris's avatar
Glenn Morris committed
163
@itemx kill-buffer-query-functions
Glenn Morris's avatar
Glenn Morris committed
164 165 166
@xref{Killing Buffers}.

@item kill-emacs-hook
Glenn Morris's avatar
Glenn Morris committed
167
@itemx kill-emacs-query-functions
Glenn Morris's avatar
Glenn Morris committed
168 169 170 171 172 173
@xref{Killing Emacs}.

@item menu-bar-update-hook
@xref{Menu Bar}.

@item minibuffer-setup-hook
Glenn Morris's avatar
Glenn Morris committed
174
@itemx minibuffer-exit-hook
Glenn Morris's avatar
Glenn Morris committed
175 176
@xref{Minibuffer Misc}.

Glenn Morris's avatar
Glenn Morris committed
177 178 179
@item mouse-leave-buffer-hook
@vindex mouse-leave-buffer-hook
Hook run when about to switch windows with a mouse command.
Glenn Morris's avatar
Glenn Morris committed
180 181 182 183

@item mouse-position-function
@xref{Mouse Position}.

184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
@item prefix-command-echo-keystrokes-functions
@vindex prefix-command-echo-keystrokes-functions
An abnormal hook run by prefix commands (such as @kbd{C-u}) which
should return a string describing the current prefix state.  For
example, @kbd{C-u} produces @samp{C-u-} and @samp{C-u 1 2 3-}.  Each
hook function is called with no arguments and should return a string
describing the current prefix state, or @code{nil} if there's no
prefix state.  @xref{Prefix Command Arguments}.

@item prefix-command-preserve-state-hook
@vindex prefix-command-preserve-state-hook
Hook run when a prefix command needs to preserve the prefix by passing
the current prefix command state to the next command.  For example,
@kbd{C-u} needs to pass the state to the next command when the user
types @kbd{C-u -} or follows @kbd{C-u} with a digit.

200 201 202 203 204 205 206 207 208 209 210 211 212 213
@item pre-redisplay-functions
Hook run in each window just before redisplaying it.  @xref{Forcing
Redisplay}.

@item post-command-hook
@itemx pre-command-hook
@xref{Command Overview}.

@item post-gc-hook
@xref{Garbage Collection}.

@item post-self-insert-hook
@xref{Keymaps and Minor Modes}.

Glenn Morris's avatar
Glenn Morris committed
214
@ignore
215
@item prog-mode-hook
Glenn Morris's avatar
Glenn Morris committed
216 217
@itemx special-mode-hook
@vindex special-mode-hook
218
@xref{Basic Major Modes}.
Glenn Morris's avatar
Glenn Morris committed
219
@end ignore
220

Glenn Morris's avatar
Glenn Morris committed
221
@item suspend-hook
Glenn Morris's avatar
Glenn Morris committed
222 223 224
@itemx suspend-resume-hook
@itemx suspend-tty-functions
@itemx resume-tty-functions
Glenn Morris's avatar
Glenn Morris committed
225 226
@xref{Suspending Emacs}.

Glenn Morris's avatar
Glenn Morris committed
227 228 229 230 231
@item syntax-begin-function
@itemx syntax-propertize-extend-region-functions
@itemx syntax-propertize-function
@itemx font-lock-syntactic-face-function
@xref{Syntactic Font Lock}.  @xref{Syntax Properties}.
Glenn Morris's avatar
Glenn Morris committed
232 233

@item temp-buffer-setup-hook
Glenn Morris's avatar
Glenn Morris committed
234 235
@itemx temp-buffer-show-function
@itemx temp-buffer-show-hook
Glenn Morris's avatar
Glenn Morris committed
236 237
@xref{Temporary Displays}.

238
@item tty-setup-hook
Glenn Morris's avatar
Glenn Morris committed
239 240 241
@xref{Terminal-Specific}.

@item window-configuration-change-hook
Glenn Morris's avatar
Glenn Morris committed
242 243
@itemx window-scroll-functions
@itemx window-size-change-functions
Glenn Morris's avatar
Glenn Morris committed
244 245
@xref{Window Hooks}.
@end table
Glenn Morris's avatar
Glenn Morris committed
246 247 248 249 250 251 252 253 254 255 256 257 258

@ignore
Some -hook, -function, -functions from preloaded Lisp or C files that
I thought did not need to be mentioned here:

Lisp:
after-load-functions
auto-coding-functions
choose-completion-string-functions
completing-read-function
completion-annotate-function
completion-at-point-functions
completion-list-insert-choice-function
259
deactivate-current-input-method-function
Glenn Morris's avatar
Glenn Morris committed
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
describe-current-input-method-function
font-lock-function
menu-bar-select-buffer-function
read-file-name-function
replace-re-search-function
replace-search-function
yank-undo-function

C hooks:
kbd-macro-termination-hook
signal-hook-function

C functions:
redisplay-end-trigger-functions
x-lost-selection-functions
x-sent-selection-functions

C function:
auto-composition-function
auto-fill-function
command-error-function
compose-chars-after-function
composition-function-table
deferred-action-function
input-method-function
load-read-function
load-source-file-function
read-buffer-function
ring-bell-function
select-safe-coding-system-function
set-auto-coding-function
show-help-function
signal-hook-function
undo-outer-limit-function

@end ignore