1 This is ../info/lispref.info, produced by makeinfo version 4.6 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 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 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 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
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::.
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
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
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
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
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
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
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 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 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 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 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
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 prefix
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 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
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 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
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
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 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 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 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
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 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
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 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 cap-up
2923 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 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 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
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 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
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 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 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
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
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
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 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.
3726 The least specialized major mode is called "Fundamental mode". This
3727 mode has no mode-specific definitions or variable settings, so each
3728 XEmacs command behaves in its default manner, and each option is in its
3729 default state. All other major modes redefine various keys and options.
3730 For example, Lisp Interaction mode provides special key bindings for
3731 <LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
3734 When you need to write several editing commands to help you perform a
3735 specialized editing task, creating a new major mode is usually a good
3736 idea. In practice, writing a major mode is easy (in contrast to
3737 writing a minor mode, which is often difficult).
3739 If the new mode is similar to an old one, it is often unwise to
3740 modify the old one to serve two purposes, since it may become harder to
3741 use and maintain. Instead, copy and rename an existing major mode
3742 definition and alter the copy--or define a "derived mode" (*note
3743 Derived Modes::). For example, Rmail Edit mode, which is in
3744 `emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
3745 mode except that it provides three additional commands. Its definition
3746 is distinct from that of Text mode, but was derived from it.
3748 Rmail Edit mode is an example of a case where one piece of text is
3749 put temporarily into a different major mode so it can be edited in a
3750 different way (with ordinary XEmacs commands rather than Rmail). In
3751 such cases, the temporary major mode usually has a command to switch
3752 back to the buffer's usual mode (Rmail mode, in this case). You might
3753 be tempted to present the temporary redefinitions inside a recursive
3754 edit and restore the usual ones when the user exits; but this is a bad
3755 idea because it constrains the user's options when it is done in more
3756 than one buffer: recursive edits must be exited most-recently-entered
3757 first. Using alternative major modes avoids this limitation. *Note
3758 Recursive Editing::.
3760 The standard XEmacs Lisp library directory contains the code for
3761 several major modes, in files including `text-mode.el', `texinfo.el',
3762 `lisp-mode.el', `c-mode.el', and `rmail.el'. You can look at these
3763 libraries to see how modes are written. Text mode is perhaps the
3764 simplest major mode aside from Fundamental mode. Rmail mode is a
3765 complicated and specialized mode.
3769 * Major Mode Conventions:: Coding conventions for keymaps, etc.
3770 * Example Major Modes:: Text mode and Lisp modes.
3771 * Auto Major Mode:: How XEmacs chooses the major mode automatically.
3772 * Mode Help:: Finding out how to use a mode.
3773 * Derived Modes:: Defining a new major mode based on another major
3777 File: lispref.info, Node: Major Mode Conventions, Next: Example Major Modes, Up: Major Modes
3779 Major Mode Conventions
3780 ----------------------
3782 The code for existing major modes follows various coding conventions,
3783 including conventions for local keymap and syntax table initialization,
3784 global names, and hooks. Please follow these conventions when you
3785 define a new major mode:
3787 * Define a command whose name ends in `-mode', with no arguments,
3788 that switches to the new mode in the current buffer. This command
3789 should set up the keymap, syntax table, and local variables in an
3790 existing buffer without changing the buffer's text.
3792 * Write a documentation string for this command that describes the
3793 special commands available in this mode. `C-h m'
3794 (`describe-mode') in your mode will display this string.
3796 The documentation string may include the special documentation
3797 substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
3798 enable the documentation to adapt automatically to the user's own
3799 key bindings. *Note Keys in Documentation::.
3801 * The major mode command should start by calling
3802 `kill-all-local-variables'. This is what gets rid of the local
3803 variables of the major mode previously in effect.
3805 * The major mode command should set the variable `major-mode' to the
3806 major mode command symbol. This is how `describe-mode' discovers
3807 which documentation to print.
3809 * The major mode command should set the variable `mode-name' to the
3810 "pretty" name of the mode, as a string. This appears in the mode
3813 * Since all global names are in the same name space, all the global
3814 variables, constants, and functions that are part of the mode
3815 should have names that start with the major mode name (or with an
3816 abbreviation of it if the name is long). *Note Style Tips::.
3818 * The major mode should usually have its own keymap, which is used
3819 as the local keymap in all buffers in that mode. The major mode
3820 function should call `use-local-map' to install this local map.
3821 *Note Active Keymaps::, for more information.
3823 This keymap should be kept in a global variable named
3824 `MODENAME-mode-map'. Normally the library that defines the mode
3827 * The mode may have its own syntax table or may share one with other
3828 related modes. If it has its own syntax table, it should store
3829 this in a variable named `MODENAME-mode-syntax-table'. *Note
3832 * The mode may have its own abbrev table or may share one with other
3833 related modes. If it has its own abbrev table, it should store
3834 this in a variable named `MODENAME-mode-abbrev-table'. *Note
3837 * Use `defvar' to set mode-related variables, so that they are not
3838 reinitialized if they already have a value. (Such reinitialization
3839 could discard customizations made by the user.)
3841 * To make a buffer-local binding for an Emacs customization
3842 variable, use `make-local-variable' in the major mode command, not
3843 `make-variable-buffer-local'. The latter function would make the
3844 variable local to every buffer in which it is subsequently set,
3845 which would affect buffers that do not use this mode. It is
3846 undesirable for a mode to have such global effects. *Note
3847 Buffer-Local Variables::.
3849 It's ok to use `make-variable-buffer-local', if you wish, for a
3850 variable used only within a single Lisp package.
3852 * Each major mode should have a "mode hook" named
3853 `MODENAME-mode-hook'. The major mode command should run that
3854 hook, with `run-hooks', as the very last thing it does. *Note
3857 * The major mode command may also run the hooks of some more basic
3858 modes. For example, `indented-text-mode' runs `text-mode-hook' as
3859 well as `indented-text-mode-hook'. It may run these other hooks
3860 immediately before the mode's own hook (that is, after everything
3861 else), or it may run them earlier.
3863 * If something special should be done if the user switches a buffer
3864 from this mode to any other major mode, the mode can set a local
3865 value for `change-major-mode-hook'.
3867 * If this mode is appropriate only for specially-prepared text, then
3868 the major mode command symbol should have a property named
3869 `mode-class' with value `special', put on as follows:
3871 (put 'funny-mode 'mode-class 'special)
3873 This tells XEmacs that new buffers created while the current
3874 buffer has Funny mode should not inherit Funny mode. Modes such
3875 as Dired, Rmail, and Buffer List use this feature.
3877 * If you want to make the new mode the default for files with certain
3878 recognizable names, add an element to `auto-mode-alist' to select
3879 the mode for those file names. If you define the mode command to
3880 autoload, you should add this element in the same file that calls
3881 `autoload'. Otherwise, it is sufficient to add the element in the
3882 file that contains the mode definition. *Note Auto Major Mode::.
3884 * In the documentation, you should provide a sample `autoload' form
3885 and an example of how to add to `auto-mode-alist', that users can
3886 include in their `.emacs' files.
3888 * The top-level forms in the file defining the mode should be
3889 written so that they may be evaluated more than once without
3890 adverse consequences. Even if you never load the file more than
3891 once, someone else will.
3893 - Variable: change-major-mode-hook
3894 This normal hook is run by `kill-all-local-variables' before it
3895 does anything else. This gives major modes a way to arrange for
3896 something special to be done if the user switches to a different
3897 major mode. For best results, make this variable buffer-local, so
3898 that it will disappear after doing its job and will not interfere
3899 with the subsequent major mode. *Note Hooks::.
3902 File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes
3907 Text mode is perhaps the simplest mode besides Fundamental mode. Here
3908 are excerpts from `text-mode.el' that illustrate many of the
3909 conventions listed above:
3911 ;; Create mode-specific tables.
3912 (defvar text-mode-syntax-table nil
3913 "Syntax table used while in text mode.")
3915 (if text-mode-syntax-table
3916 () ; Do not change the table if it is already set up.
3917 (setq text-mode-syntax-table (make-syntax-table))
3918 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
3919 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
3920 (modify-syntax-entry ?' "w " text-mode-syntax-table))
3922 (defvar text-mode-abbrev-table nil
3923 "Abbrev table used while in text mode.")
3924 (define-abbrev-table 'text-mode-abbrev-table ())
3926 (defvar text-mode-map nil) ; Create a mode-specific keymap.
3929 () ; Do not change the keymap if it is already set up.
3930 (setq text-mode-map (make-sparse-keymap))
3931 (define-key text-mode-map "\t" 'tab-to-tab-stop)
3932 (define-key text-mode-map "\es" 'center-line)
3933 (define-key text-mode-map "\eS" 'center-paragraph))
3935 Here is the complete major mode function definition for Text mode:
3938 "Major mode for editing text intended for humans to read.
3939 Special commands: \\{text-mode-map}
3940 Turning on text-mode runs the hook `text-mode-hook'."
3942 (kill-all-local-variables)
3943 (use-local-map text-mode-map) ; This provides the local keymap.
3944 (setq mode-name "Text") ; This name goes into the modeline.
3945 (setq major-mode 'text-mode) ; This is how `describe-mode'
3946 ; finds the doc string to print.
3947 (setq local-abbrev-table text-mode-abbrev-table)
3948 (set-syntax-table text-mode-syntax-table)
3949 (run-hooks 'text-mode-hook)) ; Finally, this permits the user to
3950 ; customize the mode with a hook.
3952 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
3953 Interaction mode) have more features than Text mode and the code is
3954 correspondingly more complicated. Here are excerpts from
3955 `lisp-mode.el' that illustrate how these modes are written.
3957 ;; Create mode-specific table variables.
3958 (defvar lisp-mode-syntax-table nil "")
3959 (defvar emacs-lisp-mode-syntax-table nil "")
3960 (defvar lisp-mode-abbrev-table nil "")
3962 (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
3963 ; if it is already set.
3965 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
3967 ;; Set syntax of chars up to 0 to class of chars that are
3968 ;; part of symbol names but not words.
3969 ;; (The number 0 is `48' in the ASCII character set.)
3971 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
3974 ;; Set the syntax for other characters.
3975 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
3976 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
3978 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
3979 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
3981 ;; Create an abbrev table for lisp-mode.
3982 (define-abbrev-table 'lisp-mode-abbrev-table ())
3984 Much code is shared among the three Lisp modes. The following
3985 function sets various variables; it is called by each of the major Lisp
3988 (defun lisp-mode-variables (lisp-syntax)
3989 ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
3990 ;; and `t' in the other two Lisp modes.
3992 (if (not lisp-mode-syntax-table)
3993 ;; The Emacs Lisp mode syntax table always exists, but
3994 ;; the Lisp Mode syntax table is created the first time a
3995 ;; mode that needs it is called. This is to save space.
3996 (progn (setq lisp-mode-syntax-table
3997 (copy-syntax-table emacs-lisp-mode-syntax-table))
3998 ;; Change some entries for Lisp mode.
3999 (modify-syntax-entry ?\| "\" "
4000 lisp-mode-syntax-table)
4001 (modify-syntax-entry ?\[ "_ "
4002 lisp-mode-syntax-table)
4003 (modify-syntax-entry ?\] "_ "
4004 lisp-mode-syntax-table)))
4005 (set-syntax-table lisp-mode-syntax-table)))
4006 (setq local-abbrev-table lisp-mode-abbrev-table)
4009 Functions such as `forward-paragraph' use the value of the
4010 `paragraph-start' variable. Since Lisp code is different from ordinary
4011 text, the `paragraph-start' variable needs to be set specially to
4012 handle Lisp. Also, comments are indented in a special fashion in Lisp
4013 and the Lisp modes need their own mode-specific
4014 `comment-indent-function'. The code to set these variables is the rest
4015 of `lisp-mode-variables'.
4017 (make-local-variable 'paragraph-start)
4018 ;; Having `^' is not clean, but `page-delimiter'
4019 ;; has them too, and removing those is a pain.
4020 (setq paragraph-start (concat "^$\\|" page-delimiter))
4022 (make-local-variable 'comment-indent-function)
4023 (setq comment-indent-function 'lisp-comment-indent))
4025 Each of the different Lisp modes has a slightly different keymap.
4026 For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
4027 Lisp modes do not. However, all Lisp modes have some commands in
4028 common. The following function adds these common commands to a given
4031 (defun lisp-mode-commands (map)
4032 (define-key map "\e\C-q" 'indent-sexp)
4033 (define-key map "\177" 'backward-delete-char-untabify)
4034 (define-key map "\t" 'lisp-indent-line))
4036 Here is an example of using `lisp-mode-commands' to initialize a
4037 keymap, as part of the code for Emacs Lisp mode. First we declare a
4038 variable with `defvar' to hold the mode-specific keymap. When this
4039 `defvar' executes, it sets the variable to `nil' if it was void. Then
4040 we set up the keymap if the variable is `nil'.
4042 This code avoids changing the keymap or the variable if it is already
4043 set up. This lets the user customize the keymap.
4045 (defvar emacs-lisp-mode-map () "")
4046 (if emacs-lisp-mode-map
4048 (setq emacs-lisp-mode-map (make-sparse-keymap))
4049 (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
4050 (lisp-mode-commands emacs-lisp-mode-map))
4052 Finally, here is the complete major mode function definition for
4055 (defun emacs-lisp-mode ()
4056 "Major mode for editing Lisp code to run in XEmacs.
4058 Delete converts tabs to spaces as it moves back.
4059 Blank lines separate paragraphs. Semicolons start comments.
4060 \\{emacs-lisp-mode-map}
4061 Entry to this mode runs the hook `emacs-lisp-mode-hook'."
4063 (kill-all-local-variables)
4064 (use-local-map emacs-lisp-mode-map) ; This provides the local keymap.
4065 (set-syntax-table emacs-lisp-mode-syntax-table)
4066 (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode'
4067 ; finds out what to describe.
4068 (setq mode-name "Emacs-Lisp") ; This goes into the modeline.
4069 (lisp-mode-variables nil) ; This defines various variables.
4070 (run-hooks 'emacs-lisp-mode-hook)) ; This permits the user to use a
4071 ; hook to customize the mode.
4074 File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes
4076 How XEmacs Chooses a Major Mode
4077 -------------------------------
4079 Based on information in the file name or in the file itself, XEmacs
4080 automatically selects a major mode for the new buffer when a file is
4083 - Command: fundamental-mode
4084 Fundamental mode is a major mode that is not specialized for
4085 anything in particular. Other major modes are defined in effect
4086 by comparison with this one--their definitions say what to change,
4087 starting from Fundamental mode. The `fundamental-mode' function
4088 does _not_ run any hooks; you're not supposed to customize it.
4089 (If you want Emacs to behave differently in Fundamental mode,
4090 change the _global_ state of Emacs.)
4092 - Command: normal-mode &optional find-file
4093 This function establishes the proper major mode and local variable
4094 bindings for the current buffer. First it calls `set-auto-mode',
4095 then it runs `hack-local-variables' to parse, and bind or evaluate
4096 as appropriate, any local variables.
4098 If the FIND-FILE argument to `normal-mode' is non-`nil',
4099 `normal-mode' assumes that the `find-file' function is calling it.
4100 In this case, it may process a local variables list at the end of
4101 the file and in the `-*-' line. The variable
4102 `enable-local-variables' controls whether to do so.
4104 If you run `normal-mode' interactively, the argument FIND-FILE is
4105 normally `nil'. In this case, `normal-mode' unconditionally
4106 processes any local variables list. *Note Local Variables in
4107 Files: (xemacs)File variables, for the syntax of the local
4108 variables section of a file.
4110 `normal-mode' uses `condition-case' around the call to the major
4111 mode function, so errors are caught and reported as a `File mode
4112 specification error', followed by the original error message.
4114 - User Option: enable-local-variables
4115 This variable controls processing of local variables lists in files
4116 being visited. A value of `t' means process the local variables
4117 lists unconditionally; `nil' means ignore them; anything else means
4118 ask the user what to do for each file. The default value is `t'.
4120 - Variable: ignored-local-variables
4121 This variable holds a list of variables that should not be set by
4122 a local variables list. Any value specified for one of these
4123 variables is ignored.
4125 In addition to this list, any variable whose name has a non-`nil'
4126 `risky-local-variable' property is also ignored.
4128 - User Option: enable-local-eval
4129 This variable controls processing of `Eval:' in local variables
4130 lists in files being visited. A value of `t' means process them
4131 unconditionally; `nil' means ignore them; anything else means ask
4132 the user what to do for each file. The default value is `maybe'.
4134 - Function: set-auto-mode
4135 This function selects the major mode that is appropriate for the
4136 current buffer. It may base its decision on the value of the `-*-'
4137 line, on the visited file name (using `auto-mode-alist'), or on the
4138 value of a local variable. However, this function does not look
4139 for the `mode:' local variable near the end of a file; the
4140 `hack-local-variables' function does that. *Note How Major Modes
4141 are Chosen: (xemacs)Choosing Modes.
4143 - User Option: default-major-mode
4144 This variable holds the default major mode for new buffers. The
4145 standard value is `fundamental-mode'.
4147 If the value of `default-major-mode' is `nil', XEmacs uses the
4148 (previously) current buffer's major mode for the major mode of a
4149 new buffer. However, if the major mode symbol has a `mode-class'
4150 property with value `special', then it is not used for new buffers;
4151 Fundamental mode is used instead. The modes that have this
4152 property are those such as Dired and Rmail that are useful only
4153 with text that has been specially prepared.
4155 - Function: set-buffer-major-mode buffer
4156 This function sets the major mode of BUFFER to the value of
4157 `default-major-mode'. If that variable is `nil', it uses the
4158 current buffer's major mode (if that is suitable).
4160 The low-level primitives for creating buffers do not use this
4161 function, but medium-level commands such as `switch-to-buffer' and
4162 `find-file-noselect' use it whenever they create buffers.
4164 - Variable: initial-major-mode
4165 The value of this variable determines the major mode of the initial
4166 `*scratch*' buffer. The value should be a symbol that is a major
4167 mode command name. The default value is `lisp-interaction-mode'.
4169 - Variable: auto-mode-alist
4170 This variable contains an association list of file name patterns
4171 (regular expressions; *note Regular Expressions::) and
4172 corresponding major mode functions. Usually, the file name
4173 patterns test for suffixes, such as `.el' and `.c', but this need
4174 not be the case. An ordinary element of the alist looks like
4175 `(REGEXP . MODE-FUNCTION)'.
4179 (("^/tmp/fol/" . text-mode)
4180 ("\\.texinfo\\'" . texinfo-mode)
4181 ("\\.texi\\'" . texinfo-mode)
4182 ("\\.el\\'" . emacs-lisp-mode)
4183 ("\\.c\\'" . c-mode)
4184 ("\\.h\\'" . c-mode)
4187 When you visit a file whose expanded file name (*note File Name
4188 Expansion::) matches a REGEXP, `set-auto-mode' calls the
4189 corresponding MODE-FUNCTION. This feature enables XEmacs to select
4190 the proper major mode for most files.
4192 If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
4193 t)', then after calling FUNCTION, XEmacs searches
4194 `auto-mode-alist' again for a match against the portion of the file
4195 name that did not match before.
4197 This match-again feature is useful for uncompression packages: an
4198 entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
4199 and then put the uncompressed file in the proper mode according to
4200 the name sans `.gz'.
4202 Here is an example of how to prepend several pattern pairs to
4203 `auto-mode-alist'. (You might use this sort of expression in your
4206 (setq auto-mode-alist
4208 ;; File name starts with a dot.
4209 '(("/\\.[^/]*\\'" . fundamental-mode)
4210 ;; File name has no dot.
4211 ("[^\\./]*\\'" . fundamental-mode)
4212 ;; File name ends in `.C'.
4213 ("\\.C\\'" . c++-mode))
4216 - Variable: interpreter-mode-alist
4217 This variable specifies major modes to use for scripts that
4218 specify a command interpreter in an `#!' line. Its value is a
4219 list of elements of the form `(INTERPRETER . MODE)'; for example,
4220 `("perl" . perl-mode)' is one element present by default. The
4221 element says to use mode MODE if the file specifies INTERPRETER.
4223 This variable is applicable only when the `auto-mode-alist' does
4224 not indicate which major mode to use.
4226 - Function: hack-local-variables &optional force
4227 This function parses, and binds or evaluates as appropriate, any
4228 local variables for the current buffer.
4230 The handling of `enable-local-variables' documented for
4231 `normal-mode' actually takes place here. The argument FORCE
4232 usually comes from the argument FIND-FILE given to `normal-mode'.
4235 File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes
4237 Getting Help about a Major Mode
4238 -------------------------------
4240 The `describe-mode' function is used to provide information about major
4241 modes. It is normally called with `C-h m'. The `describe-mode'
4242 function uses the value of `major-mode', which is why every major mode
4243 function needs to set the `major-mode' variable.
4245 - Command: describe-mode
4246 This function displays the documentation of the current major mode.
4248 The `describe-mode' function calls the `documentation' function
4249 using the value of `major-mode' as an argument. Thus, it displays
4250 the documentation string of the major mode function. (*Note
4251 Accessing Documentation::.)
4253 - Variable: major-mode
4254 This variable holds the symbol for the current buffer's major mode.
4255 This symbol should have a function definition that is the command
4256 to switch to that major mode. The `describe-mode' function uses
4257 the documentation string of the function as the documentation of
4261 File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes
4263 Defining Derived Modes
4264 ----------------------
4266 It's often useful to define a new major mode in terms of an existing
4267 one. An easy way to do this is to use `define-derived-mode'.
4269 - Macro: define-derived-mode variant parent name docstring body...
4270 This construct defines VARIANT as a major mode command, using NAME
4271 as the string form of the mode name.
4273 The new command VARIANT is defined to call the function PARENT,
4274 then override certain aspects of that parent mode:
4276 * The new mode has its own keymap, named `VARIANT-map'.
4277 `define-derived-mode' initializes this map to inherit from
4278 `PARENT-map', if it is not already set.
4280 * The new mode has its own syntax table, kept in the variable
4281 `VARIANT-syntax-table'. `define-derived-mode' initializes
4282 this variable by copying `PARENT-syntax-table', if it is not
4285 * The new mode has its own abbrev table, kept in the variable
4286 `VARIANT-abbrev-table'. `define-derived-mode' initializes
4287 this variable by copying `PARENT-abbrev-table', if it is not
4290 * The new mode has its own mode hook, `VARIANT-hook', which it
4291 runs in standard fashion as the very last thing that it does.
4292 (The new mode also runs the mode hook of PARENT as part of
4295 In addition, you can specify how to override other aspects of
4296 PARENT with BODY. The command VARIANT evaluates the forms in BODY
4297 after setting up all its usual overrides, just before running
4300 The argument DOCSTRING specifies the documentation string for the
4301 new mode. If you omit DOCSTRING, `define-derived-mode' generates
4302 a documentation string.
4304 Here is a hypothetical example:
4306 (define-derived-mode hypertext-mode
4307 text-mode "Hypertext"
4308 "Major mode for hypertext.
4309 \\{hypertext-mode-map}"
4310 (setq case-fold-search nil))
4312 (define-key hypertext-mode-map
4313 [down-mouse-3] 'do-hyper-link)
4316 File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes
4321 A "minor mode" provides features that users may enable or disable
4322 independently of the choice of major mode. Minor modes can be enabled
4323 individually or in combination. Minor modes would be better named
4324 "Generally available, optional feature modes" except that such a name is
4327 A minor mode is not usually a modification of single major mode. For
4328 example, Auto Fill mode may be used in any major mode that permits text
4329 insertion. To be general, a minor mode must be effectively independent
4330 of the things major modes do.
4332 A minor mode is often much more difficult to implement than a major
4333 mode. One reason is that you should be able to activate and deactivate
4334 minor modes in any order. A minor mode should be able to have its
4335 desired effect regardless of the major mode and regardless of the other
4336 minor modes in effect.
4338 Often the biggest problem in implementing a minor mode is finding a
4339 way to insert the necessary hook into the rest of XEmacs. Minor mode
4340 keymaps make this easier than it used to be.
4344 * Minor Mode Conventions:: Tips for writing a minor mode.
4345 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
4348 File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes
4350 Conventions for Writing Minor Modes
4351 -----------------------------------
4353 There are conventions for writing minor modes just as there are for
4354 major modes. Several of the major mode conventions apply to minor
4355 modes as well: those regarding the name of the mode initialization
4356 function, the names of global symbols, and the use of keymaps and other
4359 In addition, there are several conventions that are specific to
4362 * Make a variable whose name ends in `-mode' to represent the minor
4363 mode. Its value should enable or disable the mode (`nil' to
4364 disable; anything else to enable.) We call this the "mode
4367 This variable is used in conjunction with the `minor-mode-alist' to
4368 display the minor mode name in the modeline. It can also enable
4369 or disable a minor mode keymap. Individual commands or hooks can
4370 also check the variable's value.
4372 If you want the minor mode to be enabled separately in each buffer,
4373 make the variable buffer-local.
4375 * Define a command whose name is the same as the mode variable. Its
4376 job is to enable and disable the mode by setting the variable.
4378 The command should accept one optional argument. If the argument
4379 is `nil', it should toggle the mode (turn it on if it is off, and
4380 off if it is on). Otherwise, it should turn the mode on if the
4381 argument is a positive integer, a symbol other than `nil' or `-',
4382 or a list whose CAR is such an integer or symbol; it should turn
4383 the mode off otherwise.
4385 Here is an example taken from the definition of
4386 `transient-mark-mode'. It shows the use of `transient-mark-mode'
4387 as a variable that enables or disables the mode's behavior, and
4388 also shows the proper way to toggle, enable or disable the minor
4389 mode based on the raw prefix argument value.
4391 (setq transient-mark-mode
4392 (if (null arg) (not transient-mark-mode)
4393 (> (prefix-numeric-value arg) 0)))
4395 * Add an element to `minor-mode-alist' for each minor mode (*note
4396 Modeline Variables::). This element should be a list of the
4399 (MODE-VARIABLE STRING)
4401 Here MODE-VARIABLE is the variable that controls enabling of the
4402 minor mode, and STRING is a short string, starting with a space,
4403 to represent the mode in the modeline. These strings must be
4404 short so that there is room for several of them at once.
4406 When you add an element to `minor-mode-alist', use `assq' to check
4407 for an existing element, to avoid duplication. For example:
4409 (or (assq 'leif-mode minor-mode-alist)
4410 (setq minor-mode-alist
4411 (cons '(leif-mode " Leif") minor-mode-alist)))
4414 File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes
4416 Keymaps and Minor Modes
4417 -----------------------
4419 Each minor mode can have its own keymap, which is active when the mode
4420 is enabled. To set up a keymap for a minor mode, add an element to the
4421 alist `minor-mode-map-alist'. *Note Active Keymaps::.
4423 One use of minor mode keymaps is to modify the behavior of certain
4424 self-inserting characters so that they do something else as well as
4425 self-insert. In general, this is the only way to do that, since the
4426 facilities for customizing `self-insert-command' are limited to special
4427 cases (designed for abbrevs and Auto Fill mode). (Do not try
4428 substituting your own definition of `self-insert-command' for the
4429 standard one. The editor command loop handles this function specially.)
4432 File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes
4437 Each Emacs window (aside from minibuffer windows) includes a modeline,
4438 which displays status information about the buffer displayed in the
4439 window. The modeline contains information about the buffer, such as its
4440 name, associated file, depth of recursive editing, and the major and
4443 This section describes how the contents of the modeline are
4444 controlled. It is in the chapter on modes because much of the
4445 information displayed in the modeline relates to the enabled major and
4448 `modeline-format' is a buffer-local variable that holds a template
4449 used to display the modeline of the current buffer. All windows for
4450 the same buffer use the same `modeline-format' and their modelines
4451 appear the same (except for scrolling percentages and line numbers).
4453 The modeline of a window is normally updated whenever a different
4454 buffer is shown in the window, or when the buffer's modified-status
4455 changes from `nil' to `t' or vice-versa. If you modify any of the
4456 variables referenced by `modeline-format' (*note Modeline Variables::),
4457 you may want to force an update of the modeline so as to display the
4460 - Function: redraw-modeline &optional all
4461 Force redisplay of the current buffer's modeline. If ALL is
4462 non-`nil', then force redisplay of all modelines.
4464 The modeline is usually displayed in inverse video. This is
4465 controlled using the `modeline' face. *Note Faces::.
4469 * Modeline Data:: The data structure that controls the modeline.
4470 * Modeline Variables:: Variables used in that data structure.
4471 * %-Constructs:: Putting information into a modeline.
4474 File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format
4476 The Data Structure of the Modeline
4477 ----------------------------------
4479 The modeline contents are controlled by a data structure of lists,
4480 strings, symbols, and numbers kept in the buffer-local variable
4481 `modeline-format'. The data structure is called a "modeline
4482 construct", and it is built in recursive fashion out of simpler modeline
4483 constructs. The same data structure is used for constructing frame
4484 titles (*note Frame Titles::).
4486 - Variable: modeline-format
4487 The value of this variable is a modeline construct with overall
4488 responsibility for the modeline format. The value of this variable
4489 controls which other variables are used to form the modeline text,
4490 and where they appear.
4492 A modeline construct may be as simple as a fixed string of text, but
4493 it usually specifies how to use other variables to construct the text.
4494 Many of these variables are themselves defined to have modeline
4495 constructs as their values.
4497 The default value of `modeline-format' incorporates the values of
4498 variables such as `mode-name' and `minor-mode-alist'. Because of this,
4499 very few modes need to alter `modeline-format'. For most purposes, it
4500 is sufficient to alter the variables referenced by `modeline-format'.
4502 A modeline construct may be a string, symbol, glyph, generic
4503 specifier, list or cons cell.
4506 A string as a modeline construct is displayed verbatim in the mode
4507 line except for "`%'-constructs". Decimal digits after the `%'
4508 specify the field width for space filling on the right (i.e., the
4509 data is left justified). *Note %-Constructs::.
4512 A symbol as a modeline construct stands for its value. The value
4513 of SYMBOL is processed as a modeline construct, in place of
4514 SYMBOL. However, the symbols `t' and `nil' are ignored; so is any
4515 symbol whose value is void.
4517 There is one exception: if the value of SYMBOL is a string, it is
4518 displayed verbatim: the `%'-constructs are not recognized.
4521 A glyph is displayed as is.
4524 A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands
4525 for its instance. The instance of GENERIC-SPECIFIER is computed
4526 in the current window using the equivalent of `specifier-instance'
4527 and the value is processed.
4529 `(STRING REST...) or (LIST REST...)'
4530 A list whose first element is a string or list means to process
4531 all the elements recursively and concatenate the results. This is
4532 the most common form of mode line construct.
4534 `(SYMBOL THEN ELSE)'
4535 A list whose first element is a symbol is a conditional. Its
4536 meaning depends on the value of SYMBOL. If the value is non-`nil',
4537 the second element, THEN, is processed recursively as a modeline
4538 element. But if the value of SYMBOL is `nil', the third element,
4539 ELSE, is processed recursively. You may omit ELSE; then the mode
4540 line element displays nothing if the value of SYMBOL is `nil'.
4543 A list whose first element is an integer specifies truncation or
4544 padding of the results of REST. The remaining elements REST are
4545 processed recursively as modeline constructs and concatenated
4546 together. Then the result is space filled (if WIDTH is positive)
4547 or truncated (to -WIDTH columns, if WIDTH is negative) on the
4550 For example, the usual way to show what percentage of a buffer is
4551 above the top of the window is to use a list like this: `(-3
4555 A list whose car is an extent means the cdr of the list is
4556 processed normally but the results are displayed using the face of
4557 the extent, and mouse clicks over this section are processed using
4558 the keymap of the extent. (In addition, if the extent has a
4559 help-echo property, that string will be echoed when the mouse
4560 moves over this section.) If extents are nested, all keymaps are
4561 properly consulted when processing mouse clicks, but multiple
4562 faces are not correctly merged (only the first face is used), and
4563 lists of faces are not correctly handled.
4565 If you do alter `modeline-format' itself, the new value should use
4566 the same variables that appear in the default value (*note Modeline
4567 Variables::), rather than duplicating their contents or displaying the
4568 information in another fashion. This way, customizations made by the
4569 user or by Lisp programs (such as `display-time' and major modes) via
4570 changes to those variables remain effective.
4572 Here is an example of a `modeline-format' that might be useful for
4573 `shell-mode', since it contains the hostname and default directory.
4575 (setq modeline-format
4579 (getenv "HOST") ; One element is not constant.
4590 '(line-number-mode "L%l--")
4595 File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format
4597 Variables Used in the Modeline
4598 ------------------------------
4600 This section describes variables incorporated by the standard value of
4601 `modeline-format' into the text of the mode line. There is nothing
4602 inherently special about these variables; any other variables could
4603 have the same effects on the modeline if `modeline-format' were changed
4606 - Variable: modeline-modified
4607 This variable holds the value of the modeline construct that
4608 displays whether the current buffer is modified.
4610 The default value of `modeline-modified' is `("--%1*%1+-")'. This
4611 means that the modeline displays `--**-' if the buffer is
4612 modified, `-----' if the buffer is not modified, `--%%-' if the
4613 buffer is read only, and `--%*--' if the buffer is read only and
4616 Changing this variable does not force an update of the modeline.
4618 - Variable: modeline-buffer-identification
4619 This variable identifies the buffer being displayed in the window.
4620 Its default value is `("%F: %17b")', which means that it usually
4621 displays `Emacs:' followed by seventeen characters of the buffer
4622 name. (In a terminal frame, it displays the frame name instead of
4623 `Emacs'; this has the effect of showing the frame number.) You may
4624 want to change this in modes such as Rmail that do not behave like
4627 - Variable: global-mode-string
4628 This variable holds a modeline spec that appears in the mode line
4629 by default, just after the buffer name. The command `display-time'
4630 sets `global-mode-string' to refer to the variable
4631 `display-time-string', which holds a string containing the time and
4634 The `%M' construct substitutes the value of `global-mode-string',
4635 but this is obsolete, since the variable is included directly in
4638 - Variable: mode-name
4639 This buffer-local variable holds the "pretty" name of the current
4640 buffer's major mode. Each major mode should set this variable so
4641 that the mode name will appear in the modeline.
4643 - Variable: minor-mode-alist
4644 This variable holds an association list whose elements specify how
4645 the modeline should indicate that a minor mode is active. Each
4646 element of the `minor-mode-alist' should be a two-element list:
4648 (MINOR-MODE-VARIABLE MODELINE-STRING)
4650 More generally, MODELINE-STRING can be any mode line spec. It
4651 appears in the mode line when the value of MINOR-MODE-VARIABLE is
4652 non-`nil', and not otherwise. These strings should begin with
4653 spaces so that they don't run together. Conventionally, the
4654 MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
4655 value when that minor mode is activated.
4657 The default value of `minor-mode-alist' is:
4660 => ((vc-mode vc-mode)
4661 (abbrev-mode " Abbrev")
4662 (overwrite-mode overwrite-mode)
4663 (auto-fill-function " Fill")
4664 (defining-kbd-macro " Def")
4665 (isearch-mode isearch-mode))
4667 `minor-mode-alist' is not buffer-local. The variables mentioned
4668 in the alist should be buffer-local if the minor mode can be
4669 enabled separately in each buffer.
4671 - Variable: modeline-process
4672 This buffer-local variable contains the modeline information on
4673 process status in modes used for communicating with subprocesses.
4674 It is displayed immediately following the major mode name, with no
4675 intervening space. For example, its value in the `*shell*' buffer
4676 is `(": %s")', which allows the shell to display its status along
4677 with the major mode as: `(Shell: run)'. Normally this variable is
4680 - Variable: default-modeline-format
4681 This variable holds the default `modeline-format' for buffers that
4682 do not override it. This is the same as `(default-value
4685 The default value of `default-modeline-format' is:
4689 modeline-buffer-identification
4698 (line-number-mode "L%l--")
4703 The variable `vc-mode', local in each buffer, records whether the
4704 buffer's visited file is maintained with version control, and, if
4705 so, which kind. Its value is `nil' for no version control, or a
4706 string that appears in the mode line.
4709 File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format
4711 `%'-Constructs in the ModeLine
4712 ------------------------------
4714 The following table lists the recognized `%'-constructs and what they
4715 mean. In any construct except `%%', you can add a decimal integer
4716 after the `%' to specify how many characters to display.
4719 The current buffer name, obtained with the `buffer-name' function.
4720 *Note Buffer Names::.
4723 The visited file name, obtained with the `buffer-file-name'
4724 function. *Note Buffer File Name::.
4727 The name of the selected frame.
4730 The current column number of point.
4733 The current line number of point.
4736 `%' if the buffer is read only (see `buffer-read-only');
4737 `*' if the buffer is modified (see `buffer-modified-p');
4738 `-' otherwise. *Note Buffer Modification::.
4741 `*' if the buffer is modified (see `buffer-modified-p');
4742 `%' if the buffer is read only (see `buffer-read-only');
4743 `-' otherwise. This differs from `%*' only for a modified
4744 read-only buffer. *Note Buffer Modification::.
4747 `*' if the buffer is modified, and `-' otherwise.
4750 The status of the subprocess belonging to the current buffer,
4751 obtained with `process-status'. *Note Process Information::.
4754 The current line number.
4757 The name of the selected frame; this is only meaningful under the
4758 X Window System. *Note Frame Name::.
4761 Whether the visited file is a text file or a binary file. (This
4762 is a meaningful distinction only on certain operating systems.)
4765 The percentage of the buffer text above the *top* of window, or
4766 `Top', `Bottom' or `All'.
4769 The percentage of the buffer text that is above the *bottom* of
4770 the window (which includes the text visible in the window, as well
4771 as the text above the top), plus `Top' if the top of the buffer is
4772 visible on screen; or `Bottom' or `All'.
4775 `Narrow' when narrowing is in effect; nothing otherwise (see
4776 `narrow-to-region' in *Note Narrowing::).
4779 Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.
4782 An indication of the depth of recursive editing levels (not
4783 counting minibuffer levels): one `[' for each editing level.
4784 *Note Recursive Editing::.
4787 One `]' for each recursive editing level (not counting minibuffer
4791 The character `%'--this is how to include a literal `%' in a
4792 string in which `%'-constructs are allowed.
4795 Dashes sufficient to fill the remainder of the modeline.
4797 The following two `%'-constructs are still supported, but they are
4798 obsolete, since you can get the same results with the variables
4799 `mode-name' and `global-mode-string'.
4802 The value of `mode-name'.
4805 The value of `global-mode-string'. Currently, only `display-time'
4806 modifies the value of `global-mode-string'.
4809 File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
4814 A "hook" is a variable where you can store a function or functions to
4815 be called on a particular occasion by an existing program. XEmacs
4816 provides hooks for the sake of customization. Most often, hooks are set
4817 up in the `.emacs' file, but Lisp programs can set them also. *Note
4818 Standard Hooks::, for a list of standard hook variables.
4820 Most of the hooks in XEmacs are "normal hooks". These variables
4821 contain lists of functions to be called with no arguments. The reason
4822 most hooks are normal hooks is so that you can use them in a uniform
4823 way. You can usually tell when a hook is a normal hook, because its
4824 name ends in `-hook'.
4826 The recommended way to add a hook function to a normal hook is by
4827 calling `add-hook' (see below). The hook functions may be any of the
4828 valid kinds of functions that `funcall' accepts (*note What Is a
4829 Function::). Most normal hook variables are initially void; `add-hook'
4830 knows how to deal with this.
4832 As for abnormal hooks, those whose names end in `-function' have a
4833 value that is a single function. Those whose names end in `-hooks'
4834 have a value that is a list of functions. Any hook that is abnormal is
4835 abnormal because a normal hook won't do the job; either the functions
4836 are called with arguments, or their values are meaningful. The name
4837 shows you that the hook is abnormal and that you should look at its
4838 documentation string to see how to use it properly.
4840 Major mode functions are supposed to run a hook called the "mode
4841 hook" as the last step of initialization. This makes it easy for a user
4842 to customize the behavior of the mode, by overriding the local variable
4843 assignments already made by the mode. But hooks are used in other
4844 contexts too. For example, the hook `suspend-hook' runs just before
4845 XEmacs suspends itself (*note Suspending XEmacs::).
4847 Here's an expression that uses a mode hook to turn on Auto Fill mode
4848 when in Lisp Interaction mode:
4850 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
4852 The next example shows how to use a hook to customize the way XEmacs
4853 formats C code. (People often have strong personal preferences for one
4854 format or another.) Here the hook function is an anonymous lambda
4857 (add-hook 'c-mode-hook
4858 (function (lambda ()
4859 (setq c-indent-level 4
4862 c-continued-statement-indent 0
4864 comment-column 40))))
4866 (setq c++-mode-hook c-mode-hook)
4868 The final example shows how the appearance of the modeline can be
4869 modified for a particular class of buffers only.
4871 (add-hook 'text-mode-hook
4872 (function (lambda ()
4873 (setq modeline-format
4889 At the appropriate time, XEmacs uses the `run-hooks' function to run
4890 particular hooks. This function calls the hook functions you have
4891 added with `add-hooks'.
4893 - Function: run-hooks &rest hookvar
4894 This function takes one or more hook variable names as arguments,
4895 and runs each hook in turn. Each HOOKVAR argument should be a
4896 symbol that is a hook variable. These arguments are processed in
4897 the order specified.
4899 If a hook variable has a non-`nil' value, that value may be a
4900 function or a list of functions. If the value is a function
4901 (either a lambda expression or a symbol with a function
4902 definition), it is called. If it is a list, the elements are
4903 called, in order. The hook functions are called with no arguments.
4905 For example, here's how `emacs-lisp-mode' runs its mode hook:
4907 (run-hooks 'emacs-lisp-mode-hook)
4909 - Function: add-hook hook function &optional append local
4910 This function is the handy way to add function FUNCTION to hook
4911 variable HOOK. The argument FUNCTION may be any valid Lisp
4912 function with the proper number of arguments. For example,
4914 (add-hook 'text-mode-hook 'my-text-hook-function)
4916 adds `my-text-hook-function' to the hook called `text-mode-hook'.
4918 You can use `add-hook' for abnormal hooks as well as for normal
4921 It is best to design your hook functions so that the order in
4922 which they are executed does not matter. Any dependence on the
4923 order is "asking for trouble." However, the order is predictable:
4924 normally, FUNCTION goes at the front of the hook list, so it will
4925 be executed first (barring another `add-hook' call).
4927 If the optional argument APPEND is non-`nil', the new hook
4928 function goes at the end of the hook list and will be executed
4931 If LOCAL is non-`nil', that says to make the new hook function
4932 local to the current buffer. Before you can do this, you must
4933 make the hook itself buffer-local by calling `make-local-hook'
4934 (*not* `make-local-variable'). If the hook itself is not
4935 buffer-local, then the value of LOCAL makes no difference--the
4936 hook function is always global.
4938 - Function: remove-hook hook function &optional local
4939 This function removes FUNCTION from the hook variable HOOK.
4941 If LOCAL is non-`nil', that says to remove FUNCTION from the local
4942 hook list instead of from the global hook list. If the hook
4943 itself is not buffer-local, then the value of LOCAL makes no
4946 - Function: make-local-hook hook
4947 This function makes the hook variable HOOK local to the current
4948 buffer. When a hook variable is local, it can have local and
4949 global hook functions, and `run-hooks' runs all of them.
4951 This function works by making `t' an element of the buffer-local
4952 value. That serves as a flag to use the hook functions in the
4953 default value of the hook variable as well as those in the local
4954 value. Since `run-hooks' understands this flag, `make-local-hook'
4955 works with all normal hooks. It works for only some non-normal
4956 hooks--those whose callers have been updated to understand this
4959 Do not use `make-local-variable' directly for hook variables; it is
4963 File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
4968 XEmacs Lisp has convenient on-line help facilities, most of which
4969 derive their information from the documentation strings associated with
4970 functions and variables. This chapter describes how to write good
4971 documentation strings for your Lisp programs, as well as how to write
4972 programs to access documentation.
4974 Note that the documentation strings for XEmacs are not the same thing
4975 as the XEmacs manual. Manuals have their own source files, written in
4976 the Texinfo language; documentation strings are specified in the
4977 definitions of the functions and variables they apply to. A collection
4978 of documentation strings is not sufficient as a manual because a good
4979 manual is not organized in that fashion; it is organized in terms of
4980 topics of discussion.
4984 * Documentation Basics:: Good style for doc strings.
4985 Where to put them. How XEmacs stores them.
4986 * Accessing Documentation:: How Lisp programs can access doc strings.
4987 * Keys in Documentation:: Substituting current key bindings.
4988 * Describing Characters:: Making printable descriptions of
4989 non-printing characters and key sequences.
4990 * Help Functions:: Subroutines used by XEmacs help facilities.
4991 * Obsoleteness:: Upgrading Lisp functionality over time.
4994 File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
4996 Documentation Basics
4997 ====================
4999 A documentation string is written using the Lisp syntax for strings,
5000 with double-quote characters surrounding the text of the string. This
5001 is because it really is a Lisp string object. The string serves as
5002 documentation when it is written in the proper place in the definition
5003 of a function or variable. In a function definition, the documentation
5004 string follows the argument list. In a variable definition, the
5005 documentation string follows the initial value of the variable.
5007 When you write a documentation string, make the first line a complete
5008 sentence (or two complete sentences) since some commands, such as
5009 `apropos', show only the first line of a multi-line documentation
5010 string. Also, you should not indent the second line of a documentation
5011 string, if you have one, because that looks odd when you use `C-h f'
5012 (`describe-function') or `C-h v' (`describe-variable'). *Note
5013 Documentation Tips::.
5015 Documentation strings may contain several special substrings, which
5016 stand for key bindings to be looked up in the current keymaps when the
5017 documentation is displayed. This allows documentation strings to refer
5018 to the keys for related commands and be accurate even when a user
5019 rearranges the key bindings. (*Note Accessing Documentation::.)
5021 Within the Lisp world, a documentation string is accessible through
5022 the function or variable that it describes:
5024 * The documentation for a function is stored in the function
5025 definition itself (*note Lambda Expressions::). The function
5026 `documentation' knows how to extract it.
5028 * The documentation for a variable is stored in the variable's
5029 property list under the property name `variable-documentation'.
5030 The function `documentation-property' knows how to extract it.
5032 To save space, the documentation for preloaded functions and
5033 variables (including primitive functions and autoloaded functions) is
5034 stored in the "internal doc file" `DOC'. The documentation for
5035 functions and variables loaded during the XEmacs session from
5036 byte-compiled files is stored in those very same byte-compiled files
5037 (*note Docs and Compilation::).
5039 XEmacs does not keep documentation strings in memory unless
5040 necessary. Instead, XEmacs maintains, for preloaded symbols, an
5041 integer offset into the internal doc file, and for symbols loaded from
5042 byte-compiled files, a list containing the filename of the
5043 byte-compiled file and an integer offset, in place of the documentation
5044 string. The functions `documentation' and `documentation-property' use
5045 that information to read the documentation from the appropriate file;
5046 this is transparent to the user.
5048 For information on the uses of documentation strings, see *Note
5051 The `emacs/lib-src' directory contains two utilities that you can
5052 use to print nice-looking hardcopy for the file
5053 `emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'.
5056 File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
5058 Access to Documentation Strings
5059 ===============================
5061 - Function: documentation-property symbol property &optional verbatim
5062 This function returns the documentation string that is recorded in
5063 SYMBOL's property list under property PROPERTY. It retrieves the
5064 text from a file if necessary, and runs `substitute-command-keys'
5065 to substitute actual key bindings. (This substitution is not done
5066 if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
5069 (documentation-property 'command-line-processed
5070 'variable-documentation)
5071 => "t once command line has been processed"
5072 (symbol-plist 'command-line-processed)
5073 => (variable-documentation 188902)
5075 - Function: documentation function &optional verbatim
5076 This function returns the documentation string of FUNCTION. It
5077 reads the text from a file if necessary. Then (unless VERBATIM is
5078 non-`nil') it calls `substitute-command-keys', to return a value
5079 containing the actual (current) key bindings.
5081 The function `documentation' signals a `void-function' error if
5082 FUNCTION has no function definition. However, it is ok if the
5083 function definition has no documentation string. In that case,
5084 `documentation' returns `nil'.
5086 Here is an example of using the two functions, `documentation' and
5087 `documentation-property', to display the documentation strings for
5088 several symbols in a `*Help*' buffer.
5090 (defun describe-symbols (pattern)
5091 "Describe the XEmacs Lisp symbols matching PATTERN.
5092 All symbols that have PATTERN in their name are described
5093 in the `*Help*' buffer."
5094 (interactive "sDescribe symbols matching: ")
5095 (let ((describe-func
5098 ;; Print description of symbol.
5099 (if (fboundp s) ; It is a function.
5101 (format "%s\t%s\n%s\n\n" s
5103 (let ((keys (where-is-internal s)))
5107 (mapconcat 'key-description
5111 (or (documentation s)
5112 "not documented"))))
5114 (if (boundp s) ; It is a variable.
5116 (format "%s\t%s\n%s\n\n" s
5117 (if (user-variable-p s)
5118 "Option " "Variable")
5119 (or (documentation-property
5120 s 'variable-documentation)
5121 "not documented")))))))
5124 ;; Build a list of symbols that match pattern.
5127 (if (string-match pattern (symbol-name sym))
5128 (setq sym-list (cons sym sym-list))))))
5130 ;; Display the data.
5131 (with-output-to-temp-buffer "*Help*"
5132 (mapcar describe-func (sort sym-list 'string<))
5133 (print-help-return-message))))
5135 The `describe-symbols' function works like `apropos', but provides
5138 (describe-symbols "goal")
5140 ---------- Buffer: *Help* ----------
5142 *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
5144 set-goal-column Command: C-x C-n
5145 Set the current horizontal position as a goal for C-n and C-p.
5146 Those commands will move to this position in the line moved to
5147 rather than trying to keep the same horizontal position.
5148 With a non-`nil' argument, clears out the goal column
5149 so that C-n and C-p resume vertical motion.
5150 The goal column is stored in the variable `goal-column'.
5152 temporary-goal-column Variable
5153 Current goal column for vertical motion.
5154 It is the column where point was
5155 at the start of current run of vertical motion commands.
5156 When the `track-eol' feature is doing its job, the value is 9999.
5157 ---------- Buffer: *Help* ----------
5159 - Function: Snarf-documentation filename
5160 This function is used only during XEmacs initialization, just
5161 before the runnable XEmacs is dumped. It finds the file offsets
5162 of the documentation strings stored in the file FILENAME, and
5163 records them in the in-core function definitions and variable
5164 property lists in place of the actual strings. *Note Building
5167 XEmacs finds the file FILENAME in the `lib-src' directory. When
5168 the dumped XEmacs is later executed, the same file is found in the
5169 directory `doc-directory'. The usual value for FILENAME is `DOC',
5170 but this can be changed by modifying the variable
5171 `internal-doc-file-name'.
5173 - Variable: internal-doc-file-name
5174 This variable holds the name of the file containing documentation
5175 strings of built-in symbols, usually `DOC'. The full pathname of
5176 the internal doc file is `(concat doc-directory
5177 internal-doc-file-name)'.
5179 - Variable: doc-directory
5180 This variable holds the name of the directory which contains the
5181 "internal doc file" that contains documentation strings for
5182 built-in and preloaded functions and variables.
5184 In most cases, this is the same as `exec-directory'. They may be
5185 different when you run XEmacs from the directory where you built
5186 it, without actually installing it. See `exec-directory' in *Note
5189 In older Emacs versions, `exec-directory' was used for this.
5191 - Variable: data-directory
5192 This variable holds the name of the directory in which XEmacs finds
5193 certain system independent documentation and text files that come
5194 with XEmacs. In older Emacs versions, `exec-directory' was used
5198 File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
5200 Substituting Key Bindings in Documentation
5201 ==========================================
5203 When documentation strings refer to key sequences, they should use the
5204 current, actual key bindings. They can do so using certain special text
5205 sequences described below. Accessing documentation strings in the usual
5206 way substitutes current key binding information for these special
5207 sequences. This works by calling `substitute-command-keys'. You can
5208 also call that function yourself.
5210 Here is a list of the special sequences and what they mean:
5213 stands for a key sequence that will invoke COMMAND, or `M-x
5214 COMMAND' if COMMAND has no key bindings.
5217 stands for a summary of the value of MAPVAR, which should be a
5218 keymap. The summary is made by `describe-bindings'.
5221 stands for no text itself. It is used for a side effect: it
5222 specifies MAPVAR as the keymap for any following `\[COMMAND]'
5223 sequences in this documentation string.
5226 quotes the following character and is discarded; this `\=\=' puts
5227 `\=' into the output, and `\=\[' puts `\[' into the output.
5229 *Please note:* Each `\' must be doubled when written in a string in
5232 - Function: substitute-command-keys string
5233 This function scans STRING for the above special sequences and
5234 replaces them by what they stand for, returning the result as a
5235 string. This permits display of documentation that refers
5236 accurately to the user's own customized key bindings.
5238 Here are examples of the special sequences:
5240 (substitute-command-keys
5241 "To abort recursive edit, type: \\[abort-recursive-edit]")
5242 => "To abort recursive edit, type: C-]"
5244 (substitute-command-keys
5245 "The keys that are defined for the minibuffer here are:
5246 \\{minibuffer-local-must-match-map}")
5247 => "The keys that are defined for the minibuffer here are:
5249 ? minibuffer-completion-help
5250 SPC minibuffer-complete-word
5251 TAB minibuffer-complete
5252 LFD minibuffer-complete-and-exit
5253 RET minibuffer-complete-and-exit
5254 C-g abort-recursive-edit
5257 (substitute-command-keys
5258 "To abort a recursive edit from the minibuffer, type\
5259 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
5260 => "To abort a recursive edit from the minibuffer, type C-g."
5262 (substitute-command-keys
5263 "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
5264 \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
5265 Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
5266 as the keymap for future \\=\\[COMMAND] substrings.
5267 \\=\\= quotes the following character and is discarded;
5268 thus, \\=\\=\\=\\= puts \\=\\= into the output,
5269 and \\=\\=\\=\\[ puts \\=\\[ into the output.")
5270 => "Substrings of the form \{MAPVAR} are replaced by summaries
5271 (made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
5272 Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
5273 as the keymap for future \[COMMAND] substrings.
5274 \= quotes the following character and is discarded;
5275 thus, \=\= puts \= into the output,
5276 and \=\[ puts \[ into the output."
5279 File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
5281 Describing Characters for Help Messages
5282 =======================================
5284 These functions convert events, key sequences or characters to textual
5285 descriptions. These descriptions are useful for including arbitrary
5286 text characters or key sequences in messages, because they convert
5287 non-printing and whitespace characters to sequences of printing
5288 characters. The description of a non-whitespace printing character is
5289 the character itself.
5291 - Function: key-description sequence
5292 This function returns a string containing the XEmacs standard
5293 notation for the input events in SEQUENCE. The argument SEQUENCE
5294 may be a string, vector or list. *Note Events::, for more
5295 information about valid events. See also the examples for
5296 `single-key-description', below.
5298 - Function: single-key-description key
5299 This function returns a string describing KEY in the standard
5300 XEmacs notation for keyboard input. A normal printing character
5301 appears as itself, but a control character turns into a string
5302 starting with `C-', a meta character turns into a string starting
5303 with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
5304 A symbol appears as the name of the symbol. An event that is a
5305 list appears as the name of the symbol in the CAR of the list.
5307 (single-key-description ?\C-x)
5309 (key-description "\C-x \M-y \n \t \r \f123")
5310 => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
5311 (single-key-description 'kp-next)
5313 (single-key-description '(shift button1))
5316 - Function: text-char-description character
5317 This function returns a string describing CHARACTER in the
5318 standard XEmacs notation for characters that appear in text--like
5319 `single-key-description', except that control characters are
5320 represented with a leading caret (which is how control characters
5321 in XEmacs buffers are usually displayed).
5323 (text-char-description ?\C-c)
5325 (text-char-description ?\M-m)
5327 (text-char-description ?\C-\M-m)
5331 File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
5336 XEmacs provides a variety of on-line help functions, all accessible to
5337 the user as subcommands of the prefix `C-h', or on some keyboards,
5338 `help'. For more information about them, see *Note Help: (emacs)Help.
5339 Here we describe some program-level interfaces to the same information.
5341 - Command: apropos regexp &optional do-all predicate
5342 This function finds all symbols whose names contain a match for the
5343 regular expression REGEXP, and returns a list of them (*note
5344 Regular Expressions::). It also displays the symbols in a buffer
5345 named `*Help*', each with a one-line description.
5347 If DO-ALL is non-`nil', then `apropos' also shows key bindings for
5348 the functions that are found.
5350 If PREDICATE is non-`nil', it should be a function to be called on
5351 each symbol that has matched REGEXP. Only symbols for which
5352 PREDICATE returns a non-`nil' value are listed or displayed.
5354 In the first of the following examples, `apropos' finds all the
5355 symbols with names containing `exec'. In the second example, it
5356 finds and returns only those symbols that are also commands. (We
5357 don't show the output that results in the `*Help*' buffer.)
5360 => (Buffer-menu-execute command-execute exec-directory
5361 exec-path execute-extended-command execute-kbd-macro
5362 executing-kbd-macro executing-macro)
5364 (apropos "exec" nil 'commandp)
5365 => (Buffer-menu-execute execute-extended-command)
5367 `apropos' is used by various user-level commands, such as `C-h a'
5368 (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
5369 (`command-apropos'), which does an apropos over only those
5370 functions which are user commands. `command-apropos' calls
5371 `apropos', specifying a PREDICATE to restrict the output to
5372 symbols that are commands. The call to `apropos' looks like this:
5374 (apropos string t 'commandp)
5376 - Variable: help-map
5377 The value of this variable is a local keymap for characters
5378 following the Help key, `C-h'.
5380 - Prefix Command: help-command
5381 This symbol is not a function; its function definition is actually
5382 the keymap known as `help-map'. It is defined in `help.el' as
5385 (define-key global-map "\C-h" 'help-command)
5386 (fset 'help-command help-map)
5388 - Function: print-help-return-message &optional function
5389 This function builds a string that explains how to restore the
5390 previous state of the windows after a help command. After
5391 building the message, it applies FUNCTION to it if FUNCTION is
5392 non-`nil'. Otherwise it calls `message' to display it in the echo
5395 This function expects to be called inside a
5396 `with-output-to-temp-buffer' special form, and expects
5397 `standard-output' to have the value bound by that special form.
5398 For an example of its use, see the long example in *Note Accessing
5401 - Variable: help-char
5402 The value of this variable is the help character--the character
5403 that XEmacs recognizes as meaning Help. By default, it is the
5404 character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this
5405 character, if `help-form' is non-`nil' Lisp expression, it
5406 evaluates that expression, and displays the result in a window if
5409 `help-char' can be a character or a key description such as `help'
5412 Usually the value of `help-form''s value is `nil'. Then the help
5413 character has no special meaning at the level of command input, and
5414 it becomes part of a key sequence in the normal way. The standard
5415 key binding of `C-h' is a prefix key for several general-purpose
5418 The help character is special after prefix keys, too. If it has no
5419 binding as a subcommand of the prefix key, it runs
5420 `describe-prefix-bindings', which displays a list of all the
5421 subcommands of the prefix key.
5423 - Variable: help-form
5424 If this variable is non-`nil', its value is a form to evaluate
5425 whenever the character `help-char' is read. If evaluating the form
5426 produces a string, that string is displayed.
5428 A command that calls `next-command-event' or `next-event' probably
5429 should bind `help-form' to a non-`nil' expression while it does
5430 input. (The exception is when `C-h' is meaningful input.)
5431 Evaluating this expression should result in a string that explains
5432 what the input is for and how to enter it properly.
5434 Entry to the minibuffer binds this variable to the value of
5435 `minibuffer-help-form' (*note Minibuffer Misc::).
5437 - Variable: prefix-help-command
5438 This variable holds a function to print help for a prefix
5439 character. The function is called when the user types a prefix
5440 key followed by the help character, and the help character has no
5441 binding after that prefix. The variable's default value is
5442 `describe-prefix-bindings'.
5444 - Command: describe-prefix-bindings
5445 This function calls `describe-bindings' to display a list of all
5446 the subcommands of the prefix key of the most recent key sequence.
5447 The prefix described consists of all but the last event of that
5448 key sequence. (The last event is, presumably, the help character.)
5450 The following two functions are found in the library `helper'. They
5451 are for modes that want to provide help without relinquishing control,
5452 such as the "electric" modes. You must load that library with
5453 `(require 'helper)' in order to use them. Their names begin with
5454 `Helper' to distinguish them from the ordinary help functions.
5456 - Command: Helper-describe-bindings
5457 This command pops up a window displaying a help buffer containing a
5458 listing of all of the key bindings from both the local and global
5459 keymaps. It works by calling `describe-bindings'.
5461 - Command: Helper-help
5462 This command provides help for the current mode. It prompts the
5463 user in the minibuffer with the message `Help (Type ? for further
5464 options)', and then provides assistance in finding out what the key
5465 bindings are, and what the mode is intended for. It returns `nil'.
5467 This can be customized by changing the map `Helper-help-map'.
5470 File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
5475 As you add functionality to a package, you may at times want to replace
5476 an older function with a new one. To preserve compatibility with
5477 existing code, the older function needs to still exist; but users of
5478 that function should be told to use the newer one instead. XEmacs Lisp
5479 lets you mark a function or variable as "obsolete", and indicate what
5480 should be used instead.
5482 - Command: make-obsolete function new
5483 This function indicates that FUNCTION is an obsolete function, and
5484 the function NEW should be used instead. The byte compiler will
5485 issue a warning to this effect when it encounters a usage of the
5486 older function, and the help system will also note this in the
5487 function's documentation. NEW can also be a string (if there is
5488 not a single function with the same functionality any more), and
5489 should be a descriptive statement, such as "use FOO or BAR
5490 instead" or "this function is unnecessary".
5492 - Command: make-obsolete-variable variable new
5493 This is like `make-obsolete' but is for variables instead of
5496 - Function: define-obsolete-function-alias oldfun newfun
5497 This function combines `make-obsolete' and `define-function',
5498 declaring OLDFUN to be an obsolete variant of NEWFUN and defining
5499 OLDFUN as an alias for NEWFUN.
5501 - Function: define-obsolete-variable-alias oldvar newvar
5502 This is like `define-obsolete-function-alias' but for variables.
5504 Note that you should not normally put obsoleteness information
5505 explicitly in a function or variable's doc string. The obsoleteness
5506 information that you specify using the above functions will be displayed
5507 whenever the doc string is displayed, and by adding it explicitly the
5508 result is redundancy.
5510 Also, if an obsolete function is substantially the same as a newer
5511 one but is not actually an alias, you should consider omitting the doc
5512 string entirely (use a null string `""' as the doc string). That way,
5513 the user is told about the obsoleteness and is forced to look at the
5514 documentation of the new function, making it more likely that he will
5515 use the new function.
5517 - Function: function-obsoleteness-doc function
5518 If FUNCTION is obsolete, this function returns a string describing
5519 this. This is the message that is printed out during byte
5520 compilation or in the function's documentation. If FUNCTION is
5521 not obsolete, `nil' is returned.
5523 - Function: variable-obsoleteness-doc variable
5524 This is like `function-obsoleteness-doc' but for variables.
5526 The obsoleteness information is stored internally by putting a
5527 property `byte-obsolete-info' (for functions) or
5528 `byte-obsolete-variable' (for variables) on the symbol that specifies
5529 the obsolete function or variable. For more information, see the
5530 implementation of `make-obsolete' and `make-obsolete-variable' in
5531 `lisp/bytecomp/bytecomp-runtime.el'.
5534 File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
5539 In XEmacs, you can find, create, view, save, and otherwise work with
5540 files and file directories. This chapter describes most of the
5541 file-related functions of XEmacs Lisp, but a few others are described in
5542 *Note Buffers::, and those related to backups and auto-saving are
5543 described in *Note Backups and Auto-Saving::.
5545 Many of the file functions take one or more arguments that are file
5546 names. A file name is actually a string. Most of these functions
5547 expand file name arguments using `expand-file-name', so that `~' is
5548 handled correctly, as are relative file names (including `../'). These
5549 functions don't recognize environment variable substitutions such as
5550 `$HOME'. *Note File Name Expansion::.
5554 * Visiting Files:: Reading files into Emacs buffers for editing.
5555 * Saving Buffers:: Writing changed buffers back into files.
5556 * Reading from Files:: Reading files into buffers without visiting.
5557 * Writing to Files:: Writing new files from parts of buffers.
5558 * File Locks:: Locking and unlocking files, to prevent
5559 simultaneous editing by two people.
5560 * Information about Files:: Testing existence, accessibility, size of files.
5561 * Changing File Attributes:: Renaming files, changing protection, etc.
5562 * File Names:: Decomposing and expanding file names.
5563 * Contents of Directories:: Getting a list of the files in a directory.
5564 * Create/Delete Dirs:: Creating and Deleting Directories.
5565 * Magic File Names:: Defining "magic" special handling
5566 for certain file names.
5567 * Partial Files:: Treating a section of a buffer as a file.
5568 * Format Conversion:: Conversion to and from various file formats.
5569 * Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
5572 File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
5577 Visiting a file means reading a file into a buffer. Once this is done,
5578 we say that the buffer is "visiting" that file, and call the file "the
5579 visited file" of the buffer.
5581 A file and a buffer are two different things. A file is information
5582 recorded permanently in the computer (unless you delete it). A buffer,
5583 on the other hand, is information inside of XEmacs that will vanish at
5584 the end of the editing session (or when you kill the buffer). Usually,
5585 a buffer contains information that you have copied from a file; then we
5586 say the buffer is visiting that file. The copy in the buffer is what
5587 you modify with editing commands. Such changes to the buffer do not
5588 change the file; therefore, to make the changes permanent, you must
5589 "save" the buffer, which means copying the altered buffer contents back
5592 In spite of the distinction between files and buffers, people often
5593 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
5594 "I am editing a file," rather than, "I am editing a buffer that I will
5595 soon save as a file of the same name." Humans do not usually need to
5596 make the distinction explicit. When dealing with a computer program,
5597 however, it is good to keep the distinction in mind.
5601 * Visiting Functions:: The usual interface functions for visiting.
5602 * Subroutines of Visiting:: Lower-level subroutines that they use.
5605 File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
5607 Functions for Visiting Files
5608 ----------------------------
5610 This section describes the functions normally used to visit files. For
5611 historical reasons, these functions have names starting with `find-'
5612 rather than `visit-'. *Note Buffer File Name::, for functions and
5613 variables that access the visited file name of a buffer or that find an
5614 existing buffer by its visited file name.
5616 In a Lisp program, if you want to look at the contents of a file but
5617 not alter it, the fastest way is to use `insert-file-contents' in a
5618 temporary buffer. Visiting the file is not necessary and takes longer.
5619 *Note Reading from Files::.
5621 - Command: find-file filename
5622 This command selects a buffer visiting the file FILENAME, using an
5623 existing buffer if there is one, and otherwise creating a new
5624 buffer and reading the file into it. It also returns that buffer.
5626 The body of the `find-file' function is very simple and looks like
5629 (switch-to-buffer (find-file-noselect filename))
5631 (See `switch-to-buffer' in *Note Displaying Buffers::.)
5633 When `find-file' is called interactively, it prompts for FILENAME
5636 - Function: find-file-noselect filename &optional nowarn
5637 This function is the guts of all the file-visiting functions. It
5638 finds or creates a buffer visiting the file FILENAME, and returns
5639 it. It uses an existing buffer if there is one, and otherwise
5640 creates a new buffer and reads the file into it. You may make the
5641 buffer current or display it in a window if you wish, but this
5642 function does not do so.
5644 When `find-file-noselect' uses an existing buffer, it first
5645 verifies that the file has not changed since it was last visited or
5646 saved in that buffer. If the file has changed, then this function
5647 asks the user whether to reread the changed file. If the user says
5648 `yes', any changes previously made in the buffer are lost.
5650 If `find-file-noselect' needs to create a buffer, and there is no
5651 file named FILENAME, it displays the message `New file' in the
5652 echo area, and leaves the buffer empty.
5654 If NOWARN is non-`nil', various warnings that XEmacs normally
5655 gives (e.g. if another buffer is already visiting FILENAME but
5656 FILENAME has been removed from disk since that buffer was created)
5659 The `find-file-noselect' function calls `after-find-file' after
5660 reading the file (*note Subroutines of Visiting::). That function
5661 sets the buffer major mode, parses local variables, warns the user
5662 if there exists an auto-save file more recent than the file just
5663 visited, and finishes by running the functions in
5666 The `find-file-noselect' function returns the buffer that is
5667 visiting the file FILENAME.
5669 (find-file-noselect "/etc/fstab")
5672 - Command: find-file-other-window filename
5673 This command selects a buffer visiting the file FILENAME, but does
5674 so in a window other than the selected window. It may use another
5675 existing window or split a window; see *Note Displaying Buffers::.
5677 When this command is called interactively, it prompts for FILENAME.
5679 - Command: find-file-read-only filename
5680 This command selects a buffer visiting the file FILENAME, like
5681 `find-file', but it marks the buffer as read-only. *Note Read
5682 Only Buffers::, for related functions and variables.
5684 When this command is called interactively, it prompts for FILENAME.
5686 - Command: view-file filename &optional other-window-p
5687 This command visits FILENAME in View mode, and displays it in a
5688 recursive edit, returning to the previous buffer when done. View
5689 mode is a mode that allows you to skim rapidly through the file
5690 but does not let you modify it. Entering View mode runs the
5691 normal hook `view-mode-hook'. *Note Hooks::.
5693 When `view-file' is called interactively, it prompts for FILENAME.
5695 With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in
5698 - Variable: find-file-hooks
5699 The value of this variable is a list of functions to be called
5700 after a file is visited. The file's local-variables specification
5701 (if any) will have been processed before the hooks are run. The
5702 buffer visiting the file is current when the hook functions are
5705 This variable works just like a normal hook, but we think that
5706 renaming it would not be advisable.
5708 - Variable: find-file-not-found-hooks
5709 The value of this variable is a list of functions to be called when
5710 `find-file' or `find-file-noselect' is passed a nonexistent file
5711 name. `find-file-noselect' calls these functions as soon as it
5712 detects a nonexistent file. It calls them in the order of the
5713 list, until one of them returns non-`nil'. `buffer-file-name' is
5716 This is not a normal hook because the values of the functions are
5717 used and they may not all be called.
5720 File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
5722 Subroutines of Visiting
5723 -----------------------
5725 The `find-file-noselect' function uses the `create-file-buffer' and
5726 `after-find-file' functions as subroutines. Sometimes it is useful to
5729 - Function: create-file-buffer filename
5730 This function creates a suitably named buffer for visiting
5731 FILENAME, and returns it. It uses FILENAME (sans directory) as
5732 the name if that name is free; otherwise, it appends a string such
5733 as `<2>' to get an unused name. See also *Note Creating Buffers::.
5735 *Please note:* `create-file-buffer' does _not_ associate the new
5736 buffer with a file and does not select the buffer. It also does
5737 not use the default major mode.
5739 (create-file-buffer "foo")
5741 (create-file-buffer "foo")
5743 (create-file-buffer "foo")
5746 This function is used by `find-file-noselect'. It uses
5747 `generate-new-buffer' (*note Creating Buffers::).
5749 - Function: after-find-file &optional error warn noauto
5750 This function sets the buffer major mode, and parses local
5751 variables (*note Auto Major Mode::). It is called by
5752 `find-file-noselect' and by the default revert function (*note
5755 If reading the file got an error because the file does not exist,
5756 but its directory does exist, the caller should pass a non-`nil'
5757 value for ERROR. In that case, `after-find-file' issues a warning:
5758 `(New File)'. For more serious errors, the caller should usually
5759 not call `after-find-file'.
5761 If WARN is non-`nil', then this function issues a warning if an
5762 auto-save file exists and is more recent than the visited file.
5764 If NOAUTO is non-`nil', then this function does not turn on
5765 auto-save mode; otherwise, it does.
5767 The last thing `after-find-file' does is call all the functions in
5771 File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
5776 When you edit a file in XEmacs, you are actually working on a buffer
5777 that is visiting that file--that is, the contents of the file are
5778 copied into the buffer and the copy is what you edit. Changes to the
5779 buffer do not change the file until you "save" the buffer, which means
5780 copying the contents of the buffer into the file.
5782 - Command: save-buffer &optional backup-option
5783 This function saves the contents of the current buffer in its
5784 visited file if the buffer has been modified since it was last
5785 visited or saved. Otherwise it does nothing.
5787 `save-buffer' is responsible for making backup files. Normally,
5788 BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
5789 if this is the first save since visiting the file. Other values
5790 for BACKUP-OPTION request the making of backup files in other
5793 * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
5794 `save-buffer' function marks this version of the file to be
5795 backed up when the buffer is next saved.
5797 * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
5798 `save-buffer' function unconditionally backs up the previous
5799 version of the file before saving it.
5801 - Command: save-some-buffers &optional save-silently-p exiting
5802 This command saves some modified file-visiting buffers. Normally
5803 it asks the user about each buffer. But if SAVE-SILENTLY-P is
5804 non-`nil', it saves all the file-visiting buffers without querying
5807 The optional EXITING argument, if non-`nil', requests this
5808 function to offer also to save certain other buffers that are not
5809 visiting files. These are buffers that have a non-`nil' local
5810 value of `buffer-offer-save'. (A user who says yes to saving one
5811 of these is asked to specify a file name to use.) The
5812 `save-buffers-kill-emacs' function passes a non-`nil' value for
5815 - Variable: buffer-offer-save
5816 When this variable is non-`nil' in a buffer, XEmacs offers to save
5817 the buffer on exit even if the buffer is not visiting a file. The
5818 variable is automatically local in all buffers. Normally, Mail
5819 mode (used for editing outgoing mail) sets this to `t'.
5821 - Command: write-file filename
5822 This function writes the current buffer into file FILENAME, makes
5823 the buffer visit that file, and marks it not modified. Then it
5824 renames the buffer based on FILENAME, appending a string like `<2>'
5825 if necessary to make a unique buffer name. It does most of this
5826 work by calling `set-visited-file-name' and `save-buffer'.
5828 - Variable: write-file-hooks
5829 The value of this variable is a list of functions to be called
5830 before writing out a buffer to its visited file. If one of them
5831 returns non-`nil', the file is considered already written and the
5832 rest of the functions are not called, nor is the usual code for
5833 writing the file executed.
5835 If a function in `write-file-hooks' returns non-`nil', it is
5836 responsible for making a backup file (if that is appropriate). To
5837 do so, execute the following code:
5839 (or buffer-backed-up (backup-buffer))
5841 You might wish to save the file modes value returned by
5842 `backup-buffer' and use that to set the mode bits of the file that
5843 you write. This is what `save-buffer' normally does.
5845 Even though this is not a normal hook, you can use `add-hook' and
5846 `remove-hook' to manipulate the list. *Note Hooks::.
5848 - Variable: local-write-file-hooks
5849 This works just like `write-file-hooks', but it is intended to be
5850 made local to particular buffers. It's not a good idea to make
5851 `write-file-hooks' local to a buffer--use this variable instead.
5853 The variable is marked as a permanent local, so that changing the
5854 major mode does not alter a buffer-local value. This is
5855 convenient for packages that read "file" contents in special ways,
5856 and set up hooks to save the data in a corresponding way.
5858 - Variable: write-contents-hooks
5859 This works just like `write-file-hooks', but it is intended for
5860 hooks that pertain to the contents of the file, as opposed to
5861 hooks that pertain to where the file came from. Such hooks are
5862 usually set up by major modes, as buffer-local bindings for this
5863 variable. Switching to a new major mode always resets this
5866 - Variable: after-save-hook
5867 This normal hook runs after a buffer has been saved in its visited
5870 - Variable: file-precious-flag
5871 If this variable is non-`nil', then `save-buffer' protects against
5872 I/O errors while saving by writing the new file to a temporary
5873 name instead of the name it is supposed to have, and then renaming
5874 it to the intended name after it is clear there are no errors.
5875 This procedure prevents problems such as a lack of disk space from
5876 resulting in an invalid file.
5878 As a side effect, backups are necessarily made by copying. *Note
5879 Rename or Copy::. Yet, at the same time, saving a precious file
5880 always breaks all hard links between the file you save and other
5883 Some modes set this variable non-`nil' locally in particular
5886 - User Option: require-final-newline
5887 This variable determines whether files may be written out that do
5888 _not_ end with a newline. If the value of the variable is `t',
5889 then `save-buffer' silently adds a newline at the end of the file
5890 whenever the buffer being saved does not already end in one. If
5891 the value of the variable is non-`nil', but not `t', then
5892 `save-buffer' asks the user whether to add a newline each time the
5895 If the value of the variable is `nil', then `save-buffer' doesn't
5896 add newlines at all. `nil' is the default value, but a few major
5897 modes set it to `t' in particular buffers.
5900 File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
5905 You can copy a file from the disk and insert it into a buffer using the
5906 `insert-file-contents' function. Don't use the user-level command
5907 `insert-file' in a Lisp program, as that sets the mark.
5909 - Function: insert-file-contents filename &optional visit start end
5911 This function inserts the contents of file FILENAME into the
5912 current buffer after point. It returns a list of the absolute
5913 file name and the length of the data inserted. An error is
5914 signaled if FILENAME is not the name of a file that can be read.
5916 The function `insert-file-contents' checks the file contents
5917 against the defined file formats, and converts the file contents if
5918 appropriate. *Note Format Conversion::. It also calls the
5919 functions in the list `after-insert-file-functions'; see *Note
5920 Saving Properties::.
5922 If VISIT is non-`nil', this function additionally marks the buffer
5923 as unmodified and sets up various fields in the buffer so that it
5924 is visiting the file FILENAME: these include the buffer's visited
5925 file name and its last save file modtime. This feature is used by
5926 `find-file-noselect' and you probably should not use it yourself.
5928 If START and END are non-`nil', they should be integers specifying
5929 the portion of the file to insert. In this case, VISIT must be
5932 (insert-file-contents filename nil 0 500)
5934 inserts the first 500 characters of a file.
5936 If the argument REPLACE is non-`nil', it means to replace the
5937 contents of the buffer (actually, just the accessible portion)
5938 with the contents of the file. This is better than simply
5939 deleting the buffer contents and inserting the whole file, because
5940 (1) it preserves some marker positions and (2) it puts less data
5943 If you want to pass a file name to another process so that another
5944 program can read the file, use the function `file-local-copy'; see
5945 *Note Magic File Names::.
5948 File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
5953 You can write the contents of a buffer, or part of a buffer, directly
5954 to a file on disk using the `append-to-file' and `write-region'
5955 functions. Don't use these functions to write to files that are being
5956 visited; that could cause confusion in the mechanisms for visiting.
5958 - Command: append-to-file start end filename
5959 This function appends the contents of the region delimited by
5960 START and END in the current buffer to the end of file FILENAME.
5961 If that file does not exist, it is created. If that file exists
5962 it is overwritten. This function returns `nil'.
5964 An error is signaled if FILENAME specifies a nonwritable file, or
5965 a nonexistent file in a directory where files cannot be created.
5967 - Command: write-region start end filename &optional append visit
5968 This function writes the region delimited by START and END in the
5969 current buffer into the file specified by FILENAME.
5971 If START is a string, then `write-region' writes or appends that
5972 string, rather than text from the buffer.
5974 If APPEND is non-`nil', then the specified text is appended to the
5975 existing file contents (if any).
5977 If VISIT is `t', then XEmacs establishes an association between
5978 the buffer and the file: the buffer is then visiting that file.
5979 It also sets the last file modification time for the current
5980 buffer to FILENAME's modtime, and marks the buffer as not
5981 modified. This feature is used by `save-buffer', but you probably
5982 should not use it yourself.
5984 If VISIT is a string, it specifies the file name to visit. This
5985 way, you can write the data to one file (FILENAME) while recording
5986 the buffer as visiting another file (VISIT). The argument VISIT
5987 is used in the echo area message and also for file locking; VISIT
5988 is stored in `buffer-file-name'. This feature is used to
5989 implement `file-precious-flag'; don't use it yourself unless you
5990 really know what you're doing.
5992 The function `write-region' converts the data which it writes to
5993 the appropriate file formats specified by `buffer-file-format'.
5994 *Note Format Conversion::. It also calls the functions in the list
5995 `write-region-annotate-functions'; see *Note Saving Properties::.
5997 Normally, `write-region' displays a message `Wrote file FILENAME'
5998 in the echo area. If VISIT is neither `t' nor `nil' nor a string,
5999 then this message is inhibited. This feature is useful for
6000 programs that use files for internal purposes, files that the user
6001 does not need to know about.
6004 File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
6009 When two users edit the same file at the same time, they are likely to
6010 interfere with each other. XEmacs tries to prevent this situation from
6011 arising by recording a "file lock" when a file is being modified.
6012 XEmacs can then detect the first attempt to modify a buffer visiting a
6013 file that is locked by another XEmacs process, and ask the user what to
6016 File locks do not work properly when multiple machines can share
6017 file systems, such as with NFS. Perhaps a better file locking system
6018 will be implemented in the future. When file locks do not work, it is
6019 possible for two users to make changes simultaneously, but XEmacs can
6020 still warn the user who saves second. Also, the detection of
6021 modification of a buffer visiting a file changed on disk catches some
6022 cases of simultaneous editing; see *Note Modification Time::.
6024 - Function: file-locked-p &optional filename
6025 This function returns `nil' if the file FILENAME is not locked by
6026 this XEmacs process. It returns `t' if it is locked by this
6027 XEmacs, and it returns the name of the user who has locked it if it
6028 is locked by someone else.
6030 (file-locked-p "foo")
6033 - Function: lock-buffer &optional filename
6034 This function locks the file FILENAME, if the current buffer is
6035 modified. The argument FILENAME defaults to the current buffer's
6036 visited file. Nothing is done if the current buffer is not
6037 visiting a file, or is not modified.
6039 - Function: unlock-buffer
6040 This function unlocks the file being visited in the current buffer,
6041 if the buffer is modified. If the buffer is not modified, then
6042 the file should not be locked, so this function does nothing. It
6043 also does nothing if the current buffer is not visiting a file.
6045 - Function: ask-user-about-lock filename other-user
6046 This function is called when the user tries to modify FILENAME,
6047 but it is locked by another user named OTHER-USER. The value it
6048 returns determines what happens next:
6050 * A value of `t' says to grab the lock on the file. Then this
6051 user may edit the file and OTHER-USER loses the lock.
6053 * A value of `nil' says to ignore the lock and let this user
6054 edit the file anyway.
6056 * This function may instead signal a `file-locked' error, in
6057 which case the change that the user was about to make does
6060 The error message for this error looks like this:
6062 error--> File is locked: FILENAME OTHER-USER
6064 where FILENAME is the name of the file and OTHER-USER is the
6065 name of the user who has locked the file.
6067 The default definition of this function asks the user to choose
6068 what to do. If you wish, you can replace the `ask-user-about-lock'
6069 function with your own version that decides in another way. The
6070 code for its usual definition is in `userlock.el'.
6073 File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
6075 Information about Files
6076 =======================
6078 The functions described in this section all operate on strings that
6079 designate file names. All the functions have names that begin with the
6080 word `file'. These functions all return information about actual files
6081 or directories, so their arguments must all exist as actual files or
6082 directories unless otherwise noted.
6086 * Testing Accessibility:: Is a given file readable? Writable?
6087 * Kinds of Files:: Is it a directory? A symbolic link?
6088 * Truenames:: Eliminating symbolic links from a file name.
6089 * File Attributes:: How large is it? Any other names? Etc.
6092 File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
6094 Testing Accessibility
6095 ---------------------
6097 These functions test for permission to access a file in specific ways.
6099 - Function: file-exists-p filename
6100 This function returns `t' if a file named FILENAME appears to
6101 exist. This does not mean you can necessarily read the file, only
6102 that you can find out its attributes. (On Unix, this is true if
6103 the file exists and you have execute permission on the containing
6104 directories, regardless of the protection of the file itself.)
6106 If the file does not exist, or if fascist access control policies
6107 prevent you from finding the attributes of the file, this function
6110 - Function: file-readable-p filename
6111 This function returns `t' if a file named FILENAME exists and you
6112 can read it. It returns `nil' otherwise.
6114 (file-readable-p "files.texi")
6116 (file-exists-p "/usr/spool/mqueue")
6118 (file-readable-p "/usr/spool/mqueue")
6121 - Function: file-executable-p filename
6122 This function returns `t' if a file named FILENAME exists and you
6123 can execute it. It returns `nil' otherwise. If the file is a
6124 directory, execute permission means you can check the existence and
6125 attributes of files inside the directory, and open those files if
6128 - Function: file-writable-p filename
6129 This function returns `t' if the file FILENAME can be written or
6130 created by you, and `nil' otherwise. A file is writable if the
6131 file exists and you can write it. It is creatable if it does not
6132 exist, but the specified directory does exist and you can write in
6135 In the third example below, `foo' is not writable because the
6136 parent directory does not exist, even though the user could create
6139 (file-writable-p "~/foo")
6141 (file-writable-p "/foo")
6143 (file-writable-p "~/no-such-dir/foo")
6146 - Function: file-accessible-directory-p dirname
6147 This function returns `t' if you have permission to open existing
6148 files in the directory whose name as a file is DIRNAME; otherwise
6149 (or if there is no such directory), it returns `nil'. The value
6150 of DIRNAME may be either a directory name or the file name of a
6153 Example: after the following,
6155 (file-accessible-directory-p "/foo")
6158 we can deduce that any attempt to read a file in `/foo/' will give
6161 - Function: file-ownership-preserved-p filename
6162 This function returns `t' if deleting the file FILENAME and then
6163 creating it anew would keep the file's owner unchanged.
6165 - Function: file-newer-than-file-p filename1 filename2
6166 This function returns `t' if the file FILENAME1 is newer than file
6167 FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
6168 FILENAME2 does not exist, it returns `t'.
6170 In the following example, assume that the file `aug-19' was written
6171 on the 19th, `aug-20' was written on the 20th, and the file
6172 `no-file' doesn't exist at all.
6174 (file-newer-than-file-p "aug-19" "aug-20")
6176 (file-newer-than-file-p "aug-20" "aug-19")
6178 (file-newer-than-file-p "aug-19" "no-file")
6180 (file-newer-than-file-p "no-file" "aug-19")
6183 You can use `file-attributes' to get a file's last modification
6184 time as a list of two numbers. *Note File Attributes::.
6187 File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
6189 Distinguishing Kinds of Files
6190 -----------------------------
6192 This section describes how to distinguish various kinds of files, such
6193 as directories, symbolic links, and ordinary files.
6195 - Function: file-symlink-p filename
6196 If the file FILENAME is a symbolic link, the `file-symlink-p'
6197 function returns the file name to which it is linked. This may be
6198 the name of a text file, a directory, or even another symbolic
6199 link, or it may be a nonexistent file name.
6201 If the file FILENAME is not a symbolic link (or there is no such
6202 file), `file-symlink-p' returns `nil'.
6204 (file-symlink-p "foo")
6206 (file-symlink-p "sym-link")
6208 (file-symlink-p "sym-link2")
6210 (file-symlink-p "/bin")
6214 - Function: file-directory-p filename
6215 This function returns `t' if FILENAME is the name of an existing
6216 directory, `nil' otherwise.
6218 (file-directory-p "~rms")
6220 (file-directory-p "~rms/lewis/files.texi")
6222 (file-directory-p "~rms/lewis/no-such-file")
6224 (file-directory-p "$HOME")
6227 (substitute-in-file-name "$HOME"))
6230 - Function: file-regular-p filename
6231 This function returns `t' if the file FILENAME exists and is a
6232 regular file (not a directory, symbolic link, named pipe,
6233 terminal, or other I/O device).
6236 File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
6241 The "truename" of a file is the name that you get by following symbolic
6242 links until none remain, then expanding to get rid of `.' and `..' as
6243 components. Strictly speaking, a file need not have a unique truename;
6244 the number of distinct truenames a file has is equal to the number of
6245 hard links to the file. However, truenames are useful because they
6246 eliminate symbolic links as a cause of name variation.
6248 - Function: file-truename filename &optional default
6249 The function `file-truename' returns the true name of the file
6250 FILENAME. This is the name that you get by following symbolic
6251 links until none remain.
6253 If the filename is relative, DEFAULT is the directory to start
6254 with. If DEFAULT is `nil' or missing, the current buffer's value
6255 of `default-directory' is used.
6257 *Note Buffer File Name::, for related information.
6260 File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files
6262 Other Information about Files
6263 -----------------------------
6265 This section describes the functions for getting detailed information
6266 about a file, other than its contents. This information includes the
6267 mode bits that control access permission, the owner and group numbers,
6268 the number of names, the inode number, the size, and the times of access
6271 - Function: file-modes filename
6272 This function returns the mode bits of FILENAME, as an integer.
6273 The mode bits are also called the file permissions, and they
6274 specify access control in the usual Unix fashion. If the
6275 low-order bit is 1, then the file is executable by all users, if
6276 the second-lowest-order bit is 1, then the file is writable by all
6279 The highest value returnable is 4095 (7777 octal), meaning that
6280 everyone has read, write, and execute permission, that the SUID bit
6281 is set for both others and group, and that the sticky bit is set.
6283 (file-modes "~/junk/diffs")
6284 => 492 ; Decimal integer.
6286 => "754" ; Convert to octal.
6288 (set-file-modes "~/junk/diffs" 438)
6292 => "666" ; Convert to octal.
6295 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
6297 - Function: file-nlinks filename
6298 This functions returns the number of names (i.e., hard links) that
6299 file FILENAME has. If the file does not exist, then this function
6300 returns `nil'. Note that symbolic links have no effect on this
6301 function, because they are not considered to be names of the files
6305 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
6306 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
6310 (file-nlinks "doesnt-exist")
6313 - Function: file-attributes filename
6314 This function returns a list of attributes of file FILENAME. If
6315 the specified file cannot be opened, it returns `nil'.
6317 The elements of the list, in order, are:
6319 0. `t' for a directory, a string for a symbolic link (the name
6320 linked to), or `nil' for a text file.
6322 1. The number of names the file has. Alternate names, also
6323 known as hard links, can be created by using the
6324 `add-name-to-file' function (*note Changing File
6331 4. The time of last access, as a list of two integers. The
6332 first integer has the high-order 16 bits of time, the second
6333 has the low 16 bits. (This is similar to the value of
6334 `current-time'; see *Note Time of Day::.)
6336 5. The time of last modification as a list of two integers (as
6339 6. The time of last status change as a list of two integers (as
6342 7. The size of the file in bytes.
6344 8. The file's modes, as a string of ten letters or dashes, as in
6347 9. `t' if the file's GID would change if file were deleted and
6348 recreated; `nil' otherwise.
6350 10. The file's inode number.
6352 11. The file system number of the file system that the file is
6353 in. This element and the file's inode number together give
6354 enough information to distinguish any two files on the
6355 system--no two files can have the same values for both of
6358 For example, here are the file attributes for `files.texi':
6360 (file-attributes "files.texi")
6374 and here is how the result is interpreted:
6377 is neither a directory nor a symbolic link.
6380 has only one name (the name `files.texi' in the current
6384 is owned by the user with UID 2235.
6387 is in the group with GID 75.
6390 was last accessed on Aug 19 00:09. Use `format-time-string' to
6391 ! convert this number into a time string. *Note Time
6395 was last modified on Aug 19 00:09.
6398 last had its inode changed on Aug 19 00:09.
6401 is 14906 characters long.
6404 has a mode of read and write access for the owner, group, and
6408 would retain the same GID if it were recreated.
6411 has an inode number of 129500.
6414 is on file system number -32252.
6417 File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
6419 Changing File Names and Attributes
6420 ==================================
6422 The functions in this section rename, copy, delete, link, and set the
6425 In the functions that have arguments NEWNAME and
6426 OK-IF-ALREADY-EXISTS, if a file by the name of NEWNAME already exists,
6427 the actions taken depend on the value of OK-IF-ALREADY-EXISTS:
6429 * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
6432 * Request confirmation if OK-IF-ALREADY-EXISTS is a number. This is
6433 what happens when the function is invoked interactively.
6435 * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
6438 - Command: add-name-to-file filename newname &optional
6439 ok-if-already-exists
6440 This function gives the file named FILENAME the additional name
6441 NEWNAME. This means that NEWNAME becomes a new "hard link" to
6442 FILENAME. Both these arguments must be strings.
6444 In the first part of the following example, we list two files,
6448 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
6449 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
6451 Then we evaluate the form `(add-name-to-file "~/lewis/foo"
6452 "~/lewis/foo2")'. Again we list the files. This shows two names,
6455 (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
6459 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
6460 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
6461 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
6463 Finally, we evaluate the following:
6465 (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
6467 and list the files again. Now there are three names for one file:
6468 `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
6470 (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
6474 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
6475 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
6476 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
6478 This function is meaningless on non-Unix systems, where multiple
6479 names for one file are not allowed.
6481 See also `file-nlinks' in *Note File Attributes::.
6483 - Command: rename-file filename newname &optional ok-if-already-exists
6484 This command renames the file FILENAME as NEWNAME.
6486 If FILENAME has additional names aside from FILENAME, it continues
6487 to have those names. In fact, adding the name NEWNAME with
6488 `add-name-to-file' and then deleting FILENAME has the same effect
6489 as renaming, aside from momentary intermediate states.
6491 In an interactive call, this function prompts for FILENAME and
6492 NEWNAME in the minibuffer; also, it requests confirmation if
6493 NEWNAME already exists.
6495 - Command: copy-file filename newname &optional ok-if-already-exists
6497 This command copies the file FILENAME to NEWNAME. An error is
6498 signaled if FILENAME does not exist.
6500 If TIME is non-`nil', then this functions gives the new file the
6501 same last-modified time that the old one has. (This works on only
6502 some operating systems.)
6504 In an interactive call, this function prompts for FILENAME and
6505 NEWNAME in the minibuffer; also, it requests confirmation if
6506 NEWNAME already exists.
6508 - Command: delete-file filename
6509 This command deletes the file FILENAME, like the shell command `rm
6510 FILENAME'. If the file has multiple names, it continues to exist
6511 under the other names.
6513 A suitable kind of `file-error' error is signaled if the file does
6514 not exist, or is not deletable. (On Unix, a file is deletable if
6515 its directory is writable.)
6517 See also `delete-directory' in *Note Create/Delete Dirs::.
6519 - Command: make-symbolic-link filename newname &optional
6520 ok-if-already-exists
6521 This command makes a symbolic link to FILENAME, named NEWNAME.
6522 This is like the shell command `ln -s FILENAME NEWNAME'.
6524 In an interactive call, this function prompts for FILENAME and
6525 NEWNAME in the minibuffer; also, it requests confirmation if
6526 NEWNAME already exists.
6528 - Function: set-file-modes filename mode
6529 This function sets mode bits of FILENAME to MODE (which must be an
6530 integer). Only the low 12 bits of MODE are used.
6532 - Function: set-default-file-modes mode
6533 This function sets the default file protection for new files
6534 created by XEmacs and its subprocesses. Every file created with
6535 XEmacs initially has this protection. On Unix, the default
6536 protection is the bitwise complement of the "umask" value.
6538 The argument MODE must be an integer. Only the low 9 bits of MODE
6541 Saving a modified version of an existing file does not count as
6542 creating the file; it does not change the file's mode, and does
6543 not use the default file protection.
6545 - Function: default-file-modes
6546 This function returns the current default protection value.
6548 On MS-DOS, there is no such thing as an "executable" file mode bit.
6549 So Emacs considers a file executable if its name ends in `.com', `.bat'
6550 or `.exe'. This is reflected in the values returned by `file-modes'
6551 and `file-attributes'.
6554 File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
6559 Files are generally referred to by their names, in XEmacs as elsewhere.
6560 File names in XEmacs are represented as strings. The functions that
6561 operate on a file all expect a file name argument.
6563 In addition to operating on files themselves, XEmacs Lisp programs
6564 often need to operate on the names; i.e., to take them apart and to use
6565 part of a name to construct related file names. This section describes
6566 how to manipulate file names.
6568 The functions in this section do not actually access files, so they
6569 can operate on file names that do not refer to an existing file or
6572 On MS-DOS, these functions understand MS-DOS file-name syntax as
6573 well as Unix syntax. This is so that all the standard Lisp libraries
6574 can specify file names in Unix syntax and work properly on all systems
6575 without change. Similarly for other operating systems.
6579 * File Name Components:: The directory part of a file name, and the rest.
6580 * Directory Names:: A directory's name as a directory
6581 is different from its name as a file.
6582 * Relative File Names:: Some file names are relative to a current directory.
6583 * File Name Expansion:: Converting relative file names to absolute ones.
6584 * Unique File Names:: Generating names for temporary files.
6585 * File Name Completion:: Finding the completions for a given file name.
6586 * User Name Completion:: Finding the completions for a given user name.
6589 File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
6591 File Name Components
6592 --------------------
6594 The operating system groups files into directories. To specify a file,
6595 you must specify the directory and the file's name within that
6596 directory. Therefore, XEmacs considers a file name as having two main
6597 parts: the "directory name" part, and the "nondirectory" part (or "file
6598 name within the directory"). Either part may be empty. Concatenating
6599 these two parts reproduces the original file name.
6601 On Unix, the directory part is everything up to and including the
6602 last slash; the nondirectory part is the rest.
6604 For some purposes, the nondirectory part is further subdivided into
6605 the name proper and the "version number". On Unix, only backup files
6606 have version numbers in their names.
6608 - Function: file-name-directory filename
6609 This function returns the directory part of FILENAME (or `nil' if
6610 FILENAME does not include a directory part). On Unix, the
6611 function returns a string ending in a slash.
6613 (file-name-directory "lewis/foo") ; Unix example
6615 (file-name-directory "foo") ; Unix example
6618 - Function: file-name-nondirectory filename
6619 This function returns the nondirectory part of FILENAME.
6621 (file-name-nondirectory "lewis/foo")
6623 (file-name-nondirectory "foo")
6626 - Function: file-name-sans-versions filename &optional
6628 This function returns FILENAME without any file version numbers,
6629 backup version numbers, or trailing tildes.
6631 If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
6632 version numbers, only true file version numbers.
6634 (file-name-sans-versions "~rms/foo.~1~")
6636 (file-name-sans-versions "~rms/foo~")
6638 (file-name-sans-versions "~rms/foo")
6641 - Function: file-name-sans-extension filename
6642 This function returns FILENAME minus its "extension," if any. The
6643 extension, in a file name, is the part that starts with the last
6644 `.' in the last name component. For example,
6646 (file-name-sans-extension "foo.lose.c")
6648 (file-name-sans-extension "big.hack/foo")
6652 File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
6657 A "directory name" is the name of a directory. A directory is a kind
6658 of file, and it has a file name, which is related to the directory name
6659 but not identical to it. (This is not quite the same as the usual Unix
6660 terminology.) These two different names for the same entity are
6661 related by a syntactic transformation. On Unix, this is simple: a
6662 directory name ends in a slash, whereas the directory's name as a file
6665 The difference between a directory name and its name as a file is
6666 subtle but crucial. When an XEmacs variable or function argument is
6667 described as being a directory name, a file name of a directory is not
6670 The following two functions convert between directory names and file
6671 names. They do nothing special with environment variable substitutions
6672 such as `$HOME', and the constructs `~', and `..'.
6674 - Function: file-name-as-directory filename
6675 This function returns a string representing FILENAME in a form
6676 that the operating system will interpret as the name of a
6677 directory. In Unix, this means appending a slash to the string.
6679 (file-name-as-directory "~rms/lewis")
6682 - Function: directory-file-name dirname
6683 This function returns a string representing DIRNAME in a form that
6684 the operating system will interpret as the name of a file. On
6685 Unix, this means removing a final slash from the string.
6687 (directory-file-name "~lewis/")
6690 Directory name abbreviations are useful for directories that are
6691 normally accessed through symbolic links. Sometimes the users recognize
6692 primarily the link's name as "the name" of the directory, and find it
6693 annoying to see the directory's "real" name. If you define the link
6694 name as an abbreviation for the "real" name, XEmacs shows users the
6695 abbreviation instead.
6697 If you wish to convert a directory name to its abbreviation, use this
6700 - Function: abbreviate-file-name filename &optional hack-homedir
6701 This function applies abbreviations from `directory-abbrev-alist'
6702 to its argument, and substitutes `~' for the user's home directory.
6704 If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
6705 the user's home directory.
6708 - Variable: directory-abbrev-alist
6709 The variable `directory-abbrev-alist' contains an alist of
6710 abbreviations to use for file directories. Each element has the
6711 form `(FROM . TO)', and says to replace FROM with TO when it
6712 appears in a directory name. The FROM string is actually a
6713 regular expression; it should always start with `^'. The function
6714 `abbreviate-file-name' performs these substitutions.
6716 You can set this variable in `site-init.el' to describe the
6717 abbreviations appropriate for your site.
6719 Here's an example, from a system on which file system `/home/fsf'
6720 and so on are normally accessed through symbolic links named `/fsf'
6723 (("^/home/fsf" . "/fsf")
6724 ("^/home/gp" . "/gp")
6725 ("^/home/gd" . "/gd"))
6728 File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
6730 Absolute and Relative File Names
6731 --------------------------------
6733 All the directories in the file system form a tree starting at the root
6734 directory. A file name can specify all the directory names starting
6735 from the root of the tree; then it is called an "absolute" file name.
6736 Or it can specify the position of the file in the tree relative to a
6737 default directory; then it is called a "relative" file name. On Unix,
6738 an absolute file name starts with a slash or a tilde (`~'), and a
6739 relative one does not.
6741 - Function: file-name-absolute-p filename
6742 This function returns `t' if file FILENAME is an absolute file
6743 name, `nil' otherwise.
6745 (file-name-absolute-p "~rms/foo")
6747 (file-name-absolute-p "rms/foo")
6749 (file-name-absolute-p "/user/rms/foo")
6753 File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
6755 Functions that Expand Filenames
6756 -------------------------------
6758 "Expansion" of a file name means converting a relative file name to an
6759 absolute one. Since this is done relative to a default directory, you
6760 must specify the default directory name as well as the file name to be
6761 expanded. Expansion also simplifies file names by eliminating
6762 redundancies such as `./' and `NAME/../'.
6764 - Function: expand-file-name filename &optional directory
6765 This function converts FILENAME to an absolute file name. If
6766 DIRECTORY is supplied, it is the directory to start with if
6767 FILENAME is relative. (The value of DIRECTORY should itself be an
6768 absolute directory name; it may start with `~'.) Otherwise, the
6769 current buffer's value of `default-directory' is used. For
6772 (expand-file-name "foo")
6773 => "/xcssun/users/rms/lewis/foo"
6774 (expand-file-name "../foo")
6775 => "/xcssun/users/rms/foo"
6776 (expand-file-name "foo" "/usr/spool/")
6778 (expand-file-name "$HOME/foo")
6779 => "/xcssun/users/rms/lewis/$HOME/foo"
6781 Filenames containing `.' or `..' are simplified to their canonical
6784 (expand-file-name "bar/../foo")
6785 => "/xcssun/users/rms/lewis/foo"
6787 `~/' at the beginning is expanded into the user's home directory.
6788 A `/' or `~' following a `/'.
6790 Note that `expand-file-name' does _not_ expand environment
6791 variables; only `substitute-in-file-name' does that.
6793 - Function: file-relative-name filename &optional directory
6794 This function does the inverse of expansion--it tries to return a
6795 relative name that is equivalent to FILENAME when interpreted
6796 relative to DIRECTORY.
6798 If DIRECTORY is `nil' or omitted, the value of `default-directory'
6801 (file-relative-name "/foo/bar" "/foo/")
6803 (file-relative-name "/foo/bar" "/hack/")
6806 - Variable: default-directory
6807 The value of this buffer-local variable is the default directory
6808 for the current buffer. It should be an absolute directory name;
6809 it may start with `~'. This variable is local in every buffer.
6811 `expand-file-name' uses the default directory when its second
6814 On Unix systems, the value is always a string ending with a slash.
6817 => "/user/lewis/manual/"
6819 - Function: substitute-in-file-name filename
6820 This function replaces environment variable references in FILENAME
6821 with the environment variable values. Following standard Unix
6822 shell syntax, `$' is the prefix to substitute an environment
6825 The environment variable name is the series of alphanumeric
6826 characters (including underscores) that follow the `$'. If the
6827 character following the `$' is a `{', then the variable name is
6828 everything up to the matching `}'.
6830 Here we assume that the environment variable `HOME', which holds
6831 the user's home directory name, has value `/xcssun/users/rms'.
6833 (substitute-in-file-name "$HOME/foo")
6834 => "/xcssun/users/rms/foo"
6836 After substitution, a `/' or `~' following a `/' is taken to be
6837 the start of an absolute file name that overrides what precedes
6838 it, so everything before that `/' or `~' is deleted. For example:
6840 (substitute-in-file-name "bar/~/foo")
6842 (substitute-in-file-name "/usr/local/$HOME/foo")
6843 => "/xcssun/users/rms/foo"
6846 File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
6848 Generating Unique File Names
6849 ----------------------------
6851 Some programs need to write temporary files. Here is the usual way to
6852 construct a name for such a file:
6854 (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
6856 Here we use `(temp-directory)' to specify a directory for temporary
6857 files--under Unix, it will normally evaluate to `"/tmp/"'. The job of
6858 `make-temp-name' is to prevent two different users or two different
6859 processes from trying to use the same name.
6861 - Function: temp-directory
6862 This function returns the name of the directory to use for
6863 temporary files. Under Unix, this will be the value of `TMPDIR',
6864 defaulting to `/tmp'. On Windows, this will be obtained from the
6865 `TEMP' or `TMP' environment variables, defaulting to `/'.
6867 Note that the `temp-directory' function does not exist under FSF
6870 - Function: make-temp-name prefix
6871 This function generates a temporary file name starting with
6872 PREFIX. The Emacs process number forms part of the result, so
6873 there is no danger of generating a name being used by another
6876 (make-temp-name "/tmp/foo")
6879 In addition, this function makes an attempt to choose a name that
6880 does not specify an existing file. To make this work, PREFIX
6881 should be an absolute file name.
6883 To avoid confusion, each Lisp application should preferably use a
6884 unique PREFIX to `make-temp-name'.
6887 File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
6889 File Name Completion
6890 --------------------
6892 This section describes low-level subroutines for completing a file
6893 name. For other completion functions, see *Note Completion::.
6895 - Function: file-name-all-completions partial-filename directory
6896 This function returns a list of all possible completions for files
6897 whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
6898 The order of the completions is the order of the files in the
6899 directory, which is unpredictable and conveys no useful
6902 The argument PARTIAL-FILENAME must be a file name containing no
6903 directory part and no slash. The current buffer's default
6904 directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
6906 File names which end with any member of
6907 `completion-ignored-extensions' are not considered as possible
6908 completions for PARTIAL-FILENAME unless there is no other possible
6909 completion. `completion-ignored-extensions' is not applied to the
6910 names of directories.
6912 In the following example, suppose that the current default
6913 directory, `~rms/lewis', has five files whose names begin with `f':
6914 `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
6916 (file-name-all-completions "f" "")
6917 => ("foo" "file~" "file.c.~2~"
6918 "file.c.~1~" "file.c")
6920 (file-name-all-completions "fo" "")
6923 - Function: file-name-completion partial-filename directory
6924 This function completes the file name PARTIAL-FILENAME in directory
6925 DIRECTORY. It returns the longest prefix common to all file names
6926 in directory DIRECTORY that start with PARTIAL-FILENAME.
6928 If only one match exists and PARTIAL-FILENAME matches it exactly,
6929 the function returns `t'. The function returns `nil' if directory
6930 DIRECTORY contains no name starting with PARTIAL-FILENAME.
6932 File names which end with any member of
6933 `completion-ignored-extensions' are not considered as possible
6934 completions for PARTIAL-FILENAME unless there is no other possible
6935 completion. `completion-ignored-extensions' is not applied to the
6936 names of directories.
6938 In the following example, suppose that the current default
6939 directory has five files whose names begin with `f': `foo',
6940 `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
6942 (file-name-completion "fi" "")
6945 (file-name-completion "file.c.~1" "")
6948 (file-name-completion "file.c.~1~" "")
6951 (file-name-completion "file.c.~3" "")
6954 - User Option: completion-ignored-extensions
6955 `file-name-completion' usually ignores file names that end in any
6956 string in this list. It does not ignore them when all the possible
6957 completions end in one of these suffixes or when a buffer showing
6958 all possible completions is displayed.
6960 A typical value might look like this:
6962 completion-ignored-extensions
6963 => (".o" ".elc" "~" ".dvi")
6966 File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
6968 User Name Completion
6969 --------------------
6971 This section describes low-level subroutines for completing a user
6972 name. For other completion functions, see *Note Completion::.
6974 - Function: user-name-all-completions partial-username
6975 This function returns a list of all possible completions for a
6976 user name starting with PARTIAL-USERNAME. The order of the
6977 completions is unpredictable and conveys no useful information.
6979 The argument PARTIAL-USERNAME must be a partial user name
6980 containing no tilde character and no slash.
6982 - Function: user-name-completion partial-username
6983 This function completes a user name from PARTIAL-USERNAME. It
6984 returns the longest prefix common to all user names that start with
6987 If only one match exists and PARTIAL-USERNAME matches it exactly,
6988 the function returns `t'. The function returns `nil' if no user
6989 name starting with PARTIAL-USERNAME exists.
6991 - Function: user-name-completion-1 partial-username
6992 This function completes the partial user name PARTIAL-USERNAME,
6993 like `user-name-completion', differing only in the return value.
6994 This function returns the cons of the completion returned by
6995 `user-name-completion', and a boolean indicating whether that
6996 completion was unique.
6999 File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
7001 Contents of Directories
7002 =======================
7004 A directory is a kind of file that contains other files entered under
7005 various names. Directories are a feature of the file system.
7007 XEmacs can list the names of the files in a directory as a Lisp list,
7008 or display the names in a buffer using the `ls' shell command. In the
7009 latter case, it can optionally display information about each file,
7010 depending on the value of switches passed to the `ls' command.
7012 - Function: directory-files directory &optional full-name match-regexp
7014 This function returns a list of the names of the files in the
7015 directory DIRECTORY. By default, the list is in alphabetical
7018 If FULL-NAME is non-`nil', the function returns the files'
7019 absolute file names. Otherwise, it returns just the names
7020 relative to the specified directory.
7022 If MATCH-REGEXP is non-`nil', this function returns only those
7023 file names that contain that regular expression--the other file
7024 names are discarded from the list.
7026 If NOSORT is non-`nil', `directory-files' does not sort the list,
7027 so you get the file names in no particular order. Use this if you
7028 want the utmost possible speed and don't care what order the files
7029 are processed in. If the order of processing is visible to the
7030 user, then the user will probably be happier if you do sort the
7033 If FILES-ONLY is the symbol `t', then only the "files" in the
7034 directory will be returned; subdirectories will be excluded. If
7035 FILES-ONLY is not `nil' and not `t', then only the subdirectories
7036 will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
7037 then both files and subdirectories will be returned.
7039 (directory-files "~lewis")
7040 => ("#foo#" "#foo.el#" "." ".."
7041 "dired-mods.el" "files.texi"
7044 An error is signaled if DIRECTORY is not the name of a directory
7047 - Function: insert-directory file switches &optional wildcard
7049 This function inserts (in the current buffer) a directory listing
7050 for directory FILE, formatted with `ls' according to SWITCHES. It
7051 leaves point after the inserted text.
7053 The argument FILE may be either a directory name or a file
7054 specification including wildcard characters. If WILDCARD is
7055 non-`nil', that means treat FILE as a file specification with
7058 If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
7059 and switches do not contain `-d', so that the listing should show
7060 the full contents of the directory. (The `-d' option to `ls' says
7061 to describe a directory itself rather than its contents.)
7063 This function works by running a directory listing program whose
7064 name is in the variable `insert-directory-program'. If WILDCARD is
7065 non-`nil', it also runs the shell specified by `shell-file-name',
7066 to expand the wildcards.
7068 - Variable: insert-directory-program
7069 This variable's value is the program to run to generate a
7070 directory listing for the function `insert-directory'.
projects / chise / xemacs-chise.git.1 / blob