hooks.texi 8.2 KB

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