2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/modes.info
6 @node Modes, Documentation, Drag and Drop, Top
7 @chapter Major and Minor Modes
10 A @dfn{mode} is a set of definitions that customize XEmacs and can be
11 turned on and off while you edit. There are two varieties of modes:
12 @dfn{major modes}, which are mutually exclusive and used for editing
13 particular kinds of text, and @dfn{minor modes}, which provide features
14 that users can enable individually.
16 This chapter describes how to write both major and minor modes, how to
17 indicate them in the modeline, and how they run hooks supplied by the
18 user. For related topics such as keymaps and syntax tables, see
19 @ref{Keymaps}, and @ref{Syntax Tables}.
22 * Major Modes:: Defining major modes.
23 * Minor Modes:: Defining minor modes.
24 * Modeline Format:: Customizing the text that appears in the modeline.
25 * Hooks:: How to use hooks; how to write code that provides hooks.
31 @cindex Fundamental mode
33 Major modes specialize XEmacs for editing particular kinds of text.
34 Each buffer has only one major mode at a time.
36 The least specialized major mode is called @dfn{Fundamental mode}.
37 This mode has no mode-specific definitions or variable settings, so each
38 XEmacs command behaves in its default manner, and each option is in its
39 default state. All other major modes redefine various keys and options.
40 For example, Lisp Interaction mode provides special key bindings for
41 @key{LFD} (@code{eval-print-last-sexp}), @key{TAB}
42 (@code{lisp-indent-line}), and other keys.
44 When you need to write several editing commands to help you perform a
45 specialized editing task, creating a new major mode is usually a good
46 idea. In practice, writing a major mode is easy (in contrast to
47 writing a minor mode, which is often difficult).
49 If the new mode is similar to an old one, it is often unwise to modify
50 the old one to serve two purposes, since it may become harder to use and
51 maintain. Instead, copy and rename an existing major mode definition
52 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
53 Modes}). For example, Rmail Edit mode, which is in
54 @file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to
55 Text mode except that it provides three additional commands. Its
56 definition is distinct from that of Text mode, but was derived from it.
58 Rmail Edit mode is an example of a case where one piece of text is put
59 temporarily into a different major mode so it can be edited in a
60 different way (with ordinary XEmacs commands rather than Rmail). In such
61 cases, the temporary major mode usually has a command to switch back to
62 the buffer's usual mode (Rmail mode, in this case). You might be
63 tempted to present the temporary redefinitions inside a recursive edit
64 and restore the usual ones when the user exits; but this is a bad idea
65 because it constrains the user's options when it is done in more than
66 one buffer: recursive edits must be exited most-recently-entered first.
67 Using alternative major modes avoids this limitation. @xref{Recursive
70 The standard XEmacs Lisp library directory contains the code for
71 several major modes, in files including @file{text-mode.el},
72 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
73 @file{rmail.el}. You can look at these libraries to see how modes are
74 written. Text mode is perhaps the simplest major mode aside from
75 Fundamental mode. Rmail mode is a complicated and specialized mode.
78 * Major Mode Conventions:: Coding conventions for keymaps, etc.
79 * Example Major Modes:: Text mode and Lisp modes.
80 * Auto Major Mode:: How XEmacs chooses the major mode automatically.
81 * Mode Help:: Finding out how to use a mode.
82 * Derived Modes:: Defining a new major mode based on another major
86 @node Major Mode Conventions
87 @subsection Major Mode Conventions
89 The code for existing major modes follows various coding conventions,
90 including conventions for local keymap and syntax table initialization,
91 global names, and hooks. Please follow these conventions when you
92 define a new major mode:
96 Define a command whose name ends in @samp{-mode}, with no arguments,
97 that switches to the new mode in the current buffer. This command
98 should set up the keymap, syntax table, and local variables in an
99 existing buffer without changing the buffer's text.
102 Write a documentation string for this command that describes the
103 special commands available in this mode. @kbd{C-h m}
104 (@code{describe-mode}) in your mode will display this string.
106 The documentation string may include the special documentation
107 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
108 @samp{\<@var{keymap}>}, that enable the documentation to adapt
109 automatically to the user's own key bindings. @xref{Keys in
113 The major mode command should start by calling
114 @code{kill-all-local-variables}. This is what gets rid of the local
115 variables of the major mode previously in effect.
118 The major mode command should set the variable @code{major-mode} to the
119 major mode command symbol. This is how @code{describe-mode} discovers
120 which documentation to print.
123 The major mode command should set the variable @code{mode-name} to the
124 ``pretty'' name of the mode, as a string. This appears in the mode
128 @cindex functions in modes
129 Since all global names are in the same name space, all the global
130 variables, constants, and functions that are part of the mode should
131 have names that start with the major mode name (or with an abbreviation
132 of it if the name is long). @xref{Style Tips}.
135 @cindex keymaps in modes
136 The major mode should usually have its own keymap, which is used as the
137 local keymap in all buffers in that mode. The major mode function
138 should call @code{use-local-map} to install this local map.
139 @xref{Active Keymaps}, for more information.
141 This keymap should be kept in a global variable named
142 @code{@var{modename}-mode-map}. Normally the library that defines the
143 mode sets this variable.
146 @cindex syntax tables in modes
147 The mode may have its own syntax table or may share one with other
148 related modes. If it has its own syntax table, it should store this in
149 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
153 @cindex abbrev tables in modes
154 The mode may have its own abbrev table or may share one with other
155 related modes. If it has its own abbrev table, it should store this in
156 a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
160 Use @code{defvar} to set mode-related variables, so that they are not
161 reinitialized if they already have a value. (Such reinitialization
162 could discard customizations made by the user.)
165 @cindex buffer-local variables in modes
166 To make a buffer-local binding for an Emacs customization variable, use
167 @code{make-local-variable} in the major mode command, not
168 @code{make-variable-buffer-local}. The latter function would make the
169 variable local to every buffer in which it is subsequently set, which
170 would affect buffers that do not use this mode. It is undesirable for a
171 mode to have such global effects. @xref{Buffer-Local Variables}.
173 It's ok to use @code{make-variable-buffer-local}, if you wish, for a
174 variable used only within a single Lisp package.
178 @cindex major mode hook
179 Each major mode should have a @dfn{mode hook} named
180 @code{@var{modename}-mode-hook}. The major mode command should run that
181 hook, with @code{run-hooks}, as the very last thing it
185 The major mode command may also run the hooks of some more basic modes.
186 For example, @code{indented-text-mode} runs @code{text-mode-hook} as
187 well as @code{indented-text-mode-hook}. It may run these other hooks
188 immediately before the mode's own hook (that is, after everything else),
189 or it may run them earlier.
192 If something special should be done if the user switches a buffer from
193 this mode to any other major mode, the mode can set a local value for
194 @code{change-major-mode-hook}.
197 If this mode is appropriate only for specially-prepared text, then the
198 major mode command symbol should have a property named @code{mode-class}
199 with value @code{special}, put on as follows:
201 @cindex @code{mode-class} property
202 @cindex @code{special}
204 (put 'funny-mode 'mode-class 'special)
208 This tells XEmacs that new buffers created while the current buffer has
209 Funny mode should not inherit Funny mode. Modes such as Dired, Rmail,
210 and Buffer List use this feature.
213 If you want to make the new mode the default for files with certain
214 recognizable names, add an element to @code{auto-mode-alist} to select
215 the mode for those file names. If you define the mode command to
216 autoload, you should add this element in the same file that calls
217 @code{autoload}. Otherwise, it is sufficient to add the element in the
218 file that contains the mode definition. @xref{Auto Major Mode}.
221 @cindex @file{.emacs} customization
222 In the documentation, you should provide a sample @code{autoload} form
223 and an example of how to add to @code{auto-mode-alist}, that users can
224 include in their @file{.emacs} files.
228 The top-level forms in the file defining the mode should be written so
229 that they may be evaluated more than once without adverse consequences.
230 Even if you never load the file more than once, someone else will.
233 @defvar change-major-mode-hook
234 This normal hook is run by @code{kill-all-local-variables} before it
235 does anything else. This gives major modes a way to arrange for
236 something special to be done if the user switches to a different major
237 mode. For best results, make this variable buffer-local, so that it
238 will disappear after doing its job and will not interfere with the
239 subsequent major mode. @xref{Hooks}.
242 @node Example Major Modes
243 @subsection Major Mode Examples
245 Text mode is perhaps the simplest mode besides Fundamental mode.
246 Here are excerpts from @file{text-mode.el} that illustrate many of
247 the conventions listed above:
251 ;; @r{Create mode-specific tables.}
252 (defvar text-mode-syntax-table nil
253 "Syntax table used while in text mode.")
257 (if text-mode-syntax-table
258 () ; @r{Do not change the table if it is already set up.}
259 (setq text-mode-syntax-table (make-syntax-table))
260 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
261 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
262 (modify-syntax-entry ?' "w " text-mode-syntax-table))
266 (defvar text-mode-abbrev-table nil
267 "Abbrev table used while in text mode.")
268 (define-abbrev-table 'text-mode-abbrev-table ())
272 (defvar text-mode-map nil) ; @r{Create a mode-specific keymap.}
275 () ; @r{Do not change the keymap if it is already set up.}
276 (setq text-mode-map (make-sparse-keymap))
277 (define-key text-mode-map "\t" 'tab-to-tab-stop)
278 (define-key text-mode-map "\es" 'center-line)
279 (define-key text-mode-map "\eS" 'center-paragraph))
283 Here is the complete major mode function definition for Text mode:
288 "Major mode for editing text intended for humans to read.
289 Special commands: \\@{text-mode-map@}
292 Turning on text-mode runs the hook `text-mode-hook'."
294 (kill-all-local-variables)
297 (use-local-map text-mode-map) ; @r{This provides the local keymap.}
298 (setq mode-name "Text") ; @r{This name goes into the modeline.}
299 (setq major-mode 'text-mode) ; @r{This is how @code{describe-mode}}
300 ; @r{finds the doc string to print.}
301 (setq local-abbrev-table text-mode-abbrev-table)
302 (set-syntax-table text-mode-syntax-table)
303 (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
304 ; @r{customize the mode with a hook.}
308 @cindex @file{lisp-mode.el}
309 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
310 Interaction mode) have more features than Text mode and the code is
311 correspondingly more complicated. Here are excerpts from
312 @file{lisp-mode.el} that illustrate how these modes are written.
314 @cindex syntax table example
317 ;; @r{Create mode-specific table variables.}
318 (defvar lisp-mode-syntax-table nil "")
319 (defvar emacs-lisp-mode-syntax-table nil "")
320 (defvar lisp-mode-abbrev-table nil "")
324 (if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
325 ; @r{if it is already set.}
327 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
331 ;; @r{Set syntax of chars up to 0 to class of chars that are}
332 ;; @r{part of symbol names but not words.}
333 ;; @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)}
335 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
340 ;; @r{Set the syntax for other characters.}
341 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
342 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
346 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
347 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
349 ;; @r{Create an abbrev table for lisp-mode.}
350 (define-abbrev-table 'lisp-mode-abbrev-table ())
354 Much code is shared among the three Lisp modes. The following
355 function sets various variables; it is called by each of the major Lisp
360 (defun lisp-mode-variables (lisp-syntax)
361 ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
362 ;; @r{and @code{t} in the other two Lisp modes.}
364 (if (not lisp-mode-syntax-table)
365 ;; @r{The Emacs Lisp mode syntax table always exists, but}
366 ;; @r{the Lisp Mode syntax table is created the first time a}
367 ;; @r{mode that needs it is called. This is to save space.}
370 (progn (setq lisp-mode-syntax-table
371 (copy-syntax-table emacs-lisp-mode-syntax-table))
372 ;; @r{Change some entries for Lisp mode.}
373 (modify-syntax-entry ?\| "\" "
374 lisp-mode-syntax-table)
375 (modify-syntax-entry ?\[ "_ "
376 lisp-mode-syntax-table)
377 (modify-syntax-entry ?\] "_ "
378 lisp-mode-syntax-table)))
381 (set-syntax-table lisp-mode-syntax-table)))
382 (setq local-abbrev-table lisp-mode-abbrev-table)
387 Functions such as @code{forward-paragraph} use the value of the
388 @code{paragraph-start} variable. Since Lisp code is different from
389 ordinary text, the @code{paragraph-start} variable needs to be set
390 specially to handle Lisp. Also, comments are indented in a special
391 fashion in Lisp and the Lisp modes need their own mode-specific
392 @code{comment-indent-function}. The code to set these variables is the
393 rest of @code{lisp-mode-variables}.
397 (make-local-variable 'paragraph-start)
398 ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
399 ;; @r{has them too, and removing those is a pain.}
400 (setq paragraph-start (concat "^$\\|" page-delimiter))
404 (make-local-variable 'comment-indent-function)
405 (setq comment-indent-function 'lisp-comment-indent))
409 Each of the different Lisp modes has a slightly different keymap. For
410 example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other
411 Lisp modes do not. However, all Lisp modes have some commands in
412 common. The following function adds these common commands to a given
417 (defun lisp-mode-commands (map)
418 (define-key map "\e\C-q" 'indent-sexp)
419 (define-key map "\177" 'backward-delete-char-untabify)
420 (define-key map "\t" 'lisp-indent-line))
424 Here is an example of using @code{lisp-mode-commands} to initialize a
425 keymap, as part of the code for Emacs Lisp mode. First we declare a
426 variable with @code{defvar} to hold the mode-specific keymap. When this
427 @code{defvar} executes, it sets the variable to @code{nil} if it was
428 void. Then we set up the keymap if the variable is @code{nil}.
430 This code avoids changing the keymap or the variable if it is already
431 set up. This lets the user customize the keymap.
435 (defvar emacs-lisp-mode-map () "")
436 (if emacs-lisp-mode-map
438 (setq emacs-lisp-mode-map (make-sparse-keymap))
439 (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
440 (lisp-mode-commands emacs-lisp-mode-map))
444 Finally, here is the complete major mode function definition for
449 (defun emacs-lisp-mode ()
450 "Major mode for editing Lisp code to run in XEmacs.
452 Delete converts tabs to spaces as it moves back.
453 Blank lines separate paragraphs. Semicolons start comments.
454 \\@{emacs-lisp-mode-map@}
457 Entry to this mode runs the hook `emacs-lisp-mode-hook'."
459 (kill-all-local-variables)
460 (use-local-map emacs-lisp-mode-map) ; @r{This provides the local keymap.}
461 (set-syntax-table emacs-lisp-mode-syntax-table)
464 (setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}}
465 ; @r{finds out what to describe.}
466 (setq mode-name "Emacs-Lisp") ; @r{This goes into the modeline.}
467 (lisp-mode-variables nil) ; @r{This defines various variables.}
468 (run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a}
469 ; @r{hook to customize the mode.}
473 @node Auto Major Mode
474 @subsection How XEmacs Chooses a Major Mode
476 Based on information in the file name or in the file itself, XEmacs
477 automatically selects a major mode for the new buffer when a file is
480 @deffn Command fundamental-mode
481 Fundamental mode is a major mode that is not specialized for anything
482 in particular. Other major modes are defined in effect by comparison
483 with this one---their definitions say what to change, starting from
484 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
485 run any hooks; you're not supposed to customize it. (If you want Emacs
486 to behave differently in Fundamental mode, change the @emph{global}
490 @deffn Command normal-mode &optional find-file
491 This function establishes the proper major mode and local variable
492 bindings for the current buffer. First it calls @code{set-auto-mode},
493 then it runs @code{hack-local-variables} to parse, and bind or
494 evaluate as appropriate, any local variables.
496 If the @var{find-file} argument to @code{normal-mode} is
497 non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
498 function is calling it. In this case, it may process a local variables
499 list at the end of the file and in the @samp{-*-} line. The variable
500 @code{enable-local-variables} controls whether to do so.
502 If you run @code{normal-mode} interactively, the argument
503 @var{find-file} is normally @code{nil}. In this case,
504 @code{normal-mode} unconditionally processes any local variables list.
505 @xref{File variables, , Local Variables in Files, emacs, The XEmacs
506 Reference Manual}, for the syntax of the local variables section of a file.
508 @cindex file mode specification error
509 @code{normal-mode} uses @code{condition-case} around the call to the
510 major mode function, so errors are caught and reported as a @samp{File
511 mode specification error}, followed by the original error message.
514 @defopt enable-local-variables
515 This variable controls processing of local variables lists in files
516 being visited. A value of @code{t} means process the local variables
517 lists unconditionally; @code{nil} means ignore them; anything else means
518 ask the user what to do for each file. The default value is @code{t}.
521 @defvar ignored-local-variables
522 This variable holds a list of variables that should not be
523 set by a local variables list. Any value specified
524 for one of these variables is ignored.
527 In addition to this list, any variable whose name has a non-@code{nil}
528 @code{risky-local-variable} property is also ignored.
530 @defopt enable-local-eval
531 This variable controls processing of @samp{Eval:} in local variables
532 lists in files being visited. A value of @code{t} means process them
533 unconditionally; @code{nil} means ignore them; anything else means ask
534 the user what to do for each file. The default value is @code{maybe}.
538 @cindex visited file mode
539 This function selects the major mode that is appropriate for the
540 current buffer. It may base its decision on the value of the @w{@samp{-*-}}
541 line, on the visited file name (using @code{auto-mode-alist}), or on the
542 value of a local variable. However, this function does not look for
543 the @samp{mode:} local variable near the end of a file; the
544 @code{hack-local-variables} function does that. @xref{Choosing Modes, ,
545 How Major Modes are Chosen, emacs, The XEmacs Reference Manual}.
548 @defopt default-major-mode
549 This variable holds the default major mode for new buffers. The
550 standard value is @code{fundamental-mode}.
552 If the value of @code{default-major-mode} is @code{nil}, XEmacs uses
553 the (previously) current buffer's major mode for the major mode of a new
554 buffer. However, if the major mode symbol has a @code{mode-class}
555 property with value @code{special}, then it is not used for new buffers;
556 Fundamental mode is used instead. The modes that have this property are
557 those such as Dired and Rmail that are useful only with text that has
558 been specially prepared.
561 @defun set-buffer-major-mode buffer
562 This function sets the major mode of @var{buffer} to the value of
563 @code{default-major-mode}. If that variable is @code{nil}, it uses
564 the current buffer's major mode (if that is suitable).
566 The low-level primitives for creating buffers do not use this function,
567 but medium-level commands such as @code{switch-to-buffer} and
568 @code{find-file-noselect} use it whenever they create buffers.
571 @defvar initial-major-mode
572 @cindex @samp{*scratch*}
573 The value of this variable determines the major mode of the initial
574 @samp{*scratch*} buffer. The value should be a symbol that is a major
575 mode command name. The default value is @code{lisp-interaction-mode}.
578 @defvar auto-mode-alist
579 This variable contains an association list of file name patterns
580 (regular expressions; @pxref{Regular Expressions}) and corresponding
581 major mode functions. Usually, the file name patterns test for
582 suffixes, such as @samp{.el} and @samp{.c}, but this need not be the
583 case. An ordinary element of the alist looks like @code{(@var{regexp} .
584 @var{mode-function})}.
590 (("^/tmp/fol/" . text-mode)
591 ("\\.texinfo\\'" . texinfo-mode)
592 ("\\.texi\\'" . texinfo-mode)
595 ("\\.el\\'" . emacs-lisp-mode)
602 When you visit a file whose expanded file name (@pxref{File Name
603 Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
604 corresponding @var{mode-function}. This feature enables XEmacs to select
605 the proper major mode for most files.
607 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
608 @var{function} t)}, then after calling @var{function}, XEmacs searches
609 @code{auto-mode-alist} again for a match against the portion of the file
610 name that did not match before.
612 This match-again feature is useful for uncompression packages: an entry
613 of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file
614 and then put the uncompressed file in the proper mode according to the
615 name sans @samp{.gz}.
617 Here is an example of how to prepend several pattern pairs to
618 @code{auto-mode-alist}. (You might use this sort of expression in your
623 (setq auto-mode-alist
625 ;; @r{File name starts with a dot.}
626 '(("/\\.[^/]*\\'" . fundamental-mode)
627 ;; @r{File name has no dot.}
628 ("[^\\./]*\\'" . fundamental-mode)
629 ;; @r{File name ends in @samp{.C}.}
630 ("\\.C\\'" . c++-mode))
636 @defvar interpreter-mode-alist
637 This variable specifies major modes to use for scripts that specify a
638 command interpreter in an @samp{#!} line. Its value is a list of
639 elements of the form @code{(@var{interpreter} . @var{mode})}; for
640 example, @code{("perl" . perl-mode)} is one element present by default.
641 The element says to use mode @var{mode} if the file specifies
644 This variable is applicable only when the @code{auto-mode-alist} does
645 not indicate which major mode to use.
648 @defun hack-local-variables &optional force
649 This function parses, and binds or evaluates as appropriate, any local
650 variables for the current buffer.
652 The handling of @code{enable-local-variables} documented for
653 @code{normal-mode} actually takes place here. The argument @var{force}
654 usually comes from the argument @var{find-file} given to
659 @subsection Getting Help about a Major Mode
661 @cindex help for major mode
662 @cindex documentation for major mode
664 The @code{describe-mode} function is used to provide information
665 about major modes. It is normally called with @kbd{C-h m}. The
666 @code{describe-mode} function uses the value of @code{major-mode},
667 which is why every major mode function needs to set the
668 @code{major-mode} variable.
670 @deffn Command describe-mode
671 This function displays the documentation of the current major mode.
673 The @code{describe-mode} function calls the @code{documentation}
674 function using the value of @code{major-mode} as an argument. Thus, it
675 displays the documentation string of the major mode function.
676 (@xref{Accessing Documentation}.)
680 This variable holds the symbol for the current buffer's major mode.
681 This symbol should have a function definition that is the command to
682 switch to that major mode. The @code{describe-mode} function uses the
683 documentation string of the function as the documentation of the major
688 @subsection Defining Derived Modes
690 It's often useful to define a new major mode in terms of an existing
691 one. An easy way to do this is to use @code{define-derived-mode}.
693 @defmac define-derived-mode variant parent name docstring body@dots{}
694 This construct defines @var{variant} as a major mode command, using
695 @var{name} as the string form of the mode name.
697 The new command @var{variant} is defined to call the function
698 @var{parent}, then override certain aspects of that parent mode:
702 The new mode has its own keymap, named @code{@var{variant}-map}.
703 @code{define-derived-mode} initializes this map to inherit from
704 @code{@var{parent}-map}, if it is not already set.
707 The new mode has its own syntax table, kept in the variable
708 @code{@var{variant}-syntax-table}.
709 @code{define-derived-mode} initializes this variable by copying
710 @code{@var{parent}-syntax-table}, if it is not already set.
713 The new mode has its own abbrev table, kept in the variable
714 @code{@var{variant}-abbrev-table}.
715 @code{define-derived-mode} initializes this variable by copying
716 @code{@var{parent}-abbrev-table}, if it is not already set.
719 The new mode has its own mode hook, @code{@var{variant}-hook},
720 which it runs in standard fashion as the very last thing that it does.
721 (The new mode also runs the mode hook of @var{parent} as part
722 of calling @var{parent}.)
725 In addition, you can specify how to override other aspects of
726 @var{parent} with @var{body}. The command @var{variant}
727 evaluates the forms in @var{body} after setting up all its usual
728 overrides, just before running @code{@var{variant}-hook}.
730 The argument @var{docstring} specifies the documentation string for the
731 new mode. If you omit @var{docstring}, @code{define-derived-mode}
732 generates a documentation string.
734 Here is a hypothetical example:
737 (define-derived-mode hypertext-mode
738 text-mode "Hypertext"
739 "Major mode for hypertext.
740 \\@{hypertext-mode-map@}"
741 (setq case-fold-search nil))
743 (define-key hypertext-mode-map
744 [down-mouse-3] 'do-hyper-link)
752 A @dfn{minor mode} provides features that users may enable or disable
753 independently of the choice of major mode. Minor modes can be enabled
754 individually or in combination. Minor modes would be better named
755 ``Generally available, optional feature modes'' except that such a name is
758 A minor mode is not usually a modification of single major mode. For
759 example, Auto Fill mode may be used in any major mode that permits text
760 insertion. To be general, a minor mode must be effectively independent
761 of the things major modes do.
763 A minor mode is often much more difficult to implement than a major
764 mode. One reason is that you should be able to activate and deactivate
765 minor modes in any order. A minor mode should be able to have its
766 desired effect regardless of the major mode and regardless of the other
767 minor modes in effect.
769 Often the biggest problem in implementing a minor mode is finding a
770 way to insert the necessary hook into the rest of XEmacs. Minor mode
771 keymaps make this easier than it used to be.
774 * Minor Mode Conventions:: Tips for writing a minor mode.
775 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
778 @node Minor Mode Conventions
779 @subsection Conventions for Writing Minor Modes
780 @cindex minor mode conventions
781 @cindex conventions for writing minor modes
783 There are conventions for writing minor modes just as there are for
784 major modes. Several of the major mode conventions apply to minor
785 modes as well: those regarding the name of the mode initialization
786 function, the names of global symbols, and the use of keymaps and
789 In addition, there are several conventions that are specific to
794 @cindex mode variable
795 Make a variable whose name ends in @samp{-mode} to represent the minor
796 mode. Its value should enable or disable the mode (@code{nil} to
797 disable; anything else to enable.) We call this the @dfn{mode
800 This variable is used in conjunction with the @code{minor-mode-alist} to
801 display the minor mode name in the modeline. It can also enable
802 or disable a minor mode keymap. Individual commands or hooks can also
803 check the variable's value.
805 If you want the minor mode to be enabled separately in each buffer,
806 make the variable buffer-local.
809 Define a command whose name is the same as the mode variable.
810 Its job is to enable and disable the mode by setting the variable.
812 The command should accept one optional argument. If the argument is
813 @code{nil}, it should toggle the mode (turn it on if it is off, and off
814 if it is on). Otherwise, it should turn the mode on if the argument is
815 a positive integer, a symbol other than @code{nil} or @code{-}, or a
816 list whose @sc{car} is such an integer or symbol; it should turn the
819 Here is an example taken from the definition of @code{transient-mark-mode}.
820 It shows the use of @code{transient-mark-mode} as a variable that enables or
821 disables the mode's behavior, and also shows the proper way to toggle,
822 enable or disable the minor mode based on the raw prefix argument value.
826 (setq transient-mark-mode
827 (if (null arg) (not transient-mark-mode)
828 (> (prefix-numeric-value arg) 0)))
833 Add an element to @code{minor-mode-alist} for each minor mode
834 (@pxref{Modeline Variables}). This element should be a list of the
838 (@var{mode-variable} @var{string})
841 Here @var{mode-variable} is the variable that controls enabling of the
842 minor mode, and @var{string} is a short string, starting with a space,
843 to represent the mode in the modeline. These strings must be short so
844 that there is room for several of them at once.
846 When you add an element to @code{minor-mode-alist}, use @code{assq} to
847 check for an existing element, to avoid duplication. For example:
851 (or (assq 'leif-mode minor-mode-alist)
852 (setq minor-mode-alist
853 (cons '(leif-mode " Leif") minor-mode-alist)))
858 @node Keymaps and Minor Modes
859 @subsection Keymaps and Minor Modes
861 Each minor mode can have its own keymap, which is active when the mode
862 is enabled. To set up a keymap for a minor mode, add an element to the
863 alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
865 @cindex @code{self-insert-command}, minor modes
866 One use of minor mode keymaps is to modify the behavior of certain
867 self-inserting characters so that they do something else as well as
868 self-insert. In general, this is the only way to do that, since the
869 facilities for customizing @code{self-insert-command} are limited to
870 special cases (designed for abbrevs and Auto Fill mode). (Do not try
871 substituting your own definition of @code{self-insert-command} for the
872 standard one. The editor command loop handles this function specially.)
874 @node Modeline Format
875 @section Modeline Format
878 Each Emacs window (aside from minibuffer windows) includes a modeline,
879 which displays status information about the buffer displayed in the
880 window. The modeline contains information about the buffer, such as its
881 name, associated file, depth of recursive editing, and the major and
884 This section describes how the contents of the modeline are
885 controlled. It is in the chapter on modes because much of the
886 information displayed in the modeline relates to the enabled major and
889 @code{modeline-format} is a buffer-local variable that holds a
890 template used to display the modeline of the current buffer. All
891 windows for the same buffer use the same @code{modeline-format} and
892 their modelines appear the same (except for scrolling percentages and
895 The modeline of a window is normally updated whenever a different
896 buffer is shown in the window, or when the buffer's modified-status
897 changes from @code{nil} to @code{t} or vice-versa. If you modify any of
898 the variables referenced by @code{modeline-format} (@pxref{Modeline
899 Variables}), you may want to force an update of the modeline so as to
900 display the new information.
903 @defun redraw-modeline &optional all
904 Force redisplay of the current buffer's modeline. If @var{all} is
905 non-@code{nil}, then force redisplay of all modelines.
908 The modeline is usually displayed in inverse video. This
909 is controlled using the @code{modeline} face. @xref{Faces}.
912 * Modeline Data:: The data structure that controls the modeline.
913 * Modeline Variables:: Variables used in that data structure.
914 * %-Constructs:: Putting information into a modeline.
918 @subsection The Data Structure of the Modeline
919 @cindex modeline construct
921 The modeline contents are controlled by a data structure of lists,
922 strings, symbols, and numbers kept in the buffer-local variable
923 @code{mode-line-format}. The data structure is called a @dfn{modeline
924 construct}, and it is built in recursive fashion out of simpler modeline
925 constructs. The same data structure is used for constructing
926 frame titles (@pxref{Frame Titles}).
928 @defvar modeline-format
929 The value of this variable is a modeline construct with overall
930 responsibility for the modeline format. The value of this variable
931 controls which other variables are used to form the modeline text, and
935 A modeline construct may be as simple as a fixed string of text, but
936 it usually specifies how to use other variables to construct the text.
937 Many of these variables are themselves defined to have modeline
938 constructs as their values.
940 The default value of @code{modeline-format} incorporates the values
941 of variables such as @code{mode-name} and @code{minor-mode-alist}.
942 Because of this, very few modes need to alter @code{modeline-format}.
943 For most purposes, it is sufficient to alter the variables referenced by
944 @code{modeline-format}.
946 A modeline construct may be a list, a symbol, or a string. If the
947 value is a list, each element may be a list, a symbol, or a string.
950 @cindex percent symbol in modeline
952 A string as a modeline construct is displayed verbatim in the mode line
953 except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
954 specify the field width for space filling on the right (i.e., the data
955 is left justified). @xref{%-Constructs}.
958 A symbol as a modeline construct stands for its value. The value of
959 @var{symbol} is used as a modeline construct, in place of @var{symbol}.
960 However, the symbols @code{t} and @code{nil} are ignored; so is any
961 symbol whose value is void.
963 There is one exception: if the value of @var{symbol} is a string, it is
964 displayed verbatim: the @code{%}-constructs are not recognized.
966 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
967 A list whose first element is a string or list means to process all the
968 elements recursively and concatenate the results. This is the most
969 common form of mode line construct.
971 @item (@var{symbol} @var{then} @var{else})
972 A list whose first element is a symbol is a conditional. Its meaning
973 depends on the value of @var{symbol}. If the value is non-@code{nil},
974 the second element, @var{then}, is processed recursively as a modeline
975 element. But if the value of @var{symbol} is @code{nil}, the third
976 element, @var{else}, is processed recursively. You may omit @var{else};
977 then the mode line element displays nothing if the value of @var{symbol}
980 @item (@var{width} @var{rest}@dots{})
981 A list whose first element is an integer specifies truncation or
982 padding of the results of @var{rest}. The remaining elements
983 @var{rest} are processed recursively as modeline constructs and
984 concatenated together. Then the result is space filled (if
985 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
986 if @var{width} is negative) on the right.
988 For example, the usual way to show what percentage of a buffer is above
989 the top of the window is to use a list like this: @code{(-3 "%p")}.
992 If you do alter @code{modeline-format} itself, the new value should
993 use the same variables that appear in the default value (@pxref{Modeline
994 Variables}), rather than duplicating their contents or displaying
995 the information in another fashion. This way, customizations made by
996 the user or by Lisp programs (such as @code{display-time} and major
997 modes) via changes to those variables remain effective.
999 @cindex Shell mode @code{modeline-format}
1000 Here is an example of a @code{modeline-format} that might be
1001 useful for @code{shell-mode}, since it contains the hostname and default
1006 (setq modeline-format
1011 (getenv "HOST") ; @r{One element is not constant.}
1023 '(line-number-mode "L%l--")
1029 @node Modeline Variables
1030 @subsection Variables Used in the Modeline
1032 This section describes variables incorporated by the
1033 standard value of @code{modeline-format} into the text of the mode
1034 line. There is nothing inherently special about these variables; any
1035 other variables could have the same effects on the modeline if
1036 @code{modeline-format} were changed to use them.
1038 @defvar modeline-modified
1039 This variable holds the value of the modeline construct that displays
1040 whether the current buffer is modified.
1042 The default value of @code{modeline-modified} is @code{("--%1*%1+-")}.
1043 This means that the modeline displays @samp{--**-} if the buffer is
1044 modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
1045 the buffer is read only, and @samp{--%*--} if the buffer is read only
1048 Changing this variable does not force an update of the modeline.
1051 @defvar modeline-buffer-identification
1052 This variable identifies the buffer being displayed in the window. Its
1053 default value is @code{("%F: %17b")}, which means that it usually
1054 displays @samp{Emacs:} followed by seventeen characters of the buffer
1055 name. (In a terminal frame, it displays the frame name instead of
1056 @samp{Emacs}; this has the effect of showing the frame number.) You may
1057 want to change this in modes such as Rmail that do not behave like a
1061 @defvar global-mode-string
1062 This variable holds a modeline spec that appears in the mode line by
1063 default, just after the buffer name. The command @code{display-time}
1064 sets @code{global-mode-string} to refer to the variable
1065 @code{display-time-string}, which holds a string containing the time and
1068 The @samp{%M} construct substitutes the value of
1069 @code{global-mode-string}, but this is obsolete, since the variable is
1070 included directly in the modeline.
1074 This buffer-local variable holds the ``pretty'' name of the current
1075 buffer's major mode. Each major mode should set this variable so that the
1076 mode name will appear in the modeline.
1079 @defvar minor-mode-alist
1080 This variable holds an association list whose elements specify how the
1081 modeline should indicate that a minor mode is active. Each element of
1082 the @code{minor-mode-alist} should be a two-element list:
1085 (@var{minor-mode-variable} @var{modeline-string})
1088 More generally, @var{modeline-string} can be any mode line spec. It
1089 appears in the mode line when the value of @var{minor-mode-variable} is
1090 non-@code{nil}, and not otherwise. These strings should begin with
1091 spaces so that they don't run together. Conventionally, the
1092 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
1093 value when that minor mode is activated.
1095 The default value of @code{minor-mode-alist} is:
1100 @result{} ((vc-mode vc-mode)
1101 (abbrev-mode " Abbrev")
1102 (overwrite-mode overwrite-mode)
1103 (auto-fill-function " Fill")
1104 (defining-kbd-macro " Def")
1105 (isearch-mode isearch-mode))
1109 @code{minor-mode-alist} is not buffer-local. The variables mentioned
1110 in the alist should be buffer-local if the minor mode can be enabled
1111 separately in each buffer.
1114 @defvar modeline-process
1115 This buffer-local variable contains the modeline information on process
1116 status in modes used for communicating with subprocesses. It is
1117 displayed immediately following the major mode name, with no intervening
1118 space. For example, its value in the @samp{*shell*} buffer is
1119 @code{(":@: %s")}, which allows the shell to display its status along
1120 with the major mode as: @samp{(Shell:@: run)}. Normally this variable
1124 @defvar default-modeline-format
1125 This variable holds the default @code{modeline-format} for buffers
1126 that do not override it. This is the same as @code{(default-value
1129 The default value of @code{default-modeline-format} is:
1135 modeline-buffer-identification
1146 (line-number-mode "L%l--")
1154 The variable @code{vc-mode}, local in each buffer, records whether the
1155 buffer's visited file is maintained with version control, and, if so,
1156 which kind. Its value is @code{nil} for no version control, or a string
1157 that appears in the mode line.
1161 @subsection @code{%}-Constructs in the ModeLine
1163 The following table lists the recognized @code{%}-constructs and what
1164 they mean. In any construct except @samp{%%}, you can add a decimal
1165 integer after the @samp{%} to specify how many characters to display.
1169 The current buffer name, obtained with the @code{buffer-name} function.
1170 @xref{Buffer Names}.
1173 The visited file name, obtained with the @code{buffer-file-name}
1174 function. @xref{Buffer File Name}.
1177 The name of the selected frame.
1180 The current column number of point.
1183 The current line number of point.
1186 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1187 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1188 @samp{-} otherwise. @xref{Buffer Modification}.
1191 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1192 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1193 @samp{-} otherwise. This differs from @samp{%*} only for a modified
1194 read-only buffer. @xref{Buffer Modification}.
1197 @samp{*} if the buffer is modified, and @samp{-} otherwise.
1200 The status of the subprocess belonging to the current buffer, obtained with
1201 @code{process-status}. @xref{Process Information}.
1203 @c The following two may only apply in XEmacs.
1205 the current line number.
1208 the name of the selected frame; this is only meaningful under the
1209 X Window System. @xref{Frame Name}.
1212 Whether the visited file is a text file or a binary file. (This is a
1213 meaningful distinction only on certain operating systems.)
1216 The percentage of the buffer text above the @strong{top} of window, or
1217 @samp{Top}, @samp{Bottom} or @samp{All}.
1220 The percentage of the buffer text that is above the @strong{bottom} of
1221 the window (which includes the text visible in the window, as well as
1222 the text above the top), plus @samp{Top} if the top of the buffer is
1223 visible on screen; or @samp{Bottom} or @samp{All}.
1226 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1227 @code{narrow-to-region} in @ref{Narrowing}).
1230 An indication of the depth of recursive editing levels (not counting
1231 minibuffer levels): one @samp{[} for each editing level.
1232 @xref{Recursive Editing}.
1235 One @samp{]} for each recursive editing level (not counting minibuffer
1239 The character @samp{%}---this is how to include a literal @samp{%} in a
1240 string in which @code{%}-constructs are allowed.
1243 Dashes sufficient to fill the remainder of the modeline.
1246 The following two @code{%}-constructs are still supported, but they are
1247 obsolete, since you can get the same results with the variables
1248 @code{mode-name} and @code{global-mode-string}.
1252 The value of @code{mode-name}.
1255 The value of @code{global-mode-string}. Currently, only
1256 @code{display-time} modifies the value of @code{global-mode-string}.
1263 A @dfn{hook} is a variable where you can store a function or functions
1264 to be called on a particular occasion by an existing program. XEmacs
1265 provides hooks for the sake of customization. Most often, hooks are set
1266 up in the @file{.emacs} file, but Lisp programs can set them also.
1267 @xref{Standard Hooks}, for a list of standard hook variables.
1269 Most of the hooks in XEmacs are @dfn{normal hooks}. These variables
1270 contain lists of functions to be called with no arguments. The reason
1271 most hooks are normal hooks is so that you can use them in a uniform
1272 way. You can usually tell when a hook is a normal hook, because its
1273 name ends in @samp{-hook}.
1275 The recommended way to add a hook function to a normal hook is by
1276 calling @code{add-hook} (see below). The hook functions may be any of
1277 the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
1278 a Function}). Most normal hook variables are initially void;
1279 @code{add-hook} knows how to deal with this.
1281 As for abnormal hooks, those whose names end in @samp{-function} have
1282 a value that is a single function. Those whose names end in
1283 @samp{-hooks} have a value that is a list of functions. Any hook that
1284 is abnormal is abnormal because a normal hook won't do the job; either
1285 the functions are called with arguments, or their values are meaningful.
1286 The name shows you that the hook is abnormal and that you should look at
1287 its documentation string to see how to use it properly.
1289 Major mode functions are supposed to run a hook called the @dfn{mode
1290 hook} as the last step of initialization. This makes it easy for a user
1291 to customize the behavior of the mode, by overriding the local variable
1292 assignments already made by the mode. But hooks are used in other
1293 contexts too. For example, the hook @code{suspend-hook} runs just
1294 before XEmacs suspends itself (@pxref{Suspending XEmacs}).
1296 Here's an expression that uses a mode hook to turn on Auto Fill mode
1297 when in Lisp Interaction mode:
1300 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
1303 The next example shows how to use a hook to customize the way XEmacs
1304 formats C code. (People often have strong personal preferences for one
1305 format or another.) Here the hook function is an anonymous lambda
1308 @cindex lambda expression in hook
1311 (add-hook 'c-mode-hook
1312 (function (lambda ()
1313 (setq c-indent-level 4
1318 c-continued-statement-indent 0
1320 comment-column 40))))
1322 (setq c++-mode-hook c-mode-hook)
1326 The final example shows how the appearance of the modeline can be
1327 modified for a particular class of buffers only.
1331 (add-hook 'text-mode-hook
1332 (function (lambda ()
1333 (setq modeline-format
1353 At the appropriate time, XEmacs uses the @code{run-hooks} function to
1354 run particular hooks. This function calls the hook functions you have
1355 added with @code{add-hooks}.
1357 @defun run-hooks &rest hookvar
1358 This function takes one or more hook variable names as arguments, and
1359 runs each hook in turn. Each @var{hookvar} argument should be a symbol
1360 that is a hook variable. These arguments are processed in the order
1363 If a hook variable has a non-@code{nil} value, that value may be a
1364 function or a list of functions. If the value is a function (either a
1365 lambda expression or a symbol with a function definition), it is
1366 called. If it is a list, the elements are called, in order.
1367 The hook functions are called with no arguments.
1369 For example, here's how @code{emacs-lisp-mode} runs its mode hook:
1372 (run-hooks 'emacs-lisp-mode-hook)
1376 @defun add-hook hook function &optional append local
1377 This function is the handy way to add function @var{function} to hook
1378 variable @var{hook}. The argument @var{function} may be any valid Lisp
1379 function with the proper number of arguments. For example,
1382 (add-hook 'text-mode-hook 'my-text-hook-function)
1386 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
1388 You can use @code{add-hook} for abnormal hooks as well as for normal
1391 It is best to design your hook functions so that the order in which they
1392 are executed does not matter. Any dependence on the order is ``asking
1393 for trouble.'' However, the order is predictable: normally,
1394 @var{function} goes at the front of the hook list, so it will be
1395 executed first (barring another @code{add-hook} call).
1397 If the optional argument @var{append} is non-@code{nil}, the new hook
1398 function goes at the end of the hook list and will be executed last.
1400 If @var{local} is non-@code{nil}, that says to make the new hook
1401 function local to the current buffer. Before you can do this, you must
1402 make the hook itself buffer-local by calling @code{make-local-hook}
1403 (@strong{not} @code{make-local-variable}). If the hook itself is not
1404 buffer-local, then the value of @var{local} makes no difference---the
1405 hook function is always global.
1408 @defun remove-hook hook function &optional local
1409 This function removes @var{function} from the hook variable @var{hook}.
1411 If @var{local} is non-@code{nil}, that says to remove @var{function}
1412 from the local hook list instead of from the global hook list. If the
1413 hook itself is not buffer-local, then the value of @var{local} makes no
1417 @defun make-local-hook hook
1418 This function makes the hook variable @code{hook} local to the current
1419 buffer. When a hook variable is local, it can have local and global
1420 hook functions, and @code{run-hooks} runs all of them.
1422 This function works by making @code{t} an element of the buffer-local
1423 value. That serves as a flag to use the hook functions in the default
1424 value of the hook variable as well as those in the local value. Since
1425 @code{run-hooks} understands this flag, @code{make-local-hook} works
1426 with all normal hooks. It works for only some non-normal hooks---those
1427 whose callers have been updated to understand this meaning of @code{t}.
1429 Do not use @code{make-local-variable} directly for hook variables; it is