/[emacs]/emacs/lispref/modes.texi
ViewVC logotype

Diff of /emacs/lispref/modes.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.58.2.3 by miles, Fri Aug 27 07:00:30 2004 UTC revision 1.58.2.4 by miles, Sat Sep 25 12:05:24 2004 UTC
# Line 1  Line 1 
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
# Line 103  Fundamental mode.  Rmail mode is a compl Line 103  Fundamental mode.  Rmail mode is a compl
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
# Line 276  other packages would interfere with them Line 277  other packages would interfere with them
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
# Line 284  command (called the @dfn{parent mode}) a Line 285  command (called the @dfn{parent mode}) a
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
# Line 575  visited.  It also processes local variab Line 578  visited.  It also processes local variab
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
# Line 808  Do not write an @code{interactive} spec Line 811  Do not write an @code{interactive} spec
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
# Line 2087  if there is no subexpression numbered @v Line 2142  if there is no subexpression numbered @v
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:
# Line 2450  a file, don't have to do anything to use Line 2505  a file, don't have to do anything to use
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
# Line 2563  obsolete.)  If the value is a function ( Line 2618  obsolete.)  If the value is a function (
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

Legend:
Removed from v.1.58.2.3  
changed lines
  Added in v.1.58.2.4

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26