1 |
@c -*-texinfo-*- |
@c -*-texinfo-*- |
2 |
@c This is part of the GNU Emacs Lisp Reference Manual. |
@c This is part of the GNU Emacs Lisp Reference Manual. |
3 |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003 |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003, 2004 |
4 |
@c Free Software Foundation, Inc. |
@c Free Software Foundation, Inc. |
5 |
@c See the file elisp.texi for copying conditions. |
@c See the file elisp.texi for copying conditions. |
6 |
@setfilename ../info/modes |
@setfilename ../info/modes |
103 |
* Mode Help:: Finding out how to use a mode. |
* Mode Help:: Finding out how to use a mode. |
104 |
* Derived Modes:: Defining a new major mode based on another major |
* Derived Modes:: Defining a new major mode based on another major |
105 |
mode. |
mode. |
106 |
|
* Mode Hooks:: Hooks run at the end of major mode functions. |
107 |
@end menu |
@end menu |
108 |
|
|
109 |
@node Major Mode Conventions |
@node Major Mode Conventions |
277 |
Each major mode should have a @dfn{mode hook} named |
Each major mode should have a @dfn{mode hook} named |
278 |
@code{@var{modename}-mode-hook}. The major mode command should run that |
@code{@var{modename}-mode-hook}. The major mode command should run that |
279 |
hook, with @code{run-mode-hooks}, as the very last thing it |
hook, with @code{run-mode-hooks}, as the very last thing it |
280 |
does. @xref{Hooks}. |
does. @xref{Mode Hooks}. |
281 |
|
|
282 |
@item |
@item |
283 |
The major mode command may start by calling some other major mode |
The major mode command may start by calling some other major mode |
285 |
settings. A mode that does this is called a @dfn{derived mode}. The |
settings. A mode that does this is called a @dfn{derived mode}. The |
286 |
recommended way to define one is to use @code{define-derived-mode}, |
recommended way to define one is to use @code{define-derived-mode}, |
287 |
but this is not required. Such a mode should use |
but this is not required. Such a mode should use |
288 |
@code{delay-mode-hooks} around its entire body, including the call to |
@code{delay-mode-hooks} around its entire body (including the call to |
289 |
the parent mode command and the final call to @code{run-mode-hooks}. |
the parent mode command) @emph{except} for the final call to |
290 |
(Using @code{define-derived-mode} does this automatically.) |
@code{run-mode-hooks}, which runs the derived mode's hook. (Using |
291 |
|
@code{define-derived-mode} does this automatically.) @xref{Derived |
292 |
|
Modes}, and @ref{Mode Hooks}. |
293 |
|
|
294 |
@item |
@item |
295 |
If something special should be done if the user switches a buffer from |
If something special should be done if the user switches a buffer from |
578 |
in particular. Other major modes are defined in effect by comparison |
in particular. Other major modes are defined in effect by comparison |
579 |
with this one---their definitions say what to change, starting from |
with this one---their definitions say what to change, starting from |
580 |
Fundamental mode. The @code{fundamental-mode} function does @emph{not} |
Fundamental mode. The @code{fundamental-mode} function does @emph{not} |
581 |
run any hooks; you're not supposed to customize it. (If you want Emacs |
run any mode hooks; you're not supposed to customize it. (If you want Emacs |
582 |
to behave differently in Fundamental mode, change the @emph{global} |
to behave differently in Fundamental mode, change the @emph{global} |
583 |
state of Emacs.) |
state of Emacs.) |
584 |
@end deffn |
@end deffn |
811 |
@code{define-derived-mode} does that automatically. |
@code{define-derived-mode} does that automatically. |
812 |
@end defmac |
@end defmac |
813 |
|
|
814 |
|
@node Mode Hooks |
815 |
|
@subsection Mode Hooks |
816 |
|
|
817 |
|
The two last things a major mode function does is to run its mode |
818 |
|
hook and finally the mode independent normal hook |
819 |
|
@code{after-change-major-mode-hook}. If the major mode is a derived |
820 |
|
mode, that is if it calls another major mode (the parent mode) in its |
821 |
|
body, then the parent's mode hook is run just before the derived |
822 |
|
mode's hook. Neither the parent's mode hook nor |
823 |
|
@code{after-change-major-mode-hook} are run at the end of the actual |
824 |
|
call to the parent mode. This applies recursively if the parent mode |
825 |
|
has itself a parent. That is, the mode hooks of all major modes called |
826 |
|
directly or indirectly by the major mode function are all run in |
827 |
|
sequence at the end, just before @code{after-change-major-mode-hook}. |
828 |
|
|
829 |
|
If you are customizing a major mode, rather than defining one, the |
830 |
|
above is all you need to know about the hooks run at the end of a |
831 |
|
major mode. This also applies if you use @code{define-derived-mode} |
832 |
|
to define a major mode, because that macro will automatically |
833 |
|
implement the above for you. |
834 |
|
|
835 |
|
Programmers wishing to define a major mode without using |
836 |
|
@code{define-derived-mode}, should make sure that their major mode |
837 |
|
follows the above conventions. @xref{Major Mode Conventions}, for how |
838 |
|
this should be accomplished. Below, we give some implementation |
839 |
|
details. |
840 |
|
|
841 |
|
@defun run-mode-hooks &rest hookvars |
842 |
|
Major modes should run their mode hook using this function. It is |
843 |
|
similar to @code{run-hooks} (@pxref{Hooks}), but if run inside a |
844 |
|
@code{delay-mode-hooks} form, this function does not run any hooks. |
845 |
|
Instead, it arranges for @var{hookvars} to be run at a later call to |
846 |
|
the function. Otherwise, @code{run-mode-hooks} runs any delayed hooks |
847 |
|
in order, then @var{hookvars} and finally |
848 |
|
@code{after-change-major-mode-hook}. |
849 |
|
@end defun |
850 |
|
|
851 |
|
@defmac delay-mode-hooks body... |
852 |
|
This macro executes @var{body} like @code{progn}, but all calls to |
853 |
|
@code{run-mode-hooks} inside @var{body} delay running their hooks. |
854 |
|
They will be run by the first call to @code{run-mode-hooks} after exit |
855 |
|
from @code{delay-mode-hooks}. |
856 |
|
@end defmac |
857 |
|
|
858 |
|
@defvar after-change-major-mode-hook |
859 |
|
Every major mode function should run this normal hook at its very end. |
860 |
|
It normally does not need to do so explicitly. Indeed, a major mode |
861 |
|
function should normally run its mode hook with @code{run-mode-hooks} |
862 |
|
as the very last thing it does and @code{run-mode-hooks} runs |
863 |
|
@code{after-change-major-mode-hook} at its very end. |
864 |
|
@end defvar |
865 |
|
|
866 |
@node Minor Modes |
@node Minor Modes |
867 |
@section Minor Modes |
@section Minor Modes |
868 |
@cindex minor mode |
@cindex minor mode |
2142 |
Obviously, fontification of the subexpression numbered @var{subexp} will |
Obviously, fontification of the subexpression numbered @var{subexp} will |
2143 |
not occur. However, fontification of other subexpressions (and other |
not occur. However, fontification of other subexpressions (and other |
2144 |
regexps) will continue. If @var{laxmatch} is @code{nil}, and the |
regexps) will continue. If @var{laxmatch} is @code{nil}, and the |
2145 |
specified subexpression is missing, then an error is signalled which |
specified subexpression is missing, then an error is signaled which |
2146 |
terminates search-based fontification. |
terminates search-based fontification. |
2147 |
|
|
2148 |
Here are some examples of elements of this kind, and what they do: |
Here are some examples of elements of this kind, and what they do: |
2505 |
|
|
2506 |
For buffers not visiting a file to have their state saved, the major |
For buffers not visiting a file to have their state saved, the major |
2507 |
mode must bind the buffer local variable @code{desktop-save-buffer} to |
mode must bind the buffer local variable @code{desktop-save-buffer} to |
2508 |
a non-nil value. |
a non-@code{nil} value. |
2509 |
|
|
2510 |
@defvar desktop-save-buffer |
@defvar desktop-save-buffer |
2511 |
If this buffer-local variable is non-@code{nil}, the buffer will have |
If this buffer-local variable is non-@code{nil}, the buffer will have |
2618 |
a symbol with a function definition), it is called. If it is a list |
a symbol with a function definition), it is called. If it is a list |
2619 |
that isn't a function, its elements are called, consecutively. All |
that isn't a function, its elements are called, consecutively. All |
2620 |
the hook functions are called with no arguments. |
the hook functions are called with no arguments. |
|
|
|
|
For example, here's how @code{emacs-lisp-mode} runs its mode hook: |
|
|
|
|
|
@example |
|
|
(run-hooks 'emacs-lisp-mode-hook) |
|
|
@end example |
|
|
@end defun |
|
|
|
|
|
@defun run-mode-hooks &rest hookvars |
|
|
Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks} |
|
|
macro. |
|
2621 |
@end defun |
@end defun |
2622 |
|
|
|
@defmac delay-mode-hooks body... |
|
|
This macro executes the @var{body} forms but defers all calls to |
|
|
@code{run-mode-hooks} within them until the end of @var{body}. |
|
|
This macro enables a derived mode to arrange not to run |
|
|
its parent modes' mode hooks until the end. |
|
|
@end defmac |
|
|
|
|
2623 |
@defun run-hook-with-args hook &rest args |
@defun run-hook-with-args hook &rest args |
2624 |
This function is the way to run an abnormal hook and always call all |
This function is the way to run an abnormal hook and always call all |
2625 |
of the hook functions. It calls each of the hook functions one by |
of the hook functions. It calls each of the hook functions one by |