/[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.56 by rms, Mon Jul 7 20:49:02 2003 UTC revision 1.57 by rms, Mon Jul 14 15:59:12 2003 UTC
# Line 263  other packages would interfere with them Line 263  other packages would interfere with them
263  @cindex major mode hook  @cindex major mode hook
264  Each major mode should have a @dfn{mode hook} named  Each major mode should have a @dfn{mode hook} named
265  @code{@var{modename}-mode-hook}.  The major mode command should run that  @code{@var{modename}-mode-hook}.  The major mode command should run that
266  hook, with @code{run-hooks}, as the very last thing it  hook, with @code{run-mode-hooks}, as the very last thing it
267  does.  @xref{Hooks}.  does.  @xref{Hooks}.
268    
269  @item  @item
270  The major mode command may also run the hooks of some more basic modes.  The major mode command may start by calling some other major mode
271  For example, @code{indented-text-mode} runs @code{text-mode-hook} as  command (called the @dfn{parent mode}) and then alter some of its
272  well as @code{indented-text-mode-hook}.  It may run these other hooks  settings.  A mode that does this is called a @dfn{derived mode}.  The
273  immediately before the mode's own hook (that is, after everything else),  recommended way to define one is to use @code{define-derived-mode},
274  or it may run them earlier.  but this is not required.  Such a mode should use
275    @code{delay-mode-hooks} around its entire body, including the call to
276    the parent mode command and the final call to @code{run-mode-hooks}.
277    (Using @code{define-derived-mode} does this automatically.)
278    
279  @item  @item
280  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 359  inherit all the commands defined in this Line 362  inherit all the commands defined in this
362  @end group  @end group
363  @end smallexample  @end smallexample
364    
365    Here is the complete major mode function definition for Text mode:    This was formerly the complete major mode function definition for Text mode:
366    
367  @smallexample  @smallexample
368  @group  @group
# Line 388  Turning on text-mode runs the hook `text Line 391  Turning on text-mode runs the hook `text
391  @group  @group
392    (setq mode-name "Text")    (setq mode-name "Text")
393    (setq major-mode 'text-mode)    (setq major-mode 'text-mode)
394    (run-hooks 'text-mode-hook))      ; @r{Finally, this permits the user to}    (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
395                                      ;   @r{customize the mode with a hook.}                                      ;   @r{customize the mode with a hook.}
396  @end group  @end group
397  @end smallexample  @end smallexample
# Line 543  if that value is non-nil." Line 546  if that value is non-nil."
546  @group  @group
547    (setq imenu-case-fold-search t)    (setq imenu-case-fold-search t)
548    (set-syntax-table lisp-mode-syntax-table)    (set-syntax-table lisp-mode-syntax-table)
549    (run-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}    (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
550                                           ;   @r{hook to customize the mode.}                                           ;   @r{hook to customize the mode.}
551  @end group  @end group
552  @end smallexample  @end smallexample
# Line 819  minor modes in effect. Line 822  minor modes in effect.
822  way to insert the necessary hook into the rest of Emacs.  Minor mode  way to insert the necessary hook into the rest of Emacs.  Minor mode
823  keymaps make this easier than it used to be.  keymaps make this easier than it used to be.
824    
825    @defvar minor-mode-list
826    The value of this variable is a list of all minor mode commands.
827    @end defvar
828    
829  @menu  @menu
830  * Minor Mode Conventions::      Tips for writing a minor mode.  * Minor Mode Conventions::      Tips for writing a minor mode.
831  * Keymaps and Minor Modes::     How a minor mode can have its own keymap.  * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
# Line 981  characters are reserved for major modes. Line 988  characters are reserved for major modes.
988  implementing a mode in one self-contained definition.  It supports only  implementing a mode in one self-contained definition.  It supports only
989  buffer-local minor modes, not global ones.  buffer-local minor modes, not global ones.
990    
991  @defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body...  @defmac define-minor-mode mode doc [init-value [lighter [keymap keyword-args... body...]]]
992  @tindex define-minor-mode  @tindex define-minor-mode
993  This macro defines a new minor mode whose name is @var{mode} (a symbol).  This macro defines a new minor mode whose name is @var{mode} (a
994  It defines a command named @var{mode} to toggle the minor  symbol).  It defines a command named @var{mode} to toggle the minor
995  mode, with @var{doc} as its documentation string.  It also defines a  mode, with @var{doc} as its documentation string.  It also defines a
996  variable named @var{mode}, which is set to @code{t} or @code{nil} by  variable named @var{mode}, which is set to @code{t} or @code{nil} by
997  enabling or disabling the mode.  The variable is initialized to  enabling or disabling the mode.  The variable is initialized to
998  @var{init-value}.  @var{init-value}.
999    
1000  The command named @var{mode} finishes by executing the @var{body} forms,  The string @var{lighter} says what to display in the mode line
 if any, after it has performed the standard actions such as setting  
 the variable named @var{mode}.  
   
 The string @var{mode-indicator} says what to display in the mode line  
1001  when the mode is enabled; if it is @code{nil}, the mode is not displayed  when the mode is enabled; if it is @code{nil}, the mode is not displayed
1002  in the mode line.  in the mode line.
1003    
# Line 1005  specifying bindings in this form: Line 1008  specifying bindings in this form:
1008  @example  @example
1009  (@var{key-sequence} . @var{definition})  (@var{key-sequence} . @var{definition})
1010  @end example  @end example
1011    
1012    The @var{keyword-args} consist of keywords followed by corresponding
1013    values.  A few keywords have special meanings:
1014    
1015    @table @code
1016    @item :global @var{global}
1017    If non-@code{nil} specifies that the minor mode should be global.
1018    By default, minor modes are buffer-local.
1019    
1020    @item :init-value @var{init-value}
1021    This is equivalent to specifying @var{init-value} positionally.
1022    
1023    @item :lighter @var{lighter}
1024    This is equivalent to specifying @var{lighter} positionally.
1025    
1026    @item :keymap @var{keymap}
1027    This is equivalent to specifying @var{keymap} positionally.
1028    @end table
1029    
1030    Any other keyword arguments are passed passed directly to the
1031    @code{defcustom} generated for the variable @var{mode}.
1032    
1033    The command named @var{mode} finishes by executing the @var{body} forms,
1034    if any, after it has performed the standard actions such as setting
1035    the variable named @var{mode}.
1036  @end defmac  @end defmac
1037    
1038    @findex easy-mmode-define-minor-mode
1039      The name @code{easy-mmode-define-minor-mode} is an alias
1040    for this macro.
1041    
1042    Here is an example of using @code{define-minor-mode}:    Here is an example of using @code{define-minor-mode}:
1043    
1044  @smallexample  @smallexample
# Line 1028  See the command \\[hungry-electric-delet Line 1060  See the command \\[hungry-electric-delet
1060     ("\C-\M-\^?"     ("\C-\M-\^?"
1061      . (lambda ()      . (lambda ()
1062          (interactive)          (interactive)
1063          (hungry-electric-delete t)))))          (hungry-electric-delete t))))
1064     :group 'hunger)
1065  @end smallexample  @end smallexample
1066    
1067  @noindent  @noindent
# Line 1037  This defines a minor mode named ``Hungry Line 1070  This defines a minor mode named ``Hungry
1070  which indicates whether the mode is enabled, and a variable named  which indicates whether the mode is enabled, and a variable named
1071  @code{hungry-mode-map} which holds the keymap that is active when the  @code{hungry-mode-map} which holds the keymap that is active when the
1072  mode is enabled.  It initializes the keymap with key bindings for  mode is enabled.  It initializes the keymap with key bindings for
1073  @kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.  @kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.  It puts the variable
1074    @code{hungry-mode} into custom group @code{hunger}.  There are no
1075    @var{body} forms---many minor modes don't need any.
1076    
1077      Here's an equivalent way to write it:
1078    
1079  @findex easy-mmode-define-minor-mode  @smallexample
1080    The name @code{easy-mmode-define-minor-mode} is an alias  (define-minor-mode hungry-mode
1081  for this macro.    "Toggle Hungry mode.
1082    With no argument, this command toggles the mode.
1083    Non-null prefix argument turns on the mode.
1084    Null prefix argument turns off the mode.
1085    
1086    When Hungry mode is enabled, the control delete key
1087    gobbles all preceding whitespace except the last.
1088    See the command \\[hungry-electric-delete]."
1089     ;; The initial value.
1090     :initial-value nil
1091     ;; The indicator for the mode line.
1092     :lighter " Hungry"
1093     ;; The minor mode bindings.
1094     :keymap
1095     '(("\C-\^?" . hungry-electric-delete)
1096       ("\C-\M-\^?"
1097        . (lambda ()
1098            (interactive)
1099            (hungry-electric-delete t))))
1100     :group 'hunger)
1101    @end smallexample
1102    
1103  @node Mode Line Format  @node Mode Line Format
1104  @section Mode Line Format  @section Mode Line Format
# Line 1885  specifies the face name to use for highl Line 1941  specifies the face name to use for highl
1941  ("fubar" . fubar-face)  ("fubar" . fubar-face)
1942  @end example  @end example
1943    
1944    The value of @var{facename} is usually a face name (a symbol), but it
1945    can also be a list of the form
1946    
1947    @example
1948    (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
1949    @end example
1950    
1951    to specify various text properties to put on the text that matches.
1952    If you do this, be sure to add the other text property names that you
1953    set in this way to the value of @code{font-lock-extra-managed-props}
1954    so that the properties will also be cleared out when they are no longer
1955    appropriate.
1956    
1957  @item (@var{matcher} . @var{highlighter})  @item (@var{matcher} . @var{highlighter})
1958  In this kind of element, @var{highlighter} is a list  In this kind of element, @var{highlighter} is a list
1959  which specifies how to highlight matches found by @var{matcher}.  which specifies how to highlight matches found by @var{matcher}.
# Line 2060  are @code{mark-defun} for programming mo Line 2129  are @code{mark-defun} for programming mo
2129  textual modes.  textual modes.
2130  @end defvar  @end defvar
2131    
2132    @defvar font-lock-extra-managed-props
2133    Additional properties (other than @code{face}) that are being managed
2134    by Font Lock mode.  Font Lock mode normally manages only the @code{face}
2135    property; if you want it to manage others as well, you must specify
2136    them in a @var{facename} in @code{font-lock-keywords} as well as adding
2137    them to this list.
2138    @end defvar
2139    
2140  @node Levels of Font Lock  @node Levels of Font Lock
2141  @subsection Levels of Font Lock  @subsection Levels of Font Lock
2142    
# Line 2163  where they are defined and where they ar Line 2240  where they are defined and where they ar
2240  @vindex font-lock-constant-face  @vindex font-lock-constant-face
2241  Used (typically) for constant names.  Used (typically) for constant names.
2242    
2243    @item font-locl-preprocessor-face
2244    @vindex font-locl-preprocessor-face
2245    Used (typically) for preprocessor commands.
2246    
2247  @item font-lock-warning-face  @item font-lock-warning-face
2248  @vindex font-lock-warning-face  @vindex font-lock-warning-face
2249  Used (typically) for constructs that are peculiar, or that greatly  Used (typically) for constructs that are peculiar, or that greatly
# Line 2312  For example, here's how @code{emacs-lisp Line 2393  For example, here's how @code{emacs-lisp
2393  @end example  @end example
2394  @end defun  @end defun
2395    
2396    @defun run-mode-hooks &rest hookvars
2397    Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks}
2398    macro.
2399    @end defun
2400    
2401    @defmac delay-mode-hooks body...
2402    This macro executes the @var{body} forms but defers all calls to
2403    @code{run-mode-hooks} within them until the end of @var{body}.
2404    This macro enables a derived mode to arrange not to run
2405    its parent modes' mode hooks until the end.
2406    @end defmac
2407    
2408  @defun run-hook-with-args hook &rest args  @defun run-hook-with-args hook &rest args
2409  This function is the way to run an abnormal hook which passes arguments  This function is the way to run an abnormal hook which passes arguments
2410  to the hook functions.  It calls each of the hook functions, passing  to the hook functions.  It calls each of the hook functions, passing

Legend:
Removed from v.1.56  
changed lines
  Added in v.1.57

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