(lispref.info)Hooks


Prev: Mode Line Format Up: Modes

Hooks
=====

   A "hook" is a variable where you can store a function or functions
to be called on a particular occasion by an existing program.  Emacs
provides lots of hooks for the sake of customization.  Most often, hooks
are set up in the `.emacs' file, but Lisp programs can set them also.
Note: Standard Hooks, for a list of standard hook variables.

   Most of the hooks in Emacs are "normal hooks".  These variables
contain lists of functions to be called with no arguments.  The reason
most hooks are normal hooks is so that you can use them in a uniform
way.  You can usually tell when a hook is a normal hook, because its
name ends in `-hook'.

   The recommended way to add a hook function to a normal hook is by
calling `add-hook' (see below).  The hook functions may be any of the
valid kinds of functions that `funcall' accepts (Note: What Is a
Function.).  Most normal hook variables are initially void;
`add-hook' knows how to deal with this.

   As for abnormal hooks, those whose names end in `-function' have a
value which is a single function.  Those whose names end in `-hooks'
have a value which is a list of functions.  Any hook which is abnormal
is abnormal because a normal hook won't do the job; either the
functions are called with arguments, or their values are meaningful.
The name shows you that the hook is abnormal and you need to look up
how to use it properly.

   Most major modes run hooks as the last step of initialization.  This
makes it easy for a user to customize the behavior of the mode, by
overriding the local variable assignments already made by the mode.  But
hooks may also be used in other contexts.  For example, the hook
`suspend-hook' runs just before Emacs suspends itself (Note: Suspending
Emacs.).

   For example, you can put the following expression in your `.emacs'
file if you want to turn on Auto Fill mode when in Lisp Interaction
mode:

     (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)

   The next example shows how to use a hook to customize the way Emacs
formats C code.  (People often have strong personal preferences for one
format compared to another.)  Here the hook function is an anonymous
lambda expression.

     (add-hook 'c-mode-hook
       (function (lambda ()
                   (setq c-indent-level 4
                         c-argdecl-indent 0
                         c-label-offset -4
                         c-continued-statement-indent 0
                         c-brace-offset 0
                         comment-column 40))))
     
     (setq c++-mode-hook c-mode-hook)

   Finally, here is an example of how to use the Text mode hook to
provide a customized mode line for buffers in Text mode, displaying the
default directory in addition to the standard components of the mode
line.  (This may cause the mode line to run out of space if you have
very long file names or display the time and load.)

     (add-hook 'text-mode-hook
       (function (lambda ()
                   (setq mode-line-format
                         '(mode-line-modified
                           "Emacs: %14b"
                           "  "
                           default-directory
                           " "
                           global-mode-string
                           "%[("
                           mode-name
                           minor-mode-alist
                           "%n"
                           mode-line-process
                           ") %]---"
                           (-3 . "%p")
                           "-%-")))))

   At the appropriate time, Emacs uses the `run-hooks' function to run
particular hooks.  This function calls the hook functions you have
added with `add-hooks'.

 - Function: run-hooks &rest HOOKVAR
     This function takes one or more hook names as arguments and runs
     each one in turn.  Each HOOKVAR argument should be a symbol that
     is a hook variable.  These arguments are processed in the order
     specified.

     If a hook variable has a non-`nil' value, that value may be a
     function or a list of functions.  If the value is a function
     (either a lambda expression or a symbol with a function
     definition), it is called.  If it is a list, the elements are
     called, in order.  The hook functions are called with no arguments.

     For example:

          (run-hooks 'emacs-lisp-mode-hook)

     Major mode functions use this function to call any hooks defined
     by the user.

 - Function: add-hook HOOK FUNCTION &optional APPEND
     This function is the handy way to add function FUNCTION to hook
     variable HOOK.  For example,

          (add-hook 'text-mode-hook 'my-text-hook-function)

     adds `my-text-hook-function' to the hook called `text-mode-hook'.

     It is best to design your hook functions so that the order in
     which they are executed does not matter.  Any dependence on the
     order is "asking for trouble."  However, the order is predictable:
     normally, FUNCTION goes at the front of the hook list, so it will
     be executed first (barring another `add-hook' call).

     If the optional argument APPEND is non-`nil', the new hook
     function goes at the end of the hook list and will be executed
     last.


automatically generated by info2www