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