hooks.texi 7.37 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.
3
@c Copyright (C) 1990-1993, 1998, 2001-2012 Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
4
@c See the file elisp.texi for copying conditions.
5
@node Standard Hooks
Glenn Morris's avatar
Glenn Morris committed
6 7 8 9
@appendix Standard Hooks
@cindex standard hooks
@cindex hook variables, list of

Glenn Morris's avatar
Glenn Morris committed
10
The following is a list of some hook variables that let you provide
Glenn Morris's avatar
Glenn Morris committed
11 12 13 14 15 16 17 18 19
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
20 21 22 23 24
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
25

Glenn Morris's avatar
Glenn Morris committed
26 27 28 29 30 31
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.

32 33 34 35
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
36 37 38 39
@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
40 41 42

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

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

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

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

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

@item after-make-frame-functions
Glenn Morris's avatar
Glenn Morris committed
66
@itemx before-make-frame-hook
Glenn Morris's avatar
Glenn Morris committed
67 68
@xref{Creating Frames}.

Glenn Morris's avatar
Glenn Morris committed
69 70
@c Not general enough?
@ignore
Glenn Morris's avatar
Glenn Morris committed
71
@item after-revert-hook
Glenn Morris's avatar
Glenn Morris committed
72 73 74 75
@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
76
@xref{Reverting}.
Glenn Morris's avatar
Glenn Morris committed
77
@end ignore
Glenn Morris's avatar
Glenn Morris committed
78 79

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

Glenn Morris's avatar
Glenn Morris committed
85 86 87
@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
88 89 90 91

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

92
@item before-hack-local-variables-hook
Glenn Morris's avatar
Glenn Morris committed
93
@itemx hack-local-variables-hook
94 95
@xref{File Local Variables}.

Glenn Morris's avatar
Glenn Morris committed
96 97 98
@item buffer-access-fontify-functions
@xref{Lazy Properties}.

Glenn Morris's avatar
Glenn Morris committed
99 100 101 102 103 104 105
@item buffer-list-update-hook
@vindex buffer-list-update-hook
Hook run when the buffer list changes.

@item buffer-quit-function
@vindex buffer-quit-function
Function to call to ``quit'' the current buffer.
106

Glenn Morris's avatar
Glenn Morris committed
107 108 109 110 111 112
@item change-major-mode-hook
@xref{Creating Buffer-Local}.

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

Glenn Morris's avatar
Glenn Morris committed
113 114 115
@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
116

117
@item delete-frame-functions
Glenn Morris's avatar
Glenn Morris committed
118
@xref{Deleting Frames}.
119 120

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

Glenn Morris's avatar
Glenn Morris committed
123
@ignore
Glenn Morris's avatar
Glenn Morris committed
124 125
@item disabled-command-function
@xref{Disabling Commands}.
Glenn Morris's avatar
Glenn Morris committed
126 127 128 129 130 131 132
@end ignore

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

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

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

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

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

@item font-lock-fontify-buffer-function
Glenn Morris's avatar
Glenn Morris committed
148 149 150 151
@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
152 153
@xref{Other Font Lock Variables}.

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

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

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

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

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

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

Glenn Morris's avatar
Glenn Morris committed
175 176 177
@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
178 179 180 181 182

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

@item post-command-hook
Glenn Morris's avatar
Glenn Morris committed
183
@itemx pre-command-hook
Glenn Morris's avatar
Glenn Morris committed
184 185
@xref{Command Overview}.

Glenn Morris's avatar
Glenn Morris committed
186 187 188
@item post-gc-hook
@xref{Garbage Collection}.

Glenn Morris's avatar
Glenn Morris committed
189 190 191
@item post-self-insert-hook
@xref{Keymaps and Minor Modes}.

Glenn Morris's avatar
Glenn Morris committed
192
@ignore
193
@item prog-mode-hook
Glenn Morris's avatar
Glenn Morris committed
194 195
@itemx special-mode-hook
@vindex special-mode-hook
196
@xref{Basic Major Modes}.
Glenn Morris's avatar
Glenn Morris committed
197
@end ignore
198

Glenn Morris's avatar
Glenn Morris committed
199
@item suspend-hook
Glenn Morris's avatar
Glenn Morris committed
200 201 202
@itemx suspend-resume-hook
@itemx suspend-tty-functions
@itemx resume-tty-functions
Glenn Morris's avatar
Glenn Morris committed
203 204
@xref{Suspending Emacs}.

Glenn Morris's avatar
Glenn Morris committed
205 206 207 208 209
@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
210 211

@item temp-buffer-setup-hook
Glenn Morris's avatar
Glenn Morris committed
212 213
@itemx temp-buffer-show-function
@itemx temp-buffer-show-hook
Glenn Morris's avatar
Glenn Morris committed
214 215 216 217 218 219
@xref{Temporary Displays}.

@item term-setup-hook
@xref{Terminal-Specific}.

@item window-configuration-change-hook
Glenn Morris's avatar
Glenn Morris committed
220 221
@itemx window-scroll-functions
@itemx window-size-change-functions
Glenn Morris's avatar
Glenn Morris committed
222 223 224 225 226
@xref{Window Hooks}.

@item window-setup-hook
@xref{Window Systems}.

Glenn Morris's avatar
Glenn Morris committed
227 228 229
@item window-text-change-functions
@vindex window-text-change-functions
Functions to call in redisplay when text in the window might change.
Glenn Morris's avatar
Glenn Morris committed
230 231

@end table
Glenn Morris's avatar
Glenn Morris committed
232 233 234 235 236 237 238 239 240 241 242 243 244 245

@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-in-region-functions
completion-list-insert-choice-function
246
deactivate-current-input-method-function
Glenn Morris's avatar
Glenn Morris committed
247 248 249 250 251 252 253 254 255 256 257 258 259 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
describe-current-input-method-function
filter-buffer-substring-functions
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
macro-declaration-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