modes.texi 94.8 KB
Newer Older
Richard M. Stallman's avatar
Richard M. Stallman committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
3
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
4
@c   Free Software Foundation, Inc.
Richard M. Stallman's avatar
Richard M. Stallman committed
5 6
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
7
@node Modes, Documentation, Keymaps, Top
Richard M. Stallman's avatar
Richard M. Stallman committed
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
@chapter Major and Minor Modes
@cindex mode

  A @dfn{mode} is a set of definitions that customize Emacs and can be
turned on and off while you edit.  There are two varieties of modes:
@dfn{major modes}, which are mutually exclusive and used for editing
particular kinds of text, and @dfn{minor modes}, which provide features
that users can enable individually.

  This chapter describes how to write both major and minor modes, how to
indicate them in the mode line, and how they run hooks supplied by the
user.  For related topics such as keymaps and syntax tables, see
@ref{Keymaps}, and @ref{Syntax Tables}.

@menu
* Major Modes::        Defining major modes.
* Minor Modes::        Defining minor modes.
* Mode Line Format::   Customizing the text that appears in the mode line.
26 27 28
* Imenu::              How a mode can provide a menu
                         of definitions in the buffer.
* Font Lock Mode::     How modes can highlight text according to syntax.
Richard M. Stallman's avatar
Richard M. Stallman committed
29 30 31 32 33 34 35 36 37
* Hooks::              How to use hooks; how to write code that provides hooks.
@end menu

@node Major Modes
@section Major Modes
@cindex major mode
@cindex Fundamental mode

  Major modes specialize Emacs for editing particular kinds of text.
38 39 40 41 42 43
Each buffer has only one major mode at a time.  For each major mode
there is a function to switch to that mode in the current buffer; its
name should end in @samp{-mode}.  These functions work by setting
buffer-local variable bindings and other data associated with the
buffer, such as a local keymap.  The effect lasts until you switch
to another major mode in the same buffer.
Richard M. Stallman's avatar
Richard M. Stallman committed
44 45 46 47 48 49

  The least specialized major mode is called @dfn{Fundamental mode}.
This mode has no mode-specific definitions or variable settings, so each
Emacs command behaves in its default manner, and each option is in its
default state.  All other major modes redefine various keys and options.
For example, Lisp Interaction mode provides special key bindings for
50
@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
Richard M. Stallman's avatar
Richard M. Stallman committed
51 52 53 54 55 56 57 58 59 60 61 62
(@code{lisp-indent-line}), and other keys.

  When you need to write several editing commands to help you perform a
specialized editing task, creating a new major mode is usually a good
idea.  In practice, writing a major mode is easy (in contrast to
writing a minor mode, which is often difficult).

  If the new mode is similar to an old one, it is often unwise to modify
the old one to serve two purposes, since it may become harder to use and
maintain.  Instead, copy and rename an existing major mode definition
and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
Modes}).  For example, Rmail Edit mode, which is in
Phillip Rulon's avatar
Phillip Rulon committed
63 64 65
@file{emacs/lisp/mail/rmailedit.el}, is a major mode that is very similar to
Text mode except that it provides two additional commands.  Its
definition is distinct from that of Text mode, but uses that of Text mode.
Richard M. Stallman's avatar
Richard M. Stallman committed
66

67
  Even if the new mode is not an obvious derivative of any other mode,
68 69 70
it is convenient to use @code{define-derived-mode} with a @code{nil}
parent argument, since it automatically enforces the most important
coding conventions for you.
71

72 73 74 75 76
@findex define-generic-mode
  For a very simple programming language major mode that handles
comments and fontification, you can use @code{define-generic-mode}
in @file{generic.el}.

77 78
  Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
79
ordinary Emacs commands rather than Rmail commands).  In such cases, the
80
temporary major mode usually provides a command to switch back to the
81 82 83 84 85 86
buffer's usual mode (Rmail mode, in this case).  You might be tempted to
present the temporary redefinitions inside a recursive edit and restore
the usual ones when the user exits; but this is a bad idea because it
constrains the user's options when it is done in more than one buffer:
recursive edits must be exited most-recently-entered first.  Using an
alternative major mode avoids this limitation.  @xref{Recursive
Richard M. Stallman's avatar
Richard M. Stallman committed
87 88
Editing}.

89 90
  The standard GNU Emacs Lisp library directory tree contains the code
for several major modes, in files such as @file{text-mode.el},
Richard M. Stallman's avatar
Richard M. Stallman committed
91
@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
Phillip Rulon's avatar
Phillip Rulon committed
92 93 94
@file{rmail.el}.  They are found in various subdirectories of the
@file{lisp} directory.  You can study these libraries to see how modes
are written.  Text mode is perhaps the simplest major mode aside from
Richard M. Stallman's avatar
Richard M. Stallman committed
95 96 97 98 99 100 101
Fundamental mode.  Rmail mode is a complicated and specialized mode.

@menu
* Major Mode Conventions::  Coding conventions for keymaps, etc.
* Example Major Modes::     Text mode and Lisp modes.
* Auto Major Mode::         How Emacs chooses the major mode automatically.
* Mode Help::               Finding out how to use a mode.
102
* Derived Modes::           Defining a new major mode based on another major
Richard M. Stallman's avatar
Richard M. Stallman committed
103 104 105 106 107 108 109 110 111
                              mode.
@end menu

@node Major Mode Conventions
@subsection Major Mode Conventions

  The code for existing major modes follows various coding conventions,
including conventions for local keymap and syntax table initialization,
global names, and hooks.  Please follow these conventions when you
112 113 114 115 116 117 118 119
define a new major mode.

  This list of conventions is only partial, because each major mode
should aim for consistency in general with other Emacs major modes.
This makes Emacs as a whole more coherent.  It is impossible to list
here all the possible points where this issue might come up; if the
Emacs developers point out an area where your major mode deviates from
the usual conventions, please make it compatible.
Richard M. Stallman's avatar
Richard M. Stallman committed
120 121 122 123 124

@itemize @bullet
@item
Define a command whose name ends in @samp{-mode}, with no arguments,
that switches to the new mode in the current buffer.  This command
125 126
should set up the keymap, syntax table, and buffer-local variables in an
existing buffer, without changing the buffer's contents.
Richard M. Stallman's avatar
Richard M. Stallman committed
127 128

@item
129
Write a documentation string for this command that describes the
Richard M. Stallman's avatar
Richard M. Stallman committed
130 131 132 133 134
special commands available in this mode.  @kbd{C-h m}
(@code{describe-mode}) in your mode will display this string.

The documentation string may include the special documentation
substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
Karl Heuer's avatar
Karl Heuer committed
135
@samp{\<@var{keymap}>}, which enable the documentation to adapt
Richard M. Stallman's avatar
Richard M. Stallman committed
136 137 138 139 140
automatically to the user's own key bindings.  @xref{Keys in
Documentation}.

@item
The major mode command should start by calling
141 142
@code{kill-all-local-variables}.  This is what gets rid of the
buffer-local variables of the major mode previously in effect.
Richard M. Stallman's avatar
Richard M. Stallman committed
143 144 145 146 147 148 149 150

@item
The major mode command should set the variable @code{major-mode} to the
major mode command symbol.  This is how @code{describe-mode} discovers
which documentation to print.

@item
The major mode command should set the variable @code{mode-name} to the
151 152
``pretty'' name of the mode, as a string.  This string appears in the
mode line.
Richard M. Stallman's avatar
Richard M. Stallman committed
153 154 155 156 157 158

@item
@cindex functions in modes
Since all global names are in the same name space, all the global
variables, constants, and functions that are part of the mode should
have names that start with the major mode name (or with an abbreviation
159
of it if the name is long).  @xref{Coding Conventions}.
Richard M. Stallman's avatar
Richard M. Stallman committed
160

161 162 163 164 165 166 167
@item
In a major mode for editing some kind of structured text, such as a
programming language, indentation of text according to structure is
probably useful.  So the mode should set @code{indent-line-function}
to a suitable function, and probably customize other variables
for indentation.

Richard M. Stallman's avatar
Richard M. Stallman committed
168 169 170
@item
@cindex keymaps in modes
The major mode should usually have its own keymap, which is used as the
171 172 173
local keymap in all buffers in that mode.  The major mode command should
call @code{use-local-map} to install this local map.  @xref{Active
Keymaps}, for more information.
Richard M. Stallman's avatar
Richard M. Stallman committed
174

175
This keymap should be stored permanently in a global variable named
Richard M. Stallman's avatar
Richard M. Stallman committed
176
@code{@var{modename}-mode-map}.  Normally the library that defines the
177
mode sets this variable.
Richard M. Stallman's avatar
Richard M. Stallman committed
178

179 180 181
@xref{Tips for Defining}, for advice about how to write the code to set
up the mode's keymap variable.

182 183
@item
The key sequences bound in a major mode keymap should usually start with
184
@kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}.  The other punctuation
characters are reserved for minor modes, and ordinary letters are
reserved for users.

It is reasonable for a major mode to rebind a key sequence with a
standard meaning, if it implements a command that does ``the same job''
in a way that fits the major mode better.  For example, a major mode for
editing a programming language might redefine @kbd{C-M-a} to ``move to
the beginning of a function'' in a way that works better for that
language.

Major modes such as Dired or Rmail that do not allow self-insertion of
text can reasonably redefine letters and other printing characters as
editing commands.  Dired and Rmail both do this.

200 201 202
@item
Major modes must not define @key{RET} to do anything other than insert
a newline.  The command to insert a newline and then indent is
203 204 205 206 207 208 209 210
@kbd{C-j}.  Please keep this distinction uniform for all major modes.

@item
Major modes should not alter options that are primary a matter of user
preference, such as whether Auto-Fill mode is enabled.  Leave this to
each user to decide.  However, a major mode should customize other
variables so that Auto-Fill mode will work usefully @emph{if} the user
decides to use it.
211

Richard M. Stallman's avatar
Richard M. Stallman committed
212 213 214 215
@item
@cindex syntax tables in modes
The mode may have its own syntax table or may share one with other
related modes.  If it has its own syntax table, it should store this in
216
a variable named @code{@var{modename}-mode-syntax-table}.  @xref{Syntax
Richard M. Stallman's avatar
Richard M. Stallman committed
217 218
Tables}.

219 220 221 222 223
@item
If the mode handles a language that has a syntax for comments, it should
set the variables that define the comment syntax.  @xref{Options for
Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.

Richard M. Stallman's avatar
Richard M. Stallman committed
224 225 226 227 228 229 230
@item
@cindex abbrev tables in modes
The mode may have its own abbrev table or may share one with other
related modes.  If it has its own abbrev table, it should store this in
a variable named @code{@var{modename}-mode-abbrev-table}.  @xref{Abbrev
Tables}.

231 232 233
@item
The mode should specify how to do highlighting for Font Lock mode, by
setting up a buffer-local value for the variable
234
@code{font-lock-defaults} (@pxref{Font Lock Mode}).
235 236 237 238 239

@item
The mode should specify how Imenu should find the definitions or
sections of a buffer, by setting up a buffer-local value for the
variable @code{imenu-generic-expression} or
240
@code{imenu-create-index-function} (@pxref{Imenu}).
241

242
@item
243 244 245
Use @code{defvar} or @code{defcustom} to set mode-related variables, so
that they are not reinitialized if they already have a value.  (Such
reinitialization could discard customizations made by the user.)
246

Richard M. Stallman's avatar
Richard M. Stallman committed
247 248 249 250 251 252 253 254 255
@item
@cindex buffer-local variables in modes
To make a buffer-local binding for an Emacs customization variable, use
@code{make-local-variable} in the major mode command, not
@code{make-variable-buffer-local}.  The latter function would make the
variable local to every buffer in which it is subsequently set, which
would affect buffers that do not use this mode.  It is undesirable for a
mode to have such global effects.  @xref{Buffer-Local Variables}.

256
With rare exceptions, the only reasonable way to use
Phillip Rulon's avatar
Phillip Rulon committed
257 258 259
@code{make-variable-buffer-local} in a Lisp package is for a variable
which is used only within that package.  Using it on a variable used by
other packages would interfere with them.
Richard M. Stallman's avatar
Richard M. Stallman committed
260 261 262 263 264 265

@item
@cindex mode hook
@cindex major mode hook
Each major mode should have a @dfn{mode hook} named
@code{@var{modename}-mode-hook}.  The major mode command should run that
266
hook, with @code{run-mode-hooks}, as the very last thing it
267
does.  @xref{Hooks}.
Richard M. Stallman's avatar
Richard M. Stallman committed
268 269

@item
270 271 272 273 274 275 276 277
The major mode command may start by calling some other major mode
command (called the @dfn{parent mode}) and then alter some of its
settings.  A mode that does this is called a @dfn{derived mode}.  The
recommended way to define one is to use @code{define-derived-mode},
but this is not required.  Such a mode should use
@code{delay-mode-hooks} around its entire body, including the call to
the parent mode command and the final call to @code{run-mode-hooks}.
(Using @code{define-derived-mode} does this automatically.) 
Richard M. Stallman's avatar
Richard M. Stallman committed
278 279 280

@item
If something special should be done if the user switches a buffer from
281
this mode to any other major mode, this mode can set up a buffer-local
282
value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
Richard M. Stallman's avatar
Richard M. Stallman committed
283 284 285 286 287 288

@item
If this mode is appropriate only for specially-prepared text, then the
major mode command symbol should have a property named @code{mode-class}
with value @code{special}, put on as follows:

289
@kindex mode-class @r{(property)}
Richard M. Stallman's avatar
Richard M. Stallman committed
290 291 292 293 294 295
@cindex @code{special}
@example
(put 'funny-mode 'mode-class 'special)
@end example

@noindent
296
This tells Emacs that new buffers created while the current buffer is in
Richard M. Stallman's avatar
Richard M. Stallman committed
297 298 299 300 301 302 303 304 305 306 307 308 309 310
Funny mode should not inherit Funny mode.  Modes such as Dired, Rmail,
and Buffer List use this feature.

@item
If you want to make the new mode the default for files with certain
recognizable names, add an element to @code{auto-mode-alist} to select
the mode for those file names.  If you define the mode command to
autoload, you should add this element in the same file that calls
@code{autoload}.  Otherwise, it is sufficient to add the element in the
file that contains the mode definition.  @xref{Auto Major Mode}.

@item
In the documentation, you should provide a sample @code{autoload} form
and an example of how to add to @code{auto-mode-alist}, that users can
Phillip Rulon's avatar
Phillip Rulon committed
311
include in their init files (@pxref{Init File}).
Richard M. Stallman's avatar
Richard M. Stallman committed
312 313 314

@item
@cindex mode loading
315
The top-level forms in the file defining the mode should be written so
Richard M. Stallman's avatar
Richard M. Stallman committed
316 317 318 319 320 321 322 323 324 325 326 327 328 329
that they may be evaluated more than once without adverse consequences.
Even if you never load the file more than once, someone else will.
@end itemize

@node Example Major Modes
@subsection Major Mode Examples

  Text mode is perhaps the simplest mode besides Fundamental mode.
Here are excerpts from  @file{text-mode.el} that illustrate many of
the conventions listed above:

@smallexample
@group
;; @r{Create mode-specific tables.}
330
(defvar text-mode-syntax-table nil
Richard M. Stallman's avatar
Richard M. Stallman committed
331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349
  "Syntax table used while in text mode.")
@end group

@group
(if text-mode-syntax-table
    ()              ; @r{Do not change the table if it is already set up.}
  (setq text-mode-syntax-table (make-syntax-table))
  (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
  (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
  (modify-syntax-entry ?' "w   " text-mode-syntax-table))
@end group

@group
(defvar text-mode-abbrev-table nil
  "Abbrev table used while in text mode.")
(define-abbrev-table 'text-mode-abbrev-table ())
@end group

@group
Phillip Rulon's avatar
Phillip Rulon committed
350 351 352 353
(defvar text-mode-map nil    ; @r{Create a mode-specific keymap.}
  "Keymap for Text mode.
Many other modes, such as Mail mode, Outline mode and Indented Text mode,
inherit all the commands defined in this map.")
Richard M. Stallman's avatar
Richard M. Stallman committed
354 355 356 357

(if text-mode-map
    ()              ; @r{Do not change the keymap if it is already set up.}
  (setq text-mode-map (make-sparse-keymap))
Phillip Rulon's avatar
Phillip Rulon committed
358
  (define-key text-mode-map "\e\t" 'ispell-complete-word)
359
  (define-key text-mode-map "\t" 'indent-relative)
Richard M. Stallman's avatar
Richard M. Stallman committed
360 361 362 363 364
  (define-key text-mode-map "\es" 'center-line)
  (define-key text-mode-map "\eS" 'center-paragraph))
@end group
@end smallexample

365
  This was formerly the complete major mode function definition for Text mode:
Richard M. Stallman's avatar
Richard M. Stallman committed
366 367 368 369

@smallexample
@group
(defun text-mode ()
370
  "Major mode for editing text intended for humans to read...
Richard M. Stallman's avatar
Richard M. Stallman committed
371 372 373 374 375 376
 Special commands: \\@{text-mode-map@}
@end group
@group
Turning on text-mode runs the hook `text-mode-hook'."
  (interactive)
  (kill-all-local-variables)
377
  (use-local-map text-mode-map)
Richard M. Stallman's avatar
Richard M. Stallman committed
378 379 380 381
@end group
@group
  (setq local-abbrev-table text-mode-abbrev-table)
  (set-syntax-table text-mode-syntax-table)
382 383 384 385 386 387
@end group
@group
  (make-local-variable 'paragraph-start)
  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
  (make-local-variable 'paragraph-separate)
  (setq paragraph-separate paragraph-start)
Phillip Rulon's avatar
Phillip Rulon committed
388 389
  (make-local-variable 'indent-line-function)
  (setq indent-line-function 'indent-relative-maybe)
390 391 392 393
@end group
@group
  (setq mode-name "Text")
  (setq major-mode 'text-mode)
394
  (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
Richard M. Stallman's avatar
Richard M. Stallman committed
395 396 397 398 399 400 401 402 403 404 405 406 407 408
                                    ;   @r{customize the mode with a hook.}
@end group
@end smallexample

@cindex @file{lisp-mode.el}
  The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
Interaction mode) have more features than Text mode and the code is
correspondingly more complicated.  Here are excerpts from
@file{lisp-mode.el} that illustrate how these modes are written.

@cindex syntax table example
@smallexample
@group
;; @r{Create mode-specific table variables.}
409
(defvar lisp-mode-syntax-table nil "")
Richard M. Stallman's avatar
Richard M. Stallman committed
410 411 412 413 414 415 416 417 418 419 420 421 422 423
(defvar emacs-lisp-mode-syntax-table nil "")
(defvar lisp-mode-abbrev-table nil "")
@end group

@group
(if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
                                       ;   @r{if it is already set.}
    (let ((i 0))
      (setq emacs-lisp-mode-syntax-table (make-syntax-table))
@end group

@group
      ;; @r{Set syntax of chars up to 0 to class of chars that are}
      ;;   @r{part of symbol names but not words.}
424
      ;;   @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
425
      (while (< i ?0)
Richard M. Stallman's avatar
Richard M. Stallman committed
426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452
        (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
        (setq i (1+ i)))
      @dots{}
@end group
@group
      ;; @r{Set the syntax for other characters.}
      (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
      (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
      @dots{}
@end group
@group
      (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
      (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
      @dots{}))
;; @r{Create an abbrev table for lisp-mode.}
(define-abbrev-table 'lisp-mode-abbrev-table ())
@end group
@end smallexample

  Much code is shared among the three Lisp modes.  The following
function sets various variables; it is called by each of the major Lisp
mode functions:

@smallexample
@group
(defun lisp-mode-variables (lisp-syntax)
  (cond (lisp-syntax
453
	  (set-syntax-table lisp-mode-syntax-table)))
Richard M. Stallman's avatar
Richard M. Stallman committed
454
  (setq local-abbrev-table lisp-mode-abbrev-table)
455
  @dots{}
Richard M. Stallman's avatar
Richard M. Stallman committed
456 457 458 459 460 461 462 463 464 465 466 467 468 469
@end group
@end smallexample

  Functions such as @code{forward-paragraph} use the value of the
@code{paragraph-start} variable.  Since Lisp code is different from
ordinary text, the @code{paragraph-start} variable needs to be set
specially to handle Lisp.  Also, comments are indented in a special
fashion in Lisp and the Lisp modes need their own mode-specific
@code{comment-indent-function}.  The code to set these variables is the
rest of @code{lisp-mode-variables}.

@smallexample
@group
  (make-local-variable 'paragraph-start)
470 471 472
  (setq paragraph-start (concat page-delimiter "\\|$" ))
  (make-local-variable 'paragraph-separate)
  (setq paragraph-separate paragraph-start)
Richard M. Stallman's avatar
Richard M. Stallman committed
473 474 475 476 477
  @dots{}
@end group
@group
  (make-local-variable 'comment-indent-function)
  (setq comment-indent-function 'lisp-comment-indent))
Phillip Rulon's avatar
Phillip Rulon committed
478
  @dots{}
Richard M. Stallman's avatar
Richard M. Stallman committed
479 480 481 482
@end group
@end smallexample

  Each of the different Lisp modes has a slightly different keymap.  For
483
example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
Richard M. Stallman's avatar
Richard M. Stallman committed
484
Lisp modes do not.  However, all Lisp modes have some commands in
485
common.  The following code sets up the common commands:
Richard M. Stallman's avatar
Richard M. Stallman committed
486 487 488

@smallexample
@group
489 490 491 492 493 494 495 496 497
(defvar shared-lisp-mode-map ()
  "Keymap for commands shared by all sorts of Lisp modes.")

(if shared-lisp-mode-map
    ()
   (setq shared-lisp-mode-map (make-sparse-keymap))
   (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
   (define-key shared-lisp-mode-map "\177"
               'backward-delete-char-untabify))
Richard M. Stallman's avatar
Richard M. Stallman committed
498 499 500
@end group
@end smallexample

501 502
@noindent
And here is the code to set up the keymap for Lisp mode:
Richard M. Stallman's avatar
Richard M. Stallman committed
503 504 505

@smallexample
@group
506
(defvar lisp-mode-map ()
507
  "Keymap for ordinary Lisp mode...")
508 509

(if lisp-mode-map
Richard M. Stallman's avatar
Richard M. Stallman committed
510
    ()
511 512 513 514
  (setq lisp-mode-map (make-sparse-keymap))
  (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
  (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
  (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
Richard M. Stallman's avatar
Richard M. Stallman committed
515 516 517 518
@end group
@end smallexample

  Finally, here is the complete major mode function definition for
519
Lisp mode.
Richard M. Stallman's avatar
Richard M. Stallman committed
520 521 522

@smallexample
@group
523 524
(defun lisp-mode ()
  "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
Richard M. Stallman's avatar
Richard M. Stallman committed
525 526 527
Commands:
Delete converts tabs to spaces as it moves back.
Blank lines separate paragraphs.  Semicolons start comments.
528 529 530
\\@{lisp-mode-map@}
Note that `run-lisp' may be used either to start an inferior Lisp job
or to switch back to an existing one.
Richard M. Stallman's avatar
Richard M. Stallman committed
531
@end group
532

Richard M. Stallman's avatar
Richard M. Stallman committed
533
@group
534 535
Entry to this mode calls the value of `lisp-mode-hook'
if that value is non-nil."
Richard M. Stallman's avatar
Richard M. Stallman committed
536 537 538 539
  (interactive)
  (kill-all-local-variables)
@end group
@group
540 541
  (use-local-map lisp-mode-map)          ; @r{Select the mode's keymap.}
  (setq major-mode 'lisp-mode)           ; @r{This is how @code{describe-mode}}
Richard M. Stallman's avatar
Richard M. Stallman committed
542
                                         ;   @r{finds out what to describe.}
543 544 545 546 547 548
  (setq mode-name "Lisp")                ; @r{This goes into the mode line.}
  (lisp-mode-variables t)                ; @r{This defines various variables.}
@end group
@group
  (setq imenu-case-fold-search t)
  (set-syntax-table lisp-mode-syntax-table)
549
  (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
Richard M. Stallman's avatar
Richard M. Stallman committed
550 551 552 553 554 555 556 557 558
                                         ;   @r{hook to customize the mode.}
@end group
@end smallexample

@node Auto Major Mode
@subsection How Emacs Chooses a Major Mode

  Based on information in the file name or in the file itself, Emacs
automatically selects a major mode for the new buffer when a file is
559
visited.  It also processes local variables specified in the file text.
Richard M. Stallman's avatar
Richard M. Stallman committed
560 561 562 563 564 565 566 567 568 569 570 571

@deffn Command fundamental-mode
  Fundamental mode is a major mode that is not specialized for anything
in particular.  Other major modes are defined in effect by comparison
with this one---their definitions say what to change, starting from
Fundamental mode.  The @code{fundamental-mode} function does @emph{not}
run any hooks; you're not supposed to customize it.  (If you want Emacs
to behave differently in Fundamental mode, change the @emph{global}
state of Emacs.)
@end deffn

@deffn Command normal-mode &optional find-file
572
This function establishes the proper major mode and buffer-local variable
Richard M. Stallman's avatar
Richard M. Stallman committed
573 574
bindings for the current buffer.  First it calls @code{set-auto-mode},
then it runs @code{hack-local-variables} to parse, and bind or
575
evaluate as appropriate, the file's local variables.
Richard M. Stallman's avatar
Richard M. Stallman committed
576

577 578 579 580 581 582 583
If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
@code{normal-mode} assumes that the @code{find-file} function is calling
it.  In this case, it may process a local variables list at the end of
the file and in the @samp{-*-} line.  The variable
@code{enable-local-variables} controls whether to do so.  @xref{File
variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for
the syntax of the local variables section of a file.
Richard M. Stallman's avatar
Richard M. Stallman committed
584

Karl Heuer's avatar
Karl Heuer committed
585
If you run @code{normal-mode} interactively, the argument
Richard M. Stallman's avatar
Richard M. Stallman committed
586 587 588 589
@var{find-file} is normally @code{nil}.  In this case,
@code{normal-mode} unconditionally processes any local variables list.

@cindex file mode specification error
Karl Heuer's avatar
Karl Heuer committed
590
@code{normal-mode} uses @code{condition-case} around the call to the
Richard M. Stallman's avatar
Richard M. Stallman committed
591 592 593 594 595 596 597 598
major mode function, so errors are caught and reported as a @samp{File
mode specification error},  followed by the original error message.
@end deffn

@defun set-auto-mode
@cindex visited file mode
  This function selects the major mode that is appropriate for the
current buffer.  It may base its decision on the value of the @w{@samp{-*-}}
Richard M. Stallman's avatar
Richard M. Stallman committed
599 600
line, on the visited file name (using @code{auto-mode-alist}), on the
@w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
601
file's local variables list.  However, this function does not look for
Richard M. Stallman's avatar
Richard M. Stallman committed
602 603 604 605 606
the @samp{mode:} local variable near the end of a file; the
@code{hack-local-variables} function does that.  @xref{Choosing Modes, ,
How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
@end defun

607
@defopt default-major-mode
608
This variable holds the default major mode for new buffers.  The
Richard M. Stallman's avatar
Richard M. Stallman committed
609 610
standard value is @code{fundamental-mode}.

611
If the value of @code{default-major-mode} is @code{nil}, Emacs uses
Richard M. Stallman's avatar
Richard M. Stallman committed
612
the (previously) current buffer's major mode for the major mode of a new
613
buffer.  However, if that major mode symbol has a @code{mode-class}
Richard M. Stallman's avatar
Richard M. Stallman committed
614 615 616 617 618 619
property with value @code{special}, then it is not used for new buffers;
Fundamental mode is used instead.  The modes that have this property are
those such as Dired and Rmail that are useful only with text that has
been specially prepared.
@end defopt

Karl Heuer's avatar
Karl Heuer committed
620 621 622 623 624 625
@defun set-buffer-major-mode buffer
This function sets the major mode of @var{buffer} to the value of
@code{default-major-mode}.  If that variable is @code{nil}, it uses
the current buffer's major mode (if that is suitable).

The low-level primitives for creating buffers do not use this function,
Karl Heuer's avatar
Karl Heuer committed
626 627
but medium-level commands such as @code{switch-to-buffer} and
@code{find-file-noselect} use it whenever they create buffers.
Karl Heuer's avatar
Karl Heuer committed
628 629
@end defun

Richard M. Stallman's avatar
Richard M. Stallman committed
630 631 632 633
@defvar initial-major-mode
@cindex @samp{*scratch*}
The value of this variable determines the major mode of the initial
@samp{*scratch*} buffer.  The value should be a symbol that is a major
634
mode command.  The default value is @code{lisp-interaction-mode}.
Richard M. Stallman's avatar
Richard M. Stallman committed
635 636 637 638 639
@end defvar

@defvar auto-mode-alist
This variable contains an association list of file name patterns
(regular expressions; @pxref{Regular Expressions}) and corresponding
640 641 642
major mode commands.  Usually, the file name patterns test for suffixes,
such as @samp{.el} and @samp{.c}, but this need not be the case.  An
ordinary element of the alist looks like @code{(@var{regexp} .
Richard M. Stallman's avatar
Richard M. Stallman committed
643 644 645 646 647 648
@var{mode-function})}.

For example,

@smallexample
@group
649
(("\\`/tmp/fol/" . text-mode)
650 651
 ("\\.texinfo\\'" . texinfo-mode)
 ("\\.texi\\'" . texinfo-mode)
Richard M. Stallman's avatar
Richard M. Stallman committed
652 653
@end group
@group
654
 ("\\.el\\'" . emacs-lisp-mode)
655
 ("\\.c\\'" . c-mode)
656
 ("\\.h\\'" . c-mode)
Richard M. Stallman's avatar
Richard M. Stallman committed
657 658 659 660 661 662 663 664 665 666 667 668
 @dots{})
@end group
@end smallexample

When you visit a file whose expanded file name (@pxref{File Name
Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
corresponding @var{mode-function}.  This feature enables Emacs to select
the proper major mode for most files.

If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
@var{function} t)}, then after calling @var{function}, Emacs searches
@code{auto-mode-alist} again for a match against the portion of the file
669 670 671 672
name that did not match before.  This feature is useful for
uncompression packages: an entry of the form @code{("\\.gz\\'"
@var{function} t)} can uncompress the file and then put the uncompressed
file in the proper mode according to the name sans @samp{.gz}.
Richard M. Stallman's avatar
Richard M. Stallman committed
673 674 675

Here is an example of how to prepend several pattern pairs to
@code{auto-mode-alist}.  (You might use this sort of expression in your
Phillip Rulon's avatar
Phillip Rulon committed
676
init file.)
Richard M. Stallman's avatar
Richard M. Stallman committed
677 678 679 680

@smallexample
@group
(setq auto-mode-alist
681
  (append
682
   ;; @r{File name (within directory) starts with a dot.}
683
   '(("/\\.[^/]*\\'" . fundamental-mode)
684
     ;; @r{File name has no dot.}
685
     ("[^\\./]*\\'" . fundamental-mode)
686
     ;; @r{File name ends in @samp{.C}.}
687
     ("\\.C\\'" . c++-mode))
Richard M. Stallman's avatar
Richard M. Stallman committed
688 689 690 691 692 693
   auto-mode-alist))
@end group
@end smallexample
@end defvar

@defvar interpreter-mode-alist
694
This variable specifies major modes to use for scripts that specify a
Karl Heuer's avatar
Karl Heuer committed
695
command interpreter in a @samp{#!} line.  Its value is a list of
Richard M. Stallman's avatar
Richard M. Stallman committed
696 697 698
elements of the form @code{(@var{interpreter} . @var{mode})}; for
example, @code{("perl" . perl-mode)} is one element present by default.
The element says to use mode @var{mode} if the file specifies
699 700
an interpreter which matches @var{interpreter}.  The value of
@var{interpreter} is actually a regular expression.
Richard M. Stallman's avatar
Richard M. Stallman committed
701

702 703
This variable is applicable only when the @code{auto-mode-alist} does
not indicate which major mode to use.
Richard M. Stallman's avatar
Richard M. Stallman committed
704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728
@end defvar

@node Mode Help
@subsection Getting Help about a Major Mode
@cindex mode help
@cindex help for major mode
@cindex documentation for major mode

  The @code{describe-mode} function is used to provide information
about major modes.  It is normally called with @kbd{C-h m}.  The
@code{describe-mode} function uses the value of @code{major-mode},
which is why every major mode function needs to set the
@code{major-mode} variable.

@deffn Command describe-mode
This function displays the documentation of the current major mode.

The @code{describe-mode} function calls the @code{documentation}
function using the value of @code{major-mode} as an argument.  Thus, it
displays the documentation string of the major mode function.
(@xref{Accessing Documentation}.)
@end deffn

@defvar major-mode
This variable holds the symbol for the current buffer's major mode.
729
This symbol should have a function definition that is the command to
Richard M. Stallman's avatar
Richard M. Stallman committed
730
switch to that major mode.  The @code{describe-mode} function uses the
731
documentation string of the function as the documentation of the major
Richard M. Stallman's avatar
Richard M. Stallman committed
732 733 734 735 736 737 738 739 740
mode.
@end defvar

@node Derived Modes
@subsection Defining Derived Modes

  It's often useful to define a new major mode in terms of an existing
one.  An easy way to do this is to use @code{define-derived-mode}.

741
@defmac define-derived-mode variant parent name docstring body@dots{}
Richard M. Stallman's avatar
Richard M. Stallman committed
742
This construct defines @var{variant} as a major mode command, using
743
@var{name} as the string form of the mode name.
Richard M. Stallman's avatar
Richard M. Stallman committed
744

745 746
The new command @var{variant} is defined to call the function
@var{parent}, then override certain aspects of that parent mode:
Richard M. Stallman's avatar
Richard M. Stallman committed
747

748
@itemize @bullet
Richard M. Stallman's avatar
Richard M. Stallman committed
749 750 751 752 753 754
@item
The new mode has its own keymap, named @code{@var{variant}-map}.
@code{define-derived-mode} initializes this map to inherit from
@code{@var{parent}-map}, if it is not already set.

@item
755
The new mode has its own syntax table, kept in the variable
Richard M. Stallman's avatar
Richard M. Stallman committed
756
@code{@var{variant}-syntax-table}.
757
@code{define-derived-mode} initializes this variable by copying
Richard M. Stallman's avatar
Richard M. Stallman committed
758 759 760
@code{@var{parent}-syntax-table}, if it is not already set.

@item
761
The new mode has its own abbrev table, kept in the variable
Richard M. Stallman's avatar
Richard M. Stallman committed
762
@code{@var{variant}-abbrev-table}.
763
@code{define-derived-mode} initializes this variable by copying
Richard M. Stallman's avatar
Richard M. Stallman committed
764 765 766 767 768
@code{@var{parent}-abbrev-table}, if it is not already set.

@item
The new mode has its own mode hook, @code{@var{variant}-hook},
which it runs in standard fashion as the very last thing that it does.
769
(The new mode also runs the mode hook of @var{parent} as part
Richard M. Stallman's avatar
Richard M. Stallman committed
770 771 772 773
of calling @var{parent}.)
@end itemize

In addition, you can specify how to override other aspects of
774
@var{parent} with @var{body}.  The command @var{variant}
775
evaluates the forms in @var{body} after setting up all its usual
Richard M. Stallman's avatar
Richard M. Stallman committed
776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793
overrides, just before running @code{@var{variant}-hook}.

The argument @var{docstring} specifies the documentation string for the
new mode.  If you omit @var{docstring}, @code{define-derived-mode}
generates a documentation string.

Here is a hypothetical example:

@example
(define-derived-mode hypertext-mode
  text-mode "Hypertext"
  "Major mode for hypertext.
\\@{hypertext-mode-map@}"
  (setq case-fold-search nil))

(define-key hypertext-mode-map
  [down-mouse-3] 'do-hyper-link)
@end example
794 795 796

Do not write an @code{interactive} spec in the definition;
@code{define-derived-mode} does that automatically.
Richard M. Stallman's avatar
Richard M. Stallman committed
797 798 799 800 801 802 803 804 805
@end defmac

@node Minor Modes
@section Minor Modes
@cindex minor mode

  A @dfn{minor mode} provides features that users may enable or disable
independently of the choice of major mode.  Minor modes can be enabled
individually or in combination.  Minor modes would be better named
806 807
``generally available, optional feature modes,'' except that such a name
would be unwieldy.
Richard M. Stallman's avatar
Richard M. Stallman committed
808

809 810
  A minor mode is not usually meant as a variation of a single major mode.
Usually they are general and can apply to many major modes.  For
811
example, Auto Fill mode works with any major mode that permits text
Richard M. Stallman's avatar
Richard M. Stallman committed
812 813 814 815 816
insertion.  To be general, a minor mode must be effectively independent
of the things major modes do.

  A minor mode is often much more difficult to implement than a major
mode.  One reason is that you should be able to activate and deactivate
817 818 819
minor modes in any order.  A minor mode should be able to have its
desired effect regardless of the major mode and regardless of the other
minor modes in effect.
Richard M. Stallman's avatar
Richard M. Stallman committed
820 821 822

  Often the biggest problem in implementing a minor mode is finding a
way to insert the necessary hook into the rest of Emacs.  Minor mode
Karl Heuer's avatar
Karl Heuer committed
823
keymaps make this easier than it used to be.
Richard M. Stallman's avatar
Richard M. Stallman committed
824

825 826 827 828
@defvar minor-mode-list
The value of this variable is a list of all minor mode commands.
@end defvar

Richard M. Stallman's avatar
Richard M. Stallman committed
829 830 831
@menu
* Minor Mode Conventions::      Tips for writing a minor mode.
* Keymaps and Minor Modes::     How a minor mode can have its own keymap.
832
* Defining Minor Modes::        A convenient facility for defining minor modes.
Richard M. Stallman's avatar
Richard M. Stallman committed
833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851
@end menu

@node Minor Mode Conventions
@subsection Conventions for Writing Minor Modes
@cindex minor mode conventions
@cindex conventions for writing minor modes

  There are conventions for writing minor modes just as there are for
major modes.  Several of the major mode conventions apply to minor
modes as well: those regarding the name of the mode initialization
function, the names of global symbols, and the use of keymaps and
other tables.

  In addition, there are several conventions that are specific to
minor modes.

@itemize @bullet
@item
@cindex mode variable
852 853 854
Make a variable whose name ends in @samp{-mode} to control the minor
mode.  We call this the @dfn{mode variable}.  The minor mode command
should set this variable (@code{nil} to disable; anything else to
855
enable).
856

857
If possible, implement the mode so that setting the variable
858
automatically enables or disables the mode.  Then the minor mode command
859
does not need to do anything except set the variable.
Richard M. Stallman's avatar
Richard M. Stallman committed
860 861 862 863 864 865 866 867 868 869 870 871 872 873

This variable is used in conjunction with the @code{minor-mode-alist} to
display the minor mode name in the mode line.  It can also enable
or disable a minor mode keymap.  Individual commands or hooks can also
check the variable's value.

If you want the minor mode to be enabled separately in each buffer,
make the variable buffer-local.

@item
Define a command whose name is the same as the mode variable.
Its job is to enable and disable the mode by setting the variable.

The command should accept one optional argument.  If the argument is
874 875 876 877 878 879
@code{nil}, it should toggle the mode (turn it on if it is off, and
off if it is on).  It should turn the mode on if the argument is a
positive integer, the symbol @code{t}, or a list whose @sc{car} is one
of those.  It should turn the mode off if the argument is a negative
integer or zero, the symbol @code{-}, or a list whose @sc{car} is one
of those.  The meaning of other arguments is not specified.
Richard M. Stallman's avatar
Richard M. Stallman committed
880

Karl Heuer's avatar
Karl Heuer committed
881 882
Here is an example taken from the definition of @code{transient-mark-mode}.
It shows the use of @code{transient-mark-mode} as a variable that enables or
883 884
disables the mode's behavior, and also shows the proper way to toggle,
enable or disable the minor mode based on the raw prefix argument value.
Richard M. Stallman's avatar
Richard M. Stallman committed
885 886 887

@smallexample
@group
Karl Heuer's avatar
Karl Heuer committed
888 889
(setq transient-mark-mode
      (if (null arg) (not transient-mark-mode)
Richard M. Stallman's avatar
Richard M. Stallman committed
890 891 892 893 894 895
        (> (prefix-numeric-value arg) 0)))
@end group
@end smallexample

@item
Add an element to @code{minor-mode-alist} for each minor mode
896 897
(@pxref{Mode Line Variables}), if you want to indicate the minor mode in
the mode line.  This element should be a list of the following form:
Richard M. Stallman's avatar
Richard M. Stallman committed
898 899 900 901 902

@smallexample
(@var{mode-variable} @var{string})
@end smallexample

903
Here @var{mode-variable} is the variable that controls enabling of the
Richard M. Stallman's avatar
Richard M. Stallman committed
904 905 906 907 908 909 910 911 912
minor mode, and @var{string} is a short string, starting with a space,
to represent the mode in the mode line.  These strings must be short so
that there is room for several of them at once.

When you add an element to @code{minor-mode-alist}, use @code{assq} to
check for an existing element, to avoid duplication.  For example:

@smallexample
@group
Phillip Rulon's avatar
Phillip Rulon committed
913 914 915
(unless (assq 'leif-mode minor-mode-alist)
  (setq minor-mode-alist
        (cons '(leif-mode " Leif") minor-mode-alist)))
Richard M. Stallman's avatar
Richard M. Stallman committed
916 917 918
@end group
@end smallexample

Phillip Rulon's avatar
Phillip Rulon committed
919 920 921 922 923 924 925 926 927
@noindent
or like this, using @code{add-to-list} (@pxref{Setting Variables}):

@smallexample
@group
(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
@end group
@end smallexample
@end itemize
928

929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962
  Global minor modes distributed with Emacs should if possible support
enabling and disabling via Custom (@pxref{Customization}).  To do this,
the first step is to define the mode variable with @code{defcustom}, and
specify @code{:type boolean}.

  If just setting the variable is not sufficient to enable the mode, you
should also specify a @code{:set} method which enables the mode by
invoke the mode command.  Note in the variable's documentation string that
setting the variable other than via Custom may not take effect.

  Also mark the definition with an autoload cookie (@pxref{Autoload}),
and specify a @code{:require} so that customizing the variable will load
the library that defines the mode.  This will copy suitable definitions
into @file{loaddefs.el} so that users can use @code{customize-option} to
enable the mode.  For example:

@smallexample
@group

;;;###autoload
(defcustom msb-mode nil
  "Toggle msb-mode.
Setting this variable directly does not take effect;
use either \\[customize] or the function `msb-mode'."
  :set (lambda (symbol value)
	 (msb-mode (or value 0)))
  :initialize 'custom-initialize-default
  :version "20.4"
  :type    'boolean
  :group   'msb
  :require 'msb)
@end group
@end smallexample

Richard M. Stallman's avatar
Richard M. Stallman committed
963 964 965
@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes

Karl Heuer's avatar
Karl Heuer committed
966 967 968
  Each minor mode can have its own keymap, which is active when the mode
is enabled.  To set up a keymap for a minor mode, add an element to the
alist @code{minor-mode-map-alist}.  @xref{Active Keymaps}.
Richard M. Stallman's avatar
Richard M. Stallman committed
969 970

@cindex @code{self-insert-command}, minor modes
971
  One use of minor mode keymaps is to modify the behavior of certain
Richard M. Stallman's avatar
Richard M. Stallman committed
972 973 974 975 976 977 978
self-inserting characters so that they do something else as well as
self-insert.  In general, this is the only way to do that, since the
facilities for customizing @code{self-insert-command} are limited to
special cases (designed for abbrevs and Auto Fill mode).  (Do not try
substituting your own definition of @code{self-insert-command} for the
standard one.  The editor command loop handles this function specially.)

979 980
The key sequences bound in a minor mode should consist of @kbd{C-c}
followed by a punctuation character @emph{other than} @kbd{@{},
981
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}.  (Those few punctuation
982 983
characters are reserved for major modes.)

984 985
@node Defining Minor Modes
@subsection Defining Minor Modes
986

987 988
  The macro @code{define-minor-mode} offers a convenient way of
implementing a mode in one self-contained definition.  It supports only
989
buffer-local minor modes, not global ones.
990

991
@defmac define-minor-mode mode doc [init-value [lighter [keymap keyword-args... body...]]]
992
@tindex define-minor-mode
993 994
This macro defines a new minor mode whose name is @var{mode} (a
symbol).  It defines a command named @var{mode} to toggle the minor
995 996 997 998
mode, with @var{doc} as its documentation string.  It also defines a
variable named @var{mode}, which is set to @code{t} or @code{nil} by
enabling or disabling the mode.  The variable is initialized to
@var{init-value}.
999

1000
The string @var{lighter} says what to display in the mode line
1001 1002 1003 1004 1005 1006 1007 1008 1009 1010
when the mode is enabled; if it is @code{nil}, the mode is not displayed
in the mode line.

The optional argument @var{keymap} specifies the keymap for the minor mode.
It can be a variable name, whose value is the keymap, or it can be an alist
specifying bindings in this form:

@example
(@var{key-sequence} . @var{definition})
@end example
1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035

The @var{keyword-args} consist of keywords followed by corresponding
values.  A few keywords have special meanings:

@table @code
@item :global @var{global}
If non-@code{nil} specifies that the minor mode should be global.
By default, minor modes are buffer-local.

@item :init-value @var{init-value}
This is equivalent to specifying @var{init-value} positionally.

@item :lighter @var{lighter}
This is equivalent to specifying @var{lighter} positionally.

@item :keymap @var{keymap}
This is equivalent to specifying @var{keymap} positionally.
@end table

Any other keyword arguments are passed passed directly to the
@code{defcustom} generated for the variable @var{mode}.

The command named @var{mode} finishes by executing the @var{body} forms,
if any, after it has performed the standard actions such as setting
the variable named @var{mode}.
1036 1037
@end defmac

1038 1039 1040 1041
@findex easy-mmode-define-minor-mode
  The name @code{easy-mmode-define-minor-mode} is an alias
for this macro.

1042
  Here is an example of using @code{define-minor-mode}:
1043 1044

@smallexample
1045
(define-minor-mode hungry-mode
1046
  "Toggle Hungry mode.
1047
With no argument, this command toggles the mode.
1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.

When Hungry mode is enabled, the control delete key
gobbles all preceding whitespace except the last.
See the command \\[hungry-electric-delete]."
 ;; The initial value.
 nil
 ;; The indicator for the mode line.
 " Hungry"
 ;; The minor mode bindings.
 '(("\C-\^?" . hungry-electric-delete)
   ("\C-\M-\^?"
1061
    . (lambda ()
1062
        (interactive)
1063 1064
        (hungry-electric-delete t))))
 :group 'hunger)
1065 1066 1067 1068 1069 1070 1071 1072
@end smallexample

@noindent
This defines a minor mode named ``Hungry mode'', a command named
@code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
which indicates whether the mode is enabled, and a variable named
@code{hungry-mode-map} which holds the keymap that is active when the
mode is enabled.  It initializes the keymap with key bindings for
1073 1074 1075
@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.  It puts the variable
@code{hungry-mode} into custom group @code{hunger}.  There are no
@var{body} forms---many minor modes don't need any.
1076

1077
  Here's an equivalent way to write it:
1078

1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101
@smallexample
(define-minor-mode hungry-mode
  "Toggle Hungry mode.
With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.

When Hungry mode is enabled, the control delete key
gobbles all preceding whitespace except the last.
See the command \\[hungry-electric-delete]."
 ;; The initial value.
 :initial-value nil
 ;; The indicator for the mode line.
 :lighter " Hungry"
 ;; The minor mode bindings.
 :keymap
 '(("\C-\^?" . hungry-electric-delete)
   ("\C-\M-\^?"
    . (lambda ()
        (interactive)
        (hungry-electric-delete t))))
 :group 'hunger)
@end smallexample
1102

Richard M. Stallman's avatar
Richard M. Stallman committed
1103 1104 1105 1106
@node Mode Line Format
@section Mode Line Format
@cindex mode line

1107 1108 1109 1110 1111 1112 1113
  Each Emacs window (aside from minibuffer windows) typically has a mode
line at the bottom, which displays status information about the buffer
displayed in the window.  The mode line contains information about the
buffer, such as its name, associated file, depth of recursive editing,
and major and minor modes.  A window can also have a @dfn{header
line}, which is much like the mode line but appears at the top of the
window (starting in Emacs 21).
Richard M. Stallman's avatar
Richard M. Stallman committed
1114

1115 1116
  This section describes how to control the contents of the mode line
and header line.  We include it in this chapter because much of the
Richard M. Stallman's avatar
Richard M. Stallman committed
1117 1118 1119 1120 1121
information displayed in the mode line relates to the enabled major and
minor modes.

  @code{mode-line-format} is a buffer-local variable that holds a
template used to display the mode line of the current buffer.  All
1122 1123 1124 1125 1126 1127
windows for the same buffer use the same @code{mode-line-format}, so
their mode lines appear the same---except for scrolling percentages, and
line and column numbers, since those depend on point and on how the
window is scrolled.  @code{header-line-format} is used likewise for
header lines.

1128 1129 1130 1131 1132 1133 1134 1135 1136 1137
  For efficiency, Emacs does not recompute the mode line and header
line of a window in every redisplay.  It does so when circumstances
appear to call for it---for instance, if you change the window
configuration, switch buffers, narrow or widen the buffer, scroll, or
change the buffer's modification status.  If you modify any of the
variables referenced by @code{mode-line-format} (@pxref{Mode Line
Variables}), or any other variables and data structures that affect
how text is displayed (@pxref{Display}), you may want to force an
update of the mode line so as to display the new information or
display it in the new way.
Richard M. Stallman's avatar
Richard M. Stallman committed
1138 1139 1140

@c Emacs 19 feature
@defun force-mode-line-update
1141
Force redisplay of the current buffer's mode line and header line.
1142 1143 1144 1145 1146
The next redisplay will update the mode line and header line based on
the latest values of all relevant variables.

This function also forces recomputation of the menu bar menus
and the frame title.
Richard M. Stallman's avatar
Richard M. Stallman committed
1147 1148 1149 1150 1151
@end defun

  The mode line is usually displayed in inverse video; see
@code{mode-line-inverse-video} in @ref{Inverse Video}.

1152 1153 1154 1155 1156 1157
  A window that is just one line tall does not display either a mode
line or a header line, even if the variables call for one.  A window
that is two lines tall cannot display both a mode line and a header
line at once; if the variables call for both, only the mode line
actually appears.

Richard M. Stallman's avatar
Richard M. Stallman committed
1158 1159 1160 1161
@menu
* Mode Line Data::        The data structure that controls the mode line.
* Mode Line Variables::   Variables used in that data structure.
* %-Constructs::          Putting information into a mode line.
1162 1163
* Properties in Mode::    Using text properties in the mode line.
* Header Lines::          Like a mode line, but at the top.
1164
* Emulating Mode Line::   Formatting text as the mode line would.
Richard M. Stallman's avatar
Richard M. Stallman committed
1165 1166 1167 1168 1169 1170 1171
@end menu

@node Mode Line Data
@subsection The Data Structure of the Mode Line
@cindex mode line construct

  The mode line contents are controlled by a data structure of lists,
Phillip Rulon's avatar
Phillip Rulon committed
1172 1173 1174 1175 1176
strings, symbols, and numbers kept in buffer-local variables.  The data
structure is called a @dfn{mode line construct}, and it is built in
recursive fashion out of simpler mode line constructs.  The same data
structure is used for constructing frame titles (@pxref{Frame Titles})
and header lines (@pxref{Header Lines}).
Richard M. Stallman's avatar
Richard M. Stallman committed
1177 1178 1179 1180 1181 1182

@defvar mode-line-format
The value of this variable is a mode line construct with overall
responsibility for the mode line format.  The value of this variable
controls which other variables are used to form the mode line text, and
where they appear.
1183 1184 1185

If you set this variable to @code{nil} in a buffer, that buffer does not
have a mode line.  (This feature was added in Emacs 21.)
Richard M. Stallman's avatar
Richard M. Stallman committed
1186 1187 1188 1189 1190 1191 1192 1193 1194
@end defvar

  A mode line construct may be as simple as a fixed string of text, but
it usually specifies how to use other variables to construct the text.
Many of these variables are themselves defined to have mode line
constructs as their values.

  The default value of @code{mode-line-format} incorporates the values
of variables such as @code{mode-name} and @code{minor-mode-alist}.
1195 1196 1197
Because of this, very few modes need to alter @code{mode-line-format}
itself.  For most purposes, it is sufficient to alter some of the
variables that @code{mode-line-format} refers to.
Richard M. Stallman's avatar
Richard M. Stallman committed
1198

1199 1200
  A mode line construct may be a list, a symbol, or a string.  If the
value is a list, each element may be a list, a symbol, or a string.
Richard M. Stallman's avatar
Richard M. Stallman committed
1201

1202 1203 1204 1205 1206
  The mode line can display various faces, if the strings that control
it have the @code{face} property.  @xref{Properties in Mode}.  In
addition, the face @code{mode-line} is used as a default for the whole
mode line (@pxref{Standard Faces}).

Richard M. Stallman's avatar
Richard M. Stallman committed
1207 1208 1209 1210
@table @code
@cindex percent symbol in mode line
@item @var{string}
A string as a mode line construct is displayed verbatim in the mode line
Karl Heuer's avatar
Karl Heuer committed
1211
except for @dfn{@code{%}-constructs}.  Decimal digits after the @samp{%}
Richard M. Stallman's avatar
Richard M. Stallman committed
1212 1213 1214 1215 1216
specify the field width for space filling on the right (i.e., the data
is left justified).  @xref{%-Constructs}.

@item @var{symbol}
A symbol as a mode line construct stands for its value.  The value of
1217
@var{symbol} is used as a mode line construct, in place of @var{symbol}.
1218
However, the symbols @code{t} and @code{nil} are ignored, as is any
1219
symbol whose value is void.
Richard M. Stallman's avatar
Richard M. Stallman committed
1220 1221

There is one exception: if the value of @var{symbol} is a string, it is
1222
displayed verbatim: the @code{%}-constructs are not recognized.
Richard M. Stallman's avatar
Richard M. Stallman committed
1223 1224

@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
1225 1226 1227
A list whose first element is a string or list means to process all the
elements recursively and concatenate the results.  This is the most
common form of mode line construct.
Richard M. Stallman's avatar
Richard M. Stallman committed
1228

1229 1230 1231 1232 1233
@item (:eval @var{form})
A list whose first element is the symbol @code{:eval} says to evaluate
@var{form}, and use the result as a string to display.
(This feature is new as of Emacs 21.)

Richard M. Stallman's avatar
Richard M. Stallman committed
1234
@item (@var{symbol} @var{then} @var{else})
1235 1236 1237 1238 1239 1240 1241
A list whose first element is a symbol that is not a keyword specifies a
conditional.  Its meaning depends on the value of @var{symbol}.  If the
value is non-@code{nil}, the second element, @var{then}, is processed
recursively as a mode line element.  But if the value of @var{symbol} is
@code{nil}, the third element, @var{else}, is processed recursively.
You may omit @var{else}; then the mode line element displays nothing if
the value of @var{symbol} is @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1242 1243 1244 1245 1246 1247 1248 1249 1250 1251

@item (@var{width} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
padding of the results of @var{rest}.  The remaining elements
@var{rest} are processed recursively as mode line constructs and
concatenated together.  Then the result is space filled (if
@var{width} is positive) or truncated (to @minus{}@var{width} columns,
if @var{width} is negative) on the right.

For example, the usual way to show what percentage of a buffer is above
1252
the top of the window is to use a list like this: @code{(-3 "%p")}.