428
+ − 1 @c -*-texinfo-*-
+ − 2 @c This is part of the XEmacs Lisp Reference Manual.
444
+ − 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
428
+ − 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
+ − 8 @cindex mode
+ − 9
+ − 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.
+ − 15
+ − 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}.
+ − 20
+ − 21 @menu
+ − 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.
+ − 26 @end menu
+ − 27
+ − 28 @node Major Modes
+ − 29 @section Major Modes
+ − 30 @cindex major mode
+ − 31 @cindex Fundamental mode
+ − 32
+ − 33 Major modes specialize XEmacs for editing particular kinds of text.
2135
+ − 34 Each buffer has only one major mode at a time. For each major mode
+ − 35 there is a function to switch to that mode in the current buffer; its
+ − 36 name should end in @samp{-mode}. These functions work by setting
+ − 37 buffer-local variable bindings and other data associated with the
+ − 38 buffer, such as a local keymap. The effect lasts until you switch
+ − 39 to another major mode in the same buffer.
428
+ − 40
+ − 41 The least specialized major mode is called @dfn{Fundamental mode}.
+ − 42 This mode has no mode-specific definitions or variable settings, so each
+ − 43 XEmacs command behaves in its default manner, and each option is in its
+ − 44 default state. All other major modes redefine various keys and options.
+ − 45 For example, Lisp Interaction mode provides special key bindings for
+ − 46 @key{LFD} (@code{eval-print-last-sexp}), @key{TAB}
+ − 47 (@code{lisp-indent-line}), and other keys.
+ − 48
+ − 49 When you need to write several editing commands to help you perform a
+ − 50 specialized editing task, creating a new major mode is usually a good
+ − 51 idea. In practice, writing a major mode is easy (in contrast to
+ − 52 writing a minor mode, which is often difficult).
+ − 53
+ − 54 If the new mode is similar to an old one, it is often unwise to modify
+ − 55 the old one to serve two purposes, since it may become harder to use and
+ − 56 maintain. Instead, copy and rename an existing major mode definition
+ − 57 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
+ − 58 Modes}). For example, Rmail Edit mode, which is in
+ − 59 @file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to
+ − 60 Text mode except that it provides three additional commands. Its
+ − 61 definition is distinct from that of Text mode, but was derived from it.
+ − 62
2135
+ − 63 Even if the new mode is not an obvious derivative of any other mode,
+ − 64 it is convenient to use @code{define-derived-mode} with a @code{nil}
+ − 65 parent argument, since it automatically enforces the most important
+ − 66 coding conventions for you.
+ − 67
428
+ − 68 Rmail Edit mode is an example of a case where one piece of text is put
+ − 69 temporarily into a different major mode so it can be edited in a
+ − 70 different way (with ordinary XEmacs commands rather than Rmail). In such
+ − 71 cases, the temporary major mode usually has a command to switch back to
+ − 72 the buffer's usual mode (Rmail mode, in this case). You might be
+ − 73 tempted to present the temporary redefinitions inside a recursive edit
+ − 74 and restore the usual ones when the user exits; but this is a bad idea
+ − 75 because it constrains the user's options when it is done in more than
+ − 76 one buffer: recursive edits must be exited most-recently-entered first.
+ − 77 Using alternative major modes avoids this limitation. @xref{Recursive
+ − 78 Editing}.
+ − 79
+ − 80 The standard XEmacs Lisp library directory contains the code for
+ − 81 several major modes, in files including @file{text-mode.el},
+ − 82 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
+ − 83 @file{rmail.el}. You can look at these libraries to see how modes are
+ − 84 written. Text mode is perhaps the simplest major mode aside from
+ − 85 Fundamental mode. Rmail mode is a complicated and specialized mode.
+ − 86
+ − 87 @menu
+ − 88 * Major Mode Conventions:: Coding conventions for keymaps, etc.
+ − 89 * Example Major Modes:: Text mode and Lisp modes.
+ − 90 * Auto Major Mode:: How XEmacs chooses the major mode automatically.
+ − 91 * Mode Help:: Finding out how to use a mode.
444
+ − 92 * Derived Modes:: Defining a new major mode based on another major
428
+ − 93 mode.
+ − 94 @end menu
+ − 95
+ − 96 @node Major Mode Conventions
+ − 97 @subsection Major Mode Conventions
+ − 98
+ − 99 The code for existing major modes follows various coding conventions,
+ − 100 including conventions for local keymap and syntax table initialization,
+ − 101 global names, and hooks. Please follow these conventions when you
+ − 102 define a new major mode:
+ − 103
+ − 104 @itemize @bullet
+ − 105 @item
+ − 106 Define a command whose name ends in @samp{-mode}, with no arguments,
+ − 107 that switches to the new mode in the current buffer. This command
+ − 108 should set up the keymap, syntax table, and local variables in an
+ − 109 existing buffer without changing the buffer's text.
+ − 110
+ − 111 @item
+ − 112 Write a documentation string for this command that describes the
+ − 113 special commands available in this mode. @kbd{C-h m}
+ − 114 (@code{describe-mode}) in your mode will display this string.
+ − 115
+ − 116 The documentation string may include the special documentation
+ − 117 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
+ − 118 @samp{\<@var{keymap}>}, that enable the documentation to adapt
+ − 119 automatically to the user's own key bindings. @xref{Keys in
+ − 120 Documentation}.
+ − 121
+ − 122 @item
+ − 123 The major mode command should start by calling
+ − 124 @code{kill-all-local-variables}. This is what gets rid of the local
+ − 125 variables of the major mode previously in effect.
+ − 126
+ − 127 @item
+ − 128 The major mode command should set the variable @code{major-mode} to the
+ − 129 major mode command symbol. This is how @code{describe-mode} discovers
+ − 130 which documentation to print.
+ − 131
+ − 132 @item
+ − 133 The major mode command should set the variable @code{mode-name} to the
+ − 134 ``pretty'' name of the mode, as a string. This appears in the mode
+ − 135 line.
+ − 136
+ − 137 @item
+ − 138 @cindex functions in modes
+ − 139 Since all global names are in the same name space, all the global
+ − 140 variables, constants, and functions that are part of the mode should
+ − 141 have names that start with the major mode name (or with an abbreviation
+ − 142 of it if the name is long). @xref{Style Tips}.
+ − 143
+ − 144 @item
+ − 145 @cindex keymaps in modes
+ − 146 The major mode should usually have its own keymap, which is used as the
+ − 147 local keymap in all buffers in that mode. The major mode function
+ − 148 should call @code{use-local-map} to install this local map.
+ − 149 @xref{Active Keymaps}, for more information.
+ − 150
+ − 151 This keymap should be kept in a global variable named
+ − 152 @code{@var{modename}-mode-map}. Normally the library that defines the
+ − 153 mode sets this variable.
+ − 154
+ − 155 @item
+ − 156 @cindex syntax tables in modes
+ − 157 The mode may have its own syntax table or may share one with other
+ − 158 related modes. If it has its own syntax table, it should store this in
+ − 159 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
+ − 160 Tables}.
+ − 161
+ − 162 @item
+ − 163 @cindex abbrev tables in modes
+ − 164 The mode may have its own abbrev table or may share one with other
+ − 165 related modes. If it has its own abbrev table, it should store this in
+ − 166 a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
+ − 167 Tables}.
+ − 168
+ − 169 @item
+ − 170 Use @code{defvar} to set mode-related variables, so that they are not
+ − 171 reinitialized if they already have a value. (Such reinitialization
+ − 172 could discard customizations made by the user.)
+ − 173
+ − 174 @item
+ − 175 @cindex buffer-local variables in modes
+ − 176 To make a buffer-local binding for an Emacs customization variable, use
+ − 177 @code{make-local-variable} in the major mode command, not
+ − 178 @code{make-variable-buffer-local}. The latter function would make the
+ − 179 variable local to every buffer in which it is subsequently set, which
+ − 180 would affect buffers that do not use this mode. It is undesirable for a
+ − 181 mode to have such global effects. @xref{Buffer-Local Variables}.
+ − 182
+ − 183 It's ok to use @code{make-variable-buffer-local}, if you wish, for a
+ − 184 variable used only within a single Lisp package.
+ − 185
+ − 186 @item
+ − 187 @cindex mode hook
+ − 188 @cindex major mode hook
+ − 189 Each major mode should have a @dfn{mode hook} named
+ − 190 @code{@var{modename}-mode-hook}. The major mode command should run that
+ − 191 hook, with @code{run-hooks}, as the very last thing it
+ − 192 does. @xref{Hooks}.
+ − 193
+ − 194 @item
+ − 195 The major mode command may also run the hooks of some more basic modes.
+ − 196 For example, @code{indented-text-mode} runs @code{text-mode-hook} as
+ − 197 well as @code{indented-text-mode-hook}. It may run these other hooks
+ − 198 immediately before the mode's own hook (that is, after everything else),
+ − 199 or it may run them earlier.
+ − 200
+ − 201 @item
2135
+ − 202 The major mode command may start by calling some other major mode
+ − 203 command (called the @dfn{parent mode}) and then alter some of its
+ − 204 settings. A mode that does this is called a @dfn{derived mode}. The
+ − 205 recommended way to define one is to use @code{define-derived-mode},
+ − 206 but this is not required. Such a mode should use
+ − 207 @code{delay-mode-hooks} around its entire body, including the call to
+ − 208 the parent mode command and the final call to @code{run-mode-hooks}.
+ − 209 (Using @code{define-derived-mode} does this automatically.)
+ − 210
+ − 211 @item
428
+ − 212 If something special should be done if the user switches a buffer from
+ − 213 this mode to any other major mode, the mode can set a local value for
+ − 214 @code{change-major-mode-hook}.
+ − 215
+ − 216 @item
+ − 217 If this mode is appropriate only for specially-prepared text, then the
+ − 218 major mode command symbol should have a property named @code{mode-class}
+ − 219 with value @code{special}, put on as follows:
+ − 220
+ − 221 @cindex @code{mode-class} property
+ − 222 @cindex @code{special}
+ − 223 @example
+ − 224 (put 'funny-mode 'mode-class 'special)
+ − 225 @end example
+ − 226
+ − 227 @noindent
+ − 228 This tells XEmacs that new buffers created while the current buffer has
+ − 229 Funny mode should not inherit Funny mode. Modes such as Dired, Rmail,
+ − 230 and Buffer List use this feature.
+ − 231
+ − 232 @item
+ − 233 If you want to make the new mode the default for files with certain
+ − 234 recognizable names, add an element to @code{auto-mode-alist} to select
+ − 235 the mode for those file names. If you define the mode command to
+ − 236 autoload, you should add this element in the same file that calls
+ − 237 @code{autoload}. Otherwise, it is sufficient to add the element in the
+ − 238 file that contains the mode definition. @xref{Auto Major Mode}.
+ − 239
+ − 240 @item
+ − 241 @cindex @file{.emacs} customization
+ − 242 In the documentation, you should provide a sample @code{autoload} form
+ − 243 and an example of how to add to @code{auto-mode-alist}, that users can
+ − 244 include in their @file{.emacs} files.
+ − 245
+ − 246 @item
+ − 247 @cindex mode loading
+ − 248 The top-level forms in the file defining the mode should be written so
+ − 249 that they may be evaluated more than once without adverse consequences.
+ − 250 Even if you never load the file more than once, someone else will.
+ − 251 @end itemize
+ − 252
+ − 253 @defvar change-major-mode-hook
+ − 254 This normal hook is run by @code{kill-all-local-variables} before it
+ − 255 does anything else. This gives major modes a way to arrange for
+ − 256 something special to be done if the user switches to a different major
+ − 257 mode. For best results, make this variable buffer-local, so that it
+ − 258 will disappear after doing its job and will not interfere with the
+ − 259 subsequent major mode. @xref{Hooks}.
+ − 260 @end defvar
+ − 261
+ − 262 @node Example Major Modes
+ − 263 @subsection Major Mode Examples
+ − 264
+ − 265 Text mode is perhaps the simplest mode besides Fundamental mode.
+ − 266 Here are excerpts from @file{text-mode.el} that illustrate many of
+ − 267 the conventions listed above:
+ − 268
+ − 269 @smallexample
+ − 270 @group
+ − 271 ;; @r{Create mode-specific tables.}
444
+ − 272 (defvar text-mode-syntax-table nil
428
+ − 273 "Syntax table used while in text mode.")
+ − 274 @end group
+ − 275
+ − 276 @group
+ − 277 (if text-mode-syntax-table
+ − 278 () ; @r{Do not change the table if it is already set up.}
+ − 279 (setq text-mode-syntax-table (make-syntax-table))
+ − 280 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
+ − 281 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
+ − 282 (modify-syntax-entry ?' "w " text-mode-syntax-table))
+ − 283 @end group
+ − 284
+ − 285 @group
+ − 286 (defvar text-mode-abbrev-table nil
+ − 287 "Abbrev table used while in text mode.")
+ − 288 (define-abbrev-table 'text-mode-abbrev-table ())
+ − 289 @end group
+ − 290
+ − 291 @group
+ − 292 (defvar text-mode-map nil) ; @r{Create a mode-specific keymap.}
+ − 293
+ − 294 (if text-mode-map
+ − 295 () ; @r{Do not change the keymap if it is already set up.}
+ − 296 (setq text-mode-map (make-sparse-keymap))
+ − 297 (define-key text-mode-map "\t" 'tab-to-tab-stop)
+ − 298 (define-key text-mode-map "\es" 'center-line)
+ − 299 (define-key text-mode-map "\eS" 'center-paragraph))
+ − 300 @end group
+ − 301 @end smallexample
+ − 302
+ − 303 Here is the complete major mode function definition for Text mode:
+ − 304
+ − 305 @smallexample
+ − 306 @group
+ − 307 (defun text-mode ()
444
+ − 308 "Major mode for editing text intended for humans to read.
428
+ − 309 Special commands: \\@{text-mode-map@}
+ − 310 @end group
+ − 311 @group
+ − 312 Turning on text-mode runs the hook `text-mode-hook'."
+ − 313 (interactive)
+ − 314 (kill-all-local-variables)
+ − 315 @end group
+ − 316 @group
+ − 317 (use-local-map text-mode-map) ; @r{This provides the local keymap.}
+ − 318 (setq mode-name "Text") ; @r{This name goes into the modeline.}
+ − 319 (setq major-mode 'text-mode) ; @r{This is how @code{describe-mode}}
+ − 320 ; @r{finds the doc string to print.}
+ − 321 (setq local-abbrev-table text-mode-abbrev-table)
+ − 322 (set-syntax-table text-mode-syntax-table)
+ − 323 (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
+ − 324 ; @r{customize the mode with a hook.}
+ − 325 @end group
+ − 326 @end smallexample
+ − 327
+ − 328 @cindex @file{lisp-mode.el}
+ − 329 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
+ − 330 Interaction mode) have more features than Text mode and the code is
+ − 331 correspondingly more complicated. Here are excerpts from
+ − 332 @file{lisp-mode.el} that illustrate how these modes are written.
+ − 333
+ − 334 @cindex syntax table example
+ − 335 @smallexample
+ − 336 @group
+ − 337 ;; @r{Create mode-specific table variables.}
444
+ − 338 (defvar lisp-mode-syntax-table nil "")
428
+ − 339 (defvar emacs-lisp-mode-syntax-table nil "")
+ − 340 (defvar lisp-mode-abbrev-table nil "")
+ − 341 @end group
+ − 342
+ − 343 @group
+ − 344 (if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
+ − 345 ; @r{if it is already set.}
+ − 346 (let ((i 0))
+ − 347 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
+ − 348 @end group
+ − 349
+ − 350 @group
+ − 351 ;; @r{Set syntax of chars up to 0 to class of chars that are}
+ − 352 ;; @r{part of symbol names but not words.}
+ − 353 ;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
444
+ − 354 (while (< i ?0)
428
+ − 355 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
+ − 356 (setq i (1+ i)))
+ − 357 @dots{}
+ − 358 @end group
+ − 359 @group
+ − 360 ;; @r{Set the syntax for other characters.}
+ − 361 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
+ − 362 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
+ − 363 @dots{}
+ − 364 @end group
+ − 365 @group
+ − 366 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
+ − 367 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
+ − 368 @dots{}))
+ − 369 ;; @r{Create an abbrev table for lisp-mode.}
+ − 370 (define-abbrev-table 'lisp-mode-abbrev-table ())
+ − 371 @end group
+ − 372 @end smallexample
+ − 373
+ − 374 Much code is shared among the three Lisp modes. The following
+ − 375 function sets various variables; it is called by each of the major Lisp
+ − 376 mode functions:
+ − 377
+ − 378 @smallexample
+ − 379 @group
+ − 380 (defun lisp-mode-variables (lisp-syntax)
+ − 381 ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
+ − 382 ;; @r{and @code{t} in the other two Lisp modes.}
+ − 383 (cond (lisp-syntax
+ − 384 (if (not lisp-mode-syntax-table)
+ − 385 ;; @r{The Emacs Lisp mode syntax table always exists, but}
+ − 386 ;; @r{the Lisp Mode syntax table is created the first time a}
+ − 387 ;; @r{mode that needs it is called. This is to save space.}
+ − 388 @end group
+ − 389 @group
+ − 390 (progn (setq lisp-mode-syntax-table
+ − 391 (copy-syntax-table emacs-lisp-mode-syntax-table))
+ − 392 ;; @r{Change some entries for Lisp mode.}
+ − 393 (modify-syntax-entry ?\| "\" "
+ − 394 lisp-mode-syntax-table)
+ − 395 (modify-syntax-entry ?\[ "_ "
+ − 396 lisp-mode-syntax-table)
+ − 397 (modify-syntax-entry ?\] "_ "
+ − 398 lisp-mode-syntax-table)))
+ − 399 @end group
+ − 400 @group
+ − 401 (set-syntax-table lisp-mode-syntax-table)))
+ − 402 (setq local-abbrev-table lisp-mode-abbrev-table)
+ − 403 @dots{})
+ − 404 @end group
+ − 405 @end smallexample
+ − 406
+ − 407 Functions such as @code{forward-paragraph} use the value of the
+ − 408 @code{paragraph-start} variable. Since Lisp code is different from
+ − 409 ordinary text, the @code{paragraph-start} variable needs to be set
+ − 410 specially to handle Lisp. Also, comments are indented in a special
+ − 411 fashion in Lisp and the Lisp modes need their own mode-specific
+ − 412 @code{comment-indent-function}. The code to set these variables is the
+ − 413 rest of @code{lisp-mode-variables}.
+ − 414
+ − 415 @smallexample
+ − 416 @group
+ − 417 (make-local-variable 'paragraph-start)
+ − 418 ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
+ − 419 ;; @r{has them too, and removing those is a pain.}
+ − 420 (setq paragraph-start (concat "^$\\|" page-delimiter))
+ − 421 @dots{}
+ − 422 @end group
+ − 423 @group
+ − 424 (make-local-variable 'comment-indent-function)
+ − 425 (setq comment-indent-function 'lisp-comment-indent))
+ − 426 @end group
+ − 427 @end smallexample
+ − 428
+ − 429 Each of the different Lisp modes has a slightly different keymap. For
+ − 430 example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other
+ − 431 Lisp modes do not. However, all Lisp modes have some commands in
+ − 432 common. The following function adds these common commands to a given
+ − 433 keymap.
+ − 434
+ − 435 @smallexample
+ − 436 @group
+ − 437 (defun lisp-mode-commands (map)
+ − 438 (define-key map "\e\C-q" 'indent-sexp)
+ − 439 (define-key map "\177" 'backward-delete-char-untabify)
+ − 440 (define-key map "\t" 'lisp-indent-line))
+ − 441 @end group
+ − 442 @end smallexample
+ − 443
+ − 444 Here is an example of using @code{lisp-mode-commands} to initialize a
+ − 445 keymap, as part of the code for Emacs Lisp mode. First we declare a
+ − 446 variable with @code{defvar} to hold the mode-specific keymap. When this
+ − 447 @code{defvar} executes, it sets the variable to @code{nil} if it was
+ − 448 void. Then we set up the keymap if the variable is @code{nil}.
+ − 449
+ − 450 This code avoids changing the keymap or the variable if it is already
+ − 451 set up. This lets the user customize the keymap.
+ − 452
+ − 453 @smallexample
+ − 454 @group
444
+ − 455 (defvar emacs-lisp-mode-map () "")
428
+ − 456 (if emacs-lisp-mode-map
+ − 457 ()
+ − 458 (setq emacs-lisp-mode-map (make-sparse-keymap))
+ − 459 (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
+ − 460 (lisp-mode-commands emacs-lisp-mode-map))
+ − 461 @end group
+ − 462 @end smallexample
+ − 463
+ − 464 Finally, here is the complete major mode function definition for
444
+ − 465 Emacs Lisp mode.
428
+ − 466
+ − 467 @smallexample
+ − 468 @group
+ − 469 (defun emacs-lisp-mode ()
+ − 470 "Major mode for editing Lisp code to run in XEmacs.
+ − 471 Commands:
+ − 472 Delete converts tabs to spaces as it moves back.
+ − 473 Blank lines separate paragraphs. Semicolons start comments.
+ − 474 \\@{emacs-lisp-mode-map@}
+ − 475 @end group
+ − 476 @group
+ − 477 Entry to this mode runs the hook `emacs-lisp-mode-hook'."
+ − 478 (interactive)
+ − 479 (kill-all-local-variables)
+ − 480 (use-local-map emacs-lisp-mode-map) ; @r{This provides the local keymap.}
+ − 481 (set-syntax-table emacs-lisp-mode-syntax-table)
+ − 482 @end group
+ − 483 @group
+ − 484 (setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}}
+ − 485 ; @r{finds out what to describe.}
+ − 486 (setq mode-name "Emacs-Lisp") ; @r{This goes into the modeline.}
+ − 487 (lisp-mode-variables nil) ; @r{This defines various variables.}
+ − 488 (run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a}
+ − 489 ; @r{hook to customize the mode.}
+ − 490 @end group
+ − 491 @end smallexample
+ − 492
+ − 493 @node Auto Major Mode
+ − 494 @subsection How XEmacs Chooses a Major Mode
+ − 495
+ − 496 Based on information in the file name or in the file itself, XEmacs
+ − 497 automatically selects a major mode for the new buffer when a file is
+ − 498 visited.
+ − 499
+ − 500 @deffn Command fundamental-mode
+ − 501 Fundamental mode is a major mode that is not specialized for anything
+ − 502 in particular. Other major modes are defined in effect by comparison
+ − 503 with this one---their definitions say what to change, starting from
+ − 504 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
+ − 505 run any hooks; you're not supposed to customize it. (If you want Emacs
+ − 506 to behave differently in Fundamental mode, change the @emph{global}
+ − 507 state of Emacs.)
+ − 508 @end deffn
+ − 509
+ − 510 @deffn Command normal-mode &optional find-file
+ − 511 This function establishes the proper major mode and local variable
+ − 512 bindings for the current buffer. First it calls @code{set-auto-mode},
+ − 513 then it runs @code{hack-local-variables} to parse, and bind or
+ − 514 evaluate as appropriate, any local variables.
+ − 515
+ − 516 If the @var{find-file} argument to @code{normal-mode} is
+ − 517 non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
+ − 518 function is calling it. In this case, it may process a local variables
+ − 519 list at the end of the file and in the @samp{-*-} line. The variable
+ − 520 @code{enable-local-variables} controls whether to do so.
+ − 521
+ − 522 If you run @code{normal-mode} interactively, the argument
+ − 523 @var{find-file} is normally @code{nil}. In this case,
+ − 524 @code{normal-mode} unconditionally processes any local variables list.
446
+ − 525 @xref{File variables, , Local Variables in Files, xemacs, The XEmacs
428
+ − 526 Reference Manual}, for the syntax of the local variables section of a file.
+ − 527
+ − 528 @cindex file mode specification error
+ − 529 @code{normal-mode} uses @code{condition-case} around the call to the
+ − 530 major mode function, so errors are caught and reported as a @samp{File
+ − 531 mode specification error}, followed by the original error message.
+ − 532 @end deffn
+ − 533
+ − 534 @defopt enable-local-variables
+ − 535 This variable controls processing of local variables lists in files
+ − 536 being visited. A value of @code{t} means process the local variables
+ − 537 lists unconditionally; @code{nil} means ignore them; anything else means
+ − 538 ask the user what to do for each file. The default value is @code{t}.
+ − 539 @end defopt
+ − 540
+ − 541 @defvar ignored-local-variables
+ − 542 This variable holds a list of variables that should not be
+ − 543 set by a local variables list. Any value specified
+ − 544 for one of these variables is ignored.
+ − 545 @end defvar
+ − 546
+ − 547 In addition to this list, any variable whose name has a non-@code{nil}
+ − 548 @code{risky-local-variable} property is also ignored.
+ − 549
+ − 550 @defopt enable-local-eval
+ − 551 This variable controls processing of @samp{Eval:} in local variables
+ − 552 lists in files being visited. A value of @code{t} means process them
+ − 553 unconditionally; @code{nil} means ignore them; anything else means ask
+ − 554 the user what to do for each file. The default value is @code{maybe}.
+ − 555 @end defopt
+ − 556
+ − 557 @defun set-auto-mode
+ − 558 @cindex visited file mode
+ − 559 This function selects the major mode that is appropriate for the
+ − 560 current buffer. It may base its decision on the value of the @w{@samp{-*-}}
+ − 561 line, on the visited file name (using @code{auto-mode-alist}), or on the
+ − 562 value of a local variable. However, this function does not look for
+ − 563 the @samp{mode:} local variable near the end of a file; the
+ − 564 @code{hack-local-variables} function does that. @xref{Choosing Modes, ,
446
+ − 565 How Major Modes are Chosen, xemacs, The XEmacs Lisp Reference Manual}.
428
+ − 566 @end defun
+ − 567
444
+ − 568 @defopt default-major-mode
428
+ − 569 This variable holds the default major mode for new buffers. The
+ − 570 standard value is @code{fundamental-mode}.
+ − 571
+ − 572 If the value of @code{default-major-mode} is @code{nil}, XEmacs uses
+ − 573 the (previously) current buffer's major mode for the major mode of a new
+ − 574 buffer. However, if the major mode symbol has a @code{mode-class}
+ − 575 property with value @code{special}, then it is not used for new buffers;
+ − 576 Fundamental mode is used instead. The modes that have this property are
+ − 577 those such as Dired and Rmail that are useful only with text that has
+ − 578 been specially prepared.
+ − 579 @end defopt
+ − 580
+ − 581 @defun set-buffer-major-mode buffer
+ − 582 This function sets the major mode of @var{buffer} to the value of
+ − 583 @code{default-major-mode}. If that variable is @code{nil}, it uses
+ − 584 the current buffer's major mode (if that is suitable).
+ − 585
+ − 586 The low-level primitives for creating buffers do not use this function,
+ − 587 but medium-level commands such as @code{switch-to-buffer} and
+ − 588 @code{find-file-noselect} use it whenever they create buffers.
+ − 589 @end defun
+ − 590
+ − 591 @defvar initial-major-mode
+ − 592 @cindex @samp{*scratch*}
+ − 593 The value of this variable determines the major mode of the initial
+ − 594 @samp{*scratch*} buffer. The value should be a symbol that is a major
+ − 595 mode command name. The default value is @code{lisp-interaction-mode}.
+ − 596 @end defvar
+ − 597
+ − 598 @defvar auto-mode-alist
+ − 599 This variable contains an association list of file name patterns
+ − 600 (regular expressions; @pxref{Regular Expressions}) and corresponding
+ − 601 major mode functions. Usually, the file name patterns test for
+ − 602 suffixes, such as @samp{.el} and @samp{.c}, but this need not be the
+ − 603 case. An ordinary element of the alist looks like @code{(@var{regexp} .
+ − 604 @var{mode-function})}.
+ − 605
+ − 606 For example,
+ − 607
+ − 608 @smallexample
+ − 609 @group
+ − 610 (("^/tmp/fol/" . text-mode)
+ − 611 ("\\.texinfo\\'" . texinfo-mode)
+ − 612 ("\\.texi\\'" . texinfo-mode)
+ − 613 @end group
+ − 614 @group
+ − 615 ("\\.el\\'" . emacs-lisp-mode)
444
+ − 616 ("\\.c\\'" . c-mode)
428
+ − 617 ("\\.h\\'" . c-mode)
+ − 618 @dots{})
+ − 619 @end group
+ − 620 @end smallexample
+ − 621
+ − 622 When you visit a file whose expanded file name (@pxref{File Name
+ − 623 Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
+ − 624 corresponding @var{mode-function}. This feature enables XEmacs to select
+ − 625 the proper major mode for most files.
+ − 626
+ − 627 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
+ − 628 @var{function} t)}, then after calling @var{function}, XEmacs searches
+ − 629 @code{auto-mode-alist} again for a match against the portion of the file
+ − 630 name that did not match before.
+ − 631
+ − 632 This match-again feature is useful for uncompression packages: an entry
+ − 633 of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file
+ − 634 and then put the uncompressed file in the proper mode according to the
+ − 635 name sans @samp{.gz}.
+ − 636
+ − 637 Here is an example of how to prepend several pattern pairs to
+ − 638 @code{auto-mode-alist}. (You might use this sort of expression in your
+ − 639 @file{.emacs} file.)
+ − 640
+ − 641 @smallexample
+ − 642 @group
+ − 643 (setq auto-mode-alist
444
+ − 644 (append
428
+ − 645 ;; @r{File name starts with a dot.}
444
+ − 646 '(("/\\.[^/]*\\'" . fundamental-mode)
428
+ − 647 ;; @r{File name has no dot.}
444
+ − 648 ("[^\\./]*\\'" . fundamental-mode)
428
+ − 649 ;; @r{File name ends in @samp{.C}.}
+ − 650 ("\\.C\\'" . c++-mode))
+ − 651 auto-mode-alist))
+ − 652 @end group
+ − 653 @end smallexample
+ − 654 @end defvar
+ − 655
+ − 656 @defvar interpreter-mode-alist
+ − 657 This variable specifies major modes to use for scripts that specify a
+ − 658 command interpreter in an @samp{#!} line. Its value is a list of
+ − 659 elements of the form @code{(@var{interpreter} . @var{mode})}; for
+ − 660 example, @code{("perl" . perl-mode)} is one element present by default.
+ − 661 The element says to use mode @var{mode} if the file specifies
+ − 662 @var{interpreter}.
+ − 663
+ − 664 This variable is applicable only when the @code{auto-mode-alist} does
+ − 665 not indicate which major mode to use.
+ − 666 @end defvar
+ − 667
+ − 668 @defun hack-local-variables &optional force
+ − 669 This function parses, and binds or evaluates as appropriate, any local
+ − 670 variables for the current buffer.
+ − 671
+ − 672 The handling of @code{enable-local-variables} documented for
+ − 673 @code{normal-mode} actually takes place here. The argument @var{force}
+ − 674 usually comes from the argument @var{find-file} given to
+ − 675 @code{normal-mode}.
+ − 676 @end defun
+ − 677
+ − 678 @node Mode Help
+ − 679 @subsection Getting Help about a Major Mode
+ − 680 @cindex mode help
+ − 681 @cindex help for major mode
+ − 682 @cindex documentation for major mode
+ − 683
+ − 684 The @code{describe-mode} function is used to provide information
+ − 685 about major modes. It is normally called with @kbd{C-h m}. The
+ − 686 @code{describe-mode} function uses the value of @code{major-mode},
+ − 687 which is why every major mode function needs to set the
+ − 688 @code{major-mode} variable.
+ − 689
+ − 690 @deffn Command describe-mode
+ − 691 This function displays the documentation of the current major mode.
+ − 692
+ − 693 The @code{describe-mode} function calls the @code{documentation}
+ − 694 function using the value of @code{major-mode} as an argument. Thus, it
+ − 695 displays the documentation string of the major mode function.
+ − 696 (@xref{Accessing Documentation}.)
+ − 697 @end deffn
+ − 698
+ − 699 @defvar major-mode
+ − 700 This variable holds the symbol for the current buffer's major mode.
+ − 701 This symbol should have a function definition that is the command to
+ − 702 switch to that major mode. The @code{describe-mode} function uses the
+ − 703 documentation string of the function as the documentation of the major
+ − 704 mode.
+ − 705 @end defvar
+ − 706
+ − 707 @node Derived Modes
+ − 708 @subsection Defining Derived Modes
+ − 709
+ − 710 It's often useful to define a new major mode in terms of an existing
+ − 711 one. An easy way to do this is to use @code{define-derived-mode}.
+ − 712
+ − 713 @defmac define-derived-mode variant parent name docstring body@dots{}
+ − 714 This construct defines @var{variant} as a major mode command, using
+ − 715 @var{name} as the string form of the mode name.
+ − 716
+ − 717 The new command @var{variant} is defined to call the function
+ − 718 @var{parent}, then override certain aspects of that parent mode:
+ − 719
444
+ − 720 @itemize @bullet
428
+ − 721 @item
+ − 722 The new mode has its own keymap, named @code{@var{variant}-map}.
+ − 723 @code{define-derived-mode} initializes this map to inherit from
+ − 724 @code{@var{parent}-map}, if it is not already set.
+ − 725
+ − 726 @item
+ − 727 The new mode has its own syntax table, kept in the variable
+ − 728 @code{@var{variant}-syntax-table}.
444
+ − 729 @code{define-derived-mode} initializes this variable by copying
428
+ − 730 @code{@var{parent}-syntax-table}, if it is not already set.
+ − 731
+ − 732 @item
+ − 733 The new mode has its own abbrev table, kept in the variable
+ − 734 @code{@var{variant}-abbrev-table}.
444
+ − 735 @code{define-derived-mode} initializes this variable by copying
428
+ − 736 @code{@var{parent}-abbrev-table}, if it is not already set.
+ − 737
+ − 738 @item
+ − 739 The new mode has its own mode hook, @code{@var{variant}-hook},
+ − 740 which it runs in standard fashion as the very last thing that it does.
444
+ − 741 (The new mode also runs the mode hook of @var{parent} as part
428
+ − 742 of calling @var{parent}.)
+ − 743 @end itemize
+ − 744
+ − 745 In addition, you can specify how to override other aspects of
+ − 746 @var{parent} with @var{body}. The command @var{variant}
444
+ − 747 evaluates the forms in @var{body} after setting up all its usual
428
+ − 748 overrides, just before running @code{@var{variant}-hook}.
+ − 749
+ − 750 The argument @var{docstring} specifies the documentation string for the
+ − 751 new mode. If you omit @var{docstring}, @code{define-derived-mode}
+ − 752 generates a documentation string.
+ − 753
+ − 754 Here is a hypothetical example:
+ − 755
+ − 756 @example
+ − 757 (define-derived-mode hypertext-mode
+ − 758 text-mode "Hypertext"
+ − 759 "Major mode for hypertext.
+ − 760 \\@{hypertext-mode-map@}"
+ − 761 (setq case-fold-search nil))
+ − 762
+ − 763 (define-key hypertext-mode-map
+ − 764 [down-mouse-3] 'do-hyper-link)
+ − 765 @end example
2135
+ − 766
+ − 767 Do not write an @code{interactive} spec in the definition;
+ − 768 @code{define-derived-mode} does that automatically.
428
+ − 769 @end defmac
+ − 770
+ − 771 @node Minor Modes
+ − 772 @section Minor Modes
+ − 773 @cindex minor mode
+ − 774
+ − 775 A @dfn{minor mode} provides features that users may enable or disable
+ − 776 independently of the choice of major mode. Minor modes can be enabled
+ − 777 individually or in combination. Minor modes would be better named
+ − 778 ``Generally available, optional feature modes'' except that such a name is
+ − 779 unwieldy.
+ − 780
+ − 781 A minor mode is not usually a modification of single major mode. For
+ − 782 example, Auto Fill mode may be used in any major mode that permits text
+ − 783 insertion. To be general, a minor mode must be effectively independent
+ − 784 of the things major modes do.
+ − 785
+ − 786 A minor mode is often much more difficult to implement than a major
+ − 787 mode. One reason is that you should be able to activate and deactivate
+ − 788 minor modes in any order. A minor mode should be able to have its
+ − 789 desired effect regardless of the major mode and regardless of the other
+ − 790 minor modes in effect.
+ − 791
+ − 792 Often the biggest problem in implementing a minor mode is finding a
+ − 793 way to insert the necessary hook into the rest of XEmacs. Minor mode
+ − 794 keymaps make this easier than it used to be.
+ − 795
+ − 796 @menu
+ − 797 * Minor Mode Conventions:: Tips for writing a minor mode.
+ − 798 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+ − 799 @end menu
+ − 800
+ − 801 @node Minor Mode Conventions
+ − 802 @subsection Conventions for Writing Minor Modes
+ − 803 @cindex minor mode conventions
+ − 804 @cindex conventions for writing minor modes
+ − 805
+ − 806 There are conventions for writing minor modes just as there are for
+ − 807 major modes. Several of the major mode conventions apply to minor
+ − 808 modes as well: those regarding the name of the mode initialization
+ − 809 function, the names of global symbols, and the use of keymaps and
+ − 810 other tables.
+ − 811
+ − 812 In addition, there are several conventions that are specific to
+ − 813 minor modes.
+ − 814
+ − 815 @itemize @bullet
+ − 816 @item
+ − 817 @cindex mode variable
+ − 818 Make a variable whose name ends in @samp{-mode} to represent the minor
+ − 819 mode. Its value should enable or disable the mode (@code{nil} to
+ − 820 disable; anything else to enable.) We call this the @dfn{mode
+ − 821 variable}.
+ − 822
+ − 823 This variable is used in conjunction with the @code{minor-mode-alist} to
+ − 824 display the minor mode name in the modeline. It can also enable
+ − 825 or disable a minor mode keymap. Individual commands or hooks can also
+ − 826 check the variable's value.
+ − 827
+ − 828 If you want the minor mode to be enabled separately in each buffer,
+ − 829 make the variable buffer-local.
+ − 830
+ − 831 @item
+ − 832 Define a command whose name is the same as the mode variable.
+ − 833 Its job is to enable and disable the mode by setting the variable.
+ − 834
+ − 835 The command should accept one optional argument. If the argument is
+ − 836 @code{nil}, it should toggle the mode (turn it on if it is off, and off
+ − 837 if it is on). Otherwise, it should turn the mode on if the argument is
+ − 838 a positive integer, a symbol other than @code{nil} or @code{-}, or a
+ − 839 list whose @sc{car} is such an integer or symbol; it should turn the
+ − 840 mode off otherwise.
+ − 841
+ − 842 Here is an example taken from the definition of @code{transient-mark-mode}.
+ − 843 It shows the use of @code{transient-mark-mode} as a variable that enables or
+ − 844 disables the mode's behavior, and also shows the proper way to toggle,
+ − 845 enable or disable the minor mode based on the raw prefix argument value.
+ − 846
+ − 847 @smallexample
+ − 848 @group
+ − 849 (setq transient-mark-mode
+ − 850 (if (null arg) (not transient-mark-mode)
+ − 851 (> (prefix-numeric-value arg) 0)))
+ − 852 @end group
+ − 853 @end smallexample
+ − 854
+ − 855 @item
+ − 856 Add an element to @code{minor-mode-alist} for each minor mode
+ − 857 (@pxref{Modeline Variables}). This element should be a list of the
+ − 858 following form:
+ − 859
+ − 860 @smallexample
+ − 861 (@var{mode-variable} @var{string})
+ − 862 @end smallexample
+ − 863
+ − 864 Here @var{mode-variable} is the variable that controls enabling of the
+ − 865 minor mode, and @var{string} is a short string, starting with a space,
+ − 866 to represent the mode in the modeline. These strings must be short so
+ − 867 that there is room for several of them at once.
+ − 868
+ − 869 When you add an element to @code{minor-mode-alist}, use @code{assq} to
+ − 870 check for an existing element, to avoid duplication. For example:
+ − 871
+ − 872 @smallexample
+ − 873 @group
+ − 874 (or (assq 'leif-mode minor-mode-alist)
+ − 875 (setq minor-mode-alist
+ − 876 (cons '(leif-mode " Leif") minor-mode-alist)))
+ − 877 @end group
+ − 878 @end smallexample
+ − 879 @end itemize
+ − 880
+ − 881 @node Keymaps and Minor Modes
+ − 882 @subsection Keymaps and Minor Modes
+ − 883
+ − 884 Each minor mode can have its own keymap, which is active when the mode
+ − 885 is enabled. To set up a keymap for a minor mode, add an element to the
+ − 886 alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
+ − 887
+ − 888 @cindex @code{self-insert-command}, minor modes
+ − 889 One use of minor mode keymaps is to modify the behavior of certain
+ − 890 self-inserting characters so that they do something else as well as
+ − 891 self-insert. In general, this is the only way to do that, since the
+ − 892 facilities for customizing @code{self-insert-command} are limited to
+ − 893 special cases (designed for abbrevs and Auto Fill mode). (Do not try
+ − 894 substituting your own definition of @code{self-insert-command} for the
+ − 895 standard one. The editor command loop handles this function specially.)
+ − 896
+ − 897 @node Modeline Format
+ − 898 @section Modeline Format
+ − 899 @cindex modeline
+ − 900
+ − 901 Each Emacs window (aside from minibuffer windows) includes a modeline,
+ − 902 which displays status information about the buffer displayed in the
+ − 903 window. The modeline contains information about the buffer, such as its
+ − 904 name, associated file, depth of recursive editing, and the major and
+ − 905 minor modes.
+ − 906
+ − 907 This section describes how the contents of the modeline are
+ − 908 controlled. It is in the chapter on modes because much of the
+ − 909 information displayed in the modeline relates to the enabled major and
+ − 910 minor modes.
+ − 911
+ − 912 @code{modeline-format} is a buffer-local variable that holds a
+ − 913 template used to display the modeline of the current buffer. All
+ − 914 windows for the same buffer use the same @code{modeline-format} and
+ − 915 their modelines appear the same (except for scrolling percentages and
+ − 916 line numbers).
+ − 917
+ − 918 The modeline of a window is normally updated whenever a different
+ − 919 buffer is shown in the window, or when the buffer's modified-status
+ − 920 changes from @code{nil} to @code{t} or vice-versa. If you modify any of
+ − 921 the variables referenced by @code{modeline-format} (@pxref{Modeline
+ − 922 Variables}), you may want to force an update of the modeline so as to
+ − 923 display the new information.
+ − 924
+ − 925 @c Emacs 19 feature
+ − 926 @defun redraw-modeline &optional all
+ − 927 Force redisplay of the current buffer's modeline. If @var{all} is
+ − 928 non-@code{nil}, then force redisplay of all modelines.
+ − 929 @end defun
+ − 930
+ − 931 The modeline is usually displayed in inverse video. This
+ − 932 is controlled using the @code{modeline} face. @xref{Faces}.
+ − 933
+ − 934 @menu
+ − 935 * Modeline Data:: The data structure that controls the modeline.
+ − 936 * Modeline Variables:: Variables used in that data structure.
+ − 937 * %-Constructs:: Putting information into a modeline.
+ − 938 @end menu
+ − 939
+ − 940 @node Modeline Data
+ − 941 @subsection The Data Structure of the Modeline
+ − 942 @cindex modeline construct
+ − 943
+ − 944 The modeline contents are controlled by a data structure of lists,
+ − 945 strings, symbols, and numbers kept in the buffer-local variable
442
+ − 946 @code{modeline-format}. The data structure is called a @dfn{modeline
428
+ − 947 construct}, and it is built in recursive fashion out of simpler modeline
+ − 948 constructs. The same data structure is used for constructing
+ − 949 frame titles (@pxref{Frame Titles}).
+ − 950
+ − 951 @defvar modeline-format
+ − 952 The value of this variable is a modeline construct with overall
+ − 953 responsibility for the modeline format. The value of this variable
+ − 954 controls which other variables are used to form the modeline text, and
+ − 955 where they appear.
+ − 956 @end defvar
+ − 957
+ − 958 A modeline construct may be as simple as a fixed string of text, but
+ − 959 it usually specifies how to use other variables to construct the text.
+ − 960 Many of these variables are themselves defined to have modeline
+ − 961 constructs as their values.
+ − 962
+ − 963 The default value of @code{modeline-format} incorporates the values
+ − 964 of variables such as @code{mode-name} and @code{minor-mode-alist}.
+ − 965 Because of this, very few modes need to alter @code{modeline-format}.
+ − 966 For most purposes, it is sufficient to alter the variables referenced by
+ − 967 @code{modeline-format}.
+ − 968
442
+ − 969 A modeline construct may be a string, symbol, glyph, generic
+ − 970 specifier, list or cons cell.
428
+ − 971
+ − 972 @table @code
+ − 973 @cindex percent symbol in modeline
+ − 974 @item @var{string}
+ − 975 A string as a modeline construct is displayed verbatim in the mode line
+ − 976 except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
+ − 977 specify the field width for space filling on the right (i.e., the data
+ − 978 is left justified). @xref{%-Constructs}.
+ − 979
+ − 980 @item @var{symbol}
+ − 981 A symbol as a modeline construct stands for its value. The value of
442
+ − 982 @var{symbol} is processed as a modeline construct, in place of
+ − 983 @var{symbol}. However, the symbols @code{t} and @code{nil} are ignored;
+ − 984 so is any symbol whose value is void.
428
+ − 985
+ − 986 There is one exception: if the value of @var{symbol} is a string, it is
+ − 987 displayed verbatim: the @code{%}-constructs are not recognized.
+ − 988
442
+ − 989 @item @var{glyph}
+ − 990 A glyph is displayed as is.
+ − 991
+ − 992 @item @var{generic-specifier}
+ − 993 A @var{generic-specifier} (i.e. a specifier of type @code{generic})
+ − 994 stands for its instance. The instance of @var{generic-specifier} is
+ − 995 computed in the current window using the equivalent of
+ − 996 @code{specifier-instance} and the value is processed.
+ − 997
428
+ − 998 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
+ − 999 A list whose first element is a string or list means to process all the
+ − 1000 elements recursively and concatenate the results. This is the most
+ − 1001 common form of mode line construct.
+ − 1002
+ − 1003 @item (@var{symbol} @var{then} @var{else})
+ − 1004 A list whose first element is a symbol is a conditional. Its meaning
+ − 1005 depends on the value of @var{symbol}. If the value is non-@code{nil},
+ − 1006 the second element, @var{then}, is processed recursively as a modeline
+ − 1007 element. But if the value of @var{symbol} is @code{nil}, the third
+ − 1008 element, @var{else}, is processed recursively. You may omit @var{else};
+ − 1009 then the mode line element displays nothing if the value of @var{symbol}
+ − 1010 is @code{nil}.
+ − 1011
+ − 1012 @item (@var{width} @var{rest}@dots{})
+ − 1013 A list whose first element is an integer specifies truncation or
+ − 1014 padding of the results of @var{rest}. The remaining elements
+ − 1015 @var{rest} are processed recursively as modeline constructs and
+ − 1016 concatenated together. Then the result is space filled (if
+ − 1017 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
+ − 1018 if @var{width} is negative) on the right.
+ − 1019
+ − 1020 For example, the usual way to show what percentage of a buffer is above
+ − 1021 the top of the window is to use a list like this: @code{(-3 "%p")}.
442
+ − 1022
+ − 1023 @item (@var{extent} @var{rest}@dots{})
+ − 1024
+ − 1025 A list whose car is an extent means the cdr of the list is processed
+ − 1026 normally but the results are displayed using the face of the extent, and
+ − 1027 mouse clicks over this section are processed using the keymap of the
+ − 1028 extent. (In addition, if the extent has a help-echo property, that
+ − 1029 string will be echoed when the mouse moves over this section.) If
+ − 1030 extents are nested, all keymaps are properly consulted when processing
+ − 1031 mouse clicks, but multiple faces are not correctly merged (only the
+ − 1032 first face is used), and lists of faces are not correctly handled.
+ − 1033 @c #### Document generate-modeline-string.
+ − 1034 @c See `generated-modeline-string' for more information.
428
+ − 1035 @end table
+ − 1036
+ − 1037 If you do alter @code{modeline-format} itself, the new value should
+ − 1038 use the same variables that appear in the default value (@pxref{Modeline
+ − 1039 Variables}), rather than duplicating their contents or displaying
+ − 1040 the information in another fashion. This way, customizations made by
+ − 1041 the user or by Lisp programs (such as @code{display-time} and major
+ − 1042 modes) via changes to those variables remain effective.
+ − 1043
+ − 1044 @cindex Shell mode @code{modeline-format}
+ − 1045 Here is an example of a @code{modeline-format} that might be
+ − 1046 useful for @code{shell-mode}, since it contains the hostname and default
+ − 1047 directory.
+ − 1048
+ − 1049 @example
+ − 1050 @group
+ − 1051 (setq modeline-format
+ − 1052 (list ""
+ − 1053 'modeline-modified
444
+ − 1054 "%b--"
428
+ − 1055 @end group
+ − 1056 (getenv "HOST") ; @r{One element is not constant.}
444
+ − 1057 ":"
428
+ − 1058 'default-directory
+ − 1059 " "
+ − 1060 'global-mode-string
+ − 1061 " %[("
444
+ − 1062 'mode-name
+ − 1063 'modeline-process
+ − 1064 'minor-mode-alist
+ − 1065 "%n"
428
+ − 1066 ")%]----"
+ − 1067 @group
+ − 1068 '(line-number-mode "L%l--")
+ − 1069 '(-3 . "%p")
+ − 1070 "-%-"))
+ − 1071 @end group
+ − 1072 @end example
+ − 1073
+ − 1074 @node Modeline Variables
+ − 1075 @subsection Variables Used in the Modeline
+ − 1076
+ − 1077 This section describes variables incorporated by the
+ − 1078 standard value of @code{modeline-format} into the text of the mode
+ − 1079 line. There is nothing inherently special about these variables; any
+ − 1080 other variables could have the same effects on the modeline if
+ − 1081 @code{modeline-format} were changed to use them.
+ − 1082
+ − 1083 @defvar modeline-modified
+ − 1084 This variable holds the value of the modeline construct that displays
+ − 1085 whether the current buffer is modified.
+ − 1086
+ − 1087 The default value of @code{modeline-modified} is @code{("--%1*%1+-")}.
+ − 1088 This means that the modeline displays @samp{--**-} if the buffer is
+ − 1089 modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
+ − 1090 the buffer is read only, and @samp{--%*--} if the buffer is read only
+ − 1091 and modified.
+ − 1092
+ − 1093 Changing this variable does not force an update of the modeline.
+ − 1094 @end defvar
+ − 1095
+ − 1096 @defvar modeline-buffer-identification
+ − 1097 This variable identifies the buffer being displayed in the window. Its
+ − 1098 default value is @code{("%F: %17b")}, which means that it usually
+ − 1099 displays @samp{Emacs:} followed by seventeen characters of the buffer
+ − 1100 name. (In a terminal frame, it displays the frame name instead of
+ − 1101 @samp{Emacs}; this has the effect of showing the frame number.) You may
+ − 1102 want to change this in modes such as Rmail that do not behave like a
+ − 1103 ``normal'' XEmacs.
+ − 1104 @end defvar
+ − 1105
+ − 1106 @defvar global-mode-string
+ − 1107 This variable holds a modeline spec that appears in the mode line by
+ − 1108 default, just after the buffer name. The command @code{display-time}
+ − 1109 sets @code{global-mode-string} to refer to the variable
+ − 1110 @code{display-time-string}, which holds a string containing the time and
+ − 1111 load information.
+ − 1112
+ − 1113 The @samp{%M} construct substitutes the value of
+ − 1114 @code{global-mode-string}, but this is obsolete, since the variable is
+ − 1115 included directly in the modeline.
+ − 1116 @end defvar
+ − 1117
+ − 1118 @defvar mode-name
+ − 1119 This buffer-local variable holds the ``pretty'' name of the current
+ − 1120 buffer's major mode. Each major mode should set this variable so that the
+ − 1121 mode name will appear in the modeline.
+ − 1122 @end defvar
+ − 1123
+ − 1124 @defvar minor-mode-alist
+ − 1125 This variable holds an association list whose elements specify how the
+ − 1126 modeline should indicate that a minor mode is active. Each element of
+ − 1127 the @code{minor-mode-alist} should be a two-element list:
+ − 1128
+ − 1129 @example
+ − 1130 (@var{minor-mode-variable} @var{modeline-string})
+ − 1131 @end example
+ − 1132
+ − 1133 More generally, @var{modeline-string} can be any mode line spec. It
+ − 1134 appears in the mode line when the value of @var{minor-mode-variable} is
+ − 1135 non-@code{nil}, and not otherwise. These strings should begin with
+ − 1136 spaces so that they don't run together. Conventionally, the
+ − 1137 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
+ − 1138 value when that minor mode is activated.
+ − 1139
+ − 1140 The default value of @code{minor-mode-alist} is:
+ − 1141
+ − 1142 @example
+ − 1143 @group
+ − 1144 minor-mode-alist
+ − 1145 @result{} ((vc-mode vc-mode)
444
+ − 1146 (abbrev-mode " Abbrev")
+ − 1147 (overwrite-mode overwrite-mode)
+ − 1148 (auto-fill-function " Fill")
428
+ − 1149 (defining-kbd-macro " Def")
+ − 1150 (isearch-mode isearch-mode))
+ − 1151 @end group
+ − 1152 @end example
+ − 1153
+ − 1154 @code{minor-mode-alist} is not buffer-local. The variables mentioned
+ − 1155 in the alist should be buffer-local if the minor mode can be enabled
+ − 1156 separately in each buffer.
+ − 1157 @end defvar
+ − 1158
+ − 1159 @defvar modeline-process
+ − 1160 This buffer-local variable contains the modeline information on process
+ − 1161 status in modes used for communicating with subprocesses. It is
+ − 1162 displayed immediately following the major mode name, with no intervening
+ − 1163 space. For example, its value in the @samp{*shell*} buffer is
+ − 1164 @code{(":@: %s")}, which allows the shell to display its status along
+ − 1165 with the major mode as: @samp{(Shell:@: run)}. Normally this variable
+ − 1166 is @code{nil}.
+ − 1167 @end defvar
+ − 1168
+ − 1169 @defvar default-modeline-format
+ − 1170 This variable holds the default @code{modeline-format} for buffers
+ − 1171 that do not override it. This is the same as @code{(default-value
+ − 1172 'modeline-format)}.
+ − 1173
+ − 1174 The default value of @code{default-modeline-format} is:
+ − 1175
+ − 1176 @example
+ − 1177 @group
+ − 1178 (""
+ − 1179 modeline-modified
+ − 1180 modeline-buffer-identification
+ − 1181 " "
+ − 1182 global-mode-string
+ − 1183 " %[("
444
+ − 1184 mode-name
428
+ − 1185 @end group
+ − 1186 @group
+ − 1187 modeline-process
444
+ − 1188 minor-mode-alist
+ − 1189 "%n"
428
+ − 1190 ")%]----"
+ − 1191 (line-number-mode "L%l--")
+ − 1192 (-3 . "%p")
+ − 1193 "-%-")
+ − 1194 @end group
+ − 1195 @end example
+ − 1196 @end defvar
+ − 1197
+ − 1198 @defvar vc-mode
+ − 1199 The variable @code{vc-mode}, local in each buffer, records whether the
+ − 1200 buffer's visited file is maintained with version control, and, if so,
+ − 1201 which kind. Its value is @code{nil} for no version control, or a string
+ − 1202 that appears in the mode line.
+ − 1203 @end defvar
+ − 1204
+ − 1205 @node %-Constructs
+ − 1206 @subsection @code{%}-Constructs in the ModeLine
+ − 1207
+ − 1208 The following table lists the recognized @code{%}-constructs and what
+ − 1209 they mean. In any construct except @samp{%%}, you can add a decimal
+ − 1210 integer after the @samp{%} to specify how many characters to display.
+ − 1211
+ − 1212 @table @code
+ − 1213 @item %b
+ − 1214 The current buffer name, obtained with the @code{buffer-name} function.
+ − 1215 @xref{Buffer Names}.
+ − 1216
+ − 1217 @item %f
+ − 1218 The visited file name, obtained with the @code{buffer-file-name}
+ − 1219 function. @xref{Buffer File Name}.
+ − 1220
+ − 1221 @item %F
+ − 1222 The name of the selected frame.
+ − 1223
+ − 1224 @item %c
+ − 1225 The current column number of point.
+ − 1226
+ − 1227 @item %l
+ − 1228 The current line number of point.
+ − 1229
+ − 1230 @item %*
+ − 1231 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
+ − 1232 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
+ − 1233 @samp{-} otherwise. @xref{Buffer Modification}.
+ − 1234
+ − 1235 @item %+
+ − 1236 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
+ − 1237 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
+ − 1238 @samp{-} otherwise. This differs from @samp{%*} only for a modified
+ − 1239 read-only buffer. @xref{Buffer Modification}.
+ − 1240
+ − 1241 @item %&
+ − 1242 @samp{*} if the buffer is modified, and @samp{-} otherwise.
+ − 1243
+ − 1244 @item %s
+ − 1245 The status of the subprocess belonging to the current buffer, obtained with
+ − 1246 @code{process-status}. @xref{Process Information}.
+ − 1247
+ − 1248 @c The following two may only apply in XEmacs.
+ − 1249 @item %l
442
+ − 1250 The current line number.
428
+ − 1251
+ − 1252 @item %S
442
+ − 1253 The name of the selected frame; this is only meaningful under the
428
+ − 1254 X Window System. @xref{Frame Name}.
+ − 1255
+ − 1256 @item %t
+ − 1257 Whether the visited file is a text file or a binary file. (This is a
+ − 1258 meaningful distinction only on certain operating systems.)
+ − 1259
+ − 1260 @item %p
+ − 1261 The percentage of the buffer text above the @strong{top} of window, or
+ − 1262 @samp{Top}, @samp{Bottom} or @samp{All}.
+ − 1263
+ − 1264 @item %P
+ − 1265 The percentage of the buffer text that is above the @strong{bottom} of
+ − 1266 the window (which includes the text visible in the window, as well as
+ − 1267 the text above the top), plus @samp{Top} if the top of the buffer is
+ − 1268 visible on screen; or @samp{Bottom} or @samp{All}.
+ − 1269
+ − 1270 @item %n
+ − 1271 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
+ − 1272 @code{narrow-to-region} in @ref{Narrowing}).
+ − 1273
442
+ − 1274 @item %C
+ − 1275 Under XEmacs/mule, the mnemonic for @code{buffer-file-coding-system}.
+ − 1276
428
+ − 1277 @item %[
+ − 1278 An indication of the depth of recursive editing levels (not counting
+ − 1279 minibuffer levels): one @samp{[} for each editing level.
+ − 1280 @xref{Recursive Editing}.
+ − 1281
+ − 1282 @item %]
+ − 1283 One @samp{]} for each recursive editing level (not counting minibuffer
+ − 1284 levels).
+ − 1285
+ − 1286 @item %%
+ − 1287 The character @samp{%}---this is how to include a literal @samp{%} in a
+ − 1288 string in which @code{%}-constructs are allowed.
+ − 1289
+ − 1290 @item %-
+ − 1291 Dashes sufficient to fill the remainder of the modeline.
+ − 1292 @end table
+ − 1293
+ − 1294 The following two @code{%}-constructs are still supported, but they are
+ − 1295 obsolete, since you can get the same results with the variables
+ − 1296 @code{mode-name} and @code{global-mode-string}.
+ − 1297
+ − 1298 @table @code
+ − 1299 @item %m
+ − 1300 The value of @code{mode-name}.
+ − 1301
+ − 1302 @item %M
+ − 1303 The value of @code{global-mode-string}. Currently, only
+ − 1304 @code{display-time} modifies the value of @code{global-mode-string}.
+ − 1305 @end table
+ − 1306
+ − 1307 @node Hooks
+ − 1308 @section Hooks
+ − 1309 @cindex hooks
+ − 1310
+ − 1311 A @dfn{hook} is a variable where you can store a function or functions
+ − 1312 to be called on a particular occasion by an existing program. XEmacs
+ − 1313 provides hooks for the sake of customization. Most often, hooks are set
+ − 1314 up in the @file{.emacs} file, but Lisp programs can set them also.
+ − 1315 @xref{Standard Hooks}, for a list of standard hook variables.
+ − 1316
+ − 1317 Most of the hooks in XEmacs are @dfn{normal hooks}. These variables
+ − 1318 contain lists of functions to be called with no arguments. The reason
+ − 1319 most hooks are normal hooks is so that you can use them in a uniform
444
+ − 1320 way. You can usually tell when a hook is a normal hook, because its
428
+ − 1321 name ends in @samp{-hook}.
+ − 1322
+ − 1323 The recommended way to add a hook function to a normal hook is by
+ − 1324 calling @code{add-hook} (see below). The hook functions may be any of
+ − 1325 the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
+ − 1326 a Function}). Most normal hook variables are initially void;
+ − 1327 @code{add-hook} knows how to deal with this.
+ − 1328
+ − 1329 As for abnormal hooks, those whose names end in @samp{-function} have
+ − 1330 a value that is a single function. Those whose names end in
+ − 1331 @samp{-hooks} have a value that is a list of functions. Any hook that
+ − 1332 is abnormal is abnormal because a normal hook won't do the job; either
+ − 1333 the functions are called with arguments, or their values are meaningful.
+ − 1334 The name shows you that the hook is abnormal and that you should look at
+ − 1335 its documentation string to see how to use it properly.
+ − 1336
+ − 1337 Major mode functions are supposed to run a hook called the @dfn{mode
+ − 1338 hook} as the last step of initialization. This makes it easy for a user
+ − 1339 to customize the behavior of the mode, by overriding the local variable
+ − 1340 assignments already made by the mode. But hooks are used in other
+ − 1341 contexts too. For example, the hook @code{suspend-hook} runs just
+ − 1342 before XEmacs suspends itself (@pxref{Suspending XEmacs}).
+ − 1343
+ − 1344 Here's an expression that uses a mode hook to turn on Auto Fill mode
+ − 1345 when in Lisp Interaction mode:
+ − 1346
+ − 1347 @example
+ − 1348 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
+ − 1349 @end example
+ − 1350
+ − 1351 The next example shows how to use a hook to customize the way XEmacs
+ − 1352 formats C code. (People often have strong personal preferences for one
+ − 1353 format or another.) Here the hook function is an anonymous lambda
+ − 1354 expression.
+ − 1355
+ − 1356 @cindex lambda expression in hook
+ − 1357 @example
+ − 1358 @group
444
+ − 1359 (add-hook 'c-mode-hook
428
+ − 1360 (function (lambda ()
+ − 1361 (setq c-indent-level 4
+ − 1362 c-argdecl-indent 0
+ − 1363 c-label-offset -4
+ − 1364 @end group
+ − 1365 @group
+ − 1366 c-continued-statement-indent 0
+ − 1367 c-brace-offset 0
+ − 1368 comment-column 40))))
+ − 1369
+ − 1370 (setq c++-mode-hook c-mode-hook)
+ − 1371 @end group
+ − 1372 @end example
+ − 1373
+ − 1374 The final example shows how the appearance of the modeline can be
+ − 1375 modified for a particular class of buffers only.
+ − 1376
+ − 1377 @example
+ − 1378 @group
+ − 1379 (add-hook 'text-mode-hook
+ − 1380 (function (lambda ()
+ − 1381 (setq modeline-format
+ − 1382 '(modeline-modified
+ − 1383 "Emacs: %14b"
444
+ − 1384 " "
428
+ − 1385 @end group
+ − 1386 @group
+ − 1387 default-directory
+ − 1388 " "
+ − 1389 global-mode-string
444
+ − 1390 "%[("
+ − 1391 mode-name
+ − 1392 minor-mode-alist
+ − 1393 "%n"
+ − 1394 modeline-process
428
+ − 1395 ") %]---"
+ − 1396 (-3 . "%p")
+ − 1397 "-%-")))))
+ − 1398 @end group
+ − 1399 @end example
+ − 1400
+ − 1401 At the appropriate time, XEmacs uses the @code{run-hooks} function to
+ − 1402 run particular hooks. This function calls the hook functions you have
+ − 1403 added with @code{add-hooks}.
+ − 1404
+ − 1405 @defun run-hooks &rest hookvar
+ − 1406 This function takes one or more hook variable names as arguments, and
+ − 1407 runs each hook in turn. Each @var{hookvar} argument should be a symbol
+ − 1408 that is a hook variable. These arguments are processed in the order
+ − 1409 specified.
+ − 1410
+ − 1411 If a hook variable has a non-@code{nil} value, that value may be a
+ − 1412 function or a list of functions. If the value is a function (either a
+ − 1413 lambda expression or a symbol with a function definition), it is
+ − 1414 called. If it is a list, the elements are called, in order.
+ − 1415 The hook functions are called with no arguments.
+ − 1416
+ − 1417 For example, here's how @code{emacs-lisp-mode} runs its mode hook:
+ − 1418
+ − 1419 @example
+ − 1420 (run-hooks 'emacs-lisp-mode-hook)
+ − 1421 @end example
+ − 1422 @end defun
+ − 1423
2135
+ − 1424 @defun run-mode-hooks &rest hookvars
+ − 1425 Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks}
+ − 1426 macro.
+ − 1427 @end defun
+ − 1428
+ − 1429 @defmac delay-mode-hooks body...
+ − 1430 This macro executes the @var{body} forms but defers all calls to
+ − 1431 @code{run-mode-hooks} within them until the end of @var{body}.
+ − 1432 This macro enables a derived mode to arrange not to run
+ − 1433 its parent modes' mode hooks until the end.
+ − 1434 @end defmac
+ − 1435
+ − 1436 @defun run-hook-with-args hook &rest args
+ − 1437 This function is the way to run an abnormal hook and always call all
+ − 1438 of the hook functions. It calls each of the hook functions one by
+ − 1439 one, passing each of them the arguments @var{args}.
+ − 1440 @end defun
+ − 1441
+ − 1442 @defun run-hook-with-args-until-failure hook &rest args
+ − 1443 This function is the way to run an abnormal hook until one of the hook
+ − 1444 functions fails. It calls each of the hook functions, passing each of
+ − 1445 them the arguments @var{args}, until some hook function returns
+ − 1446 @code{nil}. It then stops and returns @code{nil}. If none of the
+ − 1447 hook functions return @code{nil}, it returns a non-@code{nil} value.
+ − 1448 @end defun
+ − 1449
+ − 1450 @defun run-hook-with-args-until-success hook &rest args
+ − 1451 This function is the way to run an abnormal hook until a hook function
+ − 1452 succeeds. It calls each of the hook functions, passing each of them
+ − 1453 the arguments @var{args}, until some hook function returns
+ − 1454 non-@code{nil}. Then it stops, and returns whatever was returned by
+ − 1455 the last hook function that was called. If all hook functions return
+ − 1456 @code{nil}, it returns @code{nil} as well.
+ − 1457 @end defun
+ − 1458
428
+ − 1459 @defun add-hook hook function &optional append local
+ − 1460 This function is the handy way to add function @var{function} to hook
+ − 1461 variable @var{hook}. The argument @var{function} may be any valid Lisp
+ − 1462 function with the proper number of arguments. For example,
+ − 1463
+ − 1464 @example
+ − 1465 (add-hook 'text-mode-hook 'my-text-hook-function)
+ − 1466 @end example
+ − 1467
+ − 1468 @noindent
+ − 1469 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
+ − 1470
+ − 1471 You can use @code{add-hook} for abnormal hooks as well as for normal
+ − 1472 hooks.
+ − 1473
+ − 1474 It is best to design your hook functions so that the order in which they
+ − 1475 are executed does not matter. Any dependence on the order is ``asking
+ − 1476 for trouble.'' However, the order is predictable: normally,
+ − 1477 @var{function} goes at the front of the hook list, so it will be
+ − 1478 executed first (barring another @code{add-hook} call).
+ − 1479
+ − 1480 If the optional argument @var{append} is non-@code{nil}, the new hook
+ − 1481 function goes at the end of the hook list and will be executed last.
+ − 1482
+ − 1483 If @var{local} is non-@code{nil}, that says to make the new hook
+ − 1484 function local to the current buffer. Before you can do this, you must
+ − 1485 make the hook itself buffer-local by calling @code{make-local-hook}
+ − 1486 (@strong{not} @code{make-local-variable}). If the hook itself is not
+ − 1487 buffer-local, then the value of @var{local} makes no difference---the
+ − 1488 hook function is always global.
+ − 1489 @end defun
+ − 1490
+ − 1491 @defun remove-hook hook function &optional local
+ − 1492 This function removes @var{function} from the hook variable @var{hook}.
+ − 1493
+ − 1494 If @var{local} is non-@code{nil}, that says to remove @var{function}
+ − 1495 from the local hook list instead of from the global hook list. If the
+ − 1496 hook itself is not buffer-local, then the value of @var{local} makes no
+ − 1497 difference.
+ − 1498 @end defun
+ − 1499
+ − 1500 @defun make-local-hook hook
444
+ − 1501 This function makes the hook variable @var{hook} local to the current
428
+ − 1502 buffer. When a hook variable is local, it can have local and global
+ − 1503 hook functions, and @code{run-hooks} runs all of them.
+ − 1504
+ − 1505 This function works by making @code{t} an element of the buffer-local
+ − 1506 value. That serves as a flag to use the hook functions in the default
+ − 1507 value of the hook variable as well as those in the local value. Since
+ − 1508 @code{run-hooks} understands this flag, @code{make-local-hook} works
+ − 1509 with all normal hooks. It works for only some non-normal hooks---those
+ − 1510 whose callers have been updated to understand this meaning of @code{t}.
+ − 1511
+ − 1512 Do not use @code{make-local-variable} directly for hook variables; it is
+ − 1513 not sufficient.
+ − 1514 @end defun