1 This is ../info/lispref.info, produced by makeinfo version 4.8 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input
55 25.6.5 Miscellaneous Event Input Features
56 -----------------------------------------
58 This section describes how to "peek ahead" at events without using them
59 up, how to check for pending input, and how to discard pending input.
61 See also the variables `last-command-event' and `last-command-char'
62 (*Note Command Loop Info::).
64 -- Variable: unread-command-events
65 This variable holds a list of events waiting to be read as command
66 input. The events are used in the order they appear in the list,
67 and removed one by one as they are used.
69 The variable is needed because in some cases a function reads an
70 event and then decides not to use it. Storing the event in this
71 variable causes it to be processed normally, by the command loop
72 or by the functions to read command input.
74 For example, the function that implements numeric prefix arguments
75 reads any number of digits. When it finds a non-digit event, it
76 must unread the event so that it can be read normally by the
77 command loop. Likewise, incremental search uses this feature to
78 unread events with no special meaning in a search, because these
79 events should exit the search and then execute normally.
82 -- Variable: unread-command-event
83 This variable holds a single event to be read as command input.
85 This variable is mostly obsolete now that you can use
86 `unread-command-events' instead; it exists only to support programs
87 written for versions of XEmacs prior to 19.12.
89 -- Function: input-pending-p
90 This function determines whether any command input is currently
91 available to be read. It returns immediately, with value `t' if
92 there is available input, `nil' otherwise. On rare occasions it
93 may return `t' when no input is available.
95 -- Variable: last-input-event
96 This variable is set to the last keyboard or mouse button event
99 This variable is off limits: you may not set its value or modify
100 the event that is its value, as it is destructively modified by
101 `read-key-sequence'. If you want to keep a pointer to this value,
102 you must use `copy-event'.
104 Note that this variable is an alias for `last-input-char' in FSF
107 In the example below, a character is read (the character `1'). It
108 becomes the value of `last-input-event', while `C-e' (from the
109 `C-x C-e' command used to evaluate this expression) remains the
110 value of `last-command-event'.
112 (progn (print (next-command-event))
113 (print last-command-event)
115 -| #<keypress-event 1>
116 -| #<keypress-event control-E>
117 => #<keypress-event 1>
119 -- Variable: last-input-char
120 If the value of `last-input-event' is a keyboard event, then this
121 is the nearest ASCII equivalent to it. Remember that there is
122 _not_ a 1:1 mapping between keyboard events and ASCII characters:
123 the set of keyboard events is much larger, so writing code that
124 examines this variable to determine what key has been typed is bad
125 practice, unless you are certain that it will be one of a small
128 This function exists for compatibility with Emacs version 18.
130 -- Function: discard-input
131 This function discards the contents of the terminal input buffer
132 and cancels any keyboard macro that might be in the process of
133 definition. It returns `nil'.
135 In the following example, the user may type a number of characters
136 right after starting the evaluation of the form. After the
137 `sleep-for' finishes sleeping, `discard-input' discards any
138 characters typed during the sleep.
145 File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop
147 25.7 Waiting for Elapsed Time or Input
148 ======================================
150 The wait functions are designed to wait for a certain amount of time to
151 pass or until there is input. For example, you may wish to pause in
152 the middle of a computation to allow the user time to view the display.
153 `sit-for' pauses and updates the screen, and returns immediately if
154 input comes in, while `sleep-for' pauses without updating the screen.
156 Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take
157 two arguments to specify the time (one integer and one float value),
158 instead of a single argument that can be either an integer or a float.
160 -- Function: sit-for seconds &optional nodisplay
161 This function performs redisplay (provided there is no pending
162 input from the user), then waits SECONDS seconds, or until input is
163 available. The result is `t' if `sit-for' waited the full time
164 with no input arriving (see `input-pending-p' in *Note Peeking and
165 Discarding::). Otherwise, the value is `nil'.
167 The argument SECONDS need not be an integer. If it is a floating
168 point number, `sit-for' waits for a fractional number of seconds.
170 Redisplay is normally preempted if input arrives, and does not
171 happen at all if input is available before it starts. (You can
172 force screen updating in such a case by using `force-redisplay'.
173 *Note Refresh Screen::.) If there is no input pending, you can
174 force an update with no delay by using `(sit-for 0)'.
176 If NODISPLAY is non-`nil', then `sit-for' does not redisplay, but
177 it still returns as soon as input is available (or when the
180 The usual purpose of `sit-for' is to give the user time to read
181 text that you display.
183 -- Function: sleep-for seconds
184 This function simply pauses for SECONDS seconds without updating
185 the display. This function pays no attention to available input.
188 The argument SECONDS need not be an integer. If it is a floating
189 point number, `sleep-for' waits for a fractional number of seconds.
191 Use `sleep-for' when you wish to guarantee a delay.
193 *Note Time of Day::, for functions to get the current time.
196 File: lispref.info, Node: Quitting, Next: Prefix Command Arguments, Prev: Waiting, Up: Command Loop
201 Typing `C-g' while a Lisp function is running causes XEmacs to "quit"
202 whatever it is doing. This means that control returns to the innermost
205 Typing `C-g' while the command loop is waiting for keyboard input
206 does not cause a quit; it acts as an ordinary input character. In the
207 simplest case, you cannot tell the difference, because `C-g' normally
208 runs the command `keyboard-quit', whose effect is to quit. However,
209 when `C-g' follows a prefix key, the result is an undefined key. The
210 effect is to cancel the prefix key as well as any prefix argument.
212 In the minibuffer, `C-g' has a different definition: it aborts out
213 of the minibuffer. This means, in effect, that it exits the minibuffer
214 and then quits. (Simply quitting would return to the command loop
215 _within_ the minibuffer.) The reason why `C-g' does not quit directly
216 when the command reader is reading input is so that its meaning can be
217 redefined in the minibuffer in this way. `C-g' following a prefix key
218 is not redefined in the minibuffer, and it has its normal effect of
219 canceling the prefix key and prefix argument. This too would not be
220 possible if `C-g' always quit directly.
222 When `C-g' does directly quit, it does so by setting the variable
223 `quit-flag' to `t'. XEmacs checks this variable at appropriate times
224 and quits if it is not `nil'. Setting `quit-flag' non-`nil' in any way
227 At the level of C code, quitting cannot happen just anywhere; only
228 at the special places that check `quit-flag'. The reason for this is
229 that quitting at other places might leave an inconsistency in XEmacs's
230 internal state. Because quitting is delayed until a safe place,
231 quitting cannot make XEmacs crash.
233 Certain functions such as `read-key-sequence' or `read-quoted-char'
234 prevent quitting entirely even though they wait for input. Instead of
235 quitting, `C-g' serves as the requested input. In the case of
236 `read-key-sequence', this serves to bring about the special behavior of
237 `C-g' in the command loop. In the case of `read-quoted-char', this is
238 so that `C-q' can be used to quote a `C-g'.
240 You can prevent quitting for a portion of a Lisp function by binding
241 the variable `inhibit-quit' to a non-`nil' value. Then, although `C-g'
242 still sets `quit-flag' to `t' as usual, the usual result of this--a
243 quit--is prevented. Eventually, `inhibit-quit' will become `nil'
244 again, such as when its binding is unwound at the end of a `let' form.
245 At that time, if `quit-flag' is still non-`nil', the requested quit
246 happens immediately. This behavior is ideal when you wish to make sure
247 that quitting does not happen within a "critical section" of the
250 In some functions (such as `read-quoted-char'), `C-g' is handled in
251 a special way that does not involve quitting. This is done by reading
252 the input with `inhibit-quit' bound to `t', and setting `quit-flag' to
253 `nil' before `inhibit-quit' becomes `nil' again. This excerpt from the
254 definition of `read-quoted-char' shows how this is done; it also shows
255 that normal quitting is permitted after the first character of input.
257 (defun read-quoted-char (&optional prompt)
258 "...DOCUMENTATION..."
259 (let ((count 0) (code 0) char)
261 (let ((inhibit-quit (zerop count))
263 (and prompt (message "%s-" prompt))
264 (setq char (read-char))
265 (if inhibit-quit (setq quit-flag nil)))
269 -- Variable: quit-flag
270 If this variable is non-`nil', then XEmacs quits immediately,
271 unless `inhibit-quit' is non-`nil'. Typing `C-g' ordinarily sets
272 `quit-flag' non-`nil', regardless of `inhibit-quit'.
274 -- Variable: inhibit-quit
275 This variable determines whether XEmacs should quit when
276 `quit-flag' is set to a value other than `nil'. If `inhibit-quit'
277 is non-`nil', then `quit-flag' has no special effect.
279 -- Command: keyboard-quit
280 This function signals the `quit' condition with `(signal 'quit
281 nil)'. This is the same thing that quitting does. (See `signal'
284 You can specify a character other than `C-g' to use for quitting.
285 See the function `set-input-mode' in *Note Terminal Input::.
288 File: lispref.info, Node: Prefix Command Arguments, Next: Recursive Editing, Prev: Quitting, Up: Command Loop
290 25.9 Prefix Command Arguments
291 =============================
293 Most XEmacs commands can use a "prefix argument", a number specified
294 before the command itself. (Don't confuse prefix arguments with prefix
295 keys.) The prefix argument is at all times represented by a value,
296 which may be `nil', meaning there is currently no prefix argument.
297 Each command may use the prefix argument or ignore it.
299 There are two representations of the prefix argument: "raw" and
300 "numeric". The editor command loop uses the raw representation
301 internally, and so do the Lisp variables that store the information, but
302 commands can request either representation.
304 Here are the possible values of a raw prefix argument:
306 * `nil', meaning there is no prefix argument. Its numeric value is
307 1, but numerous commands make a distinction between `nil' and the
310 * An integer, which stands for itself.
312 * A list of one element, which is an integer. This form of prefix
313 argument results from one or a succession of `C-u''s with no
314 digits. The numeric value is the integer in the list, but some
315 commands make a distinction between such a list and an integer
318 * The symbol `-'. This indicates that `M--' or `C-u -' was typed,
319 without following digits. The equivalent numeric value is -1, but
320 some commands make a distinction between the integer -1 and the
323 We illustrate these possibilities by calling the following function
324 with various prefixes:
326 (defun display-prefix (arg)
327 "Display the value of the raw prefix arg."
331 Here are the results of calling `display-prefix' with various raw
334 M-x display-prefix -| nil
336 C-u M-x display-prefix -| (4)
338 C-u C-u M-x display-prefix -| (16)
340 C-u 3 M-x display-prefix -| 3
342 M-3 M-x display-prefix -| 3 ; (Same as `C-u 3'.)
344 C-3 M-x display-prefix -| 3 ; (Same as `C-u 3'.)
346 C-u - M-x display-prefix -| -
348 M-- M-x display-prefix -| - ; (Same as `C-u -'.)
350 C-- M-x display-prefix -| - ; (Same as `C-u -'.)
352 C-u - 7 M-x display-prefix -| -7
354 M-- 7 M-x display-prefix -| -7 ; (Same as `C-u -7'.)
356 C-- 7 M-x display-prefix -| -7 ; (Same as `C-u -7'.)
358 XEmacs uses two variables to store the prefix argument: `prefix-arg'
359 and `current-prefix-arg'. Commands such as `universal-argument' that
360 set up prefix arguments for other commands store them in `prefix-arg'.
361 In contrast, `current-prefix-arg' conveys the prefix argument to the
362 current command, so setting it has no effect on the prefix arguments
365 Normally, commands specify which representation to use for the prefix
366 argument, either numeric or raw, in the `interactive' declaration.
367 (*Note Using Interactive::.) Alternatively, functions may look at the
368 value of the prefix argument directly in the variable
369 `current-prefix-arg', but this is less clean.
371 -- Function: prefix-numeric-value raw
372 This function returns the numeric meaning of a valid raw prefix
373 argument value, RAW. The argument may be a symbol, a number, or a
374 list. If it is `nil', the value 1 is returned; if it is `-', the
375 value -1 is returned; if it is a number, that number is returned;
376 if it is a list, the CAR of that list (which should be a number) is
379 -- Variable: current-prefix-arg
380 This variable holds the raw prefix argument for the _current_
381 command. Commands may examine it directly, but the usual way to
382 access it is with `(interactive "P")'.
384 -- Variable: prefix-arg
385 The value of this variable is the raw prefix argument for the
386 _next_ editing command. Commands that specify prefix arguments for
387 the following command work by setting this variable.
389 Do not call the functions `universal-argument', `digit-argument', or
390 `negative-argument' unless you intend to let the user enter the prefix
391 argument for the _next_ command.
393 -- Command: universal-argument
394 This command reads input and specifies a prefix argument for the
395 following command. Don't call this command yourself unless you
396 know what you are doing.
398 -- Command: digit-argument arg
399 This command adds to the prefix argument for the following
400 command. The argument ARG is the raw prefix argument as it was
401 before this command; it is used to compute the updated prefix
402 argument. Don't call this command yourself unless you know what
405 -- Command: negative-argument arg
406 This command adds to the numeric argument for the next command.
407 The argument ARG is the raw prefix argument as it was before this
408 command; its value is negated to form the new prefix argument.
409 Don't call this command yourself unless you know what you are
413 File: lispref.info, Node: Recursive Editing, Next: Disabling Commands, Prev: Prefix Command Arguments, Up: Command Loop
415 25.10 Recursive Editing
416 =======================
418 The XEmacs command loop is entered automatically when XEmacs starts up.
419 This top-level invocation of the command loop never exits; it keeps
420 running as long as XEmacs does. Lisp programs can also invoke the
421 command loop. Since this makes more than one activation of the command
422 loop, we call it "recursive editing". A recursive editing level has
423 the effect of suspending whatever command invoked it and permitting the
424 user to do arbitrary editing before resuming that command.
426 The commands available during recursive editing are the same ones
427 available in the top-level editing loop and defined in the keymaps.
428 Only a few special commands exit the recursive editing level; the others
429 return to the recursive editing level when they finish. (The special
430 commands for exiting are always available, but they do nothing when
431 recursive editing is not in progress.)
433 All command loops, including recursive ones, set up all-purpose error
434 handlers so that an error in a command run from the command loop will
437 Minibuffer input is a special kind of recursive editing. It has a
438 few special wrinkles, such as enabling display of the minibuffer and the
439 minibuffer window, but fewer than you might suppose. Certain keys
440 behave differently in the minibuffer, but that is only because of the
441 minibuffer's local map; if you switch windows, you get the usual XEmacs
444 To invoke a recursive editing level, call the function
445 `recursive-edit'. This function contains the command loop; it also
446 contains a call to `catch' with tag `exit', which makes it possible to
447 exit the recursive editing level by throwing to `exit' (*note Catch and
448 Throw::). If you throw a value other than `t', then `recursive-edit'
449 returns normally to the function that called it. The command `C-M-c'
450 (`exit-recursive-edit') does this. Throwing a `t' value causes
451 `recursive-edit' to quit, so that control returns to the command loop
452 one level up. This is called "aborting", and is done by `C-]'
453 (`abort-recursive-edit').
455 Most applications should not use recursive editing, except as part of
456 using the minibuffer. Usually it is more convenient for the user if you
457 change the major mode of the current buffer temporarily to a special
458 major mode, which should have a command to go back to the previous mode.
459 (The `e' command in Rmail uses this technique.) Or, if you wish to
460 give the user different text to edit "recursively", create and select a
461 new buffer in a special mode. In this mode, define a command to
462 complete the processing and go back to the previous buffer. (The `m'
463 command in Rmail does this.)
465 Recursive edits are useful in debugging. You can insert a call to
466 `debug' into a function definition as a sort of breakpoint, so that you
467 can look around when the function gets there. `debug' invokes a
468 recursive edit but also provides the other features of the debugger.
470 Recursive editing levels are also used when you type `C-r' in
471 `query-replace' or use `C-x q' (`kbd-macro-query').
473 -- Command: recursive-edit
474 This function invokes the editor command loop. It is called
475 automatically by the initialization of XEmacs, to let the user
476 begin editing. When called from a Lisp program, it enters a
477 recursive editing level.
479 In the following example, the function `simple-rec' first advances
480 point one word, then enters a recursive edit, printing out a
481 message in the echo area. The user can then do any editing
482 desired, and then type `C-M-c' to exit and continue executing
487 (message "Recursive edit in progress")
494 -- Command: exit-recursive-edit
495 This function exits from the innermost recursive edit (including
496 minibuffer input). Its definition is effectively `(throw 'exit
499 -- Command: abort-recursive-edit
500 This function aborts the command that requested the innermost
501 recursive edit (including minibuffer input), by signaling `quit'
502 after exiting the recursive edit. Its definition is effectively
503 `(throw 'exit t)'. *Note Quitting::.
505 -- Command: top-level
506 This function exits all recursive editing levels; it does not
507 return a value, as it jumps completely out of any computation
508 directly back to the main command loop.
510 -- Function: recursion-depth
511 This function returns the current depth of recursive edits. When
512 no recursive edit is active, it returns 0.
515 File: lispref.info, Node: Disabling Commands, Next: Command History, Prev: Recursive Editing, Up: Command Loop
517 25.11 Disabling Commands
518 ========================
520 "Disabling a command" marks the command as requiring user confirmation
521 before it can be executed. Disabling is used for commands which might
522 be confusing to beginning users, to prevent them from using the
523 commands by accident.
525 The low-level mechanism for disabling a command is to put a
526 non-`nil' `disabled' property on the Lisp symbol for the command.
527 These properties are normally set up by the user's `.emacs' file with
528 Lisp expressions such as this:
530 (put 'upcase-region 'disabled t)
532 For a few commands, these properties are present by default and may be
533 removed by the `.emacs' file.
535 If the value of the `disabled' property is a string, the message
536 saying the command is disabled includes that string. For example:
538 (put 'delete-region 'disabled
539 "Text deleted this way cannot be yanked back!\n")
541 *Note Disabling: (xemacs)Disabling, for the details on what happens
542 when a disabled command is invoked interactively. Disabling a command
543 has no effect on calling it as a function from Lisp programs.
545 -- Command: enable-command command
546 Allow COMMAND to be executed without special confirmation from now
547 on, and (if the user confirms) alter the user's `.emacs' file so
548 that this will apply to future sessions.
550 -- Command: disable-command command
551 Require special confirmation to execute COMMAND from now on, and
552 (if the user confirms) alter the user's `.emacs' file so that this
553 will apply to future sessions.
555 -- Variable: disabled-command-hook
556 This normal hook is run instead of a disabled command, when the
557 user invokes the disabled command interactively. The hook
558 functions can use `this-command-keys' to determine what the user
559 typed to run the command, and thus find the command itself. *Note
562 By default, `disabled-command-hook' contains a function that asks
563 the user whether to proceed.
566 File: lispref.info, Node: Command History, Next: Keyboard Macros, Prev: Disabling Commands, Up: Command Loop
568 25.12 Command History
569 =====================
571 The command loop keeps a history of the complex commands that have been
572 executed, to make it convenient to repeat these commands. A "complex
573 command" is one for which the interactive argument reading uses the
574 minibuffer. This includes any `M-x' command, any `M-:' command, and
575 any command whose `interactive' specification reads an argument from
576 the minibuffer. Explicit use of the minibuffer during the execution of
577 the command itself does not cause the command to be considered complex.
579 -- Variable: command-history
580 This variable's value is a list of recent complex commands, each
581 represented as a form to evaluate. It continues to accumulate all
582 complex commands for the duration of the editing session, but all
583 but the first (most recent) thirty elements are deleted when a
584 garbage collection takes place (*note Garbage Collection::).
587 => ((switch-to-buffer "chistory.texi")
588 (describe-key "^X^[")
589 (visit-tags-table "~/emacs/src/")
590 (find-tag "repeat-complex-command"))
592 This history list is actually a special case of minibuffer history
593 (*note Minibuffer History::), with one special twist: the elements are
594 expressions rather than strings.
596 There are a number of commands devoted to the editing and recall of
597 previous commands. The commands `repeat-complex-command', and
598 `list-command-history' are described in the user manual (*note
599 Repetition: (xemacs)Repetition.). Within the minibuffer, the history
600 commands used are the same ones available in any minibuffer.
603 File: lispref.info, Node: Keyboard Macros, Prev: Command History, Up: Command Loop
605 25.13 Keyboard Macros
606 =====================
608 A "keyboard macro" is a canned sequence of input events that can be
609 considered a command and made the definition of a key. The Lisp
610 representation of a keyboard macro is a string or vector containing the
611 events. Don't confuse keyboard macros with Lisp macros (*note
614 -- Function: execute-kbd-macro macro &optional count
615 This function executes MACRO as a sequence of events. If MACRO is
616 a string or vector, then the events in it are executed exactly as
617 if they had been input by the user. The sequence is _not_
618 expected to be a single key sequence; normally a keyboard macro
619 definition consists of several key sequences concatenated.
621 If MACRO is a symbol, then its function definition is used in
622 place of MACRO. If that is another symbol, this process repeats.
623 Eventually the result should be a string or vector. If the result
624 is not a symbol, string, or vector, an error is signaled.
626 The argument COUNT is a repeat count; MACRO is executed that many
627 times. If COUNT is omitted or `nil', MACRO is executed once. If
628 it is 0, MACRO is executed over and over until it encounters an
629 error or a failing search.
631 -- Variable: executing-macro
632 This variable contains the string or vector that defines the
633 keyboard macro that is currently executing. It is `nil' if no
634 macro is currently executing. A command can test this variable to
635 behave differently when run from an executing macro. Do not set
636 this variable yourself.
638 -- Variable: defining-kbd-macro
639 This variable indicates whether a keyboard macro is being defined.
640 A command can test this variable to behave differently while a
641 macro is being defined. The commands `start-kbd-macro' and
642 `end-kbd-macro' set this variable--do not set it yourself.
644 -- Variable: last-kbd-macro
645 This variable is the definition of the most recently defined
646 keyboard macro. Its value is a string or vector, or `nil'.
648 The commands are described in the user's manual (*note Keyboard
649 Macros: (xemacs)Keyboard Macros.).
652 File: lispref.info, Node: Keymaps, Next: Menus, Prev: Command Loop, Up: Top
657 The bindings between input events and commands are recorded in data
658 structures called "keymaps". Each binding in a keymap associates (or
659 "binds") an individual event type either with another keymap or with a
660 command. When an event is bound to a keymap, that keymap is used to
661 look up the next input event; this continues until a command is found.
662 The whole process is called "key lookup".
666 * Keymap Terminology:: Definitions of terms pertaining to keymaps.
667 * Format of Keymaps:: What a keymap looks like as a Lisp object.
668 * Creating Keymaps:: Functions to create and copy keymaps.
669 * Inheritance and Keymaps:: How one keymap can inherit the bindings
671 * Key Sequences:: How to specify key sequences.
672 * Prefix Keys:: Defining a key with a keymap as its definition.
673 * Active Keymaps:: Each buffer has a local keymap
674 to override the standard (global) bindings.
675 A minor mode can also override them.
676 * Key Lookup:: How extracting elements from keymaps works.
677 * Functions for Key Lookup:: How to request key lookup.
678 * Changing Key Bindings:: Redefining a key in a keymap.
679 * Key Binding Commands:: Interactive interfaces for redefining keys.
680 * Scanning Keymaps:: Looking through all keymaps, for printing help.
681 * Other Keymap Functions:: Miscellaneous keymap functions.
684 File: lispref.info, Node: Keymap Terminology, Next: Format of Keymaps, Up: Keymaps
686 26.1 Keymap Terminology
687 =======================
689 A "keymap" is a table mapping event types to definitions (which can be
690 any Lisp objects, though only certain types are meaningful for
691 execution by the command loop). Given an event (or an event type) and a
692 keymap, XEmacs can get the event's definition. Events mapped in keymaps
693 include keypresses, button presses, and button releases (*note
696 A sequence of input events that form a unit is called a "key
697 sequence", or "key" for short. A sequence of one event is always a key
698 sequence, and so are some multi-event sequences.
700 A keymap determines a binding or definition for any key sequence. If
701 the key sequence is a single event, its binding is the definition of the
702 event in the keymap. The binding of a key sequence of more than one
703 event is found by an iterative process: the binding of the first event
704 is found, and must be a keymap; then the second event's binding is found
705 in that keymap, and so on until all the events in the key sequence are
708 If the binding of a key sequence is a keymap, we call the key
709 sequence a "prefix key". Otherwise, we call it a "complete key"
710 (because no more events can be added to it). If the binding is `nil',
711 we call the key "undefined". Examples of prefix keys are `C-c', `C-x',
712 and `C-x 4'. Examples of defined complete keys are `X', <RET>, and
713 `C-x 4 C-f'. Examples of undefined complete keys are `C-x C-g', and
714 `C-c 3'. *Note Prefix Keys::, for more details.
716 The rule for finding the binding of a key sequence assumes that the
717 intermediate bindings (found for the events before the last) are all
718 keymaps; if this is not so, the sequence of events does not form a
719 unit--it is not really a key sequence. In other words, removing one or
720 more events from the end of any valid key must always yield a prefix
721 key. For example, `C-f C-n' is not a key; `C-f' is not a prefix key,
722 so a longer sequence starting with `C-f' cannot be a key.
724 Note that the set of possible multi-event key sequences depends on
725 the bindings for prefix keys; therefore, it can be different for
726 different keymaps, and can change when bindings are changed. However,
727 a one-event sequence is always a key sequence, because it does not
728 depend on any prefix keys for its well-formedness.
730 At any time, several primary keymaps are "active"--that is, in use
731 for finding key bindings. These are the "global map", which is shared
732 by all buffers; the "local keymap", which is usually associated with a
733 specific major mode; and zero or more "minor mode keymaps", which
734 belong to currently enabled minor modes. (Not all minor modes have
735 keymaps.) The local keymap bindings shadow (i.e., take precedence
736 over) the corresponding global bindings. The minor mode keymaps shadow
737 both local and global keymaps. *Note Active Keymaps::, for details.
740 File: lispref.info, Node: Format of Keymaps, Next: Creating Keymaps, Prev: Keymap Terminology, Up: Keymaps
742 26.2 Format of Keymaps
743 ======================
745 A keymap is a primitive type that associates events with their
746 bindings. Note that this is different from Emacs 18 and FSF Emacs,
747 where keymaps are lists.
749 -- Function: keymapp object
750 This function returns `t' if OBJECT is a keymap, `nil' otherwise.
753 File: lispref.info, Node: Creating Keymaps, Next: Inheritance and Keymaps, Prev: Format of Keymaps, Up: Keymaps
755 26.3 Creating Keymaps
756 =====================
758 Here we describe the functions for creating keymaps.
760 -- Function: make-keymap &optional name
761 This function constructs and returns a new keymap object. All
762 entries in it are `nil', meaning "command undefined".
764 Optional argument NAME specifies a name to assign to the keymap,
765 as in `set-keymap-name'. This name is only a debugging
766 convenience; it is not used except when printing the keymap.
768 -- Function: make-sparse-keymap &optional name
769 This function constructs and returns a new keymap object. All
770 entries in it are `nil', meaning "command undefined". The only
771 difference between this function and `make-keymap' is that this
772 function returns a "smaller" keymap (one that is expected to
773 contain fewer entries). As keymaps dynamically resize, this
774 distinction is not great.
776 Optional argument NAME specifies a name to assign to the keymap,
777 as in `set-keymap-name'. This name is only a debugging
778 convenience; it is not used except when printing the keymap.
780 -- Function: set-keymap-name keymap new-name
781 This function assigns a "name" to a keymap. The name is only a
782 debugging convenience; it is not used except when printing the
785 -- Function: keymap-name keymap
786 This function returns the "name" of a keymap, as assigned using
789 -- Function: copy-keymap keymap
790 This function returns a copy of KEYMAP. Any keymaps that appear
791 directly as bindings in KEYMAP are also copied recursively, and so
792 on to any number of levels. However, recursive copying does not
793 take place when the definition of a character is a symbol whose
794 function definition is a keymap; the same symbol appears in the
797 (setq map (copy-keymap (current-local-map)))
798 => #<keymap 3 entries 0x21f80>
800 (eq map (current-local-map))
804 File: lispref.info, Node: Inheritance and Keymaps, Next: Key Sequences, Prev: Creating Keymaps, Up: Keymaps
806 26.4 Inheritance and Keymaps
807 ============================
809 A keymap can inherit the bindings of other keymaps. The other keymaps
810 are called the keymap's "parents", and are set with
811 `set-keymap-parents'. When searching for a binding for a key sequence
812 in a particular keymap, that keymap itself will first be searched;
813 then, if no binding was found in the map and it has parents, the first
814 parent keymap will be searched; then that keymap's parent will be
815 searched, and so on, until either a binding for the key sequence is
816 found, or a keymap without a parent is encountered. At this point, the
817 search will continue with the next parent of the most recently
818 encountered keymap that has another parent, etc. Essentially, a
819 depth-first search of all the ancestors of the keymap is conducted.
821 `(current-global-map)' is the default parent of all keymaps.
823 -- Function: set-keymap-parents keymap parents
824 This function sets the parent keymaps of KEYMAP to the list
827 If you change the bindings in one of the keymaps in PARENTS using
828 `define-key' or other key-binding functions, these changes are
829 visible in KEYMAP unless shadowed by bindings in that map or in
830 earlier-searched ancestors. The converse is not true: if you use
831 `define-key' to change KEYMAP, that affects the bindings in that
832 map, but has no effect on any of the keymaps in PARENTS.
834 -- Function: keymap-parents keymap
835 This function returns the list of parent keymaps of KEYMAP, or
836 `nil' if KEYMAP has no parents.
838 As an alternative to specifying a parent, you can also specify a
839 "default binding" that is used whenever a key is not otherwise bound in
840 the keymap. This is useful for terminal emulators, for example, which
841 may want to trap all keystrokes and pass them on in some modified
842 format. Note that if you specify a default binding for a keymap,
843 neither the keymap's parents nor the current global map are searched for
846 -- Function: set-keymap-default-binding keymap command
847 This function sets the default binding of KEYMAP to COMMAND, or
848 `nil' if no default is desired.
850 -- Function: keymap-default-binding keymap
851 This function returns the default binding of KEYMAP, or `nil' if
855 File: lispref.info, Node: Key Sequences, Next: Prefix Keys, Prev: Inheritance and Keymaps, Up: Keymaps
860 Contrary to popular belief, the world is not ASCII. When running under
861 a window manager, XEmacs can tell the difference between, for example,
862 the keystrokes `control-h', `control-shift-h', and `backspace'. You
863 can, in fact, bind different commands to each of these.
865 A "key sequence" is a set of keystrokes. A "keystroke" is a keysym
866 and some set of modifiers (such as <CONTROL> and <META>). A "keysym"
867 is what is printed on the keys on your keyboard.
869 A keysym may be represented by a symbol, or (if and only if it is
870 equivalent to an ASCII character in the range 32 - 255) by a character
871 or its equivalent ASCII code. The `A' key may be represented by the
872 symbol `A', the character `?A', or by the number 65. The `break' key
873 may be represented only by the symbol `break'.
875 A keystroke may be represented by a list: the last element of the
876 list is the key (a symbol, character, or number, as above) and the
877 preceding elements are the symbolic names of modifier keys (<CONTROL>,
878 <META>, <SUPER>, <HYPER>, <ALT>, and <SHIFT>). Thus, the sequence
879 `control-b' is represented by the forms `(control b)', `(control ?b)',
880 and `(control 98)'. A keystroke may also be represented by an event
881 object, as returned by the `next-command-event' and `read-key-sequence'
884 Note that in this context, the keystroke `control-b' is _not_
885 represented by the number 2 (the ASCII code for `^B') or the character
888 The <SHIFT> modifier is somewhat of a special case. You should not
889 (and cannot) use `(meta shift a)' to mean `(meta A)', since for
890 characters that have ASCII equivalents, the state of the shift key is
891 implicit in the keysym (`a' vs. `A'). You also cannot say `(shift =)'
892 to mean `+', as that sort of thing varies from keyboard to keyboard.
893 The <SHIFT> modifier is for use only with characters that do not have a
894 second keysym on the same key, such as `backspace' and `tab'.
896 A key sequence is a vector of keystrokes. As a degenerate case,
897 elements of this vector may also be keysyms if they have no modifiers.
898 That is, the `A' keystroke is represented by all of these forms:
900 A ?A 65 (A) (?A) (65)
901 [A] [?A] [65] [(A)] [(?A)] [(65)]
903 the `control-a' keystroke is represented by these forms:
905 (control A) (control ?A) (control 65)
906 [(control A)] [(control ?A)] [(control 65)]
908 the key sequence `control-c control-a' is represented by these forms:
910 [(control c) (control a)] [(control ?c) (control ?a)]
911 [(control 99) (control 65)] etc.
913 Mouse button clicks work just like keypresses: `(control button1)'
914 means pressing the left mouse button while holding down the control
915 key. `[(control c) (shift button3)]' means `control-c', hold <SHIFT>,
918 Commands may be bound to the mouse-button up-stroke rather than the
919 down-stroke as well. `button1' means the down-stroke, and `button1up'
920 means the up-stroke. Different commands may be bound to the up and
921 down strokes, though that is probably not what you want, so be careful.
923 For backward compatibility, a key sequence may also be represented by
924 a string. In this case, it represents the key sequence(s) that would
925 produce that sequence of ASCII characters in a purely ASCII world. For
926 example, a string containing the ASCII backspace character, `"\^H"',
927 would represent two key sequences: `(control h)' and `backspace'.
928 Binding a command to this will actually bind both of those key
929 sequences. Likewise for the following pairs:
936 control @ control space
938 After binding a command to two key sequences with a form like
940 (define-key global-map "\^X\^I" 'command-1)
942 it is possible to redefine only one of those sequences like so:
944 (define-key global-map [(control x) (control i)] 'command-2)
945 (define-key global-map [(control x) tab] 'command-3)
947 Of course, all of this applies only when running under a window
948 system. If you're talking to XEmacs through a TTY connection, you
949 don't get any of these features.
951 -- Function: event-matches-key-specifier-p event key-specifier
952 This function returns non-`nil' if EVENT matches KEY-SPECIFIER,
953 which can be any valid form representing a key sequence. This can
954 be useful, e.g., to determine if the user pressed `help-char' or
958 File: lispref.info, Node: Prefix Keys, Next: Active Keymaps, Prev: Key Sequences, Up: Keymaps
963 A "prefix key" has an associated keymap that defines what to do with
964 key sequences that start with the prefix key. For example, `C-x' is a
965 prefix key, and it uses a keymap that is also stored in the variable
966 `ctl-x-map'. Here is a list of the standard prefix keys of XEmacs and
969 * `help-map' is used for events that follow `C-h'.
971 * `mode-specific-map' is for events that follow `C-c'. This map is
972 not actually mode specific; its name was chosen to be informative
973 for the user in `C-h b' (`display-bindings'), where it describes
974 the main use of the `C-c' prefix key.
976 * `ctl-x-map' is the map used for events that follow `C-x'. This
977 map is also the function definition of `Control-X-prefix'.
979 * `ctl-x-4-map' is used for events that follow `C-x 4'.
981 * `ctl-x-5-map' is used for events that follow `C-x 5'.
983 * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have
986 * `esc-map' is an evil hack that is present for compatibility
987 purposes with Emacs 18. Defining a key in `esc-map' is equivalent
988 to defining the same key in `global-map' but with the <META>
989 prefix added. You should _not_ use this in your code. (This map is
990 also the function definition of `ESC-prefix'.)
992 The binding of a prefix key is the keymap to use for looking up the
993 events that follow the prefix key. (It may instead be a symbol whose
994 function definition is a keymap. The effect is the same, but the symbol
995 serves as a name for the prefix key.) Thus, the binding of `C-x' is
996 the symbol `Control-X-prefix', whose function definition is the keymap
997 for `C-x' commands. (The same keymap is also the value of `ctl-x-map'.)
999 Prefix key definitions can appear in any active keymap. The
1000 definitions of `C-c', `C-x', `C-h' and <ESC> as prefix keys appear in
1001 the global map, so these prefix keys are always available. Major and
1002 minor modes can redefine a key as a prefix by putting a prefix key
1003 definition for it in the local map or the minor mode's map. *Note
1006 If a key is defined as a prefix in more than one active map, then its
1007 various definitions are in effect merged: the commands defined in the
1008 minor mode keymaps come first, followed by those in the local map's
1009 prefix definition, and then by those from the global map.
1011 In the following example, we make `C-p' a prefix key in the local
1012 keymap, in such a way that `C-p' is identical to `C-x'. Then the
1013 binding for `C-p C-f' is the function `find-file', just like `C-x C-f'.
1014 The key sequence `C-p 6' is not found in any active keymap.
1016 (use-local-map (make-sparse-keymap))
1018 (local-set-key "\C-p" ctl-x-map)
1020 (key-binding "\C-p\C-f")
1023 (key-binding "\C-p6")
1026 -- Function: define-prefix-command symbol &optional mapvar
1027 This function defines SYMBOL as a prefix command: it creates a
1028 keymap and stores it as SYMBOL's function definition. Storing the
1029 symbol as the binding of a key makes the key a prefix key that has
1030 a name. If optional argument MAPVAR is not specified, it also
1031 sets SYMBOL as a variable, to have the keymap as its value. (If
1032 MAPVAR is given and is not `t', its value is stored as the value
1033 of SYMBOL.) The function returns SYMBOL.
1035 In Emacs version 18, only the function definition of SYMBOL was
1036 set, not the value as a variable.
1039 File: lispref.info, Node: Active Keymaps, Next: Key Lookup, Prev: Prefix Keys, Up: Keymaps
1044 XEmacs normally contains many keymaps; at any given time, just a few of
1045 them are "active" in that they participate in the interpretation of
1046 user input. These are the global keymap, the current buffer's local
1047 keymap, and the keymaps of any enabled minor modes.
1049 The "global keymap" holds the bindings of keys that are defined
1050 regardless of the current buffer, such as `C-f'. The variable
1051 `global-map' holds this keymap, which is always active.
1053 Each buffer may have another keymap, its "local keymap", which may
1054 contain new or overriding definitions for keys. The current buffer's
1055 local keymap is always active except when `overriding-local-map' or
1056 `overriding-terminal-local-map' overrides it. Extents and text
1057 properties can specify an alternative local map for certain parts of the
1058 buffer; see *Note Extents and Events::.
1060 Each minor mode may have a keymap; if it does, the keymap is active
1061 when the minor mode is enabled.
1063 The variable `overriding-local-map' and
1064 `overriding-terminal-local-map', if non-`nil', specify other local
1065 keymaps that override the buffer's local map and all the minor mode
1068 All the active keymaps are used together to determine what command to
1069 execute when a key is entered. XEmacs searches these maps one by one,
1070 in order of decreasing precedence, until it finds a binding in one of
1075 For key-presses, the order of keymaps searched is:
1077 * the `keymap' property of any extent(s) or text properties at point;
1079 * any applicable minor-mode maps;
1081 * the current local map of the current buffer;
1083 * the current global map.
1085 For mouse-clicks, the order of keymaps searched is:
1087 * the current local map of the `mouse-grabbed-buffer' if any;
1089 * the `keymap' property of any extent(s) at the position of the click
1090 (this includes modeline extents);
1092 * the `modeline-map' of the buffer corresponding to the modeline
1093 under the mouse (if the click happened over a modeline);
1095 * the value of `toolbar-map' in the current buffer (if the click
1096 happened over a toolbar);
1098 * the current local map of the buffer under the mouse (does not
1099 apply to toolbar clicks);
1101 * any applicable minor-mode maps;
1103 * the current global map.
1105 Note that if `overriding-local-map' or
1106 `overriding-terminal-local-map' is non-`nil', _only_ those two maps and
1107 the current global map are searched.
1109 The procedure for searching a single keymap is called "key lookup";
1110 see *Note Key Lookup::.
1112 Since every buffer that uses the same major mode normally uses the
1113 same local keymap, you can think of the keymap as local to the mode. A
1114 change to the local keymap of a buffer (using `local-set-key', for
1115 example) is seen also in the other buffers that share that keymap.
1117 The local keymaps that are used for Lisp mode, C mode, and several
1118 other major modes exist even if they have not yet been used. These
1119 local maps are the values of the variables `lisp-mode-map',
1120 `c-mode-map', and so on. For most other modes, which are less
1121 frequently used, the local keymap is constructed only when the mode is
1122 used for the first time in a session.
1124 The minibuffer has local keymaps, too; they contain various
1125 completion and exit commands. *Note Intro to Minibuffers::.
1127 *Note Standard Keymaps::, for a list of standard keymaps.
1129 -- Function: current-keymaps &optional event-or-keys
1130 This function returns a list of the current keymaps that will be
1131 searched for bindings. This lists keymaps such as the current
1132 local map and the minor-mode maps, but does not list the parents
1133 of those keymaps. EVENT-OR-KEYS controls which keymaps will be
1134 listed. If EVENT-OR-KEYS is a mouse event (or a vector whose last
1135 element is a mouse event), the keymaps for that mouse event will
1136 be listed. Otherwise, the keymaps for key presses will be listed.
1138 -- Variable: global-map
1139 This variable contains the default global keymap that maps XEmacs
1140 keyboard input to commands. The global keymap is normally this
1141 keymap. The default global keymap is a full keymap that binds
1142 `self-insert-command' to all of the printing characters.
1144 It is normal practice to change the bindings in the global map,
1145 but you should not assign this variable any value other than the
1146 keymap it starts out with.
1148 -- Function: current-global-map
1149 This function returns the current global keymap. This is the same
1150 as the value of `global-map' unless you change one or the other.
1152 (current-global-map)
1153 => #<keymap global-map 639 entries 0x221>
1155 -- Function: current-local-map &optional buffer
1156 This function returns BUFFER's local keymap, or `nil' if it has
1157 none. BUFFER defaults to the current buffer.
1159 In the following example, the keymap for the `*scratch*' buffer
1160 (using Lisp Interaction mode) has a number of entries, including
1161 one prefix key, `C-x'.
1164 => #<keymap lisp-interaction-mode-map 5 entries 0x558>
1165 (describe-bindings-internal (current-local-map))
1166 => ; Inserted into the buffer:
1167 backspace backward-delete-char-untabify
1168 linefeed eval-print-last-sexp
1170 C-j eval-print-last-sexp
1171 C-x << Prefix Command >>
1172 M-tab lisp-complete-symbol
1173 M-; lisp-indent-for-comment
1174 M-C-i lisp-complete-symbol
1177 Alt-backspace backward-kill-sexp
1178 Alt-delete kill-sexp
1182 -- Function: current-minor-mode-maps
1183 This function returns a list of the keymaps of currently enabled
1186 -- Function: use-global-map keymap
1187 This function makes KEYMAP the new current global keymap. It
1190 It is very unusual to change the global keymap.
1192 -- Function: use-local-map keymap &optional buffer
1193 This function makes KEYMAP the new local keymap of BUFFER. BUFFER
1194 defaults to the current buffer. If KEYMAP is `nil', then the
1195 buffer has no local keymap. `use-local-map' returns `nil'. Most
1196 major mode commands use this function.
1198 -- Variable: minor-mode-map-alist
1199 This variable is an alist describing keymaps that may or may not be
1200 active according to the values of certain variables. Its elements
1205 The keymap KEYMAP is active whenever VARIABLE has a non-`nil'
1206 value. Typically VARIABLE is the variable that enables or
1207 disables a minor mode. *Note Keymaps and Minor Modes::.
1209 Note that elements of `minor-mode-map-alist' do not have the same
1210 structure as elements of `minor-mode-alist'. The map must be the
1211 CDR of the element; a list with the map as the second element will
1214 What's more, the keymap itself must appear in the CDR. It does not
1215 work to store a variable in the CDR and make the map the value of
1218 When more than one minor mode keymap is active, their order of
1219 priority is the order of `minor-mode-map-alist'. But you should
1220 design minor modes so that they don't interfere with each other.
1221 If you do this properly, the order will not matter.
1223 See also `minor-mode-key-binding', above. See *Note Keymaps and
1224 Minor Modes::, for more information about minor modes.
1226 -- Variable: modeline-map
1227 This variable holds the keymap consulted for mouse-clicks on the
1228 modeline of a window. This variable may be buffer-local; its
1229 value will be looked up in the buffer of the window whose modeline
1232 -- Variable: toolbar-map
1233 This variable holds the keymap consulted for mouse-clicks over a
1236 -- Variable: mouse-grabbed-buffer
1237 If non-`nil', a buffer which should be consulted first for all
1238 mouse activity. When a mouse-click is processed, it will first be
1239 looked up in the local-map of this buffer, and then through the
1240 normal mechanism if there is no binding for that click. This
1241 buffer's value of `mode-motion-hook' will be consulted instead of
1242 the `mode-motion-hook' of the buffer of the window under the mouse.
1243 You should _bind_ this, not set it.
1245 -- Variable: overriding-local-map
1246 If non-`nil', this variable holds a keymap to use instead of the
1247 buffer's local keymap and instead of all the minor mode keymaps.
1248 This keymap, if any, overrides all other maps that would have been
1249 active, except for the current global map.
1251 -- Variable: overriding-terminal-local-map
1252 If non-`nil', this variable holds a keymap to use instead of the
1253 buffer's local keymap and instead of all the minor mode keymaps,
1254 but for the selected console only. (In other words, this variable
1255 is always console-local; putting a keymap here only applies to
1256 keystrokes coming from the selected console. *Note Consoles and
1257 Devices::.) This keymap, if any, overrides all other maps that
1258 would have been active, except for the current global map.
1261 File: lispref.info, Node: Key Lookup, Next: Functions for Key Lookup, Prev: Active Keymaps, Up: Keymaps
1266 "Key lookup" is the process of finding the binding of a key sequence
1267 from a given keymap. Actual execution of the binding is not part of
1270 Key lookup uses just the event type of each event in the key
1271 sequence; the rest of the event is ignored. In fact, a key sequence
1272 used for key lookup may designate mouse events with just their types
1273 (symbols) instead of with entire mouse events (lists). *Note Events::.
1274 Such a pseudo-key-sequence is insufficient for `command-execute', but
1275 it is sufficient for looking up or rebinding a key.
1277 When the key sequence consists of multiple events, key lookup
1278 processes the events sequentially: the binding of the first event is
1279 found, and must be a keymap; then the second event's binding is found in
1280 that keymap, and so on until all the events in the key sequence are used
1281 up. (The binding thus found for the last event may or may not be a
1282 keymap.) Thus, the process of key lookup is defined in terms of a
1283 simpler process for looking up a single event in a keymap. How that is
1284 done depends on the type of object associated with the event in that
1287 Let's use the term "keymap entry" to describe the value found by
1288 looking up an event type in a keymap. (This doesn't include the item
1289 string and other extra elements in menu key bindings because
1290 `lookup-key' and other key lookup functions don't include them in the
1291 returned value.) While any Lisp object may be stored in a keymap as a
1292 keymap entry, not all make sense for key lookup. Here is a list of the
1293 meaningful kinds of keymap entries:
1296 `nil' means that the events used so far in the lookup form an
1297 undefined key. When a keymap fails to mention an event type at
1298 all, and has no default binding, that is equivalent to a binding
1299 of `nil' for that event type.
1302 The events used so far in the lookup form a prefix key. The next
1303 event of the key sequence is looked up in KEYMAP.
1306 The events used so far in the lookup form a complete key, and
1307 COMMAND is its binding. *Note What Is a Function::.
1310 The array (either a string or a vector) is a keyboard macro. The
1311 events used so far in the lookup form a complete key, and the
1312 array is its binding. See *Note Keyboard Macros::, for more
1313 information. (Note that you cannot use a shortened form of a key
1314 sequence here, such as `(control y)'; you must use the full form
1315 `[(control y)]'. *Note Key Sequences::.)
1318 The meaning of a list depends on the types of the elements of the
1321 * If the CAR of LIST is `lambda', then the list is a lambda
1322 expression. This is presumed to be a command, and is treated
1323 as such (see above).
1325 * If the CAR of LIST is a keymap and the CDR is an event type,
1326 then this is an "indirect entry":
1328 (OTHERMAP . OTHERTYPE)
1330 When key lookup encounters an indirect entry, it looks up
1331 instead the binding of OTHERTYPE in OTHERMAP and uses that.
1333 This feature permits you to define one key as an alias for
1334 another key. For example, an entry whose CAR is the keymap
1335 called `esc-map' and whose CDR is 32 (the code for <SPC>)
1336 means, "Use the global binding of `Meta-<SPC>', whatever that
1340 The function definition of SYMBOL is used in place of SYMBOL. If
1341 that too is a symbol, then this process is repeated, any number of
1342 times. Ultimately this should lead to an object that is a keymap,
1343 a command or a keyboard macro. A list is allowed if it is a
1344 keymap or a command, but indirect entries are not understood when
1347 Note that keymaps and keyboard macros (strings and vectors) are not
1348 valid functions, so a symbol with a keymap, string, or vector as
1349 its function definition is invalid as a function. It is, however,
1350 valid as a key binding. If the definition is a keyboard macro,
1351 then the symbol is also valid as an argument to `command-execute'
1352 (*note Interactive Call::).
1354 The symbol `undefined' is worth special mention: it means to treat
1355 the key as undefined. Strictly speaking, the key is defined, and
1356 its binding is the command `undefined'; but that command does the
1357 same thing that is done automatically for an undefined key: it
1358 rings the bell (by calling `ding') but does not signal an error.
1360 `undefined' is used in local keymaps to override a global key
1361 binding and make the key "undefined" locally. A local binding of
1362 `nil' would fail to do this because it would not override the
1366 If any other type of object is found, the events used so far in the
1367 lookup form a complete key, and the object is its binding, but the
1368 binding is not executable as a command.
1370 In short, a keymap entry may be a keymap, a command, a keyboard
1371 macro, a symbol that leads to one of them, or an indirection or `nil'.
1374 File: lispref.info, Node: Functions for Key Lookup, Next: Changing Key Bindings, Prev: Key Lookup, Up: Keymaps
1376 26.9 Functions for Key Lookup
1377 =============================
1379 Here are the functions and variables pertaining to key lookup.
1381 -- Function: lookup-key keymap key &optional accept-defaults
1382 This function returns the definition of KEY in KEYMAP. If the
1383 string or vector KEY is not a valid key sequence according to the
1384 prefix keys specified in KEYMAP (which means it is "too long" and
1385 has extra events at the end), then the value is a number, the
1386 number of events at the front of KEY that compose a complete key.
1388 If ACCEPT-DEFAULTS is non-`nil', then `lookup-key' considers
1389 default bindings as well as bindings for the specific events in
1390 KEY. Otherwise, `lookup-key' reports only bindings for the
1391 specific sequence KEY, ignoring default bindings except when you
1392 explicitly ask about them.
1394 All the other functions described in this chapter that look up
1395 keys use `lookup-key'.
1397 (lookup-key (current-global-map) "\C-x\C-f")
1399 (lookup-key (current-global-map) "\C-x\C-f12345")
1402 If KEY begins with the character whose value is contained in
1403 `meta-prefix-char', that character is implicitly removed and the
1404 <META> modifier added to the key. Thus, the first example below is
1405 handled by conversion into the second example.
1407 (lookup-key (current-global-map) "\ef")
1409 (lookup-key (current-global-map) "\M-f")
1412 Unlike `read-key-sequence', this function does not modify the
1413 specified events in ways that discard information (*note Key
1414 Sequence Input::). In particular, it does not convert letters to
1417 -- Command: undefined
1418 Used in keymaps to undefine keys. If a key sequence is defined to
1419 this, invoking this key sequence causes a "key undefined" error,
1420 just as if the key sequence had no binding.
1422 -- Function: key-binding key &optional accept-defaults
1423 This function returns the binding for KEY in the current keymaps,
1424 trying all the active keymaps. The result is `nil' if KEY is
1425 undefined in the keymaps.
1427 The argument ACCEPT-DEFAULTS controls checking for default
1428 bindings, as in `lookup-key' (above).
1430 (key-binding "\C-x\C-f")
1432 (key-binding '(control home))
1433 => beginning-of-buffer
1434 (key-binding [escape escape escape])
1435 => keyboard-escape-quit
1437 -- Function: local-key-binding keys &optional accept-defaults
1438 This function returns the binding for KEYS in the current local
1439 keymap, or `nil' if it is undefined there.
1441 The argument ACCEPT-DEFAULTS controls checking for default
1442 bindings, as in `lookup-key' (above).
1444 -- Function: global-key-binding keys &optional accept-defaults
1445 This function returns the binding for command KEYS in the current
1446 global keymap, or `nil' if it is undefined there.
1448 The argument ACCEPT-DEFAULTS controls checking for default
1449 bindings, as in `lookup-key' (above).
1451 -- Function: minor-mode-key-binding key &optional accept-defaults
1452 This function returns a list of all the active minor mode bindings
1453 of KEY. More precisely, it returns an alist of pairs `(MODENAME .
1454 BINDING)', where MODENAME is the variable that enables the minor
1455 mode, and BINDING is KEY's binding in that mode. If KEY has no
1456 minor-mode bindings, the value is `nil'.
1458 If the first binding is not a prefix command, all subsequent
1459 bindings from other minor modes are omitted, since they would be
1460 completely shadowed. Similarly, the list omits non-prefix
1461 bindings that follow prefix bindings.
1463 The argument ACCEPT-DEFAULTS controls checking for default
1464 bindings, as in `lookup-key' (above).
1466 -- Variable: meta-prefix-char
1467 This variable is the meta-prefix character code. It is used when
1468 translating a two-character sequence to a meta character so it can
1469 be looked up in a keymap. For useful results, the value should be
1470 a prefix event (*note Prefix Keys::). The default value is `?\^['
1471 (integer 27), which is the ASCII character usually produced by the
1474 As long as the value of `meta-prefix-char' remains `?\^[', key
1475 lookup translates `<ESC> b' into `M-b', which is normally defined
1476 as the `backward-word' command. However, if you set
1477 `meta-prefix-char' to `?\^X' (i.e. the keystroke `C-x') or its
1478 equivalent ASCII code `24', then XEmacs will translate `C-x b'
1479 (whose standard binding is the `switch-to-buffer' command) into
1482 meta-prefix-char ; The default value.
1483 => ?\^[ ; Under XEmacs 20.
1484 => 27 ; Under XEmacs 19.
1487 ?\C-x ; The print representation
1489 => ?\^X ; Under XEmacs 20.
1490 => 24 ; Under XEmacs 19.
1491 (setq meta-prefix-char 24)
1493 (key-binding "\C-xb")
1494 => backward-word ; Now, typing `C-x b' is
1495 ; like typing `M-b'.
1497 (setq meta-prefix-char ?\e) ; Avoid confusion!
1498 ; Restore the default value!
1499 => ?\^[ ; Under XEmacs 20.
1500 => 27 ; Under XEmacs 19.
1503 File: lispref.info, Node: Changing Key Bindings, Next: Key Binding Commands, Prev: Functions for Key Lookup, Up: Keymaps
1505 26.10 Changing Key Bindings
1506 ===========================
1508 The way to rebind a key is to change its entry in a keymap. If you
1509 change a binding in the global keymap, the change is effective in all
1510 buffers (though it has no direct effect in buffers that shadow the
1511 global binding with a local one). If you change the current buffer's
1512 local map, that usually affects all buffers using the same major mode.
1513 The `global-set-key' and `local-set-key' functions are convenient
1514 interfaces for these operations (*note Key Binding Commands::). You
1515 can also use `define-key', a more general function; then you must
1516 specify explicitly the map to change.
1518 The way to specify the key sequence that you want to rebind is
1519 described above (*note Key Sequences::).
1521 For the functions below, an error is signaled if KEYMAP is not a
1522 keymap or if KEY is not a string or vector representing a key sequence.
1523 You can use event types (symbols) as shorthand for events that are
1526 -- Function: define-key keymap key binding
1527 This function sets the binding for KEY in KEYMAP. (If KEY is more
1528 than one event long, the change is actually made in another keymap
1529 reached from KEYMAP.) The argument BINDING can be any Lisp
1530 object, but only certain types are meaningful. (For a list of
1531 meaningful types, see *Note Key Lookup::.) The value returned by
1532 `define-key' is BINDING.
1534 Every prefix of KEY must be a prefix key (i.e., bound to a keymap)
1535 or undefined; otherwise an error is signaled.
1537 If some prefix of KEY is undefined, then `define-key' defines it
1538 as a prefix key so that the rest of KEY may be defined as
1541 Here is an example that creates a sparse keymap and makes a number of
1544 (setq map (make-sparse-keymap))
1545 => #<keymap 0 entries 0xbee>
1546 (define-key map "\C-f" 'forward-char)
1549 => #<keymap 1 entry 0xbee>
1550 (describe-bindings-internal map)
1551 => ; (Inserted in buffer)
1554 ;; Build sparse submap for `C-x' and bind `f' in that.
1555 (define-key map "\C-xf" 'forward-word)
1558 => #<keymap 2 entries 0xbee>
1559 (describe-bindings-internal map)
1560 => ; (Inserted in buffer)
1562 C-x << Prefix Command >>
1566 ;; Bind `C-p' to the `ctl-x-map'.
1567 (define-key map "\C-p" ctl-x-map)
1569 => #<keymap Control-X-prefix 77 entries 0x3bf>
1571 ;; Bind `C-f' to `foo' in the `ctl-x-map'.
1572 (define-key map "\C-p\C-f" 'foo)
1575 => #<keymap 3 entries 0xbee>
1576 (describe-bindings-internal map)
1577 => ; (Inserted in buffer)
1579 C-p << Prefix command Control-X-prefix >>
1580 C-x << Prefix Command >>
1582 C-p tab indent-rigidly
1583 C-p $ set-selective-display
1585 C-p ( start-kbd-macro
1588 C-p C-x exchange-point-and-mark
1589 C-p C-z suspend-or-iconify-emacs
1590 C-p M-escape repeat-complex-command
1591 C-p M-C-[ repeat-complex-command
1595 C-p 4 . find-tag-other-window
1597 C-p 4 C-o display-buffer
1599 C-p 5 0 delete-frame
1601 C-p 5 C-f find-file-other-frame
1605 C-p a i g inverse-add-global-abbrev
1606 C-p a i l inverse-add-mode-abbrev
1608 Note that storing a new binding for `C-p C-f' actually works by
1609 changing an entry in `ctl-x-map', and this has the effect of changing
1610 the bindings of both `C-p C-f' and `C-x C-f' in the default global map.
1612 -- Function: substitute-key-definition olddef newdef keymap &optional
1614 This function replaces OLDDEF with NEWDEF for any keys in KEYMAP
1615 that were bound to OLDDEF. In other words, OLDDEF is replaced
1616 with NEWDEF wherever it appears. Prefix keymaps are checked
1619 The function returns `nil'.
1621 For example, this redefines `C-x C-f', if you do it in an XEmacs
1622 with standard bindings:
1624 (substitute-key-definition
1625 'find-file 'find-file-read-only (current-global-map))
1627 If OLDMAP is non-`nil', then its bindings determine which keys to
1628 rebind. The rebindings still happen in KEYMAP, not in OLDMAP.
1629 Thus, you can change one map under the control of the bindings in
1630 another. For example,
1632 (substitute-key-definition
1633 'delete-backward-char 'my-funny-delete
1636 puts the special deletion command in `my-map' for whichever keys
1637 are globally bound to the standard deletion command.
1639 If argument PREFIX is non-`nil', then only those occurrences of
1640 OLDDEF found in keymaps accessible through the keymap bound to
1641 PREFIX in KEYMAP are redefined. See also `accessible-keymaps'.
1644 -- Function: suppress-keymap keymap &optional nodigits
1645 This function changes the contents of the full keymap KEYMAP by
1646 making all the printing characters undefined. More precisely, it
1647 binds them to the command `undefined'. This makes ordinary
1648 insertion of text impossible. `suppress-keymap' returns `nil'.
1650 If NODIGITS is `nil', then `suppress-keymap' defines digits to run
1651 `digit-argument', and `-' to run `negative-argument'. Otherwise
1652 it makes them undefined like the rest of the printing characters.
1654 The `suppress-keymap' function does not make it impossible to
1655 modify a buffer, as it does not suppress commands such as `yank'
1656 and `quoted-insert'. To prevent any modification of a buffer, make
1657 it read-only (*note Read Only Buffers::).
1659 Since this function modifies KEYMAP, you would normally use it on
1660 a newly created keymap. Operating on an existing keymap that is
1661 used for some other purpose is likely to cause trouble; for
1662 example, suppressing `global-map' would make it impossible to use
1665 Most often, `suppress-keymap' is used to initialize local keymaps
1666 of modes such as Rmail and Dired where insertion of text is not
1667 desirable and the buffer is read-only. Here is an example taken
1668 from the file `emacs/lisp/dired.el', showing how the local keymap
1669 for Dired mode is set up:
1672 (setq dired-mode-map (make-keymap))
1673 (suppress-keymap dired-mode-map)
1674 (define-key dired-mode-map "r" 'dired-rename-file)
1675 (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
1676 (define-key dired-mode-map "d" 'dired-flag-file-deleted)
1677 (define-key dired-mode-map "v" 'dired-view-file)
1678 (define-key dired-mode-map "e" 'dired-find-file)
1679 (define-key dired-mode-map "f" 'dired-find-file)
1683 File: lispref.info, Node: Key Binding Commands, Next: Scanning Keymaps, Prev: Changing Key Bindings, Up: Keymaps
1685 26.11 Commands for Binding Keys
1686 ===============================
1688 This section describes some convenient interactive interfaces for
1689 changing key bindings. They work by calling `define-key'.
1691 People often use `global-set-key' in their `.emacs' file for simple
1692 customization. For example,
1694 (global-set-key "\C-x\C-\\" 'next-line)
1698 (global-set-key [(control ?x) (control ?\\)] 'next-line)
1702 (global-set-key [?\C-x ?\C-\\] 'next-line)
1704 redefines `C-x C-\' to move down a line.
1706 (global-set-key [(meta button1)] 'mouse-set-point)
1708 redefines the first (leftmost) mouse button, typed with the Meta key, to
1709 set point where you click.
1711 -- Command: global-set-key key definition
1712 This function sets the binding of KEY in the current global map to
1715 (global-set-key KEY DEFINITION)
1717 (define-key (current-global-map) KEY DEFINITION)
1719 -- Command: global-unset-key key
1720 This function removes the binding of KEY from the current global
1723 One use of this function is in preparation for defining a longer
1724 key that uses KEY as a prefix--which would not be allowed if KEY
1725 has a non-prefix binding. For example:
1727 (global-unset-key "\C-l")
1729 (global-set-key "\C-l\C-l" 'redraw-display)
1732 This function is implemented simply using `define-key':
1734 (global-unset-key KEY)
1736 (define-key (current-global-map) KEY nil)
1738 -- Command: local-set-key key definition
1739 This function sets the binding of KEY in the current local keymap
1742 (local-set-key KEY DEFINITION)
1744 (define-key (current-local-map) KEY DEFINITION)
1746 -- Command: local-unset-key key
1747 This function removes the binding of KEY from the current local
1750 (local-unset-key KEY)
1752 (define-key (current-local-map) KEY nil)
1755 File: lispref.info, Node: Scanning Keymaps, Next: Other Keymap Functions, Prev: Key Binding Commands, Up: Keymaps
1757 26.12 Scanning Keymaps
1758 ======================
1760 This section describes functions used to scan all the current keymaps,
1761 or all keys within a keymap, for the sake of printing help information.
1763 -- Function: accessible-keymaps keymap &optional prefix
1764 This function returns a list of all the keymaps that can be
1765 accessed (via prefix keys) from KEYMAP. The value is an
1766 association list with elements of the form `(KEY . MAP)', where
1767 KEY is a prefix key whose definition in KEYMAP is MAP.
1769 The elements of the alist are ordered so that the KEY increases in
1770 length. The first element is always `([] . KEYMAP)', because the
1771 specified keymap is accessible from itself with a prefix of no
1774 If PREFIX is given, it should be a prefix key sequence; then
1775 `accessible-keymaps' includes only the submaps whose prefixes start
1776 with PREFIX. These elements look just as they do in the value of
1777 `(accessible-keymaps)'; the only difference is that some elements
1780 In the example below, the returned alist indicates that the key
1781 `C-x', which is displayed as `[(control x)]', is a prefix key
1782 whose definition is the keymap `#<keymap ((control x) #<keymap
1783 emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>'. (The strange
1784 notation for the keymap's name indicates that this is an internal
1785 submap of `emacs-lisp-mode-map'. This is because
1786 `lisp-interaction-mode-map' has set up `emacs-lisp-mode-map' as
1787 its parent, and `lisp-interaction-mode-map' defines no key
1788 sequences beginning with `C-x'.)
1791 => #<keymap lisp-interaction-mode-map 5 entries 0x558>
1792 (accessible-keymaps (current-local-map))
1793 =>(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
1795 #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
1798 The following example shows the results of calling
1799 `accessible-keymaps' on a large, complex keymap. Notice how some
1800 keymaps were given explicit names using `set-keymap-name'; those
1801 submaps without explicit names are given descriptive names
1802 indicating their relationship to their enclosing keymap.
1804 (accessible-keymaps (current-global-map))
1805 => (([] . #<keymap global-map 639 entries 0x221>)
1806 ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
1807 ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
1808 ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
1810 #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
1812 ([(meta control \[)] .
1813 #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
1815 ([f1] . #<keymap help-map 33 entries 0x4ec>)
1816 ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
1817 ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
1818 ([(control x) \6] . #<keymap 13 entries 0x4d2>)
1820 #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
1822 ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
1823 ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
1824 ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
1825 ([(control x) a i] .
1826 #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
1830 -- Function: map-keymap function keymap &optional sort-first
1831 This function applies FUNCTION to each element of KEYMAP.
1832 FUNCTION will be called with two arguments: a key-description
1833 list, and the binding. The order in which the elements of the
1834 keymap are passed to the function is unspecified. If the function
1835 inserts new elements into the keymap, it may or may not be called
1836 with them later. No element of the keymap will ever be passed to
1837 the function more than once.
1839 The function will not be called on elements of this keymap's
1840 parents (*note Inheritance and Keymaps::) or upon keymaps which
1841 are contained within this keymap (multi-character definitions).
1842 It will be called on <META> characters since they are not really
1843 two-character sequences.
1845 If the optional third argument SORT-FIRST is non-`nil', then the
1846 elements of the keymap will be passed to the mapper function in a
1847 canonical order. Otherwise, they will be passed in hash (that is,
1848 random) order, which is faster.
1850 -- Function: keymap-fullness keymap
1851 This function returns the number of bindings in the keymap.
1853 -- Function: where-is-internal definition &optional keymaps firstonly
1854 noindirect event-or-keys
1855 This function returns a list of key sequences (of any length) that
1856 are bound to DEFINITION in a set of keymaps.
1858 The argument DEFINITION can be any object; it is compared with all
1859 keymap entries using `eq'.
1861 KEYMAPS can be either a keymap (meaning search in that keymap and
1862 the current global keymap) or a list of keymaps (meaning search in
1863 exactly those keymaps and no others). If KEYMAPS is nil, search
1864 in the currently applicable maps for EVENT-OR-KEYS.
1866 If KEYMAPS is a keymap, then the maps searched are KEYMAPS and the
1867 global keymap. If KEYMAPS is a list of keymaps, then the maps
1868 searched are exactly those keymaps, and no others. If KEYMAPS is
1869 `nil', then the maps used are the current active keymaps for
1870 EVENT-OR-KEYS (this is equivalent to specifying `(current-keymaps
1871 EVENT-OR-KEYS)' as the argument to KEYMAPS).
1873 If FIRSTONLY is non-`nil', then the value is a single vector
1874 representing the first key sequence found, rather than a list of
1875 all possible key sequences.
1877 If NOINDIRECT is non-`nil', `where-is-internal' doesn't follow
1878 indirect keymap bindings. This makes it possible to search for an
1879 indirect definition itself.
1881 This function is used by `where-is' (*note Help: (xemacs)Help.).
1883 (where-is-internal 'describe-function)
1884 => ([(control h) d] [(control h) f] [f1 d] [f1 f])
1886 -- Function: describe-bindings-internal map &optional all shadow
1888 This function inserts (into the current buffer) a list of all
1889 defined keys and their definitions in MAP. Optional second
1890 argument ALL says whether to include even "uninteresting"
1891 definitions, i.e. symbols with a non-`nil' `suppress-keymap'
1892 property. Third argument SHADOW is a list of keymaps whose
1893 bindings shadow those of map; if a binding is present in any
1894 shadowing map, it is not printed. Fourth argument PREFIX, if
1895 non-`nil', should be a key sequence; only bindings which start
1896 with that key sequence will be printed. Fifth argument
1897 MOUSE-ONLY-P says to only print bindings for mouse clicks.
1899 `describe-bindings-internal' is used to implement the help command
1900 `describe-bindings'.
1902 -- Command: describe-bindings &optional prefix mouse-only-p
1903 This function creates a listing of all defined keys and their
1904 definitions. It writes the listing in a buffer named `*Help*' and
1905 displays it in a window.
1907 If optional argument PREFIX is non-`nil', it should be a prefix
1908 key; then the listing includes only keys that start with PREFIX.
1910 When several characters with consecutive ASCII codes have the same
1911 definition, they are shown together, as `FIRSTCHAR..LASTCHAR'. In
1912 this instance, you need to know the ASCII codes to understand
1913 which characters this means. For example, in the default global
1914 map, the characters `<SPC> .. ~' are described by a single line.
1915 <SPC> is ASCII 32, `~' is ASCII 126, and the characters between
1916 them include all the normal printing characters, (e.g., letters,
1917 digits, punctuation, etc.); all these characters are bound to
1918 `self-insert-command'.
1920 If the second optional argument MOUSE-ONLY-P (prefix arg,
1921 interactively) is non-`nil' then only the mouse bindings are
1925 File: lispref.info, Node: Other Keymap Functions, Prev: Scanning Keymaps, Up: Keymaps
1927 26.13 Other Keymap Functions
1928 ============================
1930 -- Function: set-keymap-prompt keymap new-prompt
1931 This function sets the "prompt" of KEYMAP to string NEW-PROMPT, or
1932 `nil' if no prompt is desired. The prompt is shown in the
1933 echo-area when reading a key-sequence to be looked-up in this
1936 -- Function: keymap-prompt keymap &optional use-inherited
1937 This function returns the "prompt" of the given keymap. If
1938 USE-INHERITED is non-`nil', any parent keymaps will also be
1939 searched for a prompt.
1942 File: lispref.info, Node: Menus, Next: Dialog Boxes, Prev: Keymaps, Up: Top
1949 * Menu Format:: Format of a menu description.
1950 * Menubar Format:: How to specify a menubar.
1951 * Menubar:: Functions for controlling the menubar.
1952 * Modifying Menus:: Modifying a menu description.
1953 * Pop-Up Menus:: Functions for specifying pop-up menus.
1954 * Menu Filters:: Filter functions for the default menubar.
1955 * Menu Accelerators:: Using and controlling menu accelerator keys
1956 * Buffers Menu:: The menu that displays the list of buffers.
1959 File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus
1961 27.1 Format of Menus
1962 ====================
1964 A menu is described using a "menu description", which is a list of menu
1965 items, keyword-value pairs, strings, and submenus. The menu
1966 description specifies which items are present in the menu, what function
1967 each item invokes, and whether the item is selectable or not. Pop-up
1968 menus are directly described with a menu description, while menubars are
1969 described slightly differently (see below).
1971 The first element of a menu must be a string, which is the name of
1972 the menu. This is the string that will be displayed in the parent menu
1973 or menubar, if any. This string is not displayed in the menu itself,
1974 except in the case of the top level pop-up menu, where there is no
1975 parent. In this case, the string will be displayed at the top of the
1976 menu if `popup-menu-titles' is non-`nil'.
1978 Immediately following the first element there may optionally be up
1979 to four keyword-value pairs, as follows:
1982 This can be used to control the visibility of a menu. The form is
1983 evaluated and the menu will be omitted if the result is `nil'.
1986 This is an efficient shorthand for `:included (memq SYMBOL
1987 menubar-configuration)'. See the variable `menubar-configuration'.
1990 A menu filter is used to sensitize or incrementally create a
1991 submenu only when it is selected by the user and not every time
1992 the menubar is activated. The filter function is passed the list
1993 of menu items in the submenu and must return a list of menu items
1994 to be used for the menu. It is called only when the menu is about
1995 to be displayed, so other menus may already be displayed. Vile
1996 and terrible things will happen if a menu filter function changes
1997 the current buffer, window, or frame. It also should not raise,
1998 lower, or iconify any frames. Basically, the filter function
1999 should have no side-effects.
2002 A menu accelerator is a keystroke which can be pressed while the
2003 menu is visible which will immediately activate the item. KEY
2004 must be a char or the symbol name of a key. *Note Menu
2007 The rest of the menu consists of elements as follows:
2009 * A "menu item", which is a vector in the following form:
2011 `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]'
2013 NAME is a string, the name of the menu item; it is the string to
2014 display on the menu. It is filtered through the resource
2015 database, so it is possible for resources to override what string
2016 is actually displayed.
2018 CALLBACK is a form that will be invoked when the menu item is
2019 selected. If the callback of a menu item is a symbol, then it
2020 must name a command. It will be invoked with
2021 `call-interactively'. If it is a list, then it is evaluated with
2024 The valid keywords and their meanings are described below.
2026 Note that for compatibility purposes, the form
2028 `[ NAME CALLBACK ACTIVE-P ]'
2030 is also accepted and is equivalent to
2032 `[ NAME CALLBACK :active ACTIVE-P ]'
2036 `[ NAME CALLBACK ACTIVE-P SUFFIX]'
2038 is accepted and is equivalent to
2040 `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]'
2042 However, these older forms are deprecated and should generally not
2045 * If an element of a menu is a string, then that string will be
2046 presented in the menu as unselectable text.
2048 * If an element of a menu is a string consisting solely of hyphens,
2049 then that item will be presented as a solid horizontal line.
2051 * If an element of a menu is a string beginning with `--:', then a
2052 particular sort of horizontal line will be displayed, as follows:
2055 A solid horizontal line. This is equivalent to a string
2056 consisting solely of hyphens.
2059 A solid double horizontal line.
2061 `"--:singleDashedLine"'
2062 A dashed horizontal line.
2064 `"--:doubleDashedLine"'
2065 A dashed double horizontal line.
2068 No line (but a small space is left).
2070 `"--:shadowEtchedIn"'
2071 A solid horizontal line with a 3-d recessed appearance.
2073 `"--:shadowEtchedOut"'
2074 A solid horizontal line with a 3-d pushed-out appearance.
2076 `"--:shadowDoubleEtchedIn"'
2077 A solid double horizontal line with a 3-d recessed appearance.
2079 `"--:shadowDoubleEtchedOut"'
2080 A solid double horizontal line with a 3-d pushed-out
2083 `"--:shadowEtchedInDash"'
2084 A dashed horizontal line with a 3-d recessed appearance.
2086 `"--:shadowEtchedOutDash"'
2087 A dashed horizontal line with a 3-d pushed-out appearance.
2089 `"--:shadowDoubleEtchedInDash"'
2090 A dashed double horizontal line with a 3-d recessed
2093 `"--:shadowDoubleEtchedOutDash"'
2094 A dashed double horizontal line with a 3-d pushed-out
2097 * If an element of a menu is a list, it is treated as a submenu.
2098 The name of that submenu (the first element in the list) will be
2099 used as the name of the item representing this menu on the parent.
2101 The possible keywords are as follows:
2104 FORM will be evaluated when the menu that this item is a part of
2105 is about to be displayed, and the item will be selectable only if
2106 the result is non-`nil'. If the item is unselectable, it will
2107 usually be displayed grayed-out to indicate this.
2110 FORM will be evaluated when the menu that this item is a part of
2111 is about to be displayed, and the resulting string is appended to
2112 the displayed name. This provides a convenient way of adding the
2113 name of a command's "argument" to the menu, like `Kill Buffer
2117 Normally, the keyboard equivalents of commands in menus are
2118 displayed when the "callback" is a symbol. This can be used to
2119 specify keys for more complex menu items. It is passed through
2120 `substitute-command-keys' first.
2123 Specifies what kind of object this menu item is. STYLE be one of
2138 The only difference between toggle and radio buttons is how they
2139 are displayed. But for consistency, a toggle button should be
2140 used when there is one option whose value can be turned on or off,
2141 and radio buttons should be used when there is a set of mutually
2142 exclusive options. When using a group of radio buttons, you
2143 should arrange for no more than one to be marked as selected at a
2147 Meaningful only when STYLE is `toggle', `radio' or `button'. This
2148 specifies whether the button will be in the selected or unselected
2149 state. FORM is evaluated, as for `:active'.
2152 This can be used to control the visibility of a menu item. The
2153 form is evaluated and the menu item is only displayed if the
2154 result is non-`nil'. Note that this is different from `:active':
2155 If `:active' evaluates to `nil', the item will be displayed grayed
2156 out, while if `:included' evaluates to `nil', the item will be
2160 This is an efficient shorthand for `:included (memq SYMBOL
2161 menubar-configuration)'. See the variable `menubar-configuration'.
2164 A menu accelerator is a keystroke which can be pressed while the
2165 menu is visible which will immediately activate the item. KEY
2166 must be a char or the symbol name of a key. *Note Menu
2169 -- Variable: menubar-configuration
2170 This variable holds a list of symbols, against which the value of
2171 the `:config' tag for each menubar item will be compared. If a
2172 menubar item has a `:config' tag, then it is omitted from the
2173 menubar if that tag is not a member of the `menubar-configuration'
2179 :filter file-menu-filter ; file-menu-filter is a function that takes
2180 ; one argument (a list of menu items) and
2181 ; returns a list of menu items
2182 [ "Save As..." write-file]
2183 [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ]
2184 [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ]
2188 File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus
2190 27.2 Format of the Menubar
2191 ==========================
2193 A menubar is a list of menus, menu items, and strings. The format is
2194 similar to that of a menu, except:
2196 * The first item need not be a string, and is not treated specially.
2198 * A string consisting solely of hyphens is not treated specially.
2200 * If an element of a menubar is `nil', then it is used to represent
2201 the division between the set of menubar items which are flush-left
2202 and those which are flush-right. (Note: this isn't completely
2206 File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus
2211 -- Variable: current-menubar
2212 This variable holds the description of the current menubar. This
2213 may be buffer-local. When the menubar is changed, the function
2214 `set-menubar-dirty-flag' has to be called in order for the menubar
2215 to be updated on the screen.
2217 -- Constant: default-menubar
2218 This variable holds the menubar description of the menubar that is
2219 visible at startup. This is the value that `current-menubar' has
2222 -- Function: set-menubar-dirty-flag
2223 This function tells XEmacs that the menubar widget has to be
2224 updated. Changes to the menubar will generally not be visible
2225 until this function is called.
2227 The following convenience functions are provided for setting the
2228 menubar. They are equivalent to doing the appropriate action to change
2229 `current-menubar', and then calling `set-menubar-dirty-flag'. Note
2230 that these functions copy their argument using `copy-sequence'.
2232 -- Function: set-menubar menubar
2233 This function sets the default menubar to be MENUBAR (*note Menu
2234 Format::). This is the menubar that will be visible in buffers
2235 that have not defined their own, buffer-local menubar.
2237 -- Function: set-buffer-menubar menubar
2238 This function sets the buffer-local menubar to be MENUBAR. This
2239 does not change the menubar in any buffers other than the current
2244 -- Variable: menubar-show-keybindings
2245 If true, the menubar will display keyboard equivalents. If false,
2246 only the command names will be displayed.
2248 -- Variable: activate-menubar-hook
2249 Function or functions called before a menubar menu is pulled down.
2250 These functions are called with no arguments, and should
2251 interrogate and modify the value of `current-menubar' as desired.
2253 The functions on this hook are invoked after the mouse goes down,
2254 but before the menu is mapped, and may be used to activate,
2255 deactivate, add, or delete items from the menus. However, using a
2256 filter (with the `:filter' keyword in a menu description) is
2257 generally a more efficient way of accomplishing the same thing,
2258 because the filter is invoked only when the actual menu goes down.
2259 With a complex menu, there can be a quite noticeable and
2260 sometimes aggravating delay if all menu modification is
2261 implemented using the `activate-menubar-hook'. See above.
2263 These functions may return the symbol `t' to assert that they have
2264 made no changes to the menubar. If any other value is returned,
2265 the menubar is recomputed. If `t' is returned but the menubar has
2266 been changed, then the changes may not show up right away.
2267 Returning `nil' when the menubar has not changed is not so bad;
2268 more computation will be done, but redisplay of the menubar will
2269 still be performed optimally.
2271 -- Variable: menu-no-selection-hook
2272 Function or functions to call when a menu or dialog box is
2273 dismissed without a selection having been made.
2276 File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus
2278 27.4 Modifying Menus
2279 ====================
2281 The following functions are provided to modify the menubar of one of its
2282 submenus. Note that these functions modify the menu in-place, rather
2283 than copying it and making a new menu.
2285 Some of these functions take a "menu path", which is a list of
2286 strings identifying the menu to be modified. For example, `("File")'
2287 names the top-level "File" menu. `("File" "Foo")' names a hypothetical
2290 Others take a "menu item path", which is similar to a menu path but
2291 also specifies a particular item to be modified. For example, `("File"
2292 "Save")' means the menu item called "Save" under the top-level "File"
2293 menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under
2294 the "Foo" submenu of "Menu".
2296 -- Function: add-submenu menu-path submenu &optional before in-menu
2297 This function adds a menu to the menubar or one of its submenus.
2298 If the named menu exists already, it is changed.
2300 MENU-PATH identifies the menu under which the new menu should be
2301 inserted. If MENU-PATH is `nil', then the menu will be added to
2304 SUBMENU is the new menu to add (*note Menu Format::).
2306 BEFORE, if provided, is the name of a menu before which this menu
2307 should be added, if this menu is not on its parent already. If
2308 the menu is already present, it will not be moved.
2310 If IN-MENU is present use that instead of `current-menubar' as the
2313 -- Function: add-menu-button menu-path menu-leaf &optional before
2315 This function adds a menu item to some menu, creating the menu
2316 first if necessary. If the named item exists already, it is
2319 MENU-PATH identifies the menu under which the new menu item should
2322 MENU-LEAF is a menubar leaf node (*note Menu Format::).
2324 BEFORE, if provided, is the name of a menu before which this item
2325 should be added, if this item is not on the menu already. If the
2326 item is already present, it will not be moved.
2328 If IN-MENU is present use that instead of `current-menubar' as the
2331 -- Function: delete-menu-item menu-item-path &optional from-menu
2332 This function removes the menu item specified by MENU-ITEM-PATH
2333 from the menu hierarchy.
2335 If FROM-MENU is present use that instead of `current-menubar' as
2338 -- Function: enable-menu-item menu-item-path
2339 This function makes the menu item specified by MENU-ITEM-PATH be
2342 -- Function: disable-menu-item menu-item-path
2343 This function makes the menu item specified by MENU-ITEM-PATH be
2346 -- Function: relabel-menu-item menu-item-path new-name
2347 This function changes the string of the menu item specified by
2348 MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be
2349 printed as from now on.
2351 The following function can be used to search for a particular item in
2352 a menubar specification, given a path to the item.
2354 -- Function: find-menu-item menubar menu-item-path &optional parent
2355 This function searches MENUBAR for the item given by
2356 MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
2357 of MENUBAR). This function returns `(ITEM . PARENT)', where
2358 PARENT is the immediate parent of the item found (a menu
2359 description), and ITEM is either a vector, list, or string,
2360 depending on the nature of the menu item.
2362 This function signals an error if the item is not found.
2364 The following deprecated functions are also documented, so that
2365 existing code can be understood. You should not use these functions in
2368 -- Function: add-menu menu-path menu-name menu-items &optional before
2369 This function adds a menu to the menubar or one of its submenus.
2370 If the named menu exists already, it is changed. This is
2371 obsolete; use `add-submenu' instead.
2373 MENU-PATH identifies the menu under which the new menu should be
2374 inserted. If MENU-PATH is `nil', then the menu will be added to
2377 MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
2378 a list of menu items, strings, and submenus. These two arguments
2379 are the same as the first and following elements of a menu
2380 description (*note Menu Format::).
2382 BEFORE, if provided, is the name of a menu before which this menu
2383 should be added, if this menu is not on its parent already. If the
2384 menu is already present, it will not be moved.
2386 -- Function: add-menu-item menu-path item-name function enabled-p
2388 This function adds a menu item to some menu, creating the menu
2389 first if necessary. If the named item exists already, it is
2390 changed. This is obsolete; use `add-menu-button' instead.
2392 MENU-PATH identifies the menu under which the new menu item should
2393 be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
2394 second, and third elements of a menu item vector (*note Menu
2397 BEFORE, if provided, is the name of a menu item before which this
2398 item should be added, if this item is not on the menu already. If
2399 the item is already present, it will not be moved.
2402 File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus
2407 The following filter functions are provided for use in
2408 `default-menubar'. You may want to use them in your own menubar
2411 -- Function: file-menu-filter menu-items
2412 This function changes the arguments and sensitivity of these File
2416 Has the name of the current buffer appended to it.
2419 Has the name of the current buffer appended to it.
2421 `Pretty-Print Buffer'
2422 Has the name of the current buffer appended to it.
2425 Has the name of the current buffer appended to it, and is
2426 sensitive only when the current buffer is modified.
2429 Has the name of the current buffer appended to it, and is
2430 sensitive only when the current buffer has a file.
2433 Sensitive only when there is more than one visible frame.
2435 -- Function: edit-menu-filter menu-items
2436 This function changes the arguments and sensitivity of these Edit
2440 Sensitive only when XEmacs owns the primary X Selection (if
2441 `zmacs-regions' is `t', this is equivalent to saying that
2442 there is a region selected).
2445 Sensitive only when XEmacs owns the primary X Selection.
2448 Sensitive only when XEmacs owns the primary X Selection.
2451 Sensitive only when there is an owner for the X Clipboard
2455 Sensitive only when there is undo information. While in the
2456 midst of an undo, this is changed to `Undo More'.
2458 -- Function: buffers-menu-filter menu-items
2459 This function sets up the Buffers menu. *Note Buffers Menu::, for
2463 File: lispref.info, Node: Pop-Up Menus, Next: Menu Filters, Prev: Modifying Menus, Up: Menus
2468 -- Function: popup-menu menu-description &optional event
2469 This function pops up a menu specified by MENU-DESCRIPTION, which
2470 is a menu description (*note Menu Format::). The menu is
2471 displayed at the current mouse position.
2473 -- Function: popup-menu-up-p
2474 This function returns `t' if a pop-up menu is up, `nil' otherwise.
2476 -- Variable: popup-menu-titles
2477 If true (the default), pop-up menus will have title bars at the
2480 Some machinery is provided that attempts to provide a higher-level
2481 mechanism onto pop-up menus. This only works if you do not redefine
2482 the binding for button3.
2484 -- Command: popup-mode-menu
2485 This function pops up a menu of global and mode-specific commands.
2486 The menu is computed by combining `global-popup-menu' and
2487 `mode-popup-menu'. This is the default binding for button3. You
2488 should generally not change this binding.
2490 -- Variable: global-popup-menu
2491 This holds the global popup menu. This is present in all modes.
2492 (This is `nil' by default.)
2494 -- Variable: mode-popup-menu
2495 The mode-specific popup menu. Automatically buffer local. This
2496 is appended to the default items in `global-popup-menu'.
2498 -- Constant: default-popup-menu
2499 This holds the default value of `mode-popup-menu'.
2501 -- Variable: activate-popup-menu-hook
2502 Function or functions run before a mode-specific popup menu is made
2503 visible. These functions are called with no arguments, and should
2504 interrogate and modify the value of `global-popup-menu' or
2505 `mode-popup-menu' as desired. Note: this hook is only run if you
2506 use `popup-mode-menu' for activating the global and mode-specific
2507 commands; if you have your own binding for button3, this hook
2510 The following convenience functions are provided for displaying
2513 -- Command: popup-buffer-menu event
2514 This function pops up a copy of the `Buffers' menu (from the
2515 menubar) where the mouse is clicked. It should be bound to a
2518 -- Command: popup-menubar-menu event
2519 This function pops up a copy of menu that also appears in the
2520 menubar. It should be bound to a mouse button event.
2523 File: lispref.info, Node: Menu Accelerators, Next: Buffers Menu, Prev: Menu Filters, Up: Menus
2525 27.7 Menu Accelerators
2526 ======================
2528 Menu accelerators are keyboard shortcuts for accessing the menubar.
2529 Accelerator keys can be specified for menus as well as for menu items.
2530 An accelerator key for a menu is used to activate that menu when it
2531 appears as a submenu of another menu. An accelerator key for a menu
2532 item is used to activate that item.
2536 * Creating Menu Accelerators:: How to add accelerator keys to a menu.
2537 * Keyboard Menu Traversal:: How to use and modify the keys which are used
2538 to traverse the menu structure.
2539 * Menu Accelerator Functions:: Functions for working with menu accelerators.
2542 File: lispref.info, Node: Creating Menu Accelerators, Next: Keyboard Menu Traversal, Up: Menu Accelerators
2544 27.7.1 Creating Menu Accelerators
2545 ---------------------------------
2547 Menu accelerators are specified as part of the menubar format using the
2548 :accelerator tag to specify a key or by placing "%_" in the menu or
2549 menu item name prior to the letter which is to be used as the
2550 accelerator key. The advantage of the second method is that the menu
2551 rendering code then knows to draw an underline under that character,
2552 which is the canonical way of indicating an accelerator key to a user.
2554 For example, the command
2556 (add-submenu nil '("%_Test"
2557 ["One" (insert "1") :accelerator ?1 :active t]
2558 ["%_Two" (insert "2")]
2559 ["%_3" (insert "3")]))
2561 will add a new menu to the top level menubar. The new menu can be
2562 reached by pressing "t" while the top level menubar is active. When
2563 the menu is active, pressing "1" will activate the first item and
2564 insert the character "1" into the buffer. Pressing "2" will activate
2565 the second item and insert the character "2" into the buffer. Pressing
2566 "3" will activate the third item and insert the character "3" into the
2569 It is possible to activate the top level menubar itself using
2570 accelerator keys. *Note Menu Accelerator Functions::.
2573 File: lispref.info, Node: Keyboard Menu Traversal, Next: Menu Accelerator Functions, Prev: Creating Menu Accelerators, Up: Menu Accelerators
2575 27.7.2 Keyboard Menu Traversal
2576 ------------------------------
2578 In addition to immediately activating a menu or menu item, the keyboard
2579 can be used to traverse the menus without activating items. The
2580 keyboard arrow keys, the return key and the escape key are defined to
2581 traverse the menus in a way that should be familiar to users of any of
2582 a certain family of popular PC operating systems.
2584 This behavior can be changed by modifying the bindings in
2585 menu-accelerator-map. At this point, the online help is your best bet
2586 for more information about how to modify the menu traversal keys.
2589 File: lispref.info, Node: Menu Accelerator Functions, Prev: Keyboard Menu Traversal, Up: Menu Accelerators
2591 27.7.3 Menu Accelerator Functions
2592 ---------------------------------
2594 -- Command: accelerate-menu
2595 Make the menubar immediately active and place the cursor on the
2596 left most entry in the top level menu. Menu items can be selected
2599 -- Variable: menu-accelerator-enabled
2600 Whether menu accelerator keys can cause the menubar to become
2603 If `menu-force' or `menu-fallback', then menu accelerator keys can
2604 be used to activate the top level menu. Once the menubar becomes
2605 active, the accelerator keys can be used regardless of the value
2608 `menu-force' is used to indicate that the menu accelerator key
2609 takes precedence over bindings in the current keymap(s).
2610 `menu-fallback' means that bindings in the current keymap take
2611 precedence over menu accelerator keys. Thus a top level menu with
2612 an accelerator of "T" would be activated on a keypress of Meta-t
2613 if `menu-accelerator-enabled' is `menu-force'. However, if
2614 `menu-accelerator-enabled' is `menu-fallback', then Meta-t will
2615 not activate the menubar and will instead run the function
2616 transpose-words, to which it is normally bound.
2618 The default value is `nil'.
2620 See also `menu-accelerator-modifiers' and
2621 `menu-accelerator-prefix'.
2623 -- Variable: menu-accelerator-map
2624 Keymap consulted to determine the commands to run in response to
2625 keypresses occurring while the menubar is active. *Note Keyboard
2628 -- Variable: menu-accelerator-modifiers
2629 A list of modifier keys which must be pressed in addition to a
2630 valid menu accelerator in order for the top level menu to be
2631 activated in response to a keystroke. The default value of
2632 `(meta)' mirrors the usage of the alt key as a menu accelerator in
2633 popular PC operating systems.
2635 The modifier keys in `menu-accelerator-modifiers' must match
2636 exactly the modifiers present in the keypress. The only exception
2637 is that the shift modifier is accepted in conjunction with
2638 alphabetic keys even if it is not a menu accelerator modifier.
2640 See also `menu-accelerator-enabled' and `menu-accelerator-prefix'.
2642 -- Variable: menu-accelerator-prefix
2643 Prefix key(s) that must be typed before menu accelerators will be
2644 activated. Must be a valid key descriptor.
2646 The default value is `nil'.
2648 (setq menu-accelerator-prefix ?\C-x)
2649 (setq menu-accelerator-modifiers '(meta control))
2650 (setq menu-accelerator-enabled 'menu-force)
2651 (add-submenu nil '("%_Test"
2652 ["One" (insert "1") :accelerator ?1 :active t]
2653 ["%_Two" (insert "2")]
2654 ["%_3" (insert "3")]))
2656 will add the menu "Test" to the top level menubar. Pressing C-x
2657 followed by C-M-T will activate the menubar and display the "Test"
2658 menu. Pressing C-M-T by itself will not activate the menubar. Neither
2659 will pressing C-x followed by anything else.
2662 File: lispref.info, Node: Buffers Menu, Prev: Menu Accelerators, Up: Menus
2667 The following options control how the `Buffers' menu is displayed.
2668 This is a list of all (or a subset of) the buffers currently in
2669 existence, and is updated dynamically.
2671 -- User Option: buffers-menu-max-size
2672 This user option holds the maximum number of entries which may
2673 appear on the `Buffers' menu. If this is 10, then only the ten
2674 most-recently-selected buffers will be shown. If this is `nil',
2675 then all buffers will be shown. Setting this to a large number or
2676 `nil' will slow down menu responsiveness.
2678 -- Function: format-buffers-menu-line buffer
2679 This function returns a string to represent BUFFER in the
2680 `Buffers' menu. `nil' means the buffer shouldn't be listed. You
2683 -- User Option: complex-buffers-menu-p
2684 If true, the `Buffers' menu will contain several commands, as
2685 submenus of each buffer line. If this is false, then there will
2686 be only one command: select that buffer.
2688 -- User Option: buffers-menu-switch-to-buffer-function
2689 This user option holds the function to call to select a buffer
2690 from the `Buffers' menu. `switch-to-buffer' is a good choice, as
2694 File: lispref.info, Node: Dialog Boxes, Next: Toolbar, Prev: Menus, Up: Top
2701 * Dialog Box Format::
2702 * Dialog Box Functions::
2705 File: lispref.info, Node: Dialog Box Format, Next: Dialog Box Functions, Up: Dialog Boxes
2707 28.1 Dialog Box Format
2708 ======================
2710 A dialog box description is a list.
2712 * The first element of the list is a string to display in the dialog
2715 * The rest of the elements are descriptions of the dialog box's
2716 buttons. Each one is a vector of three elements:
2717 - The first element is the text of the button.
2719 - The second element is the "callback".
2721 - The third element is `t' or `nil', whether this button is
2724 If the callback of a button is a symbol, then it must name a command.
2725 It will be invoked with `call-interactively'. If it is a list, then it
2726 is evaluated with `eval'.
2728 One (and only one) of the buttons may be `nil'. This marker means
2729 that all following buttons should be flushright instead of flushleft.
2731 The syntax, more precisely:
2733 form := <something to pass to `eval'>
2734 command := <a symbol or string, to pass to `call-interactively'>
2735 callback := command | form
2736 active-p := <t, nil, or a form to evaluate to decide whether this
2737 button should be selectable>
2740 button := '[' name callback active-p ']'
2741 dialog := '(' name [ button ]+ [ partition [ button ]+ ] ')'
2744 File: lispref.info, Node: Dialog Box Functions, Prev: Dialog Box Format, Up: Dialog Boxes
2746 28.2 Dialog Box Functions
2747 =========================
2749 -- Function: popup-dialog-box dbox-desc
2750 This function pops up a dialog box. DBOX-DESC describes how the
2751 dialog box will appear (*note Dialog Box Format::).
2753 *Note Yes-or-No Queries::, for functions to ask a yes/no question
2757 File: lispref.info, Node: Toolbar, Next: Gutter, Prev: Dialog Boxes, Up: Top
2764 * Toolbar Intro:: An introduction.
2765 * Creating Toolbar:: How to create a toolbar.
2766 * Toolbar Descriptor Format:: Accessing and modifying a toolbar's
2768 * Specifying the Toolbar:: Setting a toolbar's contents.
2769 * Other Toolbar Variables:: Controlling the size of toolbars.
2772 File: lispref.info, Node: Toolbar Intro, Next: Creating Toolbar, Up: Toolbar
2777 A "toolbar" is a bar of icons displayed along one edge of a frame. You
2778 can view a toolbar as a series of menu shortcuts--the most common menu
2779 options can be accessed with a single click rather than a series of
2780 clicks and/or drags to select the option from a menu. Consistent with
2781 this, a help string (called the "help-echo") describing what an icon in
2782 the toolbar (called a "toolbar button") does, is displayed in the
2783 minibuffer when the mouse is over the button.
2785 In XEmacs, a toolbar can be displayed along any of the four edges of
2786 the frame, and two or more different edges can be displaying toolbars
2787 simultaneously. The contents, thickness, and visibility of the
2788 toolbars can be controlled separately, and the values can be
2789 per-buffer, per-frame, etc., using specifiers (*note Specifiers::).
2791 Normally, there is one toolbar displayed in a frame. Usually, this
2792 is the standard toolbar, but certain modes will override this and
2793 substitute their own toolbar. In some cases (e.g. the VM package), a
2794 package will supply its own toolbar along a different edge from the
2795 standard toolbar, so that both can be visible at once. This standard
2796 toolbar is usually positioned along the top of the frame, but this can
2797 be changed using `set-default-toolbar-position'.
2799 Note that, for each of the toolbar properties (contents, thickness,
2800 and visibility), there is a separate specifier for each of the four
2801 toolbar positions (top, bottom, left, and right), and an additional
2802 specifier for the "default" toolbar, i.e. the toolbar whose position is
2803 controlled by `set-default-toolbar-position'. The way this works is
2804 that `set-default-toolbar-position' arranges things so that the
2805 appropriate position-specific specifiers for the default position
2806 inherit from the corresponding default specifiers. That way, if the
2807 position-specific specifier does not give a value (which it usually
2808 doesn't), then the value from the default specifier applies. If you
2809 want to control the default toolbar, you just change the default
2810 specifiers, and everything works. A package such as VM that wants to
2811 put its own toolbar in a different location from the default just sets
2812 the position-specific specifiers, and if the user sets the default
2813 toolbar to the same position, it will just not be visible.
2816 File: lispref.info, Node: Creating Toolbar, Next: Toolbar Descriptor Format, Prev: Toolbar Intro, Up: Toolbar
2818 29.2 Creating Toolbar
2819 =====================
2821 -- Function: make-toolbar-specifier spec-list
2822 Return a new `toolbar' specifier object with the given
2823 specification list. SPEC-LIST can be a list of specifications
2824 (each of which is a cons of a locale and a list of instantiators),
2825 a single instantiator, or a list of instantiators. *Note
2826 Specifiers::, for more information about specifiers.
2828 Toolbar specifiers are used to specify the format of a toolbar.
2829 The values of the variables `default-toolbar', `top-toolbar',
2830 `left-toolbar', `right-toolbar', and `bottom-toolbar' are always
2833 Valid toolbar instantiators are called "toolbar descriptors" and
2834 are lists of vectors. See `default-toolbar' for a description of
2838 File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Creating Toolbar, Up: Toolbar
2840 29.3 Toolbar Descriptor Format
2841 ==============================
2843 The contents of a toolbar are specified using a "toolbar descriptor".
2844 The format of a toolbar descriptor is a list of "toolbar button
2845 descriptors". Each toolbar button descriptor is a vector in one of the
2848 * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
2850 * `[:style 2D-OR-3D]'
2852 * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
2854 * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
2856 Optionally, one of the toolbar button descriptors may be `nil'
2857 instead of a vector; this signifies the division between the toolbar
2858 buttons that are to be displayed flush-left, and the buttons to be
2859 displayed flush-right.
2861 The first vector format above specifies a normal toolbar button; the
2862 others specify blank areas in the toolbar.
2864 For the first vector format:
2866 * GLYPH-LIST should be a list of one to six glyphs (as created by
2867 `make-glyph') or a symbol whose value is such a list. The first
2868 glyph, which must be provided, is the glyph used to display the
2869 toolbar button when it is in the "up" (not pressed) state. The
2870 optional second glyph is for displaying the button when it is in
2871 the "down" (pressed) state. The optional third glyph is for when
2872 the button is disabled. The last three glyphs are for displaying
2873 the button in the "up", "down", and "disabled" states,
2874 respectively, but are used when the user has called for captioned
2875 toolbar buttons (using `toolbar-buttons-captioned-p'). The
2876 function `toolbar-make-button-list' is useful in creating these
2879 * Even if you do not provide separate down-state and disabled-state
2880 glyphs, the user will still get visual feedback to indicate which
2881 state the button is in. Buttons in the up-state are displayed
2882 with a shadowed border that gives a raised appearance to the
2883 button. Buttons in the down-state are displayed with shadows that
2884 give a recessed appearance. Buttons in the disabled state are
2885 displayed with no shadows, giving a 2-d effect.
2887 * If some of the toolbar glyphs are not provided, they inherit as
2892 DISABLED: disabled -> up
2893 CAP-UP: cap-up -> up
2894 CAP-DOWN: cap-down -> cap-up -> down -> up
2895 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
2897 * The second element FUNCTION is a function to be called when the
2898 toolbar button is activated (i.e. when the mouse is released over
2899 the toolbar button, if the press occurred in the toolbar). It can
2900 be any form accepted by `call-interactively', since this is how it
2903 * The third element ENABLED-P specifies whether the toolbar button
2904 is enabled (disabled buttons do nothing when they are activated,
2905 and are displayed differently; see above). It should be either a
2906 boolean or a form that evaluates to a boolean.
2908 * The fourth element HELP, if non-`nil', should be a string. This
2909 string is displayed in the echo area when the mouse passes over the
2912 For the other vector formats (specifying blank areas of the toolbar):
2914 * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
2915 whether the area is displayed with shadows (giving it a raised,
2916 3-d appearance) or without shadows (giving it a flat appearance).
2918 * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
2919 area. If omitted, it defaults to a device-specific value (8
2920 pixels for X devices).
2922 -- Function: toolbar-make-button-list up &optional down disabled
2923 cap-up cap-down cap-disabled
2924 This function calls `make-glyph' on each arg and returns a list of
2925 the results. This is useful for setting the first argument of a
2926 toolbar button descriptor (typically, the result of this function
2927 is assigned to a symbol, which is specified as the first argument
2928 of the toolbar button descriptor).
2930 -- Function: check-toolbar-button-syntax button &optional noerror
2931 Verify the syntax of entry BUTTON in a toolbar description list.
2932 If you want to verify the syntax of a toolbar description list as a
2933 whole, use `check-valid-instantiator' with a specifier type of
2937 File: lispref.info, Node: Specifying the Toolbar, Next: Other Toolbar Variables, Prev: Toolbar Descriptor Format, Up: Toolbar
2939 29.4 Specifying the Toolbar
2940 ===========================
2942 In order to specify the contents of a toolbar, set one of the specifier
2943 variables `default-toolbar', `top-toolbar', `bottom-toolbar',
2944 `left-toolbar', or `right-toolbar'. These are specifiers, which means
2945 you set them with `set-specifier' and query them with `specifier-specs'
2946 or `specifier-instance'. You will get an error if you try to set them
2947 using `setq'. The valid instantiators for these specifiers are toolbar
2948 descriptors, as described above. *Note Specifiers::, for more
2951 Most of the time, you will set `default-toolbar', which allows the
2952 user to choose where the toolbar should go.
2954 -- Specifier: default-toolbar
2955 The position of this toolbar is specified in the function
2956 `default-toolbar-position'. If the corresponding
2957 position-specific toolbar (e.g. `top-toolbar' if
2958 `default-toolbar-position' is `top') does not specify a toolbar in
2959 a particular domain, then the value of `default-toolbar' in that
2960 domain, of any, will be used instead.
2962 Note that the toolbar at any particular position will not be
2963 displayed unless its thickness (width or height, depending on
2964 orientation) is non-zero and its visibility status is true. The
2965 thickness is controlled by the specifiers `top-toolbar-height',
2966 `bottom-toolbar-height', `left-toolbar-width', and
2967 `right-toolbar-width', and the visibility status is controlled by the
2968 specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
2969 `left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
2970 Toolbar Variables::).
2972 -- Function: set-default-toolbar-position position
2973 This function sets the position that the `default-toolbar' will be
2974 displayed at. Valid positions are the symbols `top', `bottom',
2975 `left' and `right'. What this actually does is set the fallback
2976 specifier for the position-specific specifier corresponding to the
2977 given position to `default-toolbar', and set the fallbacks for the
2978 other position-specific specifiers to `nil'. It also does the
2979 same thing for the position-specific thickness and visibility
2980 specifiers, which inherit from one of `default-toolbar-height' or
2981 `default-toolbar-width', and from `default-toolbar-visible-p',
2982 respectively (*note Other Toolbar Variables::).
2984 -- Function: default-toolbar-position
2985 This function returns the position that the `default-toolbar' will
2988 You can also explicitly set a toolbar at a particular position. When
2989 redisplay determines what to display at a particular position in a
2990 particular domain (i.e. window), it first consults the position-specific
2991 toolbar. If that does not yield a toolbar descriptor, the
2992 `default-toolbar' is consulted if `default-toolbar-position' indicates
2995 -- Specifier: top-toolbar
2996 Specifier for the toolbar at the top of the frame.
2998 -- Specifier: bottom-toolbar
2999 Specifier for the toolbar at the bottom of the frame.
3001 -- Specifier: left-toolbar
3002 Specifier for the toolbar at the left edge of the frame.
3004 -- Specifier: right-toolbar
3005 Specifier for the toolbar at the right edge of the frame.
3007 -- Function: toolbar-specifier-p object
3008 This function returns non-`nil' if OBJECT is a toolbar specifier.
3009 Toolbar specifiers are the actual objects contained in the toolbar
3010 variables described above, and their valid instantiators are
3011 toolbar descriptors (*note Toolbar Descriptor Format::).
3014 File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar
3016 29.5 Other Toolbar Variables
3017 ============================
3019 The variables to control the toolbar thickness, visibility status, and
3020 captioned status are all specifiers. *Note Specifiers::.
3022 -- Specifier: default-toolbar-height
3023 This specifies the height of the default toolbar, if it's oriented
3024 horizontally. The position of the default toolbar is specified by
3025 the function `set-default-toolbar-position'. If the corresponding
3026 position-specific toolbar thickness specifier (e.g.
3027 `top-toolbar-height' if `default-toolbar-position' is `top') does
3028 not specify a thickness in a particular domain (a window or a
3029 frame), then the value of `default-toolbar-height' or
3030 `default-toolbar-width' (depending on the toolbar orientation) in
3031 that domain, if any, will be used instead.
3033 -- Specifier: default-toolbar-width
3034 This specifies the width of the default toolbar, if it's oriented
3035 vertically. This behaves like `default-toolbar-height'.
3037 Note that `default-toolbar-height' is only used when
3038 `default-toolbar-position' is `top' or `bottom', and
3039 `default-toolbar-width' is only used when `default-toolbar-position' is
3042 -- Specifier: top-toolbar-height
3043 This specifies the height of the top toolbar.
3045 -- Specifier: bottom-toolbar-height
3046 This specifies the height of the bottom toolbar.
3048 -- Specifier: left-toolbar-width
3049 This specifies the width of the left toolbar.
3051 -- Specifier: right-toolbar-width
3052 This specifies the width of the right toolbar.
3054 Note that all of the position-specific toolbar thickness specifiers
3055 have a fallback value of zero when they do not correspond to the
3056 default toolbar. Therefore, you will have to set a non-zero thickness
3057 value if you want a position-specific toolbar to be displayed.
3059 -- Specifier: default-toolbar-visible-p
3060 This specifies whether the default toolbar is visible. The
3061 position of the default toolbar is specified by the function
3062 `set-default-toolbar-position'. If the corresponding
3063 position-specific toolbar visibility specifier (e.g.
3064 `top-toolbar-visible-p' if `default-toolbar-position' is `top')
3065 does not specify a visible-p value in a particular domain (a
3066 window or a frame), then the value of `default-toolbar-visible-p'
3067 in that domain, if any, will be used instead.
3069 -- Specifier: top-toolbar-visible-p
3070 This specifies whether the top toolbar is visible.
3072 -- Specifier: bottom-toolbar-visible-p
3073 This specifies whether the bottom toolbar is visible.
3075 -- Specifier: left-toolbar-visible-p
3076 This specifies whether the left toolbar is visible.
3078 -- Specifier: right-toolbar-visible-p
3079 This specifies whether the right toolbar is visible.
3081 `default-toolbar-visible-p' and all of the position-specific toolbar
3082 visibility specifiers have a fallback value of true.
3084 Internally, toolbar thickness and visibility specifiers are
3085 instantiated in both window and frame domains, for different purposes.
3086 The value in the domain of a frame's selected window specifies the
3087 actual toolbar thickness or visibility that you will see in that frame.
3088 The value in the domain of a frame itself specifies the toolbar
3089 thickness or visibility that is used in frame geometry calculations.
3091 Thus, for example, if you set the frame width to 80 characters and
3092 the left toolbar width for that frame to 68 pixels, then the frame will
3093 be sized to fit 80 characters plus a 68-pixel left toolbar. If you then
3094 set the left toolbar width to 0 for a particular buffer (or if that
3095 buffer does not specify a left toolbar or has a `nil' value specified
3096 for `left-toolbar-visible-p'), you will find that, when that buffer is
3097 displayed in the selected window, the window will have a width of 86 or
3098 87 characters--the frame is sized for a 68-pixel left toolbar but the
3099 selected window specifies that the left toolbar is not visible, so it is
3100 expanded to take up the slack.
3102 -- Specifier: toolbar-buttons-captioned-p
3103 Whether toolbar buttons are captioned. This affects which glyphs
3104 from a toolbar button descriptor are chosen. *Note Toolbar
3105 Descriptor Format::.
3107 You can also reset the toolbar to what it was when XEmacs started up.
3109 -- Constant: initial-toolbar-spec
3110 The toolbar descriptor used to initialize `default-toolbar' at
3114 File: lispref.info, Node: Gutter, Next: Scrollbars, Prev: Toolbar, Up: Top
3119 A gutter is a rectangle displayed along one edge of a frame. It can
3120 contain arbitrary text or graphics.
3124 * Gutter Intro:: An introduction.
3125 * Creating Gutter:: How to create a gutter.
3126 * Gutter Descriptor Format:: Accessing and modifying a gutter's
3128 * Specifying a Gutter:: Setting a gutter's contents.
3129 * Other Gutter Variables:: Controlling the size of gutters.
3130 * Common Gutter Widgets:: Things to put in gutters.
3133 File: lispref.info, Node: Gutter Intro, Next: Creating Gutter, Prev: Gutter, Up: Gutter
3138 A "gutter" is a rectangle displayed along one edge of a frame. It can
3139 contain arbitrary text or graphics. It could be considered a
3140 generalization of a toolbar, although toolbars are not currently
3141 implemented using gutters.
3143 In XEmacs, a gutter can be displayed along any of the four edges of
3144 the frame, and two or more different edges can be displaying gutters
3145 simultaneously. The contents, thickness, and visibility of the gutters
3146 can be controlled separately, and the values can be per-buffer,
3147 per-frame, etc., using specifiers (*note Specifiers::).
3149 Normally, there is one gutter displayed in a frame. Usually, this is
3150 the default gutter, containing buffer tabs, but modes cab override this
3151 and substitute their own gutter. This default gutter is usually
3152 positioned along the top of the frame, but this can be changed using
3153 `set-default-gutter-position'.
3155 Note that, for each of the gutter properties (contents, thickness,
3156 and visibility), there is a separate specifier for each of the four
3157 gutter positions (top, bottom, left, and right), and an additional
3158 specifier for the "default" gutter, i.e. the gutter whose position is
3159 controlled by `set-default-gutter-position'. The way this works is
3160 that `set-default-gutter-position' arranges things so that the
3161 appropriate position-specific specifiers for the default position
3162 inherit from the corresponding default specifiers. That way, if the
3163 position-specific specifier does not give a value (which it usually
3164 doesn't), then the value from the default specifier applies. If you
3165 want to control the default gutter, you just change the default
3166 specifiers, and everything works. A package such as VM that wants to
3167 put its own gutter in a different location from the default just sets
3168 the position-specific specifiers, and if the user sets the default
3169 gutter to the same position, it will just not be visible.
3172 File: lispref.info, Node: Creating Gutter, Next: Gutter Descriptor Format, Prev: Gutter Intro, Up: Gutter
3174 30.2 Creating Gutter
3175 ====================
3177 -- Function: make-gutter-specifier spec-list
3178 Return a new `gutter' specifier object with the given specification
3179 list. SPEC-LIST can be a list of specifications (each of which is
3180 a cons of a locale and a list of instantiators), a single
3181 instantiator, or a list of instantiators. *Note Specifiers::, for
3182 more information about specifiers.
3184 Gutter specifiers are used to specify the format of a gutter. The
3185 values of the variables `default-gutter', `top-gutter',
3186 `left-gutter', `right-gutter', and `bottom-gutter' are always
3189 Valid gutter instantiators are called "gutter descriptors" and are
3190 either strings or property-lists of strings. See `default-gutter'
3191 for a description of the exact format.
3193 -- Function: make-gutter-size-specifier spec-list
3194 Return a new `gutter-size' specifier object with the given spec
3195 list. SPEC-LIST can be a list of specifications (each of which is
3196 a cons of a locale and a list of instantiators), a single
3197 instantiator, or a list of instantiators. *Note Specifiers::, for
3198 more information about specifiers.
3200 Gutter-size specifiers are used to specify the size of a gutter.
3201 The values of the variables `default-gutter-size',
3202 `top-gutter-size', `left-gutter-size', `right-gutter-size', and
3203 `bottom-gutter-size' are always gutter-size specifiers.
3205 Valid gutter-size instantiators are either integers or the special
3206 symbol `autodetect'. If a gutter-size is set to `autodetect' them
3207 the size of the gutter will be adjusted to just accommodate the
3208 gutters contents. `autodetect' only works for top and bottom
3211 -- Function: make-gutter-visible-specifier spec-list
3212 Return a new `gutter-visible' specifier object with the given spec
3213 list. SPEC-LIST can be a list of specifications (each of which is
3214 a cons of a locale and a list of instantiators), a single
3215 instantiator, or a list of instantiators. *Note Specifiers::, for
3216 more information about specifiers.
3218 Gutter-visible specifiers are used to specify the visibility of a
3219 gutter. The values of the variables `default-gutter-visible-p',
3220 `top-gutter-visible-p', `left-gutter-visible-p',
3221 `right-gutter-visible-p', and `bottom-gutter-visible-p' are always
3222 gutter-visible specifiers.
3224 Valid gutter-visible instantiators are `t', `nil' or a list of
3225 symbols. If a gutter-visible instantiator is set to a list of
3226 symbols, and the corresponding gutter specification is a
3227 property-list strings, then elements of the gutter specification
3228 will only be visible if the corresponding symbol occurs in the
3229 gutter-visible instantiator.
3232 File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, Up: Gutter
3234 30.3 Gutter Descriptor Format
3235 =============================
3237 The contents of a gutter are specified using a "gutter descriptor".
3238 The format of a gutter descriptor is a list of "gutter button
3239 descriptors". Each gutter button descriptor is a vector in one of the
3242 * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
3244 * `[:style 2D-OR-3D]'
3246 * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
3248 * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
3250 Optionally, one of the gutter button descriptors may be `nil'
3251 instead of a vector; this signifies the division between the gutter
3252 buttons that are to be displayed flush-left, and the buttons to be
3253 displayed flush-right.
3255 The first vector format above specifies a normal gutter button; the
3256 others specify blank areas in the gutter.
3258 For the first vector format:
3260 * GLYPH-LIST should be a list of one to six glyphs (as created by
3261 `make-glyph') or a symbol whose value is such a list. The first
3262 glyph, which must be provided, is the glyph used to display the
3263 gutter button when it is in the "up" (not pressed) state. The
3264 optional second glyph is for displaying the button when it is in
3265 the "down" (pressed) state. The optional third glyph is for when
3266 the button is disabled. The last three glyphs are for displaying
3267 the button in the "up", "down", and "disabled" states,
3268 respectively, but are used when the user has called for captioned
3269 gutter buttons (using `gutter-buttons-captioned-p'). The function
3270 `gutter-make-button-list' is useful in creating these glyph lists.
3272 * Even if you do not provide separate down-state and disabled-state
3273 glyphs, the user will still get visual feedback to indicate which
3274 state the button is in. Buttons in the up-state are displayed
3275 with a shadowed border that gives a raised appearance to the
3276 button. Buttons in the down-state are displayed with shadows that
3277 give a recessed appearance. Buttons in the disabled state are
3278 displayed with no shadows, giving a 2-d effect.
3280 * If some of the gutter glyphs are not provided, they inherit as
3285 DISABLED: disabled -> up
3286 CAP-UP: cap-up -> up
3287 CAP-DOWN: cap-down -> cap-up -> down -> up
3288 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
3290 * The second element FUNCTION is a function to be called when the
3291 gutter button is activated (i.e. when the mouse is released over
3292 the gutter button, if the press occurred in the gutter). It can
3293 be any form accepted by `call-interactively', since this is how it
3296 * The third element ENABLED-P specifies whether the gutter button is
3297 enabled (disabled buttons do nothing when they are activated, and
3298 are displayed differently; see above). It should be either a
3299 boolean or a form that evaluates to a boolean.
3301 * The fourth element HELP, if non-`nil', should be a string. This
3302 string is displayed in the echo area when the mouse passes over the
3305 For the other vector formats (specifying blank areas of the gutter):
3307 * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
3308 whether the area is displayed with shadows (giving it a raised,
3309 3-d appearance) or without shadows (giving it a flat appearance).
3311 * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
3312 area. If omitted, it defaults to a device-specific value (8
3313 pixels for X devices).
3315 -- Function: gutter-make-button-list up &optional down disabled cap-up
3316 cap-down cap-disabled
3317 This function calls `make-glyph' on each arg and returns a list of
3318 the results. This is useful for setting the first argument of a
3319 gutter button descriptor (typically, the result of this function
3320 is assigned to a symbol, which is specified as the first argument
3321 of the gutter button descriptor).
3323 -- Function: check-gutter-button-syntax button &optional noerror
3324 Verify the syntax of entry BUTTON in a gutter description list.
3325 If you want to verify the syntax of a gutter description list as a
3326 whole, use `check-valid-instantiator' with a specifier type of
3330 File: lispref.info, Node: Specifying a Gutter, Next: Other Gutter Variables, Prev: Gutter Descriptor Format, Up: Gutter
3332 30.4 Specifying a Gutter
3333 ========================
3335 In order to specify the contents of a gutter, set one of the specifier
3336 variables `default-gutter', `top-gutter', `bottom-gutter',
3337 `left-gutter', or `right-gutter'. These are specifiers, which means
3338 you set them with `set-specifier' and query them with `specifier-specs'
3339 or `specifier-instance'. You will get an error if you try to set them
3340 using `setq'. The valid instantiators for these specifiers are gutter
3341 descriptors, as described above. *Note Specifiers::, for more
3344 Most of the time, you will set `default-gutter', which allows the
3345 user to choose where the gutter should go.
3347 -- Specifier: default-gutter
3348 The position of this gutter is specified in the function
3349 `default-gutter-position'. If the corresponding position-specific
3350 gutter (e.g. `top-gutter' if `default-gutter-position' is `top')
3351 does not specify a gutter in a particular domain, then the value
3352 of `default-gutter' in that domain, of any, will be used instead.
3354 Note that the gutter at any particular position will not be displayed
3355 unless its thickness (width or height, depending on orientation) is
3356 non-zero and its visibility status is true. The thickness is controlled
3357 by the specifiers `top-gutter-height', `bottom-gutter-height',
3358 `left-gutter-width', and `right-gutter-width', and the visibility
3359 status is controlled by the specifiers `top-gutter-visible-p',
3360 `bottom-gutter-visible-p', `left-gutter-visible-p', and
3361 `right-gutter-visible-p' (*note Other Gutter Variables::).
3363 -- Function: set-default-gutter-position position
3364 This function sets the position that the `default-gutter' will be
3365 displayed at. Valid positions are the symbols `top', `bottom',
3366 `left' and `right'. What this actually does is set the fallback
3367 specifier for the position-specific specifier corresponding to the
3368 given position to `default-gutter', and set the fallbacks for the
3369 other position-specific specifiers to `nil'. It also does the
3370 same thing for the position-specific thickness and visibility
3371 specifiers, which inherit from one of `default-gutter-height' or
3372 `default-gutter-width', and from `default-gutter-visible-p',
3373 respectively (*note Other Gutter Variables::).
3375 -- Function: default-gutter-position
3376 This function returns the position that the `default-gutter' will
3379 You can also explicitly set a gutter at a particular position. When
3380 redisplay determines what to display at a particular position in a
3381 particular domain (i.e. window), it first consults the position-specific
3382 gutter. If that does not yield a gutter descriptor, the
3383 `default-gutter' is consulted if `default-gutter-position' indicates
3386 -- Specifier: top-gutter
3387 Specifier for the gutter at the top of the frame.
3389 -- Specifier: bottom-gutter
3390 Specifier for the gutter at the bottom of the frame.
3392 -- Specifier: left-gutter
3393 Specifier for the gutter at the left edge of the frame.
3395 -- Specifier: right-gutter
3396 Specifier for the gutter at the right edge of the frame.
3398 -- Function: gutter-specifier-p object
3399 This function returns non-`nil' if OBJECT is a gutter specifier.
3400 Gutter specifiers are the actual objects contained in the gutter
3401 variables described above, and their valid instantiators are
3402 gutter descriptors (*note Gutter Descriptor Format::).
3405 File: lispref.info, Node: Other Gutter Variables, Next: Common Gutter Widgets, Prev: Specifying a Gutter, Up: Gutter
3407 30.5 Other Gutter Variables
3408 ===========================
3410 The variables to control the gutter thickness, visibility status, and
3411 captioned status are all specifiers. *Note Specifiers::.
3413 -- Specifier: default-gutter-height
3414 This specifies the height of the default gutter, if it's oriented
3415 horizontally. The position of the default gutter is specified by
3416 the function `set-default-gutter-position'. If the corresponding
3417 position-specific gutter thickness specifier (e.g.
3418 `top-gutter-height' if `default-gutter-position' is `top') does
3419 not specify a thickness in a particular domain (a window or a
3420 frame), then the value of `default-gutter-height' or
3421 `default-gutter-width' (depending on the gutter orientation) in
3422 that domain, if any, will be used instead.
3424 -- Specifier: default-gutter-width
3425 This specifies the width of the default gutter, if it's oriented
3426 vertically. This behaves like `default-gutter-height'.
3428 Note that `default-gutter-height' is only used when
3429 `default-gutter-position' is `top' or `bottom', and
3430 `default-gutter-width' is only used when `default-gutter-position' is
3433 -- Specifier: top-gutter-height
3434 This specifies the height of the top gutter.
3436 -- Specifier: bottom-gutter-height
3437 This specifies the height of the bottom gutter.
3439 -- Specifier: left-gutter-width
3440 This specifies the width of the left gutter.
3442 -- Specifier: right-gutter-width
3443 This specifies the width of the right gutter.
3445 Note that all of the position-specific gutter thickness specifiers
3446 have a fallback value of zero when they do not correspond to the
3447 default gutter. Therefore, you will have to set a non-zero thickness
3448 value if you want a position-specific gutter to be displayed.
3450 -- Specifier: default-gutter-visible-p
3451 This specifies whether the default gutter is visible. The
3452 position of the default gutter is specified by the function
3453 `set-default-gutter-position'. If the corresponding
3454 position-specific gutter visibility specifier (e.g.
3455 `top-gutter-visible-p' if `default-gutter-position' is `top') does
3456 not specify a visible-p value in a particular domain (a window or
3457 a frame), then the value of `default-gutter-visible-p' in that
3458 domain, if any, will be used instead.
3460 -- Specifier: top-gutter-visible-p
3461 This specifies whether the top gutter is visible.
3463 -- Specifier: bottom-gutter-visible-p
3464 This specifies whether the bottom gutter is visible.
3466 -- Specifier: left-gutter-visible-p
3467 This specifies whether the left gutter is visible.
3469 -- Specifier: right-gutter-visible-p
3470 This specifies whether the right gutter is visible.
3472 `default-gutter-visible-p' and all of the position-specific gutter
3473 visibility specifiers have a fallback value of true.
3475 Internally, gutter thickness and visibility specifiers are
3476 instantiated in both window and frame domains, for different purposes.
3477 The value in the domain of a frame's selected window specifies the
3478 actual gutter thickness or visibility that you will see in that frame.
3479 The value in the domain of a frame itself specifies the gutter
3480 thickness or visibility that is used in frame geometry calculations.
3482 Thus, for example, if you set the frame width to 80 characters and
3483 the left gutter width for that frame to 68 pixels, then the frame will
3484 be sized to fit 80 characters plus a 68-pixel left gutter. If you then
3485 set the left gutter width to 0 for a particular buffer (or if that
3486 buffer does not specify a left gutter or has a `nil' value specified for
3487 `left-gutter-visible-p'), you will find that, when that buffer is
3488 displayed in the selected window, the window will have a width of 86 or
3489 87 characters - the frame is sized for a 68-pixel left gutter but the
3490 selected window specifies that the left gutter is not visible, so it is
3491 expanded to take up the slack.
3493 -- Specifier: gutter-buttons-captioned-p
3494 Whether gutter buttons are captioned. This affects which glyphs
3495 from a gutter button descriptor are chosen. *Note Gutter
3496 Descriptor Format::.
3498 You can also reset the gutter to what it was when XEmacs started up.
3500 -- Constant: initial-gutter-spec
3501 The gutter descriptor used to initialize `default-gutter' at
3505 File: lispref.info, Node: Common Gutter Widgets, Prev: Other Gutter Variables, Up: Gutter
3507 30.6 Common Gutter Widgets
3508 ==========================
3510 A gutter can contain arbitrary text. So, for example, in an Info
3511 buffer you could put the title of the current node in the top gutter,
3512 and it would not scroll out of view in a long node. (This is an
3513 artificial example, since usually the node name is sufficiently
3514 descriptive, and Info puts that in the mode line.)
3516 A more common use for the gutter is to hold some kind of active
3517 widget. The buffer-tab facility, available in all XEmacs frames,
3518 creates an array of file-folder-like tabs, which the user can click with
3519 the mouse to switch buffers. W3 uses a progress-bar widget in the
3520 bottom gutter to give a visual indication of the progress of
3521 time-consuming operations like downloading.
3525 * Buffer Tabs:: Tabbed divider index metaphor for switching buffers.
3526 * Progress Bars:: Visual indication of operation progress.
3529 File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets
3537 File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets
3539 30.6.2 Progress Bars
3540 --------------------
3545 File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top
3553 File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top
3558 _WARNING_: the Drag'n'Drop API is still under development and the
3559 interface may change! The current implementation is considered
3562 Drag'n'drop is a way to transfer information between multiple
3563 applications. To do this several GUIs define their own protocols.
3564 Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more.
3565 To catch all these protocols, XEmacs provides a generic API.
3567 One prime idea behind the API is to use a data interface that is
3568 transparent for all systems. The author thinks that this is best
3569 archived by using URL and MIME data, cause any internet enabled system
3570 must support these for email already. XEmacs also already provides
3571 powerful interfaces to support these types of data (tm and w3).
3575 * Supported Protocols:: Which low-level protocols are supported.
3576 * Drop Interface:: How XEmacs handles a drop from another application.
3577 * Drag Interface:: Calls to initiate a drag from XEmacs.
3580 File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop
3582 32.1 Supported Protocols
3583 ========================
3585 The current release of XEmacs only support a small set of Drag'n'drop
3586 protocols. Some of these only support limited options available in the
3591 * OffiX DND:: A generic X based protocol.
3592 * CDE dt:: Common Desktop Environment used on suns.
3593 * MSWindows OLE:: Mr. Gates way of live.
3594 * Loose ends:: The other protocols.
3597 File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols
3602 _WARNING_: If you compile in OffiX, you may not be able to use multiple
3603 X displays successfully. If the two servers are from different
3604 vendors, the results may be unpredictable.
3606 The OffiX Drag'n'Drop protocol is part of a X API/Widget library
3607 created by Cesar Crusius. It is based on X-Atoms and ClientMessage
3608 events, and works with any X platform supporting them.
3610 OffiX is supported if 'offix is member of the variable
3611 dragdrop-protocols, or the feature 'offix is defined.
3613 Unfortunately it uses it's own data types. Examples are: File, Files,
3614 Exe, Link, URL, MIME. The API tries to choose the right type for the
3615 data that is dragged from XEmacs (well, not yet...).
3617 XEmacs supports both MIME and URL drags and drops using this API. No
3618 application interaction is possible while dragging is in progress.
3620 For information about the OffiX project have a look at
3621 http://leb.net/~offix/
3624 File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols
3629 CDE stands for Common Desktop Environment. It is based on the Motif
3630 widget library. It's drag'n'drop protocol is also an abstraction of the
3631 Motif protocol (so it might be possible, that XEmacs will also support
3632 the Motif protocol soon).
3634 CDE has three different types: file, buffer, and text. XEmacs only
3635 uses file and buffer drags. The API will disallow full URL drags, only
3636 file method URLs are passed through.
3638 Buffer drags are always converted to plain text.
3641 File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
3643 32.1.3 MSWindows OLE
3644 --------------------
3646 Only allows file drags and drops.
3649 File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols
3654 The following protocols will be supported soon: Xdnd, Motif, Xde (if I
3655 get some specs), KDE OffiX (if KDE can find XEmacs windows).
3657 In particular Xdnd will be one of the protocols that can benefit from
3658 the XEmacs API, cause it also uses MIME types to encode dragged data.
3661 File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop
3666 For each activated low-level protocol, an internal routine will catch
3667 incoming drops and convert them to a dragdrop-drop type misc-user-event.
3669 This misc-user-event has its function argument set to
3670 `dragdrop-drop-dispatch' and the object contains the data of the drop
3671 (converted to URL/MIME specific data). This function will search the
3672 variable `experimental-dragdrop-drop-functions' for a function that can
3673 handle the dropped data.
3675 To modify the drop behavior, the user can modify the variable
3676 `experimental-dragdrop-drop-functions'. Each element of this list
3677 specifies a possible handler for dropped data. The first one that can
3678 handle the data will return `t' and exit. Another possibility is to set
3679 a extent-property with the same name. Extents are checked prior to the
3682 The customization group `drag-n-drop' shows all variables of user
3686 File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
3691 This describes the drag API (not implemented yet).
3694 File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top
3696 33 Major and Minor Modes
3697 ************************
3699 A "mode" is a set of definitions that customize XEmacs and can be
3700 turned on and off while you edit. There are two varieties of modes:
3701 "major modes", which are mutually exclusive and used for editing
3702 particular kinds of text, and "minor modes", which provide features
3703 that users can enable individually.
3705 This chapter describes how to write both major and minor modes, how
3706 to indicate them in the modeline, and how they run hooks supplied by the
3707 user. For related topics such as keymaps and syntax tables, see *Note
3708 Keymaps::, and *Note Syntax Tables::.
3712 * Major Modes:: Defining major modes.
3713 * Minor Modes:: Defining minor modes.
3714 * Modeline Format:: Customizing the text that appears in the modeline.
3715 * Hooks:: How to use hooks; how to write code that provides hooks.
3718 File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes
3723 Major modes specialize XEmacs for editing particular kinds of text.
3724 Each buffer has only one major mode at a time. For each major mode
3725 there is a function to switch to that mode in the current buffer; its
3726 name should end in `-mode'. These functions work by setting
3727 buffer-local variable bindings and other data associated with the
3728 buffer, such as a local keymap. The effect lasts until you switch to
3729 another major mode in the same buffer.
3731 The least specialized major mode is called "Fundamental mode". This
3732 mode has no mode-specific definitions or variable settings, so each
3733 XEmacs command behaves in its default manner, and each option is in its
3734 default state. All other major modes redefine various keys and options.
3735 For example, Lisp Interaction mode provides special key bindings for
3736 <LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
3739 When you need to write several editing commands to help you perform a
3740 specialized editing task, creating a new major mode is usually a good
3741 idea. In practice, writing a major mode is easy (in contrast to
3742 writing a minor mode, which is often difficult).
3744 If the new mode is similar to an old one, it is often unwise to
3745 modify the old one to serve two purposes, since it may become harder to
3746 use and maintain. Instead, copy and rename an existing major mode
3747 definition and alter the copy--or define a "derived mode" (*note
3748 Derived Modes::). For example, Rmail Edit mode, which is in
3749 `emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
3750 mode except that it provides three additional commands. Its definition
3751 is distinct from that of Text mode, but was derived from it.
3753 Even if the new mode is not an obvious derivative of any other mode,
3754 it is convenient to use `define-derived-mode' with a `nil' parent
3755 argument, since it automatically enforces the most important coding
3756 conventions for you.
3758 Rmail Edit mode is an example of a case where one piece of text is
3759 put temporarily into a different major mode so it can be edited in a
3760 different way (with ordinary XEmacs commands rather than Rmail). In
3761 such cases, the temporary major mode usually has a command to switch
3762 back to the buffer's usual mode (Rmail mode, in this case). You might
3763 be tempted to present the temporary redefinitions inside a recursive
3764 edit and restore the usual ones when the user exits; but this is a bad
3765 idea because it constrains the user's options when it is done in more
3766 than one buffer: recursive edits must be exited most-recently-entered
3767 first. Using alternative major modes avoids this limitation. *Note
3768 Recursive Editing::.
3770 The standard XEmacs Lisp library directory contains the code for
3771 several major modes, in files including `text-mode.el', `texinfo.el',
3772 `lisp-mode.el', `c-mode.el', and `rmail.el'. You can look at these
3773 libraries to see how modes are written. Text mode is perhaps the
3774 simplest major mode aside from Fundamental mode. Rmail mode is a
3775 complicated and specialized mode.
3779 * Major Mode Conventions:: Coding conventions for keymaps, etc.
3780 * Example Major Modes:: Text mode and Lisp modes.
3781 * Auto Major Mode:: How XEmacs chooses the major mode automatically.
3782 * Mode Help:: Finding out how to use a mode.
3783 * Derived Modes:: Defining a new major mode based on another major
3787 File: lispref.info, Node: Major Mode Conventions, Next: Example Major Modes, Up: Major Modes
3789 33.1.1 Major Mode Conventions
3790 -----------------------------
3792 The code for existing major modes follows various coding conventions,
3793 including conventions for local keymap and syntax table initialization,
3794 global names, and hooks. Please follow these conventions when you
3795 define a new major mode:
3797 * Define a command whose name ends in `-mode', with no arguments,
3798 that switches to the new mode in the current buffer. This command
3799 should set up the keymap, syntax table, and local variables in an
3800 existing buffer without changing the buffer's text.
3802 * Write a documentation string for this command that describes the
3803 special commands available in this mode. `C-h m'
3804 (`describe-mode') in your mode will display this string.
3806 The documentation string may include the special documentation
3807 substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
3808 enable the documentation to adapt automatically to the user's own
3809 key bindings. *Note Keys in Documentation::.
3811 * The major mode command should start by calling
3812 `kill-all-local-variables'. This is what gets rid of the local
3813 variables of the major mode previously in effect.
3815 * The major mode command should set the variable `major-mode' to the
3816 major mode command symbol. This is how `describe-mode' discovers
3817 which documentation to print.
3819 * The major mode command should set the variable `mode-name' to the
3820 "pretty" name of the mode, as a string. This appears in the mode
3823 * Since all global names are in the same name space, all the global
3824 variables, constants, and functions that are part of the mode
3825 should have names that start with the major mode name (or with an
3826 abbreviation of it if the name is long). *Note Style Tips::.
3828 * The major mode should usually have its own keymap, which is used
3829 as the local keymap in all buffers in that mode. The major mode
3830 function should call `use-local-map' to install this local map.
3831 *Note Active Keymaps::, for more information.
3833 This keymap should be kept in a global variable named
3834 `MODENAME-mode-map'. Normally the library that defines the mode
3837 * The mode may have its own syntax table or may share one with other
3838 related modes. If it has its own syntax table, it should store
3839 this in a variable named `MODENAME-mode-syntax-table'. *Note
3842 * The mode may have its own abbrev table or may share one with other
3843 related modes. If it has its own abbrev table, it should store
3844 this in a variable named `MODENAME-mode-abbrev-table'. *Note
3847 * Use `defvar' to set mode-related variables, so that they are not
3848 reinitialized if they already have a value. (Such reinitialization
3849 could discard customizations made by the user.)
3851 * To make a buffer-local binding for an Emacs customization
3852 variable, use `make-local-variable' in the major mode command, not
3853 `make-variable-buffer-local'. The latter function would make the
3854 variable local to every buffer in which it is subsequently set,
3855 which would affect buffers that do not use this mode. It is
3856 undesirable for a mode to have such global effects. *Note
3857 Buffer-Local Variables::.
3859 It's ok to use `make-variable-buffer-local', if you wish, for a
3860 variable used only within a single Lisp package.
3862 * Each major mode should have a "mode hook" named
3863 `MODENAME-mode-hook'. The major mode command should run that
3864 hook, with `run-hooks', as the very last thing it does. *Note
3867 * The major mode command may also run the hooks of some more basic
3868 modes. For example, `indented-text-mode' runs `text-mode-hook' as
3869 well as `indented-text-mode-hook'. It may run these other hooks
3870 immediately before the mode's own hook (that is, after everything
3871 else), or it may run them earlier.
3873 * The major mode command may start by calling some other major mode
3874 command (called the "parent mode") and then alter some of its
3875 settings. A mode that does this is called a "derived mode". The
3876 recommended way to define one is to use `define-derived-mode', but
3877 this is not required. Such a mode should use `delay-mode-hooks'
3878 around its entire body, including the call to the parent mode
3879 command and the final call to `run-mode-hooks'. (Using
3880 `define-derived-mode' does this automatically.)
3882 * If something special should be done if the user switches a buffer
3883 from this mode to any other major mode, the mode can set a local
3884 value for `change-major-mode-hook'.
3886 * If this mode is appropriate only for specially-prepared text, then
3887 the major mode command symbol should have a property named
3888 `mode-class' with value `special', put on as follows:
3890 (put 'funny-mode 'mode-class 'special)
3892 This tells XEmacs that new buffers created while the current
3893 buffer has Funny mode should not inherit Funny mode. Modes such
3894 as Dired, Rmail, and Buffer List use this feature.
3896 * If you want to make the new mode the default for files with certain
3897 recognizable names, add an element to `auto-mode-alist' to select
3898 the mode for those file names. If you define the mode command to
3899 autoload, you should add this element in the same file that calls
3900 `autoload'. Otherwise, it is sufficient to add the element in the
3901 file that contains the mode definition. *Note Auto Major Mode::.
3903 * In the documentation, you should provide a sample `autoload' form
3904 and an example of how to add to `auto-mode-alist', that users can
3905 include in their `.emacs' files.
3907 * The top-level forms in the file defining the mode should be
3908 written so that they may be evaluated more than once without
3909 adverse consequences. Even if you never load the file more than
3910 once, someone else will.
3912 -- Variable: change-major-mode-hook
3913 This normal hook is run by `kill-all-local-variables' before it
3914 does anything else. This gives major modes a way to arrange for
3915 something special to be done if the user switches to a different
3916 major mode. For best results, make this variable buffer-local, so
3917 that it will disappear after doing its job and will not interfere
3918 with the subsequent major mode. *Note Hooks::.
3921 File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes
3923 33.1.2 Major Mode Examples
3924 --------------------------
3926 Text mode is perhaps the simplest mode besides Fundamental mode. Here
3927 are excerpts from `text-mode.el' that illustrate many of the
3928 conventions listed above:
3930 ;; Create mode-specific tables.
3931 (defvar text-mode-syntax-table nil
3932 "Syntax table used while in text mode.")
3934 (if text-mode-syntax-table
3935 () ; Do not change the table if it is already set up.
3936 (setq text-mode-syntax-table (make-syntax-table))
3937 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
3938 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
3939 (modify-syntax-entry ?' "w " text-mode-syntax-table))
3941 (defvar text-mode-abbrev-table nil
3942 "Abbrev table used while in text mode.")
3943 (define-abbrev-table 'text-mode-abbrev-table ())
3945 (defvar text-mode-map nil) ; Create a mode-specific keymap.
3948 () ; Do not change the keymap if it is already set up.
3949 (setq text-mode-map (make-sparse-keymap))
3950 (define-key text-mode-map "\t" 'tab-to-tab-stop)
3951 (define-key text-mode-map "\es" 'center-line)
3952 (define-key text-mode-map "\eS" 'center-paragraph))
3954 Here is the complete major mode function definition for Text mode:
3957 "Major mode for editing text intended for humans to read.
3958 Special commands: \\{text-mode-map}
3959 Turning on text-mode runs the hook `text-mode-hook'."
3961 (kill-all-local-variables)
3962 (use-local-map text-mode-map) ; This provides the local keymap.
3963 (setq mode-name "Text") ; This name goes into the modeline.
3964 (setq major-mode 'text-mode) ; This is how `describe-mode'
3965 ; finds the doc string to print.
3966 (setq local-abbrev-table text-mode-abbrev-table)
3967 (set-syntax-table text-mode-syntax-table)
3968 (run-hooks 'text-mode-hook)) ; Finally, this permits the user to
3969 ; customize the mode with a hook.
3971 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
3972 Interaction mode) have more features than Text mode and the code is
3973 correspondingly more complicated. Here are excerpts from
3974 `lisp-mode.el' that illustrate how these modes are written.
3976 ;; Create mode-specific table variables.
3977 (defvar lisp-mode-syntax-table nil "")
3978 (defvar emacs-lisp-mode-syntax-table nil "")
3979 (defvar lisp-mode-abbrev-table nil "")
3981 (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
3982 ; if it is already set.
3984 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
3986 ;; Set syntax of chars up to 0 to class of chars that are
3987 ;; part of symbol names but not words.
3988 ;; (The number 0 is `48' in the ASCII character set.)
3990 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
3993 ;; Set the syntax for other characters.
3994 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
3995 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
3997 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
3998 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
4000 ;; Create an abbrev table for lisp-mode.
4001 (define-abbrev-table 'lisp-mode-abbrev-table ())
4003 Much code is shared among the three Lisp modes. The following
4004 function sets various variables; it is called by each of the major Lisp
4007 (defun lisp-mode-variables (lisp-syntax)
4008 ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
4009 ;; and `t' in the other two Lisp modes.
4011 (if (not lisp-mode-syntax-table)
4012 ;; The Emacs Lisp mode syntax table always exists, but
4013 ;; the Lisp Mode syntax table is created the first time a
4014 ;; mode that needs it is called. This is to save space.
4015 (progn (setq lisp-mode-syntax-table
4016 (copy-syntax-table emacs-lisp-mode-syntax-table))
4017 ;; Change some entries for Lisp mode.
4018 (modify-syntax-entry ?\| "\" "
4019 lisp-mode-syntax-table)
4020 (modify-syntax-entry ?\[ "_ "
4021 lisp-mode-syntax-table)
4022 (modify-syntax-entry ?\] "_ "
4023 lisp-mode-syntax-table)))
4024 (set-syntax-table lisp-mode-syntax-table)))
4025 (setq local-abbrev-table lisp-mode-abbrev-table)
4028 Functions such as `forward-paragraph' use the value of the
4029 `paragraph-start' variable. Since Lisp code is different from ordinary
4030 text, the `paragraph-start' variable needs to be set specially to
4031 handle Lisp. Also, comments are indented in a special fashion in Lisp
4032 and the Lisp modes need their own mode-specific
4033 `comment-indent-function'. The code to set these variables is the rest
4034 of `lisp-mode-variables'.
4036 (make-local-variable 'paragraph-start)
4037 ;; Having `^' is not clean, but `page-delimiter'
4038 ;; has them too, and removing those is a pain.
4039 (setq paragraph-start (concat "^$\\|" page-delimiter))
4041 (make-local-variable 'comment-indent-function)
4042 (setq comment-indent-function 'lisp-comment-indent))
4044 Each of the different Lisp modes has a slightly different keymap.
4045 For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
4046 Lisp modes do not. However, all Lisp modes have some commands in
4047 common. The following function adds these common commands to a given
4050 (defun lisp-mode-commands (map)
4051 (define-key map "\e\C-q" 'indent-sexp)
4052 (define-key map "\177" 'backward-delete-char-untabify)
4053 (define-key map "\t" 'lisp-indent-line))
4055 Here is an example of using `lisp-mode-commands' to initialize a
4056 keymap, as part of the code for Emacs Lisp mode. First we declare a
4057 variable with `defvar' to hold the mode-specific keymap. When this
4058 `defvar' executes, it sets the variable to `nil' if it was void. Then
4059 we set up the keymap if the variable is `nil'.
4061 This code avoids changing the keymap or the variable if it is already
4062 set up. This lets the user customize the keymap.
4064 (defvar emacs-lisp-mode-map () "")
4065 (if emacs-lisp-mode-map
4067 (setq emacs-lisp-mode-map (make-sparse-keymap))
4068 (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
4069 (lisp-mode-commands emacs-lisp-mode-map))
4071 Finally, here is the complete major mode function definition for
4074 (defun emacs-lisp-mode ()
4075 "Major mode for editing Lisp code to run in XEmacs.
4077 Delete converts tabs to spaces as it moves back.
4078 Blank lines separate paragraphs. Semicolons start comments.
4079 \\{emacs-lisp-mode-map}
4080 Entry to this mode runs the hook `emacs-lisp-mode-hook'."
4082 (kill-all-local-variables)
4083 (use-local-map emacs-lisp-mode-map) ; This provides the local keymap.
4084 (set-syntax-table emacs-lisp-mode-syntax-table)
4085 (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode'
4086 ; finds out what to describe.
4087 (setq mode-name "Emacs-Lisp") ; This goes into the modeline.
4088 (lisp-mode-variables nil) ; This defines various variables.
4089 (run-hooks 'emacs-lisp-mode-hook)) ; This permits the user to use a
4090 ; hook to customize the mode.
4093 File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes
4095 33.1.3 How XEmacs Chooses a Major Mode
4096 --------------------------------------
4098 Based on information in the file name or in the file itself, XEmacs
4099 automatically selects a major mode for the new buffer when a file is
4102 -- Command: fundamental-mode
4103 Fundamental mode is a major mode that is not specialized for
4104 anything in particular. Other major modes are defined in effect
4105 by comparison with this one--their definitions say what to change,
4106 starting from Fundamental mode. The `fundamental-mode' function
4107 does _not_ run any hooks; you're not supposed to customize it.
4108 (If you want Emacs to behave differently in Fundamental mode,
4109 change the _global_ state of Emacs.)
4111 -- Command: normal-mode &optional find-file
4112 This function establishes the proper major mode and local variable
4113 bindings for the current buffer. First it calls `set-auto-mode',
4114 then it runs `hack-local-variables' to parse, and bind or evaluate
4115 as appropriate, any local variables.
4117 If the FIND-FILE argument to `normal-mode' is non-`nil',
4118 `normal-mode' assumes that the `find-file' function is calling it.
4119 In this case, it may process a local variables list at the end of
4120 the file and in the `-*-' line. The variable
4121 `enable-local-variables' controls whether to do so.
4123 If you run `normal-mode' interactively, the argument FIND-FILE is
4124 normally `nil'. In this case, `normal-mode' unconditionally
4125 processes any local variables list. *Note Local Variables in
4126 Files: (xemacs)File variables, for the syntax of the local
4127 variables section of a file.
4129 `normal-mode' uses `condition-case' around the call to the major
4130 mode function, so errors are caught and reported as a `File mode
4131 specification error', followed by the original error message.
4133 -- User Option: enable-local-variables
4134 This variable controls processing of local variables lists in files
4135 being visited. A value of `t' means process the local variables
4136 lists unconditionally; `nil' means ignore them; anything else means
4137 ask the user what to do for each file. The default value is `t'.
4139 -- Variable: ignored-local-variables
4140 This variable holds a list of variables that should not be set by
4141 a local variables list. Any value specified for one of these
4142 variables is ignored.
4144 In addition to this list, any variable whose name has a non-`nil'
4145 `risky-local-variable' property is also ignored.
4147 -- User Option: enable-local-eval
4148 This variable controls processing of `Eval:' in local variables
4149 lists in files being visited. A value of `t' means process them
4150 unconditionally; `nil' means ignore them; anything else means ask
4151 the user what to do for each file. The default value is `maybe'.
4153 -- Function: set-auto-mode
4154 This function selects the major mode that is appropriate for the
4155 current buffer. It may base its decision on the value of the `-*-'
4156 line, on the visited file name (using `auto-mode-alist'), or on the
4157 value of a local variable. However, this function does not look
4158 for the `mode:' local variable near the end of a file; the
4159 `hack-local-variables' function does that. *Note How Major Modes
4160 are Chosen: (xemacs)Choosing Modes.
4162 -- User Option: default-major-mode
4163 This variable holds the default major mode for new buffers. The
4164 standard value is `fundamental-mode'.
4166 If the value of `default-major-mode' is `nil', XEmacs uses the
4167 (previously) current buffer's major mode for the major mode of a
4168 new buffer. However, if the major mode symbol has a `mode-class'
4169 property with value `special', then it is not used for new buffers;
4170 Fundamental mode is used instead. The modes that have this
4171 property are those such as Dired and Rmail that are useful only
4172 with text that has been specially prepared.
4174 -- Function: set-buffer-major-mode buffer
4175 This function sets the major mode of BUFFER to the value of
4176 `default-major-mode'. If that variable is `nil', it uses the
4177 current buffer's major mode (if that is suitable).
4179 The low-level primitives for creating buffers do not use this
4180 function, but medium-level commands such as `switch-to-buffer' and
4181 `find-file-noselect' use it whenever they create buffers.
4183 -- Variable: initial-major-mode
4184 The value of this variable determines the major mode of the initial
4185 `*scratch*' buffer. The value should be a symbol that is a major
4186 mode command name. The default value is `lisp-interaction-mode'.
4188 -- Variable: auto-mode-alist
4189 This variable contains an association list of file name patterns
4190 (regular expressions; *note Regular Expressions::) and
4191 corresponding major mode functions. Usually, the file name
4192 patterns test for suffixes, such as `.el' and `.c', but this need
4193 not be the case. An ordinary element of the alist looks like
4194 `(REGEXP . MODE-FUNCTION)'.
4198 (("^/tmp/fol/" . text-mode)
4199 ("\\.texinfo\\'" . texinfo-mode)
4200 ("\\.texi\\'" . texinfo-mode)
4201 ("\\.el\\'" . emacs-lisp-mode)
4202 ("\\.c\\'" . c-mode)
4203 ("\\.h\\'" . c-mode)
4206 When you visit a file whose expanded file name (*note File Name
4207 Expansion::) matches a REGEXP, `set-auto-mode' calls the
4208 corresponding MODE-FUNCTION. This feature enables XEmacs to select
4209 the proper major mode for most files.
4211 If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
4212 t)', then after calling FUNCTION, XEmacs searches
4213 `auto-mode-alist' again for a match against the portion of the file
4214 name that did not match before.
4216 This match-again feature is useful for uncompression packages: an
4217 entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
4218 and then put the uncompressed file in the proper mode according to
4219 the name sans `.gz'.
4221 Here is an example of how to prepend several pattern pairs to
4222 `auto-mode-alist'. (You might use this sort of expression in your
4225 (setq auto-mode-alist
4227 ;; File name starts with a dot.
4228 '(("/\\.[^/]*\\'" . fundamental-mode)
4229 ;; File name has no dot.
4230 ("[^\\./]*\\'" . fundamental-mode)
4231 ;; File name ends in `.C'.
4232 ("\\.C\\'" . c++-mode))
4235 -- Variable: interpreter-mode-alist
4236 This variable specifies major modes to use for scripts that
4237 specify a command interpreter in an `#!' line. Its value is a
4238 list of elements of the form `(INTERPRETER . MODE)'; for example,
4239 `("perl" . perl-mode)' is one element present by default. The
4240 element says to use mode MODE if the file specifies INTERPRETER.
4242 This variable is applicable only when the `auto-mode-alist' does
4243 not indicate which major mode to use.
4245 -- Function: hack-local-variables &optional force
4246 This function parses, and binds or evaluates as appropriate, any
4247 local variables for the current buffer.
4249 The handling of `enable-local-variables' documented for
4250 `normal-mode' actually takes place here. The argument FORCE
4251 usually comes from the argument FIND-FILE given to `normal-mode'.
4254 File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes
4256 33.1.4 Getting Help about a Major Mode
4257 --------------------------------------
4259 The `describe-mode' function is used to provide information about major
4260 modes. It is normally called with `C-h m'. The `describe-mode'
4261 function uses the value of `major-mode', which is why every major mode
4262 function needs to set the `major-mode' variable.
4264 -- Command: describe-mode
4265 This function displays the documentation of the current major mode.
4267 The `describe-mode' function calls the `documentation' function
4268 using the value of `major-mode' as an argument. Thus, it displays
4269 the documentation string of the major mode function. (*Note
4270 Accessing Documentation::.)
4272 -- Variable: major-mode
4273 This variable holds the symbol for the current buffer's major mode.
4274 This symbol should have a function definition that is the command
4275 to switch to that major mode. The `describe-mode' function uses
4276 the documentation string of the function as the documentation of
4280 File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes
4282 33.1.5 Defining Derived Modes
4283 -----------------------------
4285 It's often useful to define a new major mode in terms of an existing
4286 one. An easy way to do this is to use `define-derived-mode'.
4288 -- Macro: define-derived-mode variant parent name docstring body...
4289 This construct defines VARIANT as a major mode command, using NAME
4290 as the string form of the mode name.
4292 The new command VARIANT is defined to call the function PARENT,
4293 then override certain aspects of that parent mode:
4295 * The new mode has its own keymap, named `VARIANT-map'.
4296 `define-derived-mode' initializes this map to inherit from
4297 `PARENT-map', if it is not already set.
4299 * The new mode has its own syntax table, kept in the variable
4300 `VARIANT-syntax-table'. `define-derived-mode' initializes
4301 this variable by copying `PARENT-syntax-table', if it is not
4304 * The new mode has its own abbrev table, kept in the variable
4305 `VARIANT-abbrev-table'. `define-derived-mode' initializes
4306 this variable by copying `PARENT-abbrev-table', if it is not
4309 * The new mode has its own mode hook, `VARIANT-hook', which it
4310 runs in standard fashion as the very last thing that it does.
4311 (The new mode also runs the mode hook of PARENT as part of
4314 In addition, you can specify how to override other aspects of
4315 PARENT with BODY. The command VARIANT evaluates the forms in BODY
4316 after setting up all its usual overrides, just before running
4319 The argument DOCSTRING specifies the documentation string for the
4320 new mode. If you omit DOCSTRING, `define-derived-mode' generates
4321 a documentation string.
4323 Here is a hypothetical example:
4325 (define-derived-mode hypertext-mode
4326 text-mode "Hypertext"
4327 "Major mode for hypertext.
4328 \\{hypertext-mode-map}"
4329 (setq case-fold-search nil))
4331 (define-key hypertext-mode-map
4332 [down-mouse-3] 'do-hyper-link)
4334 Do not write an `interactive' spec in the definition;
4335 `define-derived-mode' does that automatically.
4338 File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes
4343 A "minor mode" provides features that users may enable or disable
4344 independently of the choice of major mode. Minor modes can be enabled
4345 individually or in combination. Minor modes would be better named
4346 "Generally available, optional feature modes" except that such a name is
4349 A minor mode is not usually a modification of single major mode. For
4350 example, Auto Fill mode may be used in any major mode that permits text
4351 insertion. To be general, a minor mode must be effectively independent
4352 of the things major modes do.
4354 A minor mode is often much more difficult to implement than a major
4355 mode. One reason is that you should be able to activate and deactivate
4356 minor modes in any order. A minor mode should be able to have its
4357 desired effect regardless of the major mode and regardless of the other
4358 minor modes in effect.
4360 Often the biggest problem in implementing a minor mode is finding a
4361 way to insert the necessary hook into the rest of XEmacs. Minor mode
4362 keymaps make this easier than it used to be.
4366 * Minor Mode Conventions:: Tips for writing a minor mode.
4367 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
4370 File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes
4372 33.2.1 Conventions for Writing Minor Modes
4373 ------------------------------------------
4375 There are conventions for writing minor modes just as there are for
4376 major modes. Several of the major mode conventions apply to minor
4377 modes as well: those regarding the name of the mode initialization
4378 function, the names of global symbols, and the use of keymaps and other
4381 In addition, there are several conventions that are specific to
4384 * Make a variable whose name ends in `-mode' to represent the minor
4385 mode. Its value should enable or disable the mode (`nil' to
4386 disable; anything else to enable.) We call this the "mode
4389 This variable is used in conjunction with the `minor-mode-alist' to
4390 display the minor mode name in the modeline. It can also enable
4391 or disable a minor mode keymap. Individual commands or hooks can
4392 also check the variable's value.
4394 If you want the minor mode to be enabled separately in each buffer,
4395 make the variable buffer-local.
4397 * Define a command whose name is the same as the mode variable. Its
4398 job is to enable and disable the mode by setting the variable.
4400 The command should accept one optional argument. If the argument
4401 is `nil', it should toggle the mode (turn it on if it is off, and
4402 off if it is on). Otherwise, it should turn the mode on if the
4403 argument is a positive integer, a symbol other than `nil' or `-',
4404 or a list whose CAR is such an integer or symbol; it should turn
4405 the mode off otherwise.
4407 Here is an example taken from the definition of
4408 `transient-mark-mode'. It shows the use of `transient-mark-mode'
4409 as a variable that enables or disables the mode's behavior, and
4410 also shows the proper way to toggle, enable or disable the minor
4411 mode based on the raw prefix argument value.
4413 (setq transient-mark-mode
4414 (if (null arg) (not transient-mark-mode)
4415 (> (prefix-numeric-value arg) 0)))
4417 * Add an element to `minor-mode-alist' for each minor mode (*note
4418 Modeline Variables::). This element should be a list of the
4421 (MODE-VARIABLE STRING)
4423 Here MODE-VARIABLE is the variable that controls enabling of the
4424 minor mode, and STRING is a short string, starting with a space,
4425 to represent the mode in the modeline. These strings must be
4426 short so that there is room for several of them at once.
4428 When you add an element to `minor-mode-alist', use `assq' to check
4429 for an existing element, to avoid duplication. For example:
4431 (or (assq 'leif-mode minor-mode-alist)
4432 (setq minor-mode-alist
4433 (cons '(leif-mode " Leif") minor-mode-alist)))
4436 File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes
4438 33.2.2 Keymaps and Minor Modes
4439 ------------------------------
4441 Each minor mode can have its own keymap, which is active when the mode
4442 is enabled. To set up a keymap for a minor mode, add an element to the
4443 alist `minor-mode-map-alist'. *Note Active Keymaps::.
4445 One use of minor mode keymaps is to modify the behavior of certain
4446 self-inserting characters so that they do something else as well as
4447 self-insert. In general, this is the only way to do that, since the
4448 facilities for customizing `self-insert-command' are limited to special
4449 cases (designed for abbrevs and Auto Fill mode). (Do not try
4450 substituting your own definition of `self-insert-command' for the
4451 standard one. The editor command loop handles this function specially.)
4454 File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes
4456 33.3 Modeline Format
4457 ====================
4459 Each Emacs window (aside from minibuffer windows) includes a modeline,
4460 which displays status information about the buffer displayed in the
4461 window. The modeline contains information about the buffer, such as its
4462 name, associated file, depth of recursive editing, and the major and
4465 This section describes how the contents of the modeline are
4466 controlled. It is in the chapter on modes because much of the
4467 information displayed in the modeline relates to the enabled major and
4470 `modeline-format' is a buffer-local variable that holds a template
4471 used to display the modeline of the current buffer. All windows for
4472 the same buffer use the same `modeline-format' and their modelines
4473 appear the same (except for scrolling percentages and line numbers).
4475 The modeline of a window is normally updated whenever a different
4476 buffer is shown in the window, or when the buffer's modified-status
4477 changes from `nil' to `t' or vice-versa. If you modify any of the
4478 variables referenced by `modeline-format' (*note Modeline Variables::),
4479 you may want to force an update of the modeline so as to display the
4482 -- Function: redraw-modeline &optional all
4483 Force redisplay of the current buffer's modeline. If ALL is
4484 non-`nil', then force redisplay of all modelines.
4486 The modeline is usually displayed in inverse video. This is
4487 controlled using the `modeline' face. *Note Faces::.
4491 * Modeline Data:: The data structure that controls the modeline.
4492 * Modeline Variables:: Variables used in that data structure.
4493 * %-Constructs:: Putting information into a modeline.
4496 File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format
4498 33.3.1 The Data Structure of the Modeline
4499 -----------------------------------------
4501 The modeline contents are controlled by a data structure of lists,
4502 strings, symbols, and numbers kept in the buffer-local variable
4503 `modeline-format'. The data structure is called a "modeline
4504 construct", and it is built in recursive fashion out of simpler modeline
4505 constructs. The same data structure is used for constructing frame
4506 titles (*note Frame Titles::).
4508 -- Variable: modeline-format
4509 The value of this variable is a modeline construct with overall
4510 responsibility for the modeline format. The value of this variable
4511 controls which other variables are used to form the modeline text,
4512 and where they appear.
4514 A modeline construct may be as simple as a fixed string of text, but
4515 it usually specifies how to use other variables to construct the text.
4516 Many of these variables are themselves defined to have modeline
4517 constructs as their values.
4519 The default value of `modeline-format' incorporates the values of
4520 variables such as `mode-name' and `minor-mode-alist'. Because of this,
4521 very few modes need to alter `modeline-format'. For most purposes, it
4522 is sufficient to alter the variables referenced by `modeline-format'.
4524 A modeline construct may be a string, symbol, glyph, generic
4525 specifier, list or cons cell.
4528 A string as a modeline construct is displayed verbatim in the mode
4529 line except for "`%'-constructs". Decimal digits after the `%'
4530 specify the field width for space filling on the right (i.e., the
4531 data is left justified). *Note %-Constructs::.
4534 A symbol as a modeline construct stands for its value. The value
4535 of SYMBOL is processed as a modeline construct, in place of
4536 SYMBOL. However, the symbols `t' and `nil' are ignored; so is any
4537 symbol whose value is void.
4539 There is one exception: if the value of SYMBOL is a string, it is
4540 displayed verbatim: the `%'-constructs are not recognized.
4543 A glyph is displayed as is.
4546 A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands
4547 for its instance. The instance of GENERIC-SPECIFIER is computed
4548 in the current window using the equivalent of `specifier-instance'
4549 and the value is processed.
4551 `(STRING REST...) or (LIST REST...)'
4552 A list whose first element is a string or list means to process
4553 all the elements recursively and concatenate the results. This is
4554 the most common form of mode line construct.
4556 `(SYMBOL THEN ELSE)'
4557 A list whose first element is a symbol is a conditional. Its
4558 meaning depends on the value of SYMBOL. If the value is non-`nil',
4559 the second element, THEN, is processed recursively as a modeline
4560 element. But if the value of SYMBOL is `nil', the third element,
4561 ELSE, is processed recursively. You may omit ELSE; then the mode
4562 line element displays nothing if the value of SYMBOL is `nil'.
4565 A list whose first element is an integer specifies truncation or
4566 padding of the results of REST. The remaining elements REST are
4567 processed recursively as modeline constructs and concatenated
4568 together. Then the result is space filled (if WIDTH is positive)
4569 or truncated (to -WIDTH columns, if WIDTH is negative) on the
4572 For example, the usual way to show what percentage of a buffer is
4573 above the top of the window is to use a list like this: `(-3
4577 A list whose car is an extent means the cdr of the list is
4578 processed normally but the results are displayed using the face of
4579 the extent, and mouse clicks over this section are processed using
4580 the keymap of the extent. (In addition, if the extent has a
4581 help-echo property, that string will be echoed when the mouse
4582 moves over this section.) If extents are nested, all keymaps are
4583 properly consulted when processing mouse clicks, but multiple
4584 faces are not correctly merged (only the first face is used), and
4585 lists of faces are not correctly handled.
4587 If you do alter `modeline-format' itself, the new value should use
4588 the same variables that appear in the default value (*note Modeline
4589 Variables::), rather than duplicating their contents or displaying the
4590 information in another fashion. This way, customizations made by the
4591 user or by Lisp programs (such as `display-time' and major modes) via
4592 changes to those variables remain effective.
4594 Here is an example of a `modeline-format' that might be useful for
4595 `shell-mode', since it contains the hostname and default directory.
4597 (setq modeline-format
4601 (getenv "HOST") ; One element is not constant.
4612 '(line-number-mode "L%l--")
4617 File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format
4619 33.3.2 Variables Used in the Modeline
4620 -------------------------------------
4622 This section describes variables incorporated by the standard value of
4623 `modeline-format' into the text of the mode line. There is nothing
4624 inherently special about these variables; any other variables could
4625 have the same effects on the modeline if `modeline-format' were changed
4628 -- Variable: modeline-modified
4629 This variable holds the value of the modeline construct that
4630 displays whether the current buffer is modified.
4632 The default value of `modeline-modified' is `("--%1*%1+-")'. This
4633 means that the modeline displays `--**-' if the buffer is
4634 modified, `-----' if the buffer is not modified, `--%%-' if the
4635 buffer is read only, and `--%*--' if the buffer is read only and
4638 Changing this variable does not force an update of the modeline.
4640 -- Variable: modeline-buffer-identification
4641 This variable identifies the buffer being displayed in the window.
4642 Its default value is `("%F: %17b")', which means that it usually
4643 displays `Emacs:' followed by seventeen characters of the buffer
4644 name. (In a terminal frame, it displays the frame name instead of
4645 `Emacs'; this has the effect of showing the frame number.) You may
4646 want to change this in modes such as Rmail that do not behave like
4649 -- Variable: global-mode-string
4650 This variable holds a modeline spec that appears in the mode line
4651 by default, just after the buffer name. The command `display-time'
4652 sets `global-mode-string' to refer to the variable
4653 `display-time-string', which holds a string containing the time and
4656 The `%M' construct substitutes the value of `global-mode-string',
4657 but this is obsolete, since the variable is included directly in
4660 -- Variable: mode-name
4661 This buffer-local variable holds the "pretty" name of the current
4662 buffer's major mode. Each major mode should set this variable so
4663 that the mode name will appear in the modeline.
4665 -- Variable: minor-mode-alist
4666 This variable holds an association list whose elements specify how
4667 the modeline should indicate that a minor mode is active. Each
4668 element of the `minor-mode-alist' should be a two-element list:
4670 (MINOR-MODE-VARIABLE MODELINE-STRING)
4672 More generally, MODELINE-STRING can be any mode line spec. It
4673 appears in the mode line when the value of MINOR-MODE-VARIABLE is
4674 non-`nil', and not otherwise. These strings should begin with
4675 spaces so that they don't run together. Conventionally, the
4676 MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
4677 value when that minor mode is activated.
4679 The default value of `minor-mode-alist' is:
4682 => ((vc-mode vc-mode)
4683 (abbrev-mode " Abbrev")
4684 (overwrite-mode overwrite-mode)
4685 (auto-fill-function " Fill")
4686 (defining-kbd-macro " Def")
4687 (isearch-mode isearch-mode))
4689 `minor-mode-alist' is not buffer-local. The variables mentioned
4690 in the alist should be buffer-local if the minor mode can be
4691 enabled separately in each buffer.
4693 -- Variable: modeline-process
4694 This buffer-local variable contains the modeline information on
4695 process status in modes used for communicating with subprocesses.
4696 It is displayed immediately following the major mode name, with no
4697 intervening space. For example, its value in the `*shell*' buffer
4698 is `(": %s")', which allows the shell to display its status along
4699 with the major mode as: `(Shell: run)'. Normally this variable is
4702 -- Variable: default-modeline-format
4703 This variable holds the default `modeline-format' for buffers that
4704 do not override it. This is the same as `(default-value
4707 The default value of `default-modeline-format' is:
4711 modeline-buffer-identification
4720 (line-number-mode "L%l--")
4724 -- Variable: vc-mode
4725 The variable `vc-mode', local in each buffer, records whether the
4726 buffer's visited file is maintained with version control, and, if
4727 so, which kind. Its value is `nil' for no version control, or a
4728 string that appears in the mode line.
4731 File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format
4733 33.3.3 `%'-Constructs in the ModeLine
4734 -------------------------------------
4736 The following table lists the recognized `%'-constructs and what they
4737 mean. In any construct except `%%', you can add a decimal integer
4738 after the `%' to specify how many characters to display.
4741 The current buffer name, obtained with the `buffer-name' function.
4742 *Note Buffer Names::.
4745 The visited file name, obtained with the `buffer-file-name'
4746 function. *Note Buffer File Name::.
4749 The name of the selected frame.
4752 The current column number of point.
4755 The current line number of point.
4758 `%' if the buffer is read only (see `buffer-read-only');
4759 `*' if the buffer is modified (see `buffer-modified-p');
4760 `-' otherwise. *Note Buffer Modification::.
4763 `*' if the buffer is modified (see `buffer-modified-p');
4764 `%' if the buffer is read only (see `buffer-read-only');
4765 `-' otherwise. This differs from `%*' only for a modified
4766 read-only buffer. *Note Buffer Modification::.
4769 `*' if the buffer is modified, and `-' otherwise.
4772 The status of the subprocess belonging to the current buffer,
4773 obtained with `process-status'. *Note Process Information::.
4776 The current line number.
4779 The name of the selected frame; this is only meaningful under the
4780 X Window System. *Note Frame Name::.
4783 Whether the visited file is a text file or a binary file. (This
4784 is a meaningful distinction only on certain operating systems.)
4787 The percentage of the buffer text above the *top* of window, or
4788 `Top', `Bottom' or `All'.
4791 The percentage of the buffer text that is above the *bottom* of
4792 the window (which includes the text visible in the window, as well
4793 as the text above the top), plus `Top' if the top of the buffer is
4794 visible on screen; or `Bottom' or `All'.
4797 `Narrow' when narrowing is in effect; nothing otherwise (see
4798 `narrow-to-region' in *Note Narrowing::).
4801 Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.
4804 An indication of the depth of recursive editing levels (not
4805 counting minibuffer levels): one `[' for each editing level.
4806 *Note Recursive Editing::.
4809 One `]' for each recursive editing level (not counting minibuffer
4813 The character `%'--this is how to include a literal `%' in a
4814 string in which `%'-constructs are allowed.
4817 Dashes sufficient to fill the remainder of the modeline.
4819 The following two `%'-constructs are still supported, but they are
4820 obsolete, since you can get the same results with the variables
4821 `mode-name' and `global-mode-string'.
4824 The value of `mode-name'.
4827 The value of `global-mode-string'. Currently, only `display-time'
4828 modifies the value of `global-mode-string'.
4831 File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
4836 A "hook" is a variable where you can store a function or functions to
4837 be called on a particular occasion by an existing program. XEmacs
4838 provides hooks for the sake of customization. Most often, hooks are set
4839 up in the `.emacs' file, but Lisp programs can set them also. *Note
4840 Standard Hooks::, for a list of standard hook variables.
4842 Most of the hooks in XEmacs are "normal hooks". These variables
4843 contain lists of functions to be called with no arguments. The reason
4844 most hooks are normal hooks is so that you can use them in a uniform
4845 way. You can usually tell when a hook is a normal hook, because its
4846 name ends in `-hook'.
4848 The recommended way to add a hook function to a normal hook is by
4849 calling `add-hook' (see below). The hook functions may be any of the
4850 valid kinds of functions that `funcall' accepts (*note What Is a
4851 Function::). Most normal hook variables are initially void; `add-hook'
4852 knows how to deal with this.
4854 As for abnormal hooks, those whose names end in `-function' have a
4855 value that is a single function. Those whose names end in `-hooks'
4856 have a value that is a list of functions. Any hook that is abnormal is
4857 abnormal because a normal hook won't do the job; either the functions
4858 are called with arguments, or their values are meaningful. The name
4859 shows you that the hook is abnormal and that you should look at its
4860 documentation string to see how to use it properly.
4862 Major mode functions are supposed to run a hook called the "mode
4863 hook" as the last step of initialization. This makes it easy for a user
4864 to customize the behavior of the mode, by overriding the local variable
4865 assignments already made by the mode. But hooks are used in other
4866 contexts too. For example, the hook `suspend-hook' runs just before
4867 XEmacs suspends itself (*note Suspending XEmacs::).
4869 Here's an expression that uses a mode hook to turn on Auto Fill mode
4870 when in Lisp Interaction mode:
4872 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
4874 The next example shows how to use a hook to customize the way XEmacs
4875 formats C code. (People often have strong personal preferences for one
4876 format or another.) Here the hook function is an anonymous lambda
4879 (add-hook 'c-mode-hook
4880 (function (lambda ()
4881 (setq c-indent-level 4
4884 c-continued-statement-indent 0
4886 comment-column 40))))
4888 (setq c++-mode-hook c-mode-hook)
4890 The final example shows how the appearance of the modeline can be
4891 modified for a particular class of buffers only.
4893 (add-hook 'text-mode-hook
4894 (function (lambda ()
4895 (setq modeline-format
4911 At the appropriate time, XEmacs uses the `run-hooks' function to run
4912 particular hooks. This function calls the hook functions you have
4913 added with `add-hooks'.
4915 -- Function: run-hooks &rest hookvar
4916 This function takes one or more hook variable names as arguments,
4917 and runs each hook in turn. Each HOOKVAR argument should be a
4918 symbol that is a hook variable. These arguments are processed in
4919 the order specified.
4921 If a hook variable has a non-`nil' value, that value may be a
4922 function or a list of functions. If the value is a function
4923 (either a lambda expression or a symbol with a function
4924 definition), it is called. If it is a list, the elements are
4925 called, in order. The hook functions are called with no arguments.
4927 For example, here's how `emacs-lisp-mode' runs its mode hook:
4929 (run-hooks 'emacs-lisp-mode-hook)
4931 -- Function: run-mode-hooks &rest hookvars
4932 Like `run-hooks', but is affected by the `delay-mode-hooks' macro.
4934 -- Macro: delay-mode-hooks body...
4935 This macro executes the BODY forms but defers all calls to
4936 `run-mode-hooks' within them until the end of BODY. This macro
4937 enables a derived mode to arrange not to run its parent modes'
4938 mode hooks until the end.
4940 -- Function: run-hook-with-args hook &rest args
4941 This function is the way to run an abnormal hook and always call
4942 all of the hook functions. It calls each of the hook functions
4943 one by one, passing each of them the arguments ARGS.
4945 -- Function: run-hook-with-args-until-failure hook &rest args
4946 This function is the way to run an abnormal hook until one of the
4947 hook functions fails. It calls each of the hook functions,
4948 passing each of them the arguments ARGS, until some hook function
4949 returns `nil'. It then stops and returns `nil'. If none of the
4950 hook functions return `nil', it returns a non-`nil' value.
4952 -- Function: run-hook-with-args-until-success hook &rest args
4953 This function is the way to run an abnormal hook until a hook
4954 function succeeds. It calls each of the hook functions, passing
4955 each of them the arguments ARGS, until some hook function returns
4956 non-`nil'. Then it stops, and returns whatever was returned by
4957 the last hook function that was called. If all hook functions
4958 return `nil', it returns `nil' as well.
4960 -- Function: add-hook hook function &optional append local
4961 This function is the handy way to add function FUNCTION to hook
4962 variable HOOK. The argument FUNCTION may be any valid Lisp
4963 function with the proper number of arguments. For example,
4965 (add-hook 'text-mode-hook 'my-text-hook-function)
4967 adds `my-text-hook-function' to the hook called `text-mode-hook'.
4969 You can use `add-hook' for abnormal hooks as well as for normal
4972 It is best to design your hook functions so that the order in
4973 which they are executed does not matter. Any dependence on the
4974 order is "asking for trouble." However, the order is predictable:
4975 normally, FUNCTION goes at the front of the hook list, so it will
4976 be executed first (barring another `add-hook' call).
4978 If the optional argument APPEND is non-`nil', the new hook
4979 function goes at the end of the hook list and will be executed
4982 If LOCAL is non-`nil', that says to make the new hook function
4983 local to the current buffer. Before you can do this, you must
4984 make the hook itself buffer-local by calling `make-local-hook'
4985 (*not* `make-local-variable'). If the hook itself is not
4986 buffer-local, then the value of LOCAL makes no difference--the
4987 hook function is always global.
4989 -- Function: remove-hook hook function &optional local
4990 This function removes FUNCTION from the hook variable HOOK.
4992 If LOCAL is non-`nil', that says to remove FUNCTION from the local
4993 hook list instead of from the global hook list. If the hook
4994 itself is not buffer-local, then the value of LOCAL makes no
4997 -- Function: make-local-hook hook
4998 This function makes the hook variable HOOK local to the current
4999 buffer. When a hook variable is local, it can have local and
5000 global hook functions, and `run-hooks' runs all of them.
5002 This function works by making `t' an element of the buffer-local
5003 value. That serves as a flag to use the hook functions in the
5004 default value of the hook variable as well as those in the local
5005 value. Since `run-hooks' understands this flag, `make-local-hook'
5006 works with all normal hooks. It works for only some non-normal
5007 hooks--those whose callers have been updated to understand this
5010 Do not use `make-local-variable' directly for hook variables; it is
5014 File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
5019 XEmacs Lisp has convenient on-line help facilities, most of which
5020 derive their information from the documentation strings associated with
5021 functions and variables. This chapter describes how to write good
5022 documentation strings for your Lisp programs, as well as how to write
5023 programs to access documentation.
5025 Note that the documentation strings for XEmacs are not the same thing
5026 as the XEmacs manual. Manuals have their own source files, written in
5027 the Texinfo language; documentation strings are specified in the
5028 definitions of the functions and variables they apply to. A collection
5029 of documentation strings is not sufficient as a manual because a good
5030 manual is not organized in that fashion; it is organized in terms of
5031 topics of discussion.
5035 * Documentation Basics:: Good style for doc strings.
5036 Where to put them. How XEmacs stores them.
5037 * Accessing Documentation:: How Lisp programs can access doc strings.
5038 * Keys in Documentation:: Substituting current key bindings.
5039 * Describing Characters:: Making printable descriptions of
5040 non-printing characters and key sequences.
5041 * Help Functions:: Subroutines used by XEmacs help facilities.
5042 * Obsoleteness:: Upgrading Lisp functionality over time.
5045 File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
5047 34.1 Documentation Basics
5048 =========================
5050 A documentation string is written using the Lisp syntax for strings,
5051 with double-quote characters surrounding the text of the string. This
5052 is because it really is a Lisp string object. The string serves as
5053 documentation when it is written in the proper place in the definition
5054 of a function or variable. In a function definition, the documentation
5055 string follows the argument list. In a variable definition, the
5056 documentation string follows the initial value of the variable.
5058 When you write a documentation string, make the first line a complete
5059 sentence (or two complete sentences) since some commands, such as
5060 `apropos', show only the first line of a multi-line documentation
5061 string. Also, you should not indent the second line of a documentation
5062 string, if you have one, because that looks odd when you use `C-h f'
5063 (`describe-function') or `C-h v' (`describe-variable'). *Note
5064 Documentation Tips::.
5066 Documentation strings may contain several special substrings, which
5067 stand for key bindings to be looked up in the current keymaps when the
5068 documentation is displayed. This allows documentation strings to refer
5069 to the keys for related commands and be accurate even when a user
5070 rearranges the key bindings. (*Note Accessing Documentation::.)
5072 Within the Lisp world, a documentation string is accessible through
5073 the function or variable that it describes:
5075 * The documentation for a function is stored in the function
5076 definition itself (*note Lambda Expressions::). The function
5077 `documentation' knows how to extract it.
5079 * The documentation for a variable is stored in the variable's
5080 property list under the property name `variable-documentation'.
5081 The function `documentation-property' knows how to extract it.
5083 To save space, the documentation for preloaded functions and
5084 variables (including primitive functions and autoloaded functions) is
5085 stored in the "internal doc file" `DOC'. The documentation for
5086 functions and variables loaded during the XEmacs session from
5087 byte-compiled files is stored in those very same byte-compiled files
5088 (*note Docs and Compilation::).
5090 XEmacs does not keep documentation strings in memory unless
5091 necessary. Instead, XEmacs maintains, for preloaded symbols, an
5092 integer offset into the internal doc file, and for symbols loaded from
5093 byte-compiled files, a list containing the filename of the
5094 byte-compiled file and an integer offset, in place of the documentation
5095 string. The functions `documentation' and `documentation-property' use
5096 that information to read the documentation from the appropriate file;
5097 this is transparent to the user.
5099 For information on the uses of documentation strings, see *Note
5102 The `emacs/lib-src' directory contains two utilities that you can
5103 use to print nice-looking hardcopy for the file
5104 `emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'.
5107 File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
5109 34.2 Access to Documentation Strings
5110 ====================================
5112 -- Function: documentation-property symbol property &optional verbatim
5113 This function returns the documentation string that is recorded in
5114 SYMBOL's property list under property PROPERTY. It retrieves the
5115 text from a file if necessary, and runs `substitute-command-keys'
5116 to substitute actual key bindings. (This substitution is not done
5117 if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
5120 (documentation-property 'command-line-processed
5121 'variable-documentation)
5122 => "t once command line has been processed"
5123 (symbol-plist 'command-line-processed)
5124 => (variable-documentation 188902)
5126 -- Function: documentation function &optional verbatim
5127 This function returns the documentation string of FUNCTION. It
5128 reads the text from a file if necessary. Then (unless VERBATIM is
5129 non-`nil') it calls `substitute-command-keys', to return a value
5130 containing the actual (current) key bindings.
5132 The function `documentation' signals a `void-function' error if
5133 FUNCTION has no function definition. However, it is ok if the
5134 function definition has no documentation string. In that case,
5135 `documentation' returns `nil'.
5137 Here is an example of using the two functions, `documentation' and
5138 `documentation-property', to display the documentation strings for
5139 several symbols in a `*Help*' buffer.
5141 (defun describe-symbols (pattern)
5142 "Describe the XEmacs Lisp symbols matching PATTERN.
5143 All symbols that have PATTERN in their name are described
5144 in the `*Help*' buffer."
5145 (interactive "sDescribe symbols matching: ")
5146 (let ((describe-func
5149 ;; Print description of symbol.
5150 (if (fboundp s) ; It is a function.
5152 (format "%s\t%s\n%s\n\n" s
5154 (let ((keys (where-is-internal s)))
5158 (mapconcat 'key-description
5162 (or (documentation s)
5163 "not documented"))))
5165 (if (boundp s) ; It is a variable.
5167 (format "%s\t%s\n%s\n\n" s
5168 (if (user-variable-p s)
5169 "Option " "Variable")
5170 (or (documentation-property
5171 s 'variable-documentation)
5172 "not documented")))))))
5175 ;; Build a list of symbols that match pattern.
5178 (if (string-match pattern (symbol-name sym))
5179 (setq sym-list (cons sym sym-list))))))
5181 ;; Display the data.
5182 (with-output-to-temp-buffer "*Help*"
5183 (mapcar describe-func (sort sym-list 'string<))
5184 (print-help-return-message))))
5186 The `describe-symbols' function works like `apropos', but provides
5189 (describe-symbols "goal")
5191 ---------- Buffer: *Help* ----------
5193 *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
5195 set-goal-column Command: C-x C-n
5196 Set the current horizontal position as a goal for C-n and C-p.
5197 Those commands will move to this position in the line moved to
5198 rather than trying to keep the same horizontal position.
5199 With a non-`nil' argument, clears out the goal column
5200 so that C-n and C-p resume vertical motion.
5201 The goal column is stored in the variable `goal-column'.
5203 temporary-goal-column Variable
5204 Current goal column for vertical motion.
5205 It is the column where point was
5206 at the start of current run of vertical motion commands.
5207 When the `track-eol' feature is doing its job, the value is 9999.
5208 ---------- Buffer: *Help* ----------
5210 -- Function: Snarf-documentation filename
5211 This function is used only during XEmacs initialization, just
5212 before the runnable XEmacs is dumped. It finds the file offsets
5213 of the documentation strings stored in the file FILENAME, and
5214 records them in the in-core function definitions and variable
5215 property lists in place of the actual strings. *Note Building
5218 XEmacs finds the file FILENAME in the `lib-src' directory. When
5219 the dumped XEmacs is later executed, the same file is found in the
5220 directory `doc-directory'. The usual value for FILENAME is `DOC',
5221 but this can be changed by modifying the variable
5222 `internal-doc-file-name'.
5224 -- Variable: internal-doc-file-name
5225 This variable holds the name of the file containing documentation
5226 strings of built-in symbols, usually `DOC'. The full pathname of
5227 the internal doc file is `(concat doc-directory
5228 internal-doc-file-name)'.
5230 -- Variable: doc-directory
5231 This variable holds the name of the directory which contains the
5232 "internal doc file" that contains documentation strings for
5233 built-in and preloaded functions and variables.
5235 In most cases, this is the same as `exec-directory'. They may be
5236 different when you run XEmacs from the directory where you built
5237 it, without actually installing it. See `exec-directory' in *Note
5240 In older Emacs versions, `exec-directory' was used for this.
5242 -- Variable: data-directory
5243 This variable holds the name of the directory in which XEmacs finds
5244 certain system independent documentation and text files that come
5245 with XEmacs. In older Emacs versions, `exec-directory' was used
5249 File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
5251 34.3 Substituting Key Bindings in Documentation
5252 ===============================================
5254 When documentation strings refer to key sequences, they should use the
5255 current, actual key bindings. They can do so using certain special text
5256 sequences described below. Accessing documentation strings in the usual
5257 way substitutes current key binding information for these special
5258 sequences. This works by calling `substitute-command-keys'. You can
5259 also call that function yourself.
5261 Here is a list of the special sequences and what they mean:
5264 stands for a key sequence that will invoke COMMAND, or `M-x
5265 COMMAND' if COMMAND has no key bindings.
5268 stands for a summary of the value of MAPVAR, which should be a
5269 keymap. The summary is made by `describe-bindings'.
5272 stands for no text itself. It is used for a side effect: it
5273 specifies MAPVAR as the keymap for any following `\[COMMAND]'
5274 sequences in this documentation string.
5277 quotes the following character and is discarded; this `\=\=' puts
5278 `\=' into the output, and `\=\[' puts `\[' into the output.
5280 *Please note:* Each `\' must be doubled when written in a string in
5283 -- Function: substitute-command-keys string
5284 This function scans STRING for the above special sequences and
5285 replaces them by what they stand for, returning the result as a
5286 string. This permits display of documentation that refers
5287 accurately to the user's own customized key bindings.
5289 Here are examples of the special sequences:
5291 (substitute-command-keys
5292 "To abort recursive edit, type: \\[abort-recursive-edit]")
5293 => "To abort recursive edit, type: C-]"
5295 (substitute-command-keys
5296 "The keys that are defined for the minibuffer here are:
5297 \\{minibuffer-local-must-match-map}")
5298 => "The keys that are defined for the minibuffer here are:
5300 ? minibuffer-completion-help
5301 SPC minibuffer-complete-word
5302 TAB minibuffer-complete
5303 LFD minibuffer-complete-and-exit
5304 RET minibuffer-complete-and-exit
5305 C-g abort-recursive-edit
5308 (substitute-command-keys
5309 "To abort a recursive edit from the minibuffer, type\
5310 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
5311 => "To abort a recursive edit from the minibuffer, type C-g."
5313 (substitute-command-keys
5314 "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
5315 \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
5316 Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
5317 as the keymap for future \\=\\[COMMAND] substrings.
5318 \\=\\= quotes the following character and is discarded;
5319 thus, \\=\\=\\=\\= puts \\=\\= into the output,
5320 and \\=\\=\\=\\[ puts \\=\\[ into the output.")
5321 => "Substrings of the form \{MAPVAR} are replaced by summaries
5322 (made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
5323 Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
5324 as the keymap for future \[COMMAND] substrings.
5325 \= quotes the following character and is discarded;
5326 thus, \=\= puts \= into the output,
5327 and \=\[ puts \[ into the output."
5330 File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
5332 34.4 Describing Characters for Help Messages
5333 ============================================
5335 These functions convert events, key sequences or characters to textual
5336 descriptions. These descriptions are useful for including arbitrary
5337 text characters or key sequences in messages, because they convert
5338 non-printing and whitespace characters to sequences of printing
5339 characters. The description of a non-whitespace printing character is
5340 the character itself.
5342 -- Function: key-description sequence
5343 This function returns a string containing the XEmacs standard
5344 notation for the input events in SEQUENCE. The argument SEQUENCE
5345 may be a string, vector or list. *Note Events::, for more
5346 information about valid events. See also the examples for
5347 `single-key-description', below.
5349 -- Function: single-key-description key
5350 This function returns a string describing KEY in the standard
5351 XEmacs notation for keyboard input. A normal printing character
5352 appears as itself, but a control character turns into a string
5353 starting with `C-', a meta character turns into a string starting
5354 with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
5355 A symbol appears as the name of the symbol. An event that is a
5356 list appears as the name of the symbol in the CAR of the list.
5358 (single-key-description ?\C-x)
5360 (key-description "\C-x \M-y \n \t \r \f123")
5361 => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
5362 (single-key-description 'kp-next)
5364 (single-key-description '(shift button1))
5367 -- Function: text-char-description character
5368 This function returns a string describing CHARACTER in the
5369 standard XEmacs notation for characters that appear in text--like
5370 `single-key-description', except that control characters are
5371 represented with a leading caret (which is how control characters
5372 in XEmacs buffers are usually displayed).
5374 (text-char-description ?\C-c)
5376 (text-char-description ?\M-m)
5378 (text-char-description ?\C-\M-m)
5382 File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
5387 XEmacs provides a variety of on-line help functions, all accessible to
5388 the user as subcommands of the prefix `C-h', or on some keyboards,
5389 `help'. For more information about them, see *Note Help: (emacs)Help.
5390 Here we describe some program-level interfaces to the same information.
5392 -- Command: apropos regexp &optional do-all predicate
5393 This function finds all symbols whose names contain a match for the
5394 regular expression REGEXP, and returns a list of them (*note
5395 Regular Expressions::). It also displays the symbols in a buffer
5396 named `*Help*', each with a one-line description.
5398 If DO-ALL is non-`nil', then `apropos' also shows key bindings for
5399 the functions that are found.
5401 If PREDICATE is non-`nil', it should be a function to be called on
5402 each symbol that has matched REGEXP. Only symbols for which
5403 PREDICATE returns a non-`nil' value are listed or displayed.
5405 In the first of the following examples, `apropos' finds all the
5406 symbols with names containing `exec'. In the second example, it
5407 finds and returns only those symbols that are also commands. (We
5408 don't show the output that results in the `*Help*' buffer.)
5411 => (Buffer-menu-execute command-execute exec-directory
5412 exec-path execute-extended-command execute-kbd-macro
5413 executing-kbd-macro executing-macro)
5415 (apropos "exec" nil 'commandp)
5416 => (Buffer-menu-execute execute-extended-command)
5418 `apropos' is used by various user-level commands, such as `C-h a'
5419 (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
5420 (`command-apropos'), which does an apropos over only those
5421 functions which are user commands. `command-apropos' calls
5422 `apropos', specifying a PREDICATE to restrict the output to
5423 symbols that are commands. The call to `apropos' looks like this:
5425 (apropos string t 'commandp)
5427 -- Variable: help-map
5428 The value of this variable is a local keymap for characters
5429 following the Help key, `C-h'.
5431 -- Prefix Command: help-command
5432 This symbol is not a function; its function definition is actually
5433 the keymap known as `help-map'. It is defined in `help.el' as
5436 (define-key global-map "\C-h" 'help-command)
5437 (fset 'help-command help-map)
5439 -- Function: print-help-return-message &optional function
5440 This function builds a string that explains how to restore the
5441 previous state of the windows after a help command. After
5442 building the message, it applies FUNCTION to it if FUNCTION is
5443 non-`nil'. Otherwise it calls `message' to display it in the echo
5446 This function expects to be called inside a
5447 `with-output-to-temp-buffer' special form, and expects
5448 `standard-output' to have the value bound by that special form.
5449 For an example of its use, see the long example in *Note Accessing
5452 -- Variable: help-char
5453 The value of this variable is the help character--the character
5454 that XEmacs recognizes as meaning Help. By default, it is the
5455 character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this
5456 character, if `help-form' is non-`nil' Lisp expression, it
5457 evaluates that expression, and displays the result in a window if
5460 `help-char' can be a character or a key description such as `help'
5463 Usually the value of `help-form''s value is `nil'. Then the help
5464 character has no special meaning at the level of command input, and
5465 it becomes part of a key sequence in the normal way. The standard
5466 key binding of `C-h' is a prefix key for several general-purpose
5469 The help character is special after prefix keys, too. If it has no
5470 binding as a subcommand of the prefix key, it runs
5471 `describe-prefix-bindings', which displays a list of all the
5472 subcommands of the prefix key.
5474 -- Variable: help-form
5475 If this variable is non-`nil', its value is a form to evaluate
5476 whenever the character `help-char' is read. If evaluating the form
5477 produces a string, that string is displayed.
5479 A command that calls `next-command-event' or `next-event' probably
5480 should bind `help-form' to a non-`nil' expression while it does
5481 input. (The exception is when `C-h' is meaningful input.)
5482 Evaluating this expression should result in a string that explains
5483 what the input is for and how to enter it properly.
5485 Entry to the minibuffer binds this variable to the value of
5486 `minibuffer-help-form' (*note Minibuffer Misc::).
5488 -- Variable: prefix-help-command
5489 This variable holds a function to print help for a prefix
5490 character. The function is called when the user types a prefix
5491 key followed by the help character, and the help character has no
5492 binding after that prefix. The variable's default value is
5493 `describe-prefix-bindings'.
5495 -- Command: describe-prefix-bindings
5496 This function calls `describe-bindings' to display a list of all
5497 the subcommands of the prefix key of the most recent key sequence.
5498 The prefix described consists of all but the last event of that
5499 key sequence. (The last event is, presumably, the help character.)
5501 The following two functions are found in the library `helper'. They
5502 are for modes that want to provide help without relinquishing control,
5503 such as the "electric" modes. You must load that library with
5504 `(require 'helper)' in order to use them. Their names begin with
5505 `Helper' to distinguish them from the ordinary help functions.
5507 -- Command: Helper-describe-bindings
5508 This command pops up a window displaying a help buffer containing a
5509 listing of all of the key bindings from both the local and global
5510 keymaps. It works by calling `describe-bindings'.
5512 -- Command: Helper-help
5513 This command provides help for the current mode. It prompts the
5514 user in the minibuffer with the message `Help (Type ? for further
5515 options)', and then provides assistance in finding out what the key
5516 bindings are, and what the mode is intended for. It returns `nil'.
5518 This can be customized by changing the map `Helper-help-map'.
5521 File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
5526 As you add functionality to a package, you may at times want to replace
5527 an older function with a new one. To preserve compatibility with
5528 existing code, the older function needs to still exist; but users of
5529 that function should be told to use the newer one instead. XEmacs Lisp
5530 lets you mark a function or variable as "obsolete", and indicate what
5531 should be used instead.
5533 -- Command: make-obsolete function new &optional when
5534 This function indicates that FUNCTION is an obsolete function, and
5535 the function NEW should be used instead. The byte compiler will
5536 issue a warning to this effect when it encounters a usage of the
5537 older function, and the help system will also note this in the
5538 function's documentation. NEW can also be a string (if there is
5539 not a single function with the same functionality any more), and
5540 should be a descriptive statement, such as "use FOO or BAR
5541 instead" or "this function is unnecessary". If provided, WHEN
5542 should be a string indicating when the function was first made
5543 obsolete, for example a date or a release number.
5545 -- Command: make-obsolete-variable variable new
5546 This is like `make-obsolete' but is for variables instead of
5549 -- Function: define-obsolete-function-alias oldfun newfun
5550 This function combines `make-obsolete' and `define-function',
5551 declaring OLDFUN to be an obsolete variant of NEWFUN and defining
5552 OLDFUN as an alias for NEWFUN.
5554 -- Function: define-obsolete-variable-alias oldvar newvar
5555 This is like `define-obsolete-function-alias' but for variables.
5557 Note that you should not normally put obsoleteness information
5558 explicitly in a function or variable's doc string. The obsoleteness
5559 information that you specify using the above functions will be displayed
5560 whenever the doc string is displayed, and by adding it explicitly the
5561 result is redundancy.
5563 Also, if an obsolete function is substantially the same as a newer
5564 one but is not actually an alias, you should consider omitting the doc
5565 string entirely (use a null string `""' as the doc string). That way,
5566 the user is told about the obsoleteness and is forced to look at the
5567 documentation of the new function, making it more likely that he will
5568 use the new function.
5570 -- Function: function-obsoleteness-doc function
5571 If FUNCTION is obsolete, this function returns a string describing
5572 this. This is the message that is printed out during byte
5573 compilation or in the function's documentation. If FUNCTION is
5574 not obsolete, `nil' is returned.
5576 -- Function: variable-obsoleteness-doc variable
5577 This is like `function-obsoleteness-doc' but for variables.
5579 The obsoleteness information is stored internally by putting a
5580 property `byte-obsolete-info' (for functions) or
5581 `byte-obsolete-variable' (for variables) on the symbol that specifies
5582 the obsolete function or variable. For more information, see the
5583 implementation of `make-obsolete' and `make-obsolete-variable' in
5584 `lisp/bytecomp/bytecomp-runtime.el'.
5587 File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
5592 In XEmacs, you can find, create, view, save, and otherwise work with
5593 files and file directories. This chapter describes most of the
5594 file-related functions of XEmacs Lisp, but a few others are described in
5595 *Note Buffers::, and those related to backups and auto-saving are
5596 described in *Note Backups and Auto-Saving::.
5598 Many of the file functions take one or more arguments that are file
5599 names. A file name is actually a string. Most of these functions
5600 expand file name arguments using `expand-file-name', so that `~' is
5601 handled correctly, as are relative file names (including `../'). These
5602 functions don't recognize environment variable substitutions such as
5603 `$HOME'. *Note File Name Expansion::.
5607 * Visiting Files:: Reading files into Emacs buffers for editing.
5608 * Saving Buffers:: Writing changed buffers back into files.
5609 * Reading from Files:: Reading files into buffers without visiting.
5610 * Writing to Files:: Writing new files from parts of buffers.
5611 * File Locks:: Locking and unlocking files, to prevent
5612 simultaneous editing by two people.
5613 * Information about Files:: Testing existence, accessibility, size of files.
5614 * Changing File Attributes:: Renaming files, changing protection, etc.
5615 * File Names:: Decomposing and expanding file names.
5616 * Contents of Directories:: Getting a list of the files in a directory.
5617 * Create/Delete Dirs:: Creating and Deleting Directories.
5618 * Magic File Names:: Defining "magic" special handling
5619 for certain file names.
5620 * Partial Files:: Treating a section of a buffer as a file.
5621 * Format Conversion:: Conversion to and from various file formats.
5622 * Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
5625 File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
5630 Visiting a file means reading a file into a buffer. Once this is done,
5631 we say that the buffer is "visiting" that file, and call the file "the
5632 visited file" of the buffer.
5634 A file and a buffer are two different things. A file is information
5635 recorded permanently in the computer (unless you delete it). A buffer,
5636 on the other hand, is information inside of XEmacs that will vanish at
5637 the end of the editing session (or when you kill the buffer). Usually,
5638 a buffer contains information that you have copied from a file; then we
5639 say the buffer is visiting that file. The copy in the buffer is what
5640 you modify with editing commands. Such changes to the buffer do not
5641 change the file; therefore, to make the changes permanent, you must
5642 "save" the buffer, which means copying the altered buffer contents back
5645 In spite of the distinction between files and buffers, people often
5646 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
5647 "I am editing a file," rather than, "I am editing a buffer that I will
5648 soon save as a file of the same name." Humans do not usually need to
5649 make the distinction explicit. When dealing with a computer program,
5650 however, it is good to keep the distinction in mind.
5654 * Visiting Functions:: The usual interface functions for visiting.
5655 * Subroutines of Visiting:: Lower-level subroutines that they use.
5658 File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
5660 35.1.1 Functions for Visiting Files
5661 -----------------------------------
5663 This section describes the functions normally used to visit files. For
5664 historical reasons, these functions have names starting with `find-'
5665 rather than `visit-'. *Note Buffer File Name::, for functions and
5666 variables that access the visited file name of a buffer or that find an
5667 existing buffer by its visited file name.
5669 In a Lisp program, if you want to look at the contents of a file but
5670 not alter it, the fastest way is to use `insert-file-contents' in a
5671 temporary buffer. Visiting the file is not necessary and takes longer.
5672 *Note Reading from Files::.
5674 -- Command: find-file filename
5675 This command selects a buffer visiting the file FILENAME, using an
5676 existing buffer if there is one, and otherwise creating a new
5677 buffer and reading the file into it. It also returns that buffer.
5679 The body of the `find-file' function is very simple and looks like
5682 (switch-to-buffer (find-file-noselect filename))
5684 (See `switch-to-buffer' in *Note Displaying Buffers::.)
5686 When `find-file' is called interactively, it prompts for FILENAME
5689 -- Function: find-file-noselect filename &optional nowarn
5690 This function is the guts of all the file-visiting functions. It
5691 finds or creates a buffer visiting the file FILENAME, and returns
5692 it. It uses an existing buffer if there is one, and otherwise
5693 creates a new buffer and reads the file into it. You may make the
5694 buffer current or display it in a window if you wish, but this
5695 function does not do so.
5697 When `find-file-noselect' uses an existing buffer, it first
5698 verifies that the file has not changed since it was last visited or
5699 saved in that buffer. If the file has changed, then this function
5700 asks the user whether to reread the changed file. If the user says
5701 `yes', any changes previously made in the buffer are lost.
5703 If `find-file-noselect' needs to create a buffer, and there is no
5704 file named FILENAME, it displays the message `New file' in the
5705 echo area, and leaves the buffer empty.
5707 If NOWARN is non-`nil', various warnings that XEmacs normally
5708 gives (e.g. if another buffer is already visiting FILENAME but
5709 FILENAME has been removed from disk since that buffer was created)
5712 The `find-file-noselect' function calls `after-find-file' after
5713 reading the file (*note Subroutines of Visiting::). That function
5714 sets the buffer major mode, parses local variables, warns the user
5715 if there exists an auto-save file more recent than the file just
5716 visited, and finishes by running the functions in
5719 The `find-file-noselect' function returns the buffer that is
5720 visiting the file FILENAME.
5722 (find-file-noselect "/etc/fstab")
5725 -- Command: find-file-other-window filename
5726 This command selects a buffer visiting the file FILENAME, but does
5727 so in a window other than the selected window. It may use another
5728 existing window or split a window; see *Note Displaying Buffers::.
5730 When this command is called interactively, it prompts for FILENAME.
5732 -- Command: find-file-read-only filename
5733 This command selects a buffer visiting the file FILENAME, like
5734 `find-file', but it marks the buffer as read-only. *Note Read
5735 Only Buffers::, for related functions and variables.
5737 When this command is called interactively, it prompts for FILENAME.
5739 -- Command: view-file filename &optional other-window-p
5740 This command visits FILENAME in View mode, and displays it in a
5741 recursive edit, returning to the previous buffer when done. View
5742 mode is a mode that allows you to skim rapidly through the file
5743 but does not let you modify it. Entering View mode runs the
5744 normal hook `view-mode-hook'. *Note Hooks::.
5746 When `view-file' is called interactively, it prompts for FILENAME.
5748 With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in
5751 -- Variable: find-file-hooks
5752 The value of this variable is a list of functions to be called
5753 after a file is visited. The file's local-variables specification
5754 (if any) will have been processed before the hooks are run. The
5755 buffer visiting the file is current when the hook functions are
5758 This variable works just like a normal hook, but we think that
5759 renaming it would not be advisable.
5761 -- Variable: find-file-not-found-hooks
5762 The value of this variable is a list of functions to be called when
5763 `find-file' or `find-file-noselect' is passed a nonexistent file
5764 name. `find-file-noselect' calls these functions as soon as it
5765 detects a nonexistent file. It calls them in the order of the
5766 list, until one of them returns non-`nil'. `buffer-file-name' is
5769 This is not a normal hook because the values of the functions are
5770 used and they may not all be called.
5773 File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
5775 35.1.2 Subroutines of Visiting
5776 ------------------------------
5778 The `find-file-noselect' function uses the `create-file-buffer' and
5779 `after-find-file' functions as subroutines. Sometimes it is useful to
5782 -- Function: create-file-buffer filename
5783 This function creates a suitably named buffer for visiting
5784 FILENAME, and returns it. It uses FILENAME (sans directory) as
5785 the name if that name is free; otherwise, it appends a string such
5786 as `<2>' to get an unused name. See also *Note Creating Buffers::.
5788 *Please note:* `create-file-buffer' does _not_ associate the new
5789 buffer with a file and does not select the buffer. It also does
5790 not use the default major mode.
5792 (create-file-buffer "foo")
5794 (create-file-buffer "foo")
5796 (create-file-buffer "foo")
5799 This function is used by `find-file-noselect'. It uses
5800 `generate-new-buffer' (*note Creating Buffers::).
5802 -- Function: after-find-file &optional error warn noauto
5803 This function sets the buffer major mode, and parses local
5804 variables (*note Auto Major Mode::). It is called by
5805 `find-file-noselect' and by the default revert function (*note
5808 If reading the file got an error because the file does not exist,
5809 but its directory does exist, the caller should pass a non-`nil'
5810 value for ERROR. In that case, `after-find-file' issues a warning:
5811 `(New File)'. For more serious errors, the caller should usually
5812 not call `after-find-file'.
5814 If WARN is non-`nil', then this function issues a warning if an
5815 auto-save file exists and is more recent than the visited file.
5817 If NOAUTO is non-`nil', then this function does not turn on
5818 auto-save mode; otherwise, it does.
5820 The last thing `after-find-file' does is call all the functions in
5824 File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
5829 When you edit a file in XEmacs, you are actually working on a buffer
5830 that is visiting that file--that is, the contents of the file are
5831 copied into the buffer and the copy is what you edit. Changes to the
5832 buffer do not change the file until you "save" the buffer, which means
5833 copying the contents of the buffer into the file.
5835 -- Command: save-buffer &optional backup-option
5836 This function saves the contents of the current buffer in its
5837 visited file if the buffer has been modified since it was last
5838 visited or saved. Otherwise it does nothing.
5840 `save-buffer' is responsible for making backup files. Normally,
5841 BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
5842 if this is the first save since visiting the file. Other values
5843 for BACKUP-OPTION request the making of backup files in other
5846 * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
5847 `save-buffer' function marks this version of the file to be
5848 backed up when the buffer is next saved.
5850 * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
5851 `save-buffer' function unconditionally backs up the previous
5852 version of the file before saving it.
5854 -- Command: save-some-buffers &optional save-silently-p exiting
5855 This command saves some modified file-visiting buffers. Normally
5856 it asks the user about each buffer. But if SAVE-SILENTLY-P is
5857 non-`nil', it saves all the file-visiting buffers without querying
5860 The optional EXITING argument, if non-`nil', requests this
5861 function to offer also to save certain other buffers that are not
5862 visiting files. These are buffers that have a non-`nil' local
5863 value of `buffer-offer-save'. (A user who says yes to saving one
5864 of these is asked to specify a file name to use.) The
5865 `save-buffers-kill-emacs' function passes a non-`nil' value for
5868 -- Variable: buffer-offer-save
5869 When this variable is non-`nil' in a buffer, XEmacs offers to save
5870 the buffer on exit even if the buffer is not visiting a file. The
5871 variable is automatically local in all buffers. Normally, Mail
5872 mode (used for editing outgoing mail) sets this to `t'.
5874 -- Command: write-file filename
5875 This function writes the current buffer into file FILENAME, makes
5876 the buffer visit that file, and marks it not modified. Then it
5877 renames the buffer based on FILENAME, appending a string like `<2>'
5878 if necessary to make a unique buffer name. It does most of this
5879 work by calling `set-visited-file-name' and `save-buffer'.
5881 -- Variable: write-file-hooks
5882 The value of this variable is a list of functions to be called
5883 before writing out a buffer to its visited file. If one of them
5884 returns non-`nil', the file is considered already written and the
5885 rest of the functions are not called, nor is the usual code for
5886 writing the file executed.
5888 If a function in `write-file-hooks' returns non-`nil', it is
5889 responsible for making a backup file (if that is appropriate). To
5890 do so, execute the following code:
5892 (or buffer-backed-up (backup-buffer))
5894 You might wish to save the file modes value returned by
5895 `backup-buffer' and use that to set the mode bits of the file that
5896 you write. This is what `save-buffer' normally does.
5898 Even though this is not a normal hook, you can use `add-hook' and
5899 `remove-hook' to manipulate the list. *Note Hooks::.
5901 -- Variable: local-write-file-hooks
5902 This works just like `write-file-hooks', but it is intended to be
5903 made local to particular buffers. It's not a good idea to make
5904 `write-file-hooks' local to a buffer--use this variable instead.
5906 The variable is marked as a permanent local, so that changing the
5907 major mode does not alter a buffer-local value. This is
5908 convenient for packages that read "file" contents in special ways,
5909 and set up hooks to save the data in a corresponding way.
5911 -- Variable: write-contents-hooks
5912 This works just like `write-file-hooks', but it is intended for
5913 hooks that pertain to the contents of the file, as opposed to
5914 hooks that pertain to where the file came from. Such hooks are
5915 usually set up by major modes, as buffer-local bindings for this
5916 variable. Switching to a new major mode always resets this
5919 -- Variable: after-save-hook
5920 This normal hook runs after a buffer has been saved in its visited
5923 -- Variable: file-precious-flag
5924 If this variable is non-`nil', then `save-buffer' protects against
5925 I/O errors while saving by writing the new file to a temporary
5926 name instead of the name it is supposed to have, and then renaming
5927 it to the intended name after it is clear there are no errors.
5928 This procedure prevents problems such as a lack of disk space from
5929 resulting in an invalid file.
5931 As a side effect, backups are necessarily made by copying. *Note
5932 Rename or Copy::. Yet, at the same time, saving a precious file
5933 always breaks all hard links between the file you save and other
5936 Some modes set this variable non-`nil' locally in particular
5939 -- User Option: require-final-newline
5940 This variable determines whether files may be written out that do
5941 _not_ end with a newline. If the value of the variable is `t',
5942 then `save-buffer' silently adds a newline at the end of the file
5943 whenever the buffer being saved does not already end in one. If
5944 the value of the variable is non-`nil', but not `t', then
5945 `save-buffer' asks the user whether to add a newline each time the
5948 If the value of the variable is `nil', then `save-buffer' doesn't
5949 add newlines at all. `nil' is the default value, but a few major
5950 modes set it to `t' in particular buffers.
5953 File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
5955 35.3 Reading from Files
5956 =======================
5958 You can copy a file from the disk and insert it into a buffer using the
5959 `insert-file-contents' function. Don't use the user-level command
5960 `insert-file' in a Lisp program, as that sets the mark.
5962 -- Function: insert-file-contents filename &optional visit start end
5964 This function inserts the contents of file FILENAME into the
5965 current buffer after point. It returns a list of the absolute
5966 file name and the length of the data inserted. An error is
5967 signaled if FILENAME is not the name of a file that can be read.
5969 The function `insert-file-contents' checks the file contents
5970 against the defined file formats, and converts the file contents if
5971 appropriate. *Note Format Conversion::. It also calls the
5972 functions in the list `after-insert-file-functions'; see *Note
5973 Saving Properties::.
5975 If VISIT is non-`nil', this function additionally marks the buffer
5976 as unmodified and sets up various fields in the buffer so that it
5977 is visiting the file FILENAME: these include the buffer's visited
5978 file name and its last save file modtime. This feature is used by
5979 `find-file-noselect' and you probably should not use it yourself.
5981 If START and END are non-`nil', they should be integers specifying
5982 the portion of the file to insert. In this case, VISIT must be
5985 (insert-file-contents filename nil 0 500)
5987 inserts the first 500 characters of a file.
5989 If the argument REPLACE is non-`nil', it means to replace the
5990 contents of the buffer (actually, just the accessible portion)
5991 with the contents of the file. This is better than simply
5992 deleting the buffer contents and inserting the whole file, because
5993 (1) it preserves some marker positions and (2) it puts less data
5996 If you want to pass a file name to another process so that another
5997 program can read the file, use the function `file-local-copy'; see
5998 *Note Magic File Names::.
6001 File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
6003 35.4 Writing to Files
6004 =====================
6006 You can write the contents of a buffer, or part of a buffer, directly
6007 to a file on disk using the `append-to-file' and `write-region'
6008 functions. Don't use these functions to write to files that are being
6009 visited; that could cause confusion in the mechanisms for visiting.
6011 -- Command: append-to-file start end filename
6012 This function appends the contents of the region delimited by
6013 START and END in the current buffer to the end of file FILENAME.
6014 If that file does not exist, it is created. If that file exists
6015 it is overwritten. This function returns `nil'.
6017 An error is signaled if FILENAME specifies a nonwritable file, or
6018 a nonexistent file in a directory where files cannot be created.
6020 -- Command: write-region start end filename &optional append visit
6021 This function writes the region delimited by START and END in the
6022 current buffer into the file specified by FILENAME.
6024 If START is a string, then `write-region' writes or appends that
6025 string, rather than text from the buffer.
6027 If APPEND is non-`nil', then the specified text is appended to the
6028 existing file contents (if any).
6030 If VISIT is `t', then XEmacs establishes an association between
6031 the buffer and the file: the buffer is then visiting that file.
6032 It also sets the last file modification time for the current
6033 buffer to FILENAME's modtime, and marks the buffer as not
6034 modified. This feature is used by `save-buffer', but you probably
6035 should not use it yourself.
6037 If VISIT is a string, it specifies the file name to visit. This
6038 way, you can write the data to one file (FILENAME) while recording
6039 the buffer as visiting another file (VISIT). The argument VISIT
6040 is used in the echo area message and also for file locking; VISIT
6041 is stored in `buffer-file-name'. This feature is used to
6042 implement `file-precious-flag'; don't use it yourself unless you
6043 really know what you're doing.
6045 The function `write-region' converts the data which it writes to
6046 the appropriate file formats specified by `buffer-file-format'.
6047 *Note Format Conversion::. It also calls the functions in the list
6048 `write-region-annotate-functions'; see *Note Saving Properties::.
6050 Normally, `write-region' displays a message `Wrote file FILENAME'
6051 in the echo area. If VISIT is neither `t' nor `nil' nor a string,
6052 then this message is inhibited. This feature is useful for
6053 programs that use files for internal purposes, files that the user
6054 does not need to know about.
6057 File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
6062 When two users edit the same file at the same time, they are likely to
6063 interfere with each other. XEmacs tries to prevent this situation from
6064 arising by recording a "file lock" when a file is being modified.
6065 XEmacs can then detect the first attempt to modify a buffer visiting a
6066 file that is locked by another XEmacs process, and ask the user what to
6069 File locks do not work properly when multiple machines can share
6070 file systems, such as with NFS. Perhaps a better file locking system
6071 will be implemented in the future. When file locks do not work, it is
6072 possible for two users to make changes simultaneously, but XEmacs can
6073 still warn the user who saves second. Also, the detection of
6074 modification of a buffer visiting a file changed on disk catches some
6075 cases of simultaneous editing; see *Note Modification Time::.
6077 -- Function: file-locked-p &optional filename
6078 This function returns `nil' if the file FILENAME is not locked by
6079 this XEmacs process. It returns `t' if it is locked by this
6080 XEmacs, and it returns the name of the user who has locked it if it
6081 is locked by someone else.
6083 (file-locked-p "foo")
6086 -- Function: lock-buffer &optional filename
6087 This function locks the file FILENAME, if the current buffer is
6088 modified. The argument FILENAME defaults to the current buffer's
6089 visited file. Nothing is done if the current buffer is not
6090 visiting a file, or is not modified.
6092 -- Function: unlock-buffer
6093 This function unlocks the file being visited in the current buffer,
6094 if the buffer is modified. If the buffer is not modified, then
6095 the file should not be locked, so this function does nothing. It
6096 also does nothing if the current buffer is not visiting a file.
6098 -- Function: ask-user-about-lock filename other-user
6099 This function is called when the user tries to modify FILENAME,
6100 but it is locked by another user named OTHER-USER. The value it
6101 returns determines what happens next:
6103 * A value of `t' says to grab the lock on the file. Then this
6104 user may edit the file and OTHER-USER loses the lock.
6106 * A value of `nil' says to ignore the lock and let this user
6107 edit the file anyway.
6109 * This function may instead signal a `file-locked' error, in
6110 which case the change that the user was about to make does
6113 The error message for this error looks like this:
6115 error--> File is locked: FILENAME OTHER-USER
6117 where FILENAME is the name of the file and OTHER-USER is the
6118 name of the user who has locked the file.
6120 The default definition of this function asks the user to choose
6121 what to do. If you wish, you can replace the `ask-user-about-lock'
6122 function with your own version that decides in another way. The
6123 code for its usual definition is in `userlock.el'.
6126 File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
6128 35.6 Information about Files
6129 ============================
6131 The functions described in this section all operate on strings that
6132 designate file names. All the functions have names that begin with the
6133 word `file'. These functions all return information about actual files
6134 or directories, so their arguments must all exist as actual files or
6135 directories unless otherwise noted.
6139 * Testing Accessibility:: Is a given file readable? Writable?
6140 * Kinds of Files:: Is it a directory? A symbolic link?
6141 * Truenames:: Eliminating symbolic links from a file name.
6142 * File Attributes:: How large is it? Any other names? Etc.
6145 File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
6147 35.6.1 Testing Accessibility
6148 ----------------------------
6150 These functions test for permission to access a file in specific ways.
6152 -- Function: file-exists-p filename
6153 This function returns `t' if a file named FILENAME appears to
6154 exist. This does not mean you can necessarily read the file, only
6155 that you can find out its attributes. (On Unix, this is true if
6156 the file exists and you have execute permission on the containing
6157 directories, regardless of the protection of the file itself.)
6159 If the file does not exist, or if fascist access control policies
6160 prevent you from finding the attributes of the file, this function
6163 -- Function: file-readable-p filename
6164 This function returns `t' if a file named FILENAME exists and you
6165 can read it. It returns `nil' otherwise.
6167 (file-readable-p "files.texi")
6169 (file-exists-p "/usr/spool/mqueue")
6171 (file-readable-p "/usr/spool/mqueue")
6174 -- Function: file-executable-p filename
6175 This function returns `t' if a file named FILENAME exists and you
6176 can execute it. It returns `nil' otherwise. If the file is a
6177 directory, execute permission means you can check the existence and
6178 attributes of files inside the directory, and open those files if
6181 -- Function: file-writable-p filename
6182 This function returns `t' if the file FILENAME can be written or
6183 created by you, and `nil' otherwise. A file is writable if the
6184 file exists and you can write it. It is creatable if it does not
6185 exist, but the specified directory does exist and you can write in
6188 In the third example below, `foo' is not writable because the
6189 parent directory does not exist, even though the user could create
6192 (file-writable-p "~/foo")
6194 (file-writable-p "/foo")
6196 (file-writable-p "~/no-such-dir/foo")
6199 -- Function: file-accessible-directory-p dirname
6200 This function returns `t' if you have permission to open existing
6201 files in the directory whose name as a file is DIRNAME; otherwise
6202 (or if there is no such directory), it returns `nil'. The value
6203 of DIRNAME may be either a directory name or the file name of a
6206 Example: after the following,
6208 (file-accessible-directory-p "/foo")
6211 we can deduce that any attempt to read a file in `/foo/' will give
6214 -- Function: file-ownership-preserved-p filename
6215 This function returns `t' if deleting the file FILENAME and then
6216 creating it anew would keep the file's owner unchanged.
6218 -- Function: file-newer-than-file-p filename1 filename2
6219 This function returns `t' if the file FILENAME1 is newer than file
6220 FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
6221 FILENAME2 does not exist, it returns `t'.
6223 In the following example, assume that the file `aug-19' was written
6224 on the 19th, `aug-20' was written on the 20th, and the file
6225 `no-file' doesn't exist at all.
6227 (file-newer-than-file-p "aug-19" "aug-20")
6229 (file-newer-than-file-p "aug-20" "aug-19")
6231 (file-newer-than-file-p "aug-19" "no-file")
6233 (file-newer-than-file-p "no-file" "aug-19")
6236 You can use `file-attributes' to get a file's last modification
6237 time as a list of two numbers. *Note File Attributes::.
6240 File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
6242 35.6.2 Distinguishing Kinds of Files
6243 ------------------------------------
6245 This section describes how to distinguish various kinds of files, such
6246 as directories, symbolic links, and ordinary files.
6248 -- Function: file-symlink-p filename
6249 If the file FILENAME is a symbolic link, the `file-symlink-p'
6250 function returns the file name to which it is linked. This may be
6251 the name of a text file, a directory, or even another symbolic
6252 link, or it may be a nonexistent file name.
6254 If the file FILENAME is not a symbolic link (or there is no such
6255 file), `file-symlink-p' returns `nil'.
6257 (file-symlink-p "foo")
6259 (file-symlink-p "sym-link")
6261 (file-symlink-p "sym-link2")
6263 (file-symlink-p "/bin")
6267 -- Function: file-directory-p filename
6268 This function returns `t' if FILENAME is the name of an existing
6269 directory, `nil' otherwise.
6271 (file-directory-p "~rms")
6273 (file-directory-p "~rms/lewis/files.texi")
6275 (file-directory-p "~rms/lewis/no-such-file")
6277 (file-directory-p "$HOME")
6280 (substitute-in-file-name "$HOME"))
6283 -- Function: file-regular-p filename
6284 This function returns `t' if the file FILENAME exists and is a
6285 regular file (not a directory, symbolic link, named pipe,
6286 terminal, or other I/O device).
6289 File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
6294 The "truename" of a file is the name that you get by following symbolic
6295 links until none remain, then expanding to get rid of `.' and `..' as
6296 components. Strictly speaking, a file need not have a unique truename;
6297 the number of distinct truenames a file has is equal to the number of
6298 hard links to the file. However, truenames are useful because they
6299 eliminate symbolic links as a cause of name variation.
6301 -- Function: file-truename filename &optional default
6302 The function `file-truename' returns the true name of the file
6303 FILENAME. This is the name that you get by following symbolic
6304 links until none remain.
6306 If the filename is relative, DEFAULT is the directory to start
6307 with. If DEFAULT is `nil' or missing, the current buffer's value
6308 of `default-directory' is used.
6310 *Note Buffer File Name::, for related information.
6313 File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files
6315 35.6.4 Other Information about Files
6316 ------------------------------------
6318 This section describes the functions for getting detailed information
6319 about a file, other than its contents. This information includes the
6320 mode bits that control access permission, the owner and group numbers,
6321 the number of names, the inode number, the size, and the times of access
6324 -- Function: file-modes filename
6325 This function returns the mode bits of FILENAME, as an integer.
6326 The mode bits are also called the file permissions, and they
6327 specify access control in the usual Unix fashion. If the
6328 low-order bit is 1, then the file is executable by all users, if
6329 the second-lowest-order bit is 1, then the file is writable by all
6332 The highest value returnable is 4095 (7777 octal), meaning that
6333 everyone has read, write, and execute permission, that the SUID bit
6334 is set for both others and group, and that the sticky bit is set.
6336 (file-modes "~/junk/diffs")
6337 => 492 ; Decimal integer.
6339 => "754" ; Convert to octal.
6341 (set-file-modes "~/junk/diffs" 438)
6345 => "666" ; Convert to octal.
6348 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
6350 -- Function: file-nlinks filename
6351 This functions returns the number of names (i.e., hard links) that
6352 file FILENAME has. If the file does not exist, then this function
6353 returns `nil'. Note that symbolic links have no effect on this
6354 function, because they are not considered to be names of the files
6358 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
6359 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
6363 (file-nlinks "doesnt-exist")
6366 -- Function: file-attributes filename
6367 This function returns a list of attributes of file FILENAME. If
6368 the specified file cannot be opened, it returns `nil'.
6370 The elements of the list, in order, are:
6372 0. `t' for a directory, a string for a symbolic link (the name
6373 linked to), or `nil' for a text file.
6375 1. The number of names the file has. Alternate names, also
6376 known as hard links, can be created by using the
6377 `add-name-to-file' function (*note Changing File
6384 4. The time of last access, as a list of two integers. The
6385 first integer has the high-order 16 bits of time, the second
6386 has the low 16 bits. (This is similar to the value of
6387 `current-time'; see *Note Time of Day::.)
6389 5. The time of last modification as a list of two integers (as
6392 6. The time of last status change as a list of two integers (as
6395 7. The size of the file in bytes.
6397 8. The file's modes, as a string of ten letters or dashes, as in
6400 9. `t' if the file's GID would change if file were deleted and
6401 recreated; `nil' otherwise.
6403 10. The file's inode number.
6405 11. The file system number of the file system that the file is
6406 in. This element and the file's inode number together give
6407 enough information to distinguish any two files on the
6408 system--no two files can have the same values for both of
6411 For example, here are the file attributes for `files.texi':
6413 (file-attributes "files.texi")
6427 and here is how the result is interpreted:
6430 is neither a directory nor a symbolic link.
6433 has only one name (the name `files.texi' in the current
6437 is owned by the user with UID 2235.
6440 is in the group with GID 75.
6443 was last accessed on Aug 19 00:09. Use `format-time-string' to
6444 ! convert this number into a time string. *Note Time
6448 was last modified on Aug 19 00:09.
6451 last had its inode changed on Aug 19 00:09.
6454 is 14906 characters long.
6457 has a mode of read and write access for the owner, group, and
6461 would retain the same GID if it were recreated.
6464 has an inode number of 129500.
6467 is on file system number -32252.
6470 File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
6472 35.7 Changing File Names and Attributes
6473 =======================================
6475 The functions in this section rename, copy, delete, link, and set the
6478 In the functions that have arguments NEWNAME and
6479 OK-IF-ALREADY-EXISTS, if a file by the name of NEWNAME already exists,
6480 the actions taken depend on the value of OK-IF-ALREADY-EXISTS:
6482 * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
6485 * Request confirmation if OK-IF-ALREADY-EXISTS is a number. This is
6486 what happens when the function is invoked interactively.
6488 * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
6491 -- Command: add-name-to-file filename newname &optional
6492 ok-if-already-exists
6493 This function gives the file named FILENAME the additional name
6494 NEWNAME. This means that NEWNAME becomes a new "hard link" to
6495 FILENAME. Both these arguments must be strings.
6497 In the first part of the following example, we list two files,
6501 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
6502 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
6504 Then we evaluate the form `(add-name-to-file "~/lewis/foo"
6505 "~/lewis/foo2")'. Again we list the files. This shows two names,
6508 (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
6512 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
6513 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
6514 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
6516 Finally, we evaluate the following:
6518 (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
6520 and list the files again. Now there are three names for one file:
6521 `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
6523 (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
6527 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
6528 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
6529 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
6531 This function is meaningless on non-Unix systems, where multiple
6532 names for one file are not allowed.
6534 See also `file-nlinks' in *Note File Attributes::.
6536 -- Command: rename-file filename newname &optional ok-if-already-exists
6537 This command renames the file FILENAME as NEWNAME.
6539 If FILENAME has additional names aside from FILENAME, it continues
6540 to have those names. In fact, adding the name NEWNAME with
6541 `add-name-to-file' and then deleting FILENAME has the same effect
6542 as renaming, aside from momentary intermediate states.
6544 In an interactive call, this function prompts for FILENAME and
6545 NEWNAME in the minibuffer; also, it requests confirmation if
6546 NEWNAME already exists.
6548 -- Command: copy-file filename newname &optional ok-if-already-exists
6550 This command copies the file FILENAME to NEWNAME. An error is
6551 signaled if FILENAME does not exist.
6553 If TIME is non-`nil', then this functions gives the new file the
6554 same last-modified time that the old one has. (This works on only
6555 some operating systems.)
6557 In an interactive call, this function prompts for FILENAME and
6558 NEWNAME in the minibuffer; also, it requests confirmation if
6559 NEWNAME already exists.
6561 -- Command: delete-file filename
6562 This command deletes the file FILENAME, like the shell command `rm
6563 FILENAME'. If the file has multiple names, it continues to exist
6564 under the other names.
6566 A suitable kind of `file-error' error is signaled if the file does
6567 not exist, or is not deletable. (On Unix, a file is deletable if
6568 its directory is writable.)
6570 See also `delete-directory' in *Note Create/Delete Dirs::.
6572 -- Command: make-symbolic-link filename newname &optional
6573 ok-if-already-exists
6574 This command makes a symbolic link to FILENAME, named NEWNAME.
6575 This is like the shell command `ln -s FILENAME NEWNAME'.
6577 In an interactive call, this function prompts for FILENAME and
6578 NEWNAME in the minibuffer; also, it requests confirmation if
6579 NEWNAME already exists.
6581 -- Function: set-file-modes filename mode
6582 This function sets mode bits of FILENAME to MODE (which must be an
6583 integer). Only the low 12 bits of MODE are used.
6585 -- Function: set-default-file-modes mode
6586 This function sets the default file protection for new files
6587 created by XEmacs and its subprocesses. Every file created with
6588 XEmacs initially has this protection. On Unix, the default
6589 protection is the bitwise complement of the "umask" value.
6591 The argument MODE must be an integer. Only the low 9 bits of MODE
6594 Saving a modified version of an existing file does not count as
6595 creating the file; it does not change the file's mode, and does
6596 not use the default file protection.
6598 -- Function: default-file-modes
6599 This function returns the current default protection value.
6601 On MS-DOS, there is no such thing as an "executable" file mode bit.
6602 So Emacs considers a file executable if its name ends in `.com', `.bat'
6603 or `.exe'. This is reflected in the values returned by `file-modes'
6604 and `file-attributes'.
6607 File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
6612 Files are generally referred to by their names, in XEmacs as elsewhere.
6613 File names in XEmacs are represented as strings. The functions that
6614 operate on a file all expect a file name argument.
6616 In addition to operating on files themselves, XEmacs Lisp programs
6617 often need to operate on the names; i.e., to take them apart and to use
6618 part of a name to construct related file names. This section describes
6619 how to manipulate file names.
6621 The functions in this section do not actually access files, so they
6622 can operate on file names that do not refer to an existing file or
6625 On MS-DOS, these functions understand MS-DOS file-name syntax as
6626 well as Unix syntax. This is so that all the standard Lisp libraries
6627 can specify file names in Unix syntax and work properly on all systems
6628 without change. Similarly for other operating systems.
6632 * File Name Components:: The directory part of a file name, and the rest.
6633 * Directory Names:: A directory's name as a directory
6634 is different from its name as a file.
6635 * Relative File Names:: Some file names are relative to a current directory.
6636 * File Name Expansion:: Converting relative file names to absolute ones.
6637 * Unique File Names:: Generating names for temporary files.
6638 * File Name Completion:: Finding the completions for a given file name.
6639 * User Name Completion:: Finding the completions for a given user name.
6642 File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
6644 35.8.1 File Name Components
6645 ---------------------------
6647 The operating system groups files into directories. To specify a file,
6648 you must specify the directory and the file's name within that
6649 directory. Therefore, XEmacs considers a file name as having two main
6650 parts: the "directory name" part, and the "nondirectory" part (or "file
6651 name within the directory"). Either part may be empty. Concatenating
6652 these two parts reproduces the original file name.
6654 On Unix, the directory part is everything up to and including the
6655 last slash; the nondirectory part is the rest.
6657 For some purposes, the nondirectory part is further subdivided into
6658 the name proper and the "version number". On Unix, only backup files
6659 have version numbers in their names.
6661 -- Function: file-name-directory filename
6662 This function returns the directory part of FILENAME (or `nil' if
6663 FILENAME does not include a directory part). On Unix, the
6664 function returns a string ending in a slash.
6666 (file-name-directory "lewis/foo") ; Unix example
6668 (file-name-directory "foo") ; Unix example
6671 -- Function: file-name-nondirectory filename
6672 This function returns the nondirectory part of FILENAME.
6674 (file-name-nondirectory "lewis/foo")
6676 (file-name-nondirectory "foo")
6679 -- Function: file-name-sans-versions filename &optional
6681 This function returns FILENAME without any file version numbers,
6682 backup version numbers, or trailing tildes.
6684 If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
6685 version numbers, only true file version numbers.
6687 (file-name-sans-versions "~rms/foo.~1~")
6689 (file-name-sans-versions "~rms/foo~")
6691 (file-name-sans-versions "~rms/foo")
6694 -- Function: file-name-sans-extension filename
6695 This function returns FILENAME minus its "extension," if any. The
6696 extension, in a file name, is the part that starts with the last
6697 `.' in the last name component. For example,
6699 (file-name-sans-extension "foo.lose.c")
6701 (file-name-sans-extension "big.hack/foo")
6705 File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
6707 35.8.2 Directory Names
6708 ----------------------
6710 A "directory name" is the name of a directory. A directory is a kind
6711 of file, and it has a file name, which is related to the directory name
6712 but not identical to it. (This is not quite the same as the usual Unix
6713 terminology.) These two different names for the same entity are
6714 related by a syntactic transformation. On Unix, this is simple: a
6715 directory name ends in a slash, whereas the directory's name as a file
6718 The difference between a directory name and its name as a file is
6719 subtle but crucial. When an XEmacs variable or function argument is
6720 described as being a directory name, a file name of a directory is not
6723 The following two functions convert between directory names and file
6724 names. They do nothing special with environment variable substitutions
6725 such as `$HOME', and the constructs `~', and `..'.
6727 -- Function: file-name-as-directory filename
6728 This function returns a string representing FILENAME in a form
6729 that the operating system will interpret as the name of a
6730 directory. In Unix, this means appending a slash to the string.
6732 (file-name-as-directory "~rms/lewis")
6735 -- Function: directory-file-name dirname
6736 This function returns a string representing DIRNAME in a form that
6737 the operating system will interpret as the name of a file. On
6738 Unix, this means removing a final slash from the string.
6740 (directory-file-name "~lewis/")
6743 Directory name abbreviations are useful for directories that are
6744 normally accessed through symbolic links. Sometimes the users recognize
6745 primarily the link's name as "the name" of the directory, and find it
6746 annoying to see the directory's "real" name. If you define the link
6747 name as an abbreviation for the "real" name, XEmacs shows users the
6748 abbreviation instead.
6750 If you wish to convert a directory name to its abbreviation, use this
6753 -- Function: abbreviate-file-name filename &optional hack-homedir
6754 This function applies abbreviations from `directory-abbrev-alist'
6755 to its argument, and substitutes `~' for the user's home directory.
6757 If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
6758 the user's home directory.
6761 -- Variable: directory-abbrev-alist
6762 The variable `directory-abbrev-alist' contains an alist of
6763 abbreviations to use for file directories. Each element has the
6764 form `(FROM . TO)', and says to replace FROM with TO when it
6765 appears in a directory name. The FROM string is actually a
6766 regular expression; it should always start with `^'. The function
6767 `abbreviate-file-name' performs these substitutions.
6769 You can set this variable in `site-init.el' to describe the
6770 abbreviations appropriate for your site.
6772 Here's an example, from a system on which file system `/home/fsf'
6773 and so on are normally accessed through symbolic links named `/fsf'
6776 (("^/home/fsf" . "/fsf")
6777 ("^/home/gp" . "/gp")
6778 ("^/home/gd" . "/gd"))
6781 File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
6783 35.8.3 Absolute and Relative File Names
6784 ---------------------------------------
6786 All the directories in the file system form a tree starting at the root
6787 directory. A file name can specify all the directory names starting
6788 from the root of the tree; then it is called an "absolute" file name.
6789 Or it can specify the position of the file in the tree relative to a
6790 default directory; then it is called a "relative" file name. On Unix,
6791 an absolute file name starts with a slash or a tilde (`~'), and a
6792 relative one does not.
6794 -- Function: file-name-absolute-p filename
6795 This function returns `t' if file FILENAME is an absolute file
6796 name, `nil' otherwise.
6798 (file-name-absolute-p "~rms/foo")
6800 (file-name-absolute-p "rms/foo")
6802 (file-name-absolute-p "/user/rms/foo")
6806 File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
6808 35.8.4 Functions that Expand Filenames
6809 --------------------------------------
6811 "Expansion" of a file name means converting a relative file name to an
6812 absolute one. Since this is done relative to a default directory, you
6813 must specify the default directory name as well as the file name to be
6814 expanded. Expansion also simplifies file names by eliminating
6815 redundancies such as `./' and `NAME/../'.
6817 -- Function: expand-file-name filename &optional directory
6818 This function converts FILENAME to an absolute file name. If
6819 DIRECTORY is supplied, it is the directory to start with if
6820 FILENAME is relative. (The value of DIRECTORY should itself be an
6821 absolute directory name; it may start with `~'.) Otherwise, the
6822 current buffer's value of `default-directory' is used. For
6825 (expand-file-name "foo")
6826 => "/xcssun/users/rms/lewis/foo"
6827 (expand-file-name "../foo")
6828 => "/xcssun/users/rms/foo"
6829 (expand-file-name "foo" "/usr/spool/")
6831 (expand-file-name "$HOME/foo")
6832 => "/xcssun/users/rms/lewis/$HOME/foo"
6834 Filenames containing `.' or `..' are simplified to their canonical
6837 (expand-file-name "bar/../foo")
6838 => "/xcssun/users/rms/lewis/foo"
6840 `~/' at the beginning is expanded into the user's home directory.
6841 A `/' or `~' following a `/'.
6843 Note that `expand-file-name' does _not_ expand environment
6844 variables; only `substitute-in-file-name' does that.
6846 -- Function: file-relative-name filename &optional directory
6847 This function does the inverse of expansion--it tries to return a
6848 relative name that is equivalent to FILENAME when interpreted
6849 relative to DIRECTORY.
6851 If DIRECTORY is `nil' or omitted, the value of `default-directory'
6854 (file-relative-name "/foo/bar" "/foo/")
6856 (file-relative-name "/foo/bar" "/hack/")
6859 -- Variable: default-directory
6860 The value of this buffer-local variable is the default directory
6861 for the current buffer. It should be an absolute directory name;
6862 it may start with `~'. This variable is local in every buffer.
6864 `expand-file-name' uses the default directory when its second
6867 On Unix systems, the value is always a string ending with a slash.
6870 => "/user/lewis/manual/"
6872 -- Function: substitute-in-file-name filename
6873 This function replaces environment variable references in FILENAME
6874 with the environment variable values. Following standard Unix
6875 shell syntax, `$' is the prefix to substitute an environment
6878 The environment variable name is the series of alphanumeric
6879 characters (including underscores) that follow the `$'. If the
6880 character following the `$' is a `{', then the variable name is
6881 everything up to the matching `}'.
6883 Here we assume that the environment variable `HOME', which holds
6884 the user's home directory name, has value `/xcssun/users/rms'.
6886 (substitute-in-file-name "$HOME/foo")
6887 => "/xcssun/users/rms/foo"
6889 After substitution, a `/' or `~' following a `/' is taken to be
6890 the start of an absolute file name that overrides what precedes
6891 it, so everything before that `/' or `~' is deleted. For example:
6893 (substitute-in-file-name "bar/~/foo")
6895 (substitute-in-file-name "/usr/local/$HOME/foo")
6896 => "/xcssun/users/rms/foo"
6899 File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
6901 35.8.5 Generating Unique File Names
6902 -----------------------------------
6904 Some programs need to write temporary files. Here is the usual way to
6905 construct a name for such a file:
6907 (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
6909 Here we use `(temp-directory)' to specify a directory for temporary
6910 files--under Unix, it will normally evaluate to `"/tmp/"'. The job of
6911 `make-temp-name' is to prevent two different users or two different
6912 processes from trying to use the same name.
6914 -- Function: temp-directory
6915 This function returns the name of the directory to use for
6916 temporary files. Under Unix, this will be the value of `TMPDIR',
6917 defaulting to `/tmp'. On Windows, this will be obtained from the
6918 `TEMP' or `TMP' environment variables, defaulting to `/'.
6920 Note that the `temp-directory' function does not exist under FSF
6923 -- Function: make-temp-name prefix
6924 This function generates a temporary file name starting with
6925 PREFIX. The Emacs process number forms part of the result, so
6926 there is no danger of generating a name being used by another
6929 (make-temp-name "/tmp/foo")
6932 In addition, this function makes an attempt to choose a name that
6933 does not specify an existing file. To make this work, PREFIX
6934 should be an absolute file name.
6936 To avoid confusion, each Lisp application should preferably use a
6937 unique PREFIX to `make-temp-name'.
6940 File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
6942 35.8.6 File Name Completion
6943 ---------------------------
6945 This section describes low-level subroutines for completing a file
6946 name. For other completion functions, see *Note Completion::.
6948 -- Function: file-name-all-completions partial-filename directory
6949 This function returns a list of all possible completions for files
6950 whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
6951 The order of the completions is the order of the files in the
6952 directory, which is unpredictable and conveys no useful
6955 The argument PARTIAL-FILENAME must be a file name containing no
6956 directory part and no slash. The current buffer's default
6957 directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
6959 File names which end with any member of
6960 `completion-ignored-extensions' are not considered as possible
6961 completions for PARTIAL-FILENAME unless there is no other possible
6962 completion. `completion-ignored-extensions' is not applied to the
6963 names of directories.
6965 In the following example, suppose that the current default
6966 directory, `~rms/lewis', has five files whose names begin with `f':
6967 `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
6969 (file-name-all-completions "f" "")
6970 => ("foo" "file~" "file.c.~2~"
6971 "file.c.~1~" "file.c")
6973 (file-name-all-completions "fo" "")
6976 -- Function: file-name-completion partial-filename directory
6977 This function completes the file name PARTIAL-FILENAME in directory
6978 DIRECTORY. It returns the longest prefix common to all file names
6979 in directory DIRECTORY that start with PARTIAL-FILENAME.
6981 If only one match exists and PARTIAL-FILENAME matches it exactly,
6982 the function returns `t'. The function returns `nil' if directory
6983 DIRECTORY contains no name starting with PARTIAL-FILENAME.
6985 File names which end with any member of
6986 `completion-ignored-extensions' are not considered as possible
6987 completions for PARTIAL-FILENAME unless there is no other possible
6988 completion. `completion-ignored-extensions' is not applied to the
6989 names of directories.
6991 In the following example, suppose that the current default
6992 directory has five files whose names begin with `f': `foo',
6993 `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
6995 (file-name-completion "fi" "")
6998 (file-name-completion "file.c.~1" "")
7001 (file-name-completion "file.c.~1~" "")
7004 (file-name-completion "file.c.~3" "")
7007 -- User Option: completion-ignored-extensions
7008 `file-name-completion' usually ignores file names that end in any
7009 string in this list. It does not ignore them when all the possible
7010 completions end in one of these suffixes or when a buffer showing
7011 all possible completions is displayed.
7013 A typical value might look like this:
7015 completion-ignored-extensions
7016 => (".o" ".elc" "~" ".dvi")