Previous: Modeline Format, Up: Modes [Contents][Index]
A hook is a variable where you can store a function or functions to be called on a particular occasion by an existing program. SXEmacs provides hooks for the sake of customization. Most often, hooks are set up in the init.el file, but Lisp programs can set them also. See Standard Hooks, for a list of standard hook variables.
Most of the hooks in SXEmacs 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 (see 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 that is a single function. Those whose names end in ‘-hooks’ have a value that is a list of functions. Any hook that 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 that you should look at its documentation string to see how to use it properly.
Major mode functions are supposed to run a hook called the mode
hook 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 are used in other
contexts too. For example, the hook suspend-hook
runs just
before SXEmacs suspends itself (see Suspending SXEmacs).
Here’s an expression that uses a mode hook 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 SXEmacs formats C code. (People often have strong personal preferences for one format or 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)
The final example shows how the appearance of the modeline can be modified for a particular class of buffers only.
(add-hook 'text-mode-hook (function (lambda () (setq modeline-format '(modeline-modified "SXEmacs: %14b" " "
default-directory " " global-mode-string "%[(" mode-name minor-mode-alist "%n" modeline-process ") %]---" (-3 . "%p") "-%-")))))
At the appropriate time, SXEmacs uses the run-hooks
function to
run particular hooks. This function calls the hook functions you have
added with add-hooks
.
This function takes one or more hook variable names as arguments, and runs each hook 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, here’s how emacs-lisp-mode
runs its mode hook:
(run-hooks 'emacs-lisp-mode-hook)
Like run-hooks
, but is affected by the delay-mode-hooks
macro.
This macro executes the body forms but defers all calls to
run-mode-hooks
within them until the end of body.
This macro enables a derived mode to arrange not to run
its parent modes’ mode hooks until the end.
This function is the way to run an abnormal hook and always call all of the hook functions. It calls each of the hook functions one by one, passing each of them the arguments args.
This function is the way to run an abnormal hook until one of the hook
functions fails. It calls each of the hook functions, passing each of
them the arguments args, until some hook function returns
nil
. It then stops and returns nil
. If none of the
hook functions return nil
, it returns a non-nil
value.
This function is the way to run an abnormal hook until a hook function
succeeds. It calls each of the hook functions, passing each of them
the arguments args, until some hook function returns
non-nil
. Then it stops, and returns whatever was returned by
the last hook function that was called. If all hook functions return
nil
, it returns nil
as well.
This function is the handy way to add function function to hook variable hook. The argument function may be any valid Lisp function with the proper number of arguments. For example,
(add-hook 'text-mode-hook 'my-text-hook-function)
adds my-text-hook-function
to the hook called text-mode-hook
.
You can use add-hook
for abnormal hooks as well as for normal
hooks.
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.
If local is non-nil
, that says to make the new hook
function local to the current buffer. Before you can do this, you must
make the hook itself buffer-local by calling make-local-hook
(not make-local-variable
). If the hook itself is not
buffer-local, then the value of local makes no difference—the
hook function is always global.
This function removes function from the hook variable hook.
If local is non-nil
, that says to remove function
from the local hook list instead of from the global hook list. If the
hook itself is not buffer-local, then the value of local makes no
difference.
This function makes the hook variable hook local to the current
buffer. When a hook variable is local, it can have local and global
hook functions, and run-hooks
runs all of them.
This function works by making t
an element of the buffer-local
value. That serves as a flag to use the hook functions in the default
value of the hook variable as well as those in the local value. Since
run-hooks
understands this flag, make-local-hook
works
with all normal hooks. It works for only some non-normal hooks—those
whose callers have been updated to understand this meaning of t
.
Do not use make-local-variable
directly for hook variables; it is
not sufficient.
Previous: Modeline Format, Up: Modes [Contents][Index]