|
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
|
