This is ../info/lispref.info, produced by makeinfo version 4.6 from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY * Lispref: (lispref). XEmacs Lisp Reference Manual. END-INFO-DIR-ENTRY Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995, 1996 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input Miscellaneous Event Input Features ---------------------------------- This section describes how to "peek ahead" at events without using them up, how to check for pending input, and how to discard pending input. See also the variables `last-command-event' and `last-command-char' (*Note Command Loop Info::). - Variable: unread-command-events This variable holds a list of events waiting to be read as command input. The events are used in the order they appear in the list, and removed one by one as they are used. The variable is needed because in some cases a function reads an event and then decides not to use it. Storing the event in this variable causes it to be processed normally, by the command loop or by the functions to read command input. For example, the function that implements numeric prefix arguments reads any number of digits. When it finds a non-digit event, it must unread the event so that it can be read normally by the command loop. Likewise, incremental search uses this feature to unread events with no special meaning in a search, because these events should exit the search and then execute normally. - Variable: unread-command-event This variable holds a single event to be read as command input. This variable is mostly obsolete now that you can use `unread-command-events' instead; it exists only to support programs written for versions of XEmacs prior to 19.12. - Function: input-pending-p This function determines whether any command input is currently available to be read. It returns immediately, with value `t' if there is available input, `nil' otherwise. On rare occasions it may return `t' when no input is available. - Variable: last-input-event This variable is set to the last keyboard or mouse button event received. This variable is off limits: you may not set its value or modify the event that is its value, as it is destructively modified by `read-key-sequence'. If you want to keep a pointer to this value, you must use `copy-event'. Note that this variable is an alias for `last-input-char' in FSF Emacs. In the example below, a character is read (the character `1'). It becomes the value of `last-input-event', while `C-e' (from the `C-x C-e' command used to evaluate this expression) remains the value of `last-command-event'. (progn (print (next-command-event)) (print last-command-event) last-input-event) -| # -| # => # - Variable: last-input-char If the value of `last-input-event' is a keyboard event, then this is the nearest ASCII equivalent to it. Remember that there is _not_ a 1:1 mapping between keyboard events and ASCII characters: the set of keyboard events is much larger, so writing code that examines this variable to determine what key has been typed is bad practice, unless you are certain that it will be one of a small set of characters. This function exists for compatibility with Emacs version 18. - Function: discard-input This function discards the contents of the terminal input buffer and cancels any keyboard macro that might be in the process of definition. It returns `nil'. In the following example, the user may type a number of characters right after starting the evaluation of the form. After the `sleep-for' finishes sleeping, `discard-input' discards any characters typed during the sleep. (progn (sleep-for 2) (discard-input)) => nil  File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop Waiting for Elapsed Time or Input ================================= The wait functions are designed to wait for a certain amount of time to pass or until there is input. For example, you may wish to pause in the middle of a computation to allow the user time to view the display. `sit-for' pauses and updates the screen, and returns immediately if input comes in, while `sleep-for' pauses without updating the screen. Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take two arguments to specify the time (one integer and one float value), instead of a single argument that can be either an integer or a float. - Function: sit-for seconds &optional nodisplay This function performs redisplay (provided there is no pending input from the user), then waits SECONDS seconds, or until input is available. The result is `t' if `sit-for' waited the full time with no input arriving (see `input-pending-p' in *Note Peeking and Discarding::). Otherwise, the value is `nil'. The argument SECONDS need not be an integer. If it is a floating point number, `sit-for' waits for a fractional number of seconds. Redisplay is normally preempted if input arrives, and does not happen at all if input is available before it starts. (You can force screen updating in such a case by using `force-redisplay'. *Note Refresh Screen::.) If there is no input pending, you can force an update with no delay by using `(sit-for 0)'. If NODISPLAY is non-`nil', then `sit-for' does not redisplay, but it still returns as soon as input is available (or when the timeout elapses). The usual purpose of `sit-for' is to give the user time to read text that you display. - Function: sleep-for seconds This function simply pauses for SECONDS seconds without updating the display. This function pays no attention to available input. It returns `nil'. The argument SECONDS need not be an integer. If it is a floating point number, `sleep-for' waits for a fractional number of seconds. Use `sleep-for' when you wish to guarantee a delay. *Note Time of Day::, for functions to get the current time.  File: lispref.info, Node: Quitting, Next: Prefix Command Arguments, Prev: Waiting, Up: Command Loop Quitting ======== Typing `C-g' while a Lisp function is running causes XEmacs to "quit" whatever it is doing. This means that control returns to the innermost active command loop. Typing `C-g' while the command loop is waiting for keyboard input does not cause a quit; it acts as an ordinary input character. In the simplest case, you cannot tell the difference, because `C-g' normally runs the command `keyboard-quit', whose effect is to quit. However, when `C-g' follows a prefix key, the result is an undefined key. The effect is to cancel the prefix key as well as any prefix argument. In the minibuffer, `C-g' has a different definition: it aborts out of the minibuffer. This means, in effect, that it exits the minibuffer and then quits. (Simply quitting would return to the command loop _within_ the minibuffer.) The reason why `C-g' does not quit directly when the command reader is reading input is so that its meaning can be redefined in the minibuffer in this way. `C-g' following a prefix key is not redefined in the minibuffer, and it has its normal effect of canceling the prefix key and prefix argument. This too would not be possible if `C-g' always quit directly. When `C-g' does directly quit, it does so by setting the variable `quit-flag' to `t'. XEmacs checks this variable at appropriate times and quits if it is not `nil'. Setting `quit-flag' non-`nil' in any way thus causes a quit. At the level of C code, quitting cannot happen just anywhere; only at the special places that check `quit-flag'. The reason for this is that quitting at other places might leave an inconsistency in XEmacs's internal state. Because quitting is delayed until a safe place, quitting cannot make XEmacs crash. Certain functions such as `read-key-sequence' or `read-quoted-char' prevent quitting entirely even though they wait for input. Instead of quitting, `C-g' serves as the requested input. In the case of `read-key-sequence', this serves to bring about the special behavior of `C-g' in the command loop. In the case of `read-quoted-char', this is so that `C-q' can be used to quote a `C-g'. You can prevent quitting for a portion of a Lisp function by binding the variable `inhibit-quit' to a non-`nil' value. Then, although `C-g' still sets `quit-flag' to `t' as usual, the usual result of this--a quit--is prevented. Eventually, `inhibit-quit' will become `nil' again, such as when its binding is unwound at the end of a `let' form. At that time, if `quit-flag' is still non-`nil', the requested quit happens immediately. This behavior is ideal when you wish to make sure that quitting does not happen within a "critical section" of the program. In some functions (such as `read-quoted-char'), `C-g' is handled in a special way that does not involve quitting. This is done by reading the input with `inhibit-quit' bound to `t', and setting `quit-flag' to `nil' before `inhibit-quit' becomes `nil' again. This excerpt from the definition of `read-quoted-char' shows how this is done; it also shows that normal quitting is permitted after the first character of input. (defun read-quoted-char (&optional prompt) "...DOCUMENTATION..." (let ((count 0) (code 0) char) (while (< count 3) (let ((inhibit-quit (zerop count)) (help-form nil)) (and prompt (message "%s-" prompt)) (setq char (read-char)) (if inhibit-quit (setq quit-flag nil))) ...) (logand 255 code))) - Variable: quit-flag If this variable is non-`nil', then XEmacs quits immediately, unless `inhibit-quit' is non-`nil'. Typing `C-g' ordinarily sets `quit-flag' non-`nil', regardless of `inhibit-quit'. - Variable: inhibit-quit This variable determines whether XEmacs should quit when `quit-flag' is set to a value other than `nil'. If `inhibit-quit' is non-`nil', then `quit-flag' has no special effect. - Command: keyboard-quit This function signals the `quit' condition with `(signal 'quit nil)'. This is the same thing that quitting does. (See `signal' in *Note Errors::.) You can specify a character other than `C-g' to use for quitting. See the function `set-input-mode' in *Note Terminal Input::.  File: lispref.info, Node: Prefix Command Arguments, Next: Recursive Editing, Prev: Quitting, Up: Command Loop Prefix Command Arguments ======================== Most XEmacs commands can use a "prefix argument", a number specified before the command itself. (Don't confuse prefix arguments with prefix keys.) The prefix argument is at all times represented by a value, which may be `nil', meaning there is currently no prefix argument. Each command may use the prefix argument or ignore it. There are two representations of the prefix argument: "raw" and "numeric". The editor command loop uses the raw representation internally, and so do the Lisp variables that store the information, but commands can request either representation. Here are the possible values of a raw prefix argument: * `nil', meaning there is no prefix argument. Its numeric value is 1, but numerous commands make a distinction between `nil' and the integer 1. * An integer, which stands for itself. * A list of one element, which is an integer. This form of prefix argument results from one or a succession of `C-u''s with no digits. The numeric value is the integer in the list, but some commands make a distinction between such a list and an integer alone. * The symbol `-'. This indicates that `M--' or `C-u -' was typed, without following digits. The equivalent numeric value is -1, but some commands make a distinction between the integer -1 and the symbol `-'. We illustrate these possibilities by calling the following function with various prefixes: (defun display-prefix (arg) "Display the value of the raw prefix arg." (interactive "P") (message "%s" arg)) Here are the results of calling `display-prefix' with various raw prefix arguments: M-x display-prefix -| nil C-u M-x display-prefix -| (4) C-u C-u M-x display-prefix -| (16) C-u 3 M-x display-prefix -| 3 M-3 M-x display-prefix -| 3 ; (Same as `C-u 3'.) C-3 M-x display-prefix -| 3 ; (Same as `C-u 3'.) C-u - M-x display-prefix -| - M-- M-x display-prefix -| - ; (Same as `C-u -'.) C-- M-x display-prefix -| - ; (Same as `C-u -'.) C-u - 7 M-x display-prefix -| -7 M-- 7 M-x display-prefix -| -7 ; (Same as `C-u -7'.) C-- 7 M-x display-prefix -| -7 ; (Same as `C-u -7'.) XEmacs uses two variables to store the prefix argument: `prefix-arg' and `current-prefix-arg'. Commands such as `universal-argument' that set up prefix arguments for other commands store them in `prefix-arg'. In contrast, `current-prefix-arg' conveys the prefix argument to the current command, so setting it has no effect on the prefix arguments for future commands. Normally, commands specify which representation to use for the prefix argument, either numeric or raw, in the `interactive' declaration. (*Note Using Interactive::.) Alternatively, functions may look at the value of the prefix argument directly in the variable `current-prefix-arg', but this is less clean. - Function: prefix-numeric-value raw This function returns the numeric meaning of a valid raw prefix argument value, RAW. The argument may be a symbol, a number, or a list. If it is `nil', the value 1 is returned; if it is `-', the value -1 is returned; if it is a number, that number is returned; if it is a list, the CAR of that list (which should be a number) is returned. - Variable: current-prefix-arg This variable holds the raw prefix argument for the _current_ command. Commands may examine it directly, but the usual way to access it is with `(interactive "P")'. - Variable: prefix-arg The value of this variable is the raw prefix argument for the _next_ editing command. Commands that specify prefix arguments for the following command work by setting this variable. Do not call the functions `universal-argument', `digit-argument', or `negative-argument' unless you intend to let the user enter the prefix argument for the _next_ command. - Command: universal-argument This command reads input and specifies a prefix argument for the following command. Don't call this command yourself unless you know what you are doing. - Command: digit-argument arg This command adds to the prefix argument for the following command. The argument ARG is the raw prefix argument as it was before this command; it is used to compute the updated prefix argument. Don't call this command yourself unless you know what you are doing. - Command: negative-argument arg This command adds to the numeric argument for the next command. The argument ARG is the raw prefix argument as it was before this command; its value is negated to form the new prefix argument. Don't call this command yourself unless you know what you are doing.  File: lispref.info, Node: Recursive Editing, Next: Disabling Commands, Prev: Prefix Command Arguments, Up: Command Loop Recursive Editing ================= The XEmacs command loop is entered automatically when XEmacs starts up. This top-level invocation of the command loop never exits; it keeps running as long as XEmacs does. Lisp programs can also invoke the command loop. Since this makes more than one activation of the command loop, we call it "recursive editing". A recursive editing level has the effect of suspending whatever command invoked it and permitting the user to do arbitrary editing before resuming that command. The commands available during recursive editing are the same ones available in the top-level editing loop and defined in the keymaps. Only a few special commands exit the recursive editing level; the others return to the recursive editing level when they finish. (The special commands for exiting are always available, but they do nothing when recursive editing is not in progress.) All command loops, including recursive ones, set up all-purpose error handlers so that an error in a command run from the command loop will not exit the loop. Minibuffer input is a special kind of recursive editing. It has a few special wrinkles, such as enabling display of the minibuffer and the minibuffer window, but fewer than you might suppose. Certain keys behave differently in the minibuffer, but that is only because of the minibuffer's local map; if you switch windows, you get the usual XEmacs commands. To invoke a recursive editing level, call the function `recursive-edit'. This function contains the command loop; it also contains a call to `catch' with tag `exit', which makes it possible to exit the recursive editing level by throwing to `exit' (*note Catch and Throw::). If you throw a value other than `t', then `recursive-edit' returns normally to the function that called it. The command `C-M-c' (`exit-recursive-edit') does this. Throwing a `t' value causes `recursive-edit' to quit, so that control returns to the command loop one level up. This is called "aborting", and is done by `C-]' (`abort-recursive-edit'). Most applications should not use recursive editing, except as part of using the minibuffer. Usually it is more convenient for the user if you change the major mode of the current buffer temporarily to a special major mode, which should have a command to go back to the previous mode. (The `e' command in Rmail uses this technique.) Or, if you wish to give the user different text to edit "recursively", create and select a new buffer in a special mode. In this mode, define a command to complete the processing and go back to the previous buffer. (The `m' command in Rmail does this.) Recursive edits are useful in debugging. You can insert a call to `debug' into a function definition as a sort of breakpoint, so that you can look around when the function gets there. `debug' invokes a recursive edit but also provides the other features of the debugger. Recursive editing levels are also used when you type `C-r' in `query-replace' or use `C-x q' (`kbd-macro-query'). - Command: recursive-edit This function invokes the editor command loop. It is called automatically by the initialization of XEmacs, to let the user begin editing. When called from a Lisp program, it enters a recursive editing level. In the following example, the function `simple-rec' first advances point one word, then enters a recursive edit, printing out a message in the echo area. The user can then do any editing desired, and then type `C-M-c' to exit and continue executing `simple-rec'. (defun simple-rec () (forward-word 1) (message "Recursive edit in progress") (recursive-edit) (forward-word 1)) => simple-rec (simple-rec) => nil - Command: exit-recursive-edit This function exits from the innermost recursive edit (including minibuffer input). Its definition is effectively `(throw 'exit nil)'. - Command: abort-recursive-edit This function aborts the command that requested the innermost recursive edit (including minibuffer input), by signaling `quit' after exiting the recursive edit. Its definition is effectively `(throw 'exit t)'. *Note Quitting::. - Command: top-level This function exits all recursive editing levels; it does not return a value, as it jumps completely out of any computation directly back to the main command loop. - Function: recursion-depth This function returns the current depth of recursive edits. When no recursive edit is active, it returns 0.  File: lispref.info, Node: Disabling Commands, Next: Command History, Prev: Recursive Editing, Up: Command Loop Disabling Commands ================== "Disabling a command" marks the command as requiring user confirmation before it can be executed. Disabling is used for commands which might be confusing to beginning users, to prevent them from using the commands by accident. The low-level mechanism for disabling a command is to put a non-`nil' `disabled' property on the Lisp symbol for the command. These properties are normally set up by the user's `.emacs' file with Lisp expressions such as this: (put 'upcase-region 'disabled t) For a few commands, these properties are present by default and may be removed by the `.emacs' file. If the value of the `disabled' property is a string, the message saying the command is disabled includes that string. For example: (put 'delete-region 'disabled "Text deleted this way cannot be yanked back!\n") *Note Disabling: (xemacs)Disabling, for the details on what happens when a disabled command is invoked interactively. Disabling a command has no effect on calling it as a function from Lisp programs. - Command: enable-command command Allow COMMAND to be executed without special confirmation from now on, and (if the user confirms) alter the user's `.emacs' file so that this will apply to future sessions. - Command: disable-command command Require special confirmation to execute COMMAND from now on, and (if the user confirms) alter the user's `.emacs' file so that this will apply to future sessions. - Variable: disabled-command-hook This normal hook is run instead of a disabled command, when the user invokes the disabled command interactively. The hook functions can use `this-command-keys' to determine what the user typed to run the command, and thus find the command itself. *Note Hooks::. By default, `disabled-command-hook' contains a function that asks the user whether to proceed.  File: lispref.info, Node: Command History, Next: Keyboard Macros, Prev: Disabling Commands, Up: Command Loop Command History =============== The command loop keeps a history of the complex commands that have been executed, to make it convenient to repeat these commands. A "complex command" is one for which the interactive argument reading uses the minibuffer. This includes any `M-x' command, any `M-:' command, and any command whose `interactive' specification reads an argument from the minibuffer. Explicit use of the minibuffer during the execution of the command itself does not cause the command to be considered complex. - Variable: command-history This variable's value is a list of recent complex commands, each represented as a form to evaluate. It continues to accumulate all complex commands for the duration of the editing session, but all but the first (most recent) thirty elements are deleted when a garbage collection takes place (*note Garbage Collection::). command-history => ((switch-to-buffer "chistory.texi") (describe-key "^X^[") (visit-tags-table "~/emacs/src/") (find-tag "repeat-complex-command")) This history list is actually a special case of minibuffer history (*note Minibuffer History::), with one special twist: the elements are expressions rather than strings. There are a number of commands devoted to the editing and recall of previous commands. The commands `repeat-complex-command', and `list-command-history' are described in the user manual (*note Repetition: (xemacs)Repetition.). Within the minibuffer, the history commands used are the same ones available in any minibuffer.  File: lispref.info, Node: Keyboard Macros, Prev: Command History, Up: Command Loop Keyboard Macros =============== A "keyboard macro" is a canned sequence of input events that can be considered a command and made the definition of a key. The Lisp representation of a keyboard macro is a string or vector containing the events. Don't confuse keyboard macros with Lisp macros (*note Macros::). - Function: execute-kbd-macro macro &optional count This function executes MACRO as a sequence of events. If MACRO is a string or vector, then the events in it are executed exactly as if they had been input by the user. The sequence is _not_ expected to be a single key sequence; normally a keyboard macro definition consists of several key sequences concatenated. If MACRO is a symbol, then its function definition is used in place of MACRO. If that is another symbol, this process repeats. Eventually the result should be a string or vector. If the result is not a symbol, string, or vector, an error is signaled. The argument COUNT is a repeat count; MACRO is executed that many times. If COUNT is omitted or `nil', MACRO is executed once. If it is 0, MACRO is executed over and over until it encounters an error or a failing search. - Variable: executing-macro This variable contains the string or vector that defines the keyboard macro that is currently executing. It is `nil' if no macro is currently executing. A command can test this variable to behave differently when run from an executing macro. Do not set this variable yourself. - Variable: defining-kbd-macro This variable indicates whether a keyboard macro is being defined. A command can test this variable to behave differently while a macro is being defined. The commands `start-kbd-macro' and `end-kbd-macro' set this variable--do not set it yourself. - Variable: last-kbd-macro This variable is the definition of the most recently defined keyboard macro. Its value is a string or vector, or `nil'. The commands are described in the user's manual (*note Keyboard Macros: (xemacs)Keyboard Macros.).  File: lispref.info, Node: Keymaps, Next: Menus, Prev: Command Loop, Up: Top Keymaps ******* The bindings between input events and commands are recorded in data structures called "keymaps". Each binding in a keymap associates (or "binds") an individual event type either with another keymap or with a command. When an event is bound to a keymap, that keymap is used to look up the next input event; this continues until a command is found. The whole process is called "key lookup". * Menu: * Keymap Terminology:: Definitions of terms pertaining to keymaps. * Format of Keymaps:: What a keymap looks like as a Lisp object. * Creating Keymaps:: Functions to create and copy keymaps. * Inheritance and Keymaps:: How one keymap can inherit the bindings of another keymap. * Key Sequences:: How to specify key sequences. * Prefix Keys:: Defining a key with a keymap as its definition. * Active Keymaps:: Each buffer has a local keymap to override the standard (global) bindings. A minor mode can also override them. * Key Lookup:: How extracting elements from keymaps works. * Functions for Key Lookup:: How to request key lookup. * Changing Key Bindings:: Redefining a key in a keymap. * Key Binding Commands:: Interactive interfaces for redefining keys. * Scanning Keymaps:: Looking through all keymaps, for printing help. * Other Keymap Functions:: Miscellaneous keymap functions.  File: lispref.info, Node: Keymap Terminology, Next: Format of Keymaps, Up: Keymaps Keymap Terminology ================== A "keymap" is a table mapping event types to definitions (which can be any Lisp objects, though only certain types are meaningful for execution by the command loop). Given an event (or an event type) and a keymap, XEmacs can get the event's definition. Events mapped in keymaps include keypresses, button presses, and button releases (*note Events::). A sequence of input events that form a unit is called a "key sequence", or "key" for short. A sequence of one event is always a key sequence, and so are some multi-event sequences. A keymap determines a binding or definition for any key sequence. If the key sequence is a single event, its binding is the definition of the event in the keymap. The binding of a key sequence of more than one event is found by an iterative process: the binding of the first event is found, and must be a keymap; then the second event's binding is found in that keymap, and so on until all the events in the key sequence are used up. If the binding of a key sequence is a keymap, we call the key sequence a "prefix key". Otherwise, we call it a "complete key" (because no more events can be added to it). If the binding is `nil', we call the key "undefined". Examples of prefix keys are `C-c', `C-x', and `C-x 4'. Examples of defined complete keys are `X', , and `C-x 4 C-f'. Examples of undefined complete keys are `C-x C-g', and `C-c 3'. *Note Prefix Keys::, for more details. The rule for finding the binding of a key sequence assumes that the intermediate bindings (found for the events before the last) are all keymaps; if this is not so, the sequence of events does not form a unit--it is not really a key sequence. In other words, removing one or more events from the end of any valid key must always yield a prefix key. For example, `C-f C-n' is not a key; `C-f' is not a prefix key, so a longer sequence starting with `C-f' cannot be a key. Note that the set of possible multi-event key sequences depends on the bindings for prefix keys; therefore, it can be different for different keymaps, and can change when bindings are changed. However, a one-event sequence is always a key sequence, because it does not depend on any prefix keys for its well-formedness. At any time, several primary keymaps are "active"--that is, in use for finding key bindings. These are the "global map", which is shared by all buffers; the "local keymap", which is usually associated with a specific major mode; and zero or more "minor mode keymaps", which belong to currently enabled minor modes. (Not all minor modes have keymaps.) The local keymap bindings shadow (i.e., take precedence over) the corresponding global bindings. The minor mode keymaps shadow both local and global keymaps. *Note Active Keymaps::, for details.  File: lispref.info, Node: Format of Keymaps, Next: Creating Keymaps, Prev: Keymap Terminology, Up: Keymaps Format of Keymaps ================= A keymap is a primitive type that associates events with their bindings. Note that this is different from Emacs 18 and FSF Emacs, where keymaps are lists. - Function: keymapp object This function returns `t' if OBJECT is a keymap, `nil' otherwise.  File: lispref.info, Node: Creating Keymaps, Next: Inheritance and Keymaps, Prev: Format of Keymaps, Up: Keymaps Creating Keymaps ================ Here we describe the functions for creating keymaps. - Function: make-keymap &optional name This function constructs and returns a new keymap object. All entries in it are `nil', meaning "command undefined". Optional argument NAME specifies a name to assign to the keymap, as in `set-keymap-name'. This name is only a debugging convenience; it is not used except when printing the keymap. - Function: make-sparse-keymap &optional name This function constructs and returns a new keymap object. All entries in it are `nil', meaning "command undefined". The only difference between this function and `make-keymap' is that this function returns a "smaller" keymap (one that is expected to contain fewer entries). As keymaps dynamically resize, this distinction is not great. Optional argument NAME specifies a name to assign to the keymap, as in `set-keymap-name'. This name is only a debugging convenience; it is not used except when printing the keymap. - Function: set-keymap-name keymap new-name This function assigns a "name" to a keymap. The name is only a debugging convenience; it is not used except when printing the keymap. - Function: keymap-name keymap This function returns the "name" of a keymap, as assigned using `set-keymap-name'. - Function: copy-keymap keymap This function returns a copy of KEYMAP. Any keymaps that appear directly as bindings in KEYMAP are also copied recursively, and so on to any number of levels. However, recursive copying does not take place when the definition of a character is a symbol whose function definition is a keymap; the same symbol appears in the new copy. (setq map (copy-keymap (current-local-map))) => # (eq map (current-local-map)) => nil  File: lispref.info, Node: Inheritance and Keymaps, Next: Key Sequences, Prev: Creating Keymaps, Up: Keymaps Inheritance and Keymaps ======================= A keymap can inherit the bindings of other keymaps. The other keymaps are called the keymap's "parents", and are set with `set-keymap-parents'. When searching for a binding for a key sequence in a particular keymap, that keymap itself will first be searched; then, if no binding was found in the map and it has parents, the first parent keymap will be searched; then that keymap's parent will be searched, and so on, until either a binding for the key sequence is found, or a keymap without a parent is encountered. At this point, the search will continue with the next parent of the most recently encountered keymap that has another parent, etc. Essentially, a depth-first search of all the ancestors of the keymap is conducted. `(current-global-map)' is the default parent of all keymaps. - Function: set-keymap-parents keymap parents This function sets the parent keymaps of KEYMAP to the list PARENTS. If you change the bindings in one of the keymaps in PARENTS using `define-key' or other key-binding functions, these changes are visible in KEYMAP unless shadowed by bindings in that map or in earlier-searched ancestors. The converse is not true: if you use `define-key' to change KEYMAP, that affects the bindings in that map, but has no effect on any of the keymaps in PARENTS. - Function: keymap-parents keymap This function returns the list of parent keymaps of KEYMAP, or `nil' if KEYMAP has no parents. As an alternative to specifying a parent, you can also specify a "default binding" that is used whenever a key is not otherwise bound in the keymap. This is useful for terminal emulators, for example, which may want to trap all keystrokes and pass them on in some modified format. Note that if you specify a default binding for a keymap, neither the keymap's parents nor the current global map are searched for key bindings. - Function: set-keymap-default-binding keymap command This function sets the default binding of KEYMAP to COMMAND, or `nil' if no default is desired. - Function: keymap-default-binding keymap This function returns the default binding of KEYMAP, or `nil' if it has none.  File: lispref.info, Node: Key Sequences, Next: Prefix Keys, Prev: Inheritance and Keymaps, Up: Keymaps Key Sequences ============= Contrary to popular belief, the world is not ASCII. When running under a window manager, XEmacs can tell the difference between, for example, the keystrokes `control-h', `control-shift-h', and `backspace'. You can, in fact, bind different commands to each of these. A "key sequence" is a set of keystrokes. A "keystroke" is a keysym and some set of modifiers (such as and ). A "keysym" is what is printed on the keys on your keyboard. A keysym may be represented by a symbol, or (if and only if it is equivalent to an ASCII character in the range 32 - 255) by a character or its equivalent ASCII code. The `A' key may be represented by the symbol `A', the character `?A', or by the number 65. The `break' key may be represented only by the symbol `break'. A keystroke may be represented by a list: the last element of the list is the key (a symbol, character, or number, as above) and the preceding elements are the symbolic names of modifier keys (, , , , , and ). Thus, the sequence `control-b' is represented by the forms `(control b)', `(control ?b)', and `(control 98)'. A keystroke may also be represented by an event object, as returned by the `next-command-event' and `read-key-sequence' functions. Note that in this context, the keystroke `control-b' is _not_ represented by the number 2 (the ASCII code for `^B') or the character `?\^B'. See below. The modifier is somewhat of a special case. You should not (and cannot) use `(meta shift a)' to mean `(meta A)', since for characters that have ASCII equivalents, the state of the shift key is implicit in the keysym (`a' vs. `A'). You also cannot say `(shift =)' to mean `+', as that sort of thing varies from keyboard to keyboard. The modifier is for use only with characters that do not have a second keysym on the same key, such as `backspace' and `tab'. A key sequence is a vector of keystrokes. As a degenerate case, elements of this vector may also be keysyms if they have no modifiers. That is, the `A' keystroke is represented by all of these forms: A ?A 65 (A) (?A) (65) [A] [?A] [65] [(A)] [(?A)] [(65)] the `control-a' keystroke is represented by these forms: (control A) (control ?A) (control 65) [(control A)] [(control ?A)] [(control 65)] the key sequence `control-c control-a' is represented by these forms: [(control c) (control a)] [(control ?c) (control ?a)] [(control 99) (control 65)] etc. Mouse button clicks work just like keypresses: `(control button1)' means pressing the left mouse button while holding down the control key. `[(control c) (shift button3)]' means `control-c', hold , click right. Commands may be bound to the mouse-button up-stroke rather than the down-stroke as well. `button1' means the down-stroke, and `button1up' means the up-stroke. Different commands may be bound to the up and down strokes, though that is probably not what you want, so be careful. For backward compatibility, a key sequence may also be represented by a string. In this case, it represents the key sequence(s) that would produce that sequence of ASCII characters in a purely ASCII world. For example, a string containing the ASCII backspace character, `"\^H"', would represent two key sequences: `(control h)' and `backspace'. Binding a command to this will actually bind both of those key sequences. Likewise for the following pairs: control h backspace control i tab control m return control j linefeed control [ escape control @ control space After binding a command to two key sequences with a form like (define-key global-map "\^X\^I" 'command-1) it is possible to redefine only one of those sequences like so: (define-key global-map [(control x) (control i)] 'command-2) (define-key global-map [(control x) tab] 'command-3) Of course, all of this applies only when running under a window system. If you're talking to XEmacs through a TTY connection, you don't get any of these features. - Function: event-matches-key-specifier-p event key-specifier This function returns non-`nil' if EVENT matches KEY-SPECIFIER, which can be any valid form representing a key sequence. This can be useful, e.g., to determine if the user pressed `help-char' or `quit-char'.  File: lispref.info, Node: Prefix Keys, Next: Active Keymaps, Prev: Key Sequences, Up: Keymaps Prefix Keys =========== A "prefix key" has an associated keymap that defines what to do with key sequences that start with the prefix key. For example, `C-x' is a prefix key, and it uses a keymap that is also stored in the variable `ctl-x-map'. Here is a list of the standard prefix keys of XEmacs and their keymaps: * `help-map' is used for events that follow `C-h'. * `mode-specific-map' is for events that follow `C-c'. This map is not actually mode specific; its name was chosen to be informative for the user in `C-h b' (`display-bindings'), where it describes the main use of the `C-c' prefix key. * `ctl-x-map' is the map used for events that follow `C-x'. This map is also the function definition of `Control-X-prefix'. * `ctl-x-4-map' is used for events that follow `C-x 4'. * `ctl-x-5-map' is used for events that follow `C-x 5'. * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have no special name. * `esc-map' is an evil hack that is present for compatibility purposes with Emacs 18. Defining a key in `esc-map' is equivalent to defining the same key in `global-map' but with the prefix added. You should _not_ use this in your code. (This map is also the function definition of `ESC-prefix'.) The binding of a prefix key is the keymap to use for looking up the events that follow the prefix key. (It may instead be a symbol whose function definition is a keymap. The effect is the same, but the symbol serves as a name for the prefix key.) Thus, the binding of `C-x' is the symbol `Control-X-prefix', whose function definition is the keymap for `C-x' commands. (The same keymap is also the value of `ctl-x-map'.) Prefix key definitions can appear in any active keymap. The definitions of `C-c', `C-x', `C-h' and as prefix keys appear in the global map, so these prefix keys are always available. Major and minor modes can redefine a key as a prefix by putting a prefix key definition for it in the local map or the minor mode's map. *Note Active Keymaps::. If a key is defined as a prefix in more than one active map, then its various definitions are in effect merged: the commands defined in the minor mode keymaps come first, followed by those in the local map's prefix definition, and then by those from the global map. In the following example, we make `C-p' a prefix key in the local keymap, in such a way that `C-p' is identical to `C-x'. Then the binding for `C-p C-f' is the function `find-file', just like `C-x C-f'. The key sequence `C-p 6' is not found in any active keymap. (use-local-map (make-sparse-keymap)) => nil (local-set-key "\C-p" ctl-x-map) => nil (key-binding "\C-p\C-f") => find-file (key-binding "\C-p6") => nil - Function: define-prefix-command symbol &optional mapvar This function defines SYMBOL as a prefix command: it creates a keymap and stores it as SYMBOL's function definition. Storing the symbol as the binding of a key makes the key a prefix key that has a name. If optional argument MAPVAR is not specified, it also sets SYMBOL as a variable, to have the keymap as its value. (If MAPVAR is given and is not `t', its value is stored as the value of SYMBOL.) The function returns SYMBOL. In Emacs version 18, only the function definition of SYMBOL was set, not the value as a variable.  File: lispref.info, Node: Active Keymaps, Next: Key Lookup, Prev: Prefix Keys, Up: Keymaps Active Keymaps ============== XEmacs normally contains many keymaps; at any given time, just a few of them are "active" in that they participate in the interpretation of user input. These are the global keymap, the current buffer's local keymap, and the keymaps of any enabled minor modes. The "global keymap" holds the bindings of keys that are defined regardless of the current buffer, such as `C-f'. The variable `global-map' holds this keymap, which is always active. Each buffer may have another keymap, its "local keymap", which may contain new or overriding definitions for keys. The current buffer's local keymap is always active except when `overriding-local-map' or `overriding-terminal-local-map' overrides it. Extents and text properties can specify an alternative local map for certain parts of the buffer; see *Note Extents and Events::. Each minor mode may have a keymap; if it does, the keymap is active when the minor mode is enabled. The variable `overriding-local-map' and `overriding-terminal-local-map', if non-`nil', specify other local keymaps that override the buffer's local map and all the minor mode keymaps. All the active keymaps are used together to determine what command to execute when a key is entered. XEmacs searches these maps one by one, in order of decreasing precedence, until it finds a binding in one of the maps. More specifically: For key-presses, the order of keymaps searched is: * the `keymap' property of any extent(s) or text properties at point; * any applicable minor-mode maps; * the current local map of the current buffer; * the current global map. For mouse-clicks, the order of keymaps searched is: * the current local map of the `mouse-grabbed-buffer' if any; * the `keymap' property of any extent(s) at the position of the click (this includes modeline extents); * the `modeline-map' of the buffer corresponding to the modeline under the mouse (if the click happened over a modeline); * the value of `toolbar-map' in the current buffer (if the click happened over a toolbar); * the current local map of the buffer under the mouse (does not apply to toolbar clicks); * any applicable minor-mode maps; * the current global map. Note that if `overriding-local-map' or `overriding-terminal-local-map' is non-`nil', _only_ those two maps and the current global map are searched. The procedure for searching a single keymap is called "key lookup"; see *Note Key Lookup::. Since every buffer that uses the same major mode normally uses the same local keymap, you can think of the keymap as local to the mode. A change to the local keymap of a buffer (using `local-set-key', for example) is seen also in the other buffers that share that keymap. The local keymaps that are used for Lisp mode, C mode, and several other major modes exist even if they have not yet been used. These local maps are the values of the variables `lisp-mode-map', `c-mode-map', and so on. For most other modes, which are less frequently used, the local keymap is constructed only when the mode is used for the first time in a session. The minibuffer has local keymaps, too; they contain various completion and exit commands. *Note Intro to Minibuffers::. *Note Standard Keymaps::, for a list of standard keymaps. - Function: current-keymaps &optional event-or-keys This function returns a list of the current keymaps that will be searched for bindings. This lists keymaps such as the current local map and the minor-mode maps, but does not list the parents of those keymaps. EVENT-OR-KEYS controls which keymaps will be listed. If EVENT-OR-KEYS is a mouse event (or a vector whose last element is a mouse event), the keymaps for that mouse event will be listed. Otherwise, the keymaps for key presses will be listed. - Variable: global-map This variable contains the default global keymap that maps XEmacs keyboard input to commands. The global keymap is normally this keymap. The default global keymap is a full keymap that binds `self-insert-command' to all of the printing characters. It is normal practice to change the bindings in the global map, but you should not assign this variable any value other than the keymap it starts out with. - Function: current-global-map This function returns the current global keymap. This is the same as the value of `global-map' unless you change one or the other. (current-global-map) => # - Function: current-local-map &optional buffer This function returns BUFFER's local keymap, or `nil' if it has none. BUFFER defaults to the current buffer. In the following example, the keymap for the `*scratch*' buffer (using Lisp Interaction mode) has a number of entries, including one prefix key, `C-x'. (current-local-map) => # (describe-bindings-internal (current-local-map)) => ; Inserted into the buffer: backspace backward-delete-char-untabify linefeed eval-print-last-sexp delete delete-char C-j eval-print-last-sexp C-x << Prefix Command >> M-tab lisp-complete-symbol M-; lisp-indent-for-comment M-C-i lisp-complete-symbol M-C-q indent-sexp M-C-x eval-defun Alt-backspace backward-kill-sexp Alt-delete kill-sexp C-x x edebug-defun - Function: current-minor-mode-maps This function returns a list of the keymaps of currently enabled minor modes. - Function: use-global-map keymap This function makes KEYMAP the new current global keymap. It returns `nil'. It is very unusual to change the global keymap. - Function: use-local-map keymap &optional buffer This function makes KEYMAP the new local keymap of BUFFER. BUFFER defaults to the current buffer. If KEYMAP is `nil', then the buffer has no local keymap. `use-local-map' returns `nil'. Most major mode commands use this function. - Variable: minor-mode-map-alist This variable is an alist describing keymaps that may or may not be active according to the values of certain variables. Its elements look like this: (VARIABLE . KEYMAP) The keymap KEYMAP is active whenever VARIABLE has a non-`nil' value. Typically VARIABLE is the variable that enables or disables a minor mode. *Note Keymaps and Minor Modes::. Note that elements of `minor-mode-map-alist' do not have the same structure as elements of `minor-mode-alist'. The map must be the CDR of the element; a list with the map as the second element will not do. What's more, the keymap itself must appear in the CDR. It does not work to store a variable in the CDR and make the map the value of that variable. When more than one minor mode keymap is active, their order of priority is the order of `minor-mode-map-alist'. But you should design minor modes so that they don't interfere with each other. If you do this properly, the order will not matter. See also `minor-mode-key-binding', above. See *Note Keymaps and Minor Modes::, for more information about minor modes. - Variable: modeline-map This variable holds the keymap consulted for mouse-clicks on the modeline of a window. This variable may be buffer-local; its value will be looked up in the buffer of the window whose modeline was clicked upon. - Variable: toolbar-map This variable holds the keymap consulted for mouse-clicks over a toolbar. - Variable: mouse-grabbed-buffer If non-`nil', a buffer which should be consulted first for all mouse activity. When a mouse-click is processed, it will first be looked up in the local-map of this buffer, and then through the normal mechanism if there is no binding for that click. This buffer's value of `mode-motion-hook' will be consulted instead of the `mode-motion-hook' of the buffer of the window under the mouse. You should _bind_ this, not set it. - Variable: overriding-local-map If non-`nil', this variable holds a keymap to use instead of the buffer's local keymap and instead of all the minor mode keymaps. This keymap, if any, overrides all other maps that would have been active, except for the current global map. - Variable: overriding-terminal-local-map If non-`nil', this variable holds a keymap to use instead of the buffer's local keymap and instead of all the minor mode keymaps, but for the selected console only. (In other words, this variable is always console-local; putting a keymap here only applies to keystrokes coming from the selected console. *Note Consoles and Devices::.) This keymap, if any, overrides all other maps that would have been active, except for the current global map.  File: lispref.info, Node: Key Lookup, Next: Functions for Key Lookup, Prev: Active Keymaps, Up: Keymaps Key Lookup ========== "Key lookup" is the process of finding the binding of a key sequence from a given keymap. Actual execution of the binding is not part of key lookup. Key lookup uses just the event type of each event in the key sequence; the rest of the event is ignored. In fact, a key sequence used for key lookup may designate mouse events with just their types (symbols) instead of with entire mouse events (lists). *Note Events::. Such a pseudo-key-sequence is insufficient for `command-execute', but it is sufficient for looking up or rebinding a key. When the key sequence consists of multiple events, key lookup processes the events sequentially: the binding of the first event is found, and must be a keymap; then the second event's binding is found in that keymap, and so on until all the events in the key sequence are used up. (The binding thus found for the last event may or may not be a keymap.) Thus, the process of key lookup is defined in terms of a simpler process for looking up a single event in a keymap. How that is done depends on the type of object associated with the event in that keymap. Let's use the term "keymap entry" to describe the value found by looking up an event type in a keymap. (This doesn't include the item string and other extra elements in menu key bindings because `lookup-key' and other key lookup functions don't include them in the returned value.) While any Lisp object may be stored in a keymap as a keymap entry, not all make sense for key lookup. Here is a list of the meaningful kinds of keymap entries: `nil' `nil' means that the events used so far in the lookup form an undefined key. When a keymap fails to mention an event type at all, and has no default binding, that is equivalent to a binding of `nil' for that event type. KEYMAP The events used so far in the lookup form a prefix key. The next event of the key sequence is looked up in KEYMAP. COMMAND The events used so far in the lookup form a complete key, and COMMAND is its binding. *Note What Is a Function::. ARRAY The array (either a string or a vector) is a keyboard macro. The events used so far in the lookup form a complete key, and the array is its binding. See *Note Keyboard Macros::, for more information. (Note that you cannot use a shortened form of a key sequence here, such as `(control y)'; you must use the full form `[(control y)]'. *Note Key Sequences::.) LIST The meaning of a list depends on the types of the elements of the list. * If the CAR of LIST is `lambda', then the list is a lambda expression. This is presumed to be a command, and is treated as such (see above). * If the CAR of LIST is a keymap and the CDR is an event type, then this is an "indirect entry": (OTHERMAP . OTHERTYPE) When key lookup encounters an indirect entry, it looks up instead the binding of OTHERTYPE in OTHERMAP and uses that. This feature permits you to define one key as an alias for another key. For example, an entry whose CAR is the keymap called `esc-map' and whose CDR is 32 (the code for ) means, "Use the global binding of `Meta-', whatever that may be." SYMBOL The function definition of SYMBOL is used in place of SYMBOL. If that too is a symbol, then this process is repeated, any number of times. Ultimately this should lead to an object that is a keymap, a command or a keyboard macro. A list is allowed if it is a keymap or a command, but indirect entries are not understood when found via symbols. Note that keymaps and keyboard macros (strings and vectors) are not valid functions, so a symbol with a keymap, string, or vector as its function definition is invalid as a function. It is, however, valid as a key binding. If the definition is a keyboard macro, then the symbol is also valid as an argument to `command-execute' (*note Interactive Call::). The symbol `undefined' is worth special mention: it means to treat the key as undefined. Strictly speaking, the key is defined, and its binding is the command `undefined'; but that command does the same thing that is done automatically for an undefined key: it rings the bell (by calling `ding') but does not signal an error. `undefined' is used in local keymaps to override a global key binding and make the key "undefined" locally. A local binding of `nil' would fail to do this because it would not override the global binding. ANYTHING ELSE If any other type of object is found, the events used so far in the lookup form a complete key, and the object is its binding, but the binding is not executable as a command. In short, a keymap entry may be a keymap, a command, a keyboard macro, a symbol that leads to one of them, or an indirection or `nil'.  File: lispref.info, Node: Functions for Key Lookup, Next: Changing Key Bindings, Prev: Key Lookup, Up: Keymaps Functions for Key Lookup ======================== Here are the functions and variables pertaining to key lookup. - Function: lookup-key keymap key &optional accept-defaults This function returns the definition of KEY in KEYMAP. If the string or vector KEY is not a valid key sequence according to the prefix keys specified in KEYMAP (which means it is "too long" and has extra events at the end), then the value is a number, the number of events at the front of KEY that compose a complete key. If ACCEPT-DEFAULTS is non-`nil', then `lookup-key' considers default bindings as well as bindings for the specific events in KEY. Otherwise, `lookup-key' reports only bindings for the specific sequence KEY, ignoring default bindings except when you explicitly ask about them. All the other functions described in this chapter that look up keys use `lookup-key'. (lookup-key (current-global-map) "\C-x\C-f") => find-file (lookup-key (current-global-map) "\C-x\C-f12345") => 2 If KEY begins with the character whose value is contained in `meta-prefix-char', that character is implicitly removed and the modifier added to the key. Thus, the first example below is handled by conversion into the second example. (lookup-key (current-global-map) "\ef") => forward-word (lookup-key (current-global-map) "\M-f") => forward-word Unlike `read-key-sequence', this function does not modify the specified events in ways that discard information (*note Key Sequence Input::). In particular, it does not convert letters to lower case. - Command: undefined Used in keymaps to undefine keys. If a key sequence is defined to this, invoking this key sequence causes a "key undefined" error, just as if the key sequence had no binding. - Function: key-binding key &optional accept-defaults This function returns the binding for KEY in the current keymaps, trying all the active keymaps. The result is `nil' if KEY is undefined in the keymaps. The argument ACCEPT-DEFAULTS controls checking for default bindings, as in `lookup-key' (above). (key-binding "\C-x\C-f") => find-file (key-binding '(control home)) => beginning-of-buffer (key-binding [escape escape escape]) => keyboard-escape-quit - Function: local-key-binding keys &optional accept-defaults This function returns the binding for KEYS in the current local keymap, or `nil' if it is undefined there. The argument ACCEPT-DEFAULTS controls checking for default bindings, as in `lookup-key' (above). - Function: global-key-binding keys &optional accept-defaults This function returns the binding for command KEYS in the current global keymap, or `nil' if it is undefined there. The argument ACCEPT-DEFAULTS controls checking for default bindings, as in `lookup-key' (above). - Function: minor-mode-key-binding key &optional accept-defaults This function returns a list of all the active minor mode bindings of KEY. More precisely, it returns an alist of pairs `(MODENAME . BINDING)', where MODENAME is the variable that enables the minor mode, and BINDING is KEY's binding in that mode. If KEY has no minor-mode bindings, the value is `nil'. If the first binding is not a prefix command, all subsequent bindings from other minor modes are omitted, since they would be completely shadowed. Similarly, the list omits non-prefix bindings that follow prefix bindings. The argument ACCEPT-DEFAULTS controls checking for default bindings, as in `lookup-key' (above). - Variable: meta-prefix-char This variable is the meta-prefix character code. It is used when translating a two-character sequence to a meta character so it can be looked up in a keymap. For useful results, the value should be a prefix event (*note Prefix Keys::). The default value is `?\^[' (integer 27), which is the ASCII character usually produced by the key. As long as the value of `meta-prefix-char' remains `?\^[', key lookup translates ` b' into `M-b', which is normally defined as the `backward-word' command. However, if you set `meta-prefix-char' to `?\^X' (i.e. the keystroke `C-x') or its equivalent ASCII code `24', then XEmacs will translate `C-x b' (whose standard binding is the `switch-to-buffer' command) into `M-b'. meta-prefix-char ; The default value. => ?\^[ ; Under XEmacs 20. => 27 ; Under XEmacs 19. (key-binding "\eb") => backward-word ?\C-x ; The print representation ; of a character. => ?\^X ; Under XEmacs 20. => 24 ; Under XEmacs 19. (setq meta-prefix-char 24) => 24 (key-binding "\C-xb") => backward-word ; Now, typing `C-x b' is ; like typing `M-b'. (setq meta-prefix-char ?\e) ; Avoid confusion! ; Restore the default value! => ?\^[ ; Under XEmacs 20. => 27 ; Under XEmacs 19.  File: lispref.info, Node: Changing Key Bindings, Next: Key Binding Commands, Prev: Functions for Key Lookup, Up: Keymaps Changing Key Bindings ===================== The way to rebind a key is to change its entry in a keymap. If you change a binding in the global keymap, the change is effective in all buffers (though it has no direct effect in buffers that shadow the global binding with a local one). If you change the current buffer's local map, that usually affects all buffers using the same major mode. The `global-set-key' and `local-set-key' functions are convenient interfaces for these operations (*note Key Binding Commands::). You can also use `define-key', a more general function; then you must specify explicitly the map to change. The way to specify the key sequence that you want to rebind is described above (*note Key Sequences::). For the functions below, an error is signaled if KEYMAP is not a keymap or if KEY is not a string or vector representing a key sequence. You can use event types (symbols) as shorthand for events that are lists. - Function: define-key keymap key binding This function sets the binding for KEY in KEYMAP. (If KEY is more than one event long, the change is actually made in another keymap reached from KEYMAP.) The argument BINDING can be any Lisp object, but only certain types are meaningful. (For a list of meaningful types, see *Note Key Lookup::.) The value returned by `define-key' is BINDING. Every prefix of KEY must be a prefix key (i.e., bound to a keymap) or undefined; otherwise an error is signaled. If some prefix of KEY is undefined, then `define-key' defines it as a prefix key so that the rest of KEY may be defined as specified. Here is an example that creates a sparse keymap and makes a number of bindings in it: (setq map (make-sparse-keymap)) => # (define-key map "\C-f" 'forward-char) => forward-char map => # (describe-bindings-internal map) => ; (Inserted in buffer) C-f forward-char ;; Build sparse submap for `C-x' and bind `f' in that. (define-key map "\C-xf" 'forward-word) => forward-word map => # (describe-bindings-internal map) => ; (Inserted in buffer) C-f forward-char C-x << Prefix Command >> C-x f forward-word ;; Bind `C-p' to the `ctl-x-map'. (define-key map "\C-p" ctl-x-map) ;; `ctl-x-map' => # ;; Bind `C-f' to `foo' in the `ctl-x-map'. (define-key map "\C-p\C-f" 'foo) => foo map => # (describe-bindings-internal map) => ; (Inserted in buffer) C-f forward-char C-p << Prefix command Control-X-prefix >> C-x << Prefix Command >> C-p tab indent-rigidly C-p $ set-selective-display C-p ' expand-abbrev C-p ( start-kbd-macro C-p ) end-kbd-macro ... C-p C-x exchange-point-and-mark C-p C-z suspend-or-iconify-emacs C-p M-escape repeat-complex-command C-p M-C-[ repeat-complex-command C-x f forward-word C-p 4 . find-tag-other-window ... C-p 4 C-o display-buffer C-p 5 0 delete-frame ... C-p 5 C-f find-file-other-frame ... C-p a i g inverse-add-global-abbrev C-p a i l inverse-add-mode-abbrev Note that storing a new binding for `C-p C-f' actually works by changing an entry in `ctl-x-map', and this has the effect of changing the bindings of both `C-p C-f' and `C-x C-f' in the default global map. - Function: substitute-key-definition olddef newdef keymap &optional oldmap prefix This function replaces OLDDEF with NEWDEF for any keys in KEYMAP that were bound to OLDDEF. In other words, OLDDEF is replaced with NEWDEF wherever it appears. Prefix keymaps are checked recursively. The function returns `nil'. For example, this redefines `C-x C-f', if you do it in an XEmacs with standard bindings: (substitute-key-definition 'find-file 'find-file-read-only (current-global-map)) If OLDMAP is non-`nil', then its bindings determine which keys to rebind. The rebindings still happen in KEYMAP, not in OLDMAP. Thus, you can change one map under the control of the bindings in another. For example, (substitute-key-definition 'delete-backward-char 'my-funny-delete my-map global-map) puts the special deletion command in `my-map' for whichever keys are globally bound to the standard deletion command. If argument PREFIX is non-`nil', then only those occurrences of OLDDEF found in keymaps accessible through the keymap bound to PREFIX in KEYMAP are redefined. See also `accessible-keymaps'. - Function: suppress-keymap keymap &optional nodigits This function changes the contents of the full keymap KEYMAP by making all the printing characters undefined. More precisely, it binds them to the command `undefined'. This makes ordinary insertion of text impossible. `suppress-keymap' returns `nil'. If NODIGITS is `nil', then `suppress-keymap' defines digits to run `digit-argument', and `-' to run `negative-argument'. Otherwise it makes them undefined like the rest of the printing characters. The `suppress-keymap' function does not make it impossible to modify a buffer, as it does not suppress commands such as `yank' and `quoted-insert'. To prevent any modification of a buffer, make it read-only (*note Read Only Buffers::). Since this function modifies KEYMAP, you would normally use it on a newly created keymap. Operating on an existing keymap that is used for some other purpose is likely to cause trouble; for example, suppressing `global-map' would make it impossible to use most of XEmacs. Most often, `suppress-keymap' is used to initialize local keymaps of modes such as Rmail and Dired where insertion of text is not desirable and the buffer is read-only. Here is an example taken from the file `emacs/lisp/dired.el', showing how the local keymap for Dired mode is set up: ... (setq dired-mode-map (make-keymap)) (suppress-keymap dired-mode-map) (define-key dired-mode-map "r" 'dired-rename-file) (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted) (define-key dired-mode-map "d" 'dired-flag-file-deleted) (define-key dired-mode-map "v" 'dired-view-file) (define-key dired-mode-map "e" 'dired-find-file) (define-key dired-mode-map "f" 'dired-find-file) ...  File: lispref.info, Node: Key Binding Commands, Next: Scanning Keymaps, Prev: Changing Key Bindings, Up: Keymaps Commands for Binding Keys ========================= This section describes some convenient interactive interfaces for changing key bindings. They work by calling `define-key'. People often use `global-set-key' in their `.emacs' file for simple customization. For example, (global-set-key "\C-x\C-\\" 'next-line) or (global-set-key [(control ?x) (control ?\\)] 'next-line) or (global-set-key [?\C-x ?\C-\\] 'next-line) redefines `C-x C-\' to move down a line. (global-set-key [(meta button1)] 'mouse-set-point) redefines the first (leftmost) mouse button, typed with the Meta key, to set point where you click. - Command: global-set-key key definition This function sets the binding of KEY in the current global map to DEFINITION. (global-set-key KEY DEFINITION) == (define-key (current-global-map) KEY DEFINITION) - Command: global-unset-key key This function removes the binding of KEY from the current global map. One use of this function is in preparation for defining a longer key that uses KEY as a prefix--which would not be allowed if KEY has a non-prefix binding. For example: (global-unset-key "\C-l") => nil (global-set-key "\C-l\C-l" 'redraw-display) => nil This function is implemented simply using `define-key': (global-unset-key KEY) == (define-key (current-global-map) KEY nil) - Command: local-set-key key definition This function sets the binding of KEY in the current local keymap to DEFINITION. (local-set-key KEY DEFINITION) == (define-key (current-local-map) KEY DEFINITION) - Command: local-unset-key key This function removes the binding of KEY from the current local map. (local-unset-key KEY) == (define-key (current-local-map) KEY nil)  File: lispref.info, Node: Scanning Keymaps, Next: Other Keymap Functions, Prev: Key Binding Commands, Up: Keymaps Scanning Keymaps ================ This section describes functions used to scan all the current keymaps, or all keys within a keymap, for the sake of printing help information. - Function: accessible-keymaps keymap &optional prefix This function returns a list of all the keymaps that can be accessed (via prefix keys) from KEYMAP. The value is an association list with elements of the form `(KEY . MAP)', where KEY is a prefix key whose definition in KEYMAP is MAP. The elements of the alist are ordered so that the KEY increases in length. The first element is always `([] . KEYMAP)', because the specified keymap is accessible from itself with a prefix of no events. If PREFIX is given, it should be a prefix key sequence; then `accessible-keymaps' includes only the submaps whose prefixes start with PREFIX. These elements look just as they do in the value of `(accessible-keymaps)'; the only difference is that some elements are omitted. In the example below, the returned alist indicates that the key `C-x', which is displayed as `[(control x)]', is a prefix key whose definition is the keymap `#) 1 entry 0x8a2>'. (The strange notation for the keymap's name indicates that this is an internal submap of `emacs-lisp-mode-map'. This is because `lisp-interaction-mode-map' has set up `emacs-lisp-mode-map' as its parent, and `lisp-interaction-mode-map' defines no key sequences beginning with `C-x'.) (current-local-map) => # (accessible-keymaps (current-local-map)) =>(([] . #) ([(control x)] . #) 1 entry 0x8a2>)) The following example shows the results of calling `accessible-keymaps' on a large, complex keymap. Notice how some keymaps were given explicit names using `set-keymap-name'; those submaps without explicit names are given descriptive names indicating their relationship to their enclosing keymap. (accessible-keymaps (current-global-map)) => (([] . #) ([(control c)] . #) ([(control h)] . #) ([(control x)] . #) ([(meta escape)] . #) 3 entries 0x3e0>) ([(meta control \[)] . #) 3 entries 0x3e0>) ([f1] . #) ([(control x) \4] . #) ([(control x) \5] . #) ([(control x) \6] . #) ([(control x) a] . #) 8 entries 0x3ef>) ([(control x) n] . #) ([(control x) r] . #) ([(control x) v] . #) ([(control x) a i] . #) 8 entries 0x3ef>) 2 entries 0x3f5>)) - Function: map-keymap function keymap &optional sort-first This function applies FUNCTION to each element of KEYMAP. FUNCTION will be called with two arguments: a key-description list, and the binding. The order in which the elements of the keymap are passed to the function is unspecified. If the function inserts new elements into the keymap, it may or may not be called with them later. No element of the keymap will ever be passed to the function more than once. The function will not be called on elements of this keymap's parents (*note Inheritance and Keymaps::) or upon keymaps which are contained within this keymap (multi-character definitions). It will be called on characters since they are not really two-character sequences. If the optional third argument SORT-FIRST is non-`nil', then the elements of the keymap will be passed to the mapper function in a canonical order. Otherwise, they will be passed in hash (that is, random) order, which is faster. - Function: keymap-fullness keymap This function returns the number of bindings in the keymap. - Function: where-is-internal definition &optional keymaps firstonly noindirect event-or-keys This function returns a list of key sequences (of any length) that are bound to DEFINITION in a set of keymaps. The argument DEFINITION can be any object; it is compared with all keymap entries using `eq'. KEYMAPS can be either a keymap (meaning search in that keymap and the current global keymap) or a list of keymaps (meaning search in exactly those keymaps and no others). If KEYMAPS is nil, search in the currently applicable maps for EVENT-OR-KEYS. If KEYMAPS is a keymap, then the maps searched are KEYMAPS and the global keymap. If KEYMAPS is a list of keymaps, then the maps searched are exactly those keymaps, and no others. If KEYMAPS is `nil', then the maps used are the current active keymaps for EVENT-OR-KEYS (this is equivalent to specifying `(current-keymaps EVENT-OR-KEYS)' as the argument to KEYMAPS). If FIRSTONLY is non-`nil', then the value is a single vector representing the first key sequence found, rather than a list of all possible key sequences. If NOINDIRECT is non-`nil', `where-is-internal' doesn't follow indirect keymap bindings. This makes it possible to search for an indirect definition itself. This function is used by `where-is' (*note Help: (xemacs)Help.). (where-is-internal 'describe-function) => ([(control h) d] [(control h) f] [f1 d] [f1 f]) - Function: describe-bindings-internal map &optional all shadow prefix mouse-only-p This function inserts (into the current buffer) a list of all defined keys and their definitions in MAP. Optional second argument ALL says whether to include even "uninteresting" definitions, i.e. symbols with a non-`nil' `suppress-keymap' property. Third argument SHADOW is a list of keymaps whose bindings shadow those of map; if a binding is present in any shadowing map, it is not printed. Fourth argument PREFIX, if non-`nil', should be a key sequence; only bindings which start with that key sequence will be printed. Fifth argument MOUSE-ONLY-P says to only print bindings for mouse clicks. `describe-bindings-internal' is used to implement the help command `describe-bindings'. - Command: describe-bindings &optional prefix mouse-only-p This function creates a listing of all defined keys and their definitions. It writes the listing in a buffer named `*Help*' and displays it in a window. If optional argument PREFIX is non-`nil', it should be a prefix key; then the listing includes only keys that start with PREFIX. When several characters with consecutive ASCII codes have the same definition, they are shown together, as `FIRSTCHAR..LASTCHAR'. In this instance, you need to know the ASCII codes to understand which characters this means. For example, in the default global map, the characters ` .. ~' are described by a single line. is ASCII 32, `~' is ASCII 126, and the characters between them include all the normal printing characters, (e.g., letters, digits, punctuation, etc.); all these characters are bound to `self-insert-command'. If the second optional argument MOUSE-ONLY-P (prefix arg, interactively) is non-`nil' then only the mouse bindings are displayed.  File: lispref.info, Node: Other Keymap Functions, Prev: Scanning Keymaps, Up: Keymaps Other Keymap Functions ====================== - Function: set-keymap-prompt keymap new-prompt This function sets the "prompt" of KEYMAP to string NEW-PROMPT, or `nil' if no prompt is desired. The prompt is shown in the echo-area when reading a key-sequence to be looked-up in this keymap. - Function: keymap-prompt keymap &optional use-inherited This function returns the "prompt" of the given keymap. If USE-INHERITED is non-`nil', any parent keymaps will also be searched for a prompt.  File: lispref.info, Node: Menus, Next: Dialog Boxes, Prev: Keymaps, Up: Top Menus ***** * Menu: * Menu Format:: Format of a menu description. * Menubar Format:: How to specify a menubar. * Menubar:: Functions for controlling the menubar. * Modifying Menus:: Modifying a menu description. * Pop-Up Menus:: Functions for specifying pop-up menus. * Menu Filters:: Filter functions for the default menubar. * Menu Accelerators:: Using and controlling menu accelerator keys * Buffers Menu:: The menu that displays the list of buffers.  File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus Format of Menus =============== A menu is described using a "menu description", which is a list of menu items, keyword-value pairs, strings, and submenus. The menu description specifies which items are present in the menu, what function each item invokes, and whether the item is selectable or not. Pop-up menus are directly described with a menu description, while menubars are described slightly differently (see below). The first element of a menu must be a string, which is the name of the menu. This is the string that will be displayed in the parent menu or menubar, if any. This string is not displayed in the menu itself, except in the case of the top level pop-up menu, where there is no parent. In this case, the string will be displayed at the top of the menu if `popup-menu-titles' is non-`nil'. Immediately following the first element there may optionally be up to four keyword-value pairs, as follows: `:included FORM' This can be used to control the visibility of a menu. The form is evaluated and the menu will be omitted if the result is `nil'. `:config SYMBOL' This is an efficient shorthand for `:included (memq SYMBOL menubar-configuration)'. See the variable `menubar-configuration'. `:filter FUNCTION' A menu filter is used to sensitize or incrementally create a submenu only when it is selected by the user and not every time the menubar is activated. The filter function is passed the list of menu items in the submenu and must return a list of menu items to be used for the menu. It is called only when the menu is about to be displayed, so other menus may already be displayed. Vile and terrible things will happen if a menu filter function changes the current buffer, window, or frame. It also should not raise, lower, or iconify any frames. Basically, the filter function should have no side-effects. `:accelerator KEY' A menu accelerator is a keystroke which can be pressed while the menu is visible which will immediately activate the item. KEY must be a char or the symbol name of a key. *Note Menu Accelerators::. The rest of the menu consists of elements as follows: * A "menu item", which is a vector in the following form: `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]' NAME is a string, the name of the menu item; it is the string to display on the menu. It is filtered through the resource database, so it is possible for resources to override what string is actually displayed. CALLBACK is a form that will be invoked when the menu item is selected. If the callback of a menu item is a symbol, then it must name a command. It will be invoked with `call-interactively'. If it is a list, then it is evaluated with `eval'. The valid keywords and their meanings are described below. Note that for compatibility purposes, the form `[ NAME CALLBACK ACTIVE-P ]' is also accepted and is equivalent to `[ NAME CALLBACK :active ACTIVE-P ]' and the form `[ NAME CALLBACK ACTIVE-P SUFFIX]' is accepted and is equivalent to `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]' However, these older forms are deprecated and should generally not be used. * If an element of a menu is a string, then that string will be presented in the menu as unselectable text. * If an element of a menu is a string consisting solely of hyphens, then that item will be presented as a solid horizontal line. * If an element of a menu is a string beginning with `--:', then a particular sort of horizontal line will be displayed, as follows: `"--:singleLine"' A solid horizontal line. This is equivalent to a string consisting solely of hyphens. `"--:doubleLine"' A solid double horizontal line. `"--:singleDashedLine"' A dashed horizontal line. `"--:doubleDashedLine"' A dashed double horizontal line. `"--:noLine"' No line (but a small space is left). `"--:shadowEtchedIn"' A solid horizontal line with a 3-d recessed appearance. `"--:shadowEtchedOut"' A solid horizontal line with a 3-d pushed-out appearance. `"--:shadowDoubleEtchedIn"' A solid double horizontal line with a 3-d recessed appearance. `"--:shadowDoubleEtchedOut"' A solid double horizontal line with a 3-d pushed-out appearance. `"--:shadowEtchedInDash"' A dashed horizontal line with a 3-d recessed appearance. `"--:shadowEtchedOutDash"' A dashed horizontal line with a 3-d pushed-out appearance. `"--:shadowDoubleEtchedInDash"' A dashed double horizontal line with a 3-d recessed appearance. `"--:shadowDoubleEtchedOutDash"' A dashed double horizontal line with a 3-d pushed-out appearance. * If an element of a menu is a list, it is treated as a submenu. The name of that submenu (the first element in the list) will be used as the name of the item representing this menu on the parent. The possible keywords are as follows: :active FORM FORM will be evaluated when the menu that this item is a part of is about to be displayed, and the item will be selectable only if the result is non-`nil'. If the item is unselectable, it will usually be displayed grayed-out to indicate this. :suffix FORM FORM will be evaluated when the menu that this item is a part of is about to be displayed, and the resulting string is appended to the displayed name. This provides a convenient way of adding the name of a command's "argument" to the menu, like `Kill Buffer NAME'. :keys STRING Normally, the keyboard equivalents of commands in menus are displayed when the "callback" is a symbol. This can be used to specify keys for more complex menu items. It is passed through `substitute-command-keys' first. :style STYLE Specifies what kind of object this menu item is. STYLE be one of the symbols `nil' A normal menu item. `toggle' A toggle button. `radio' A radio button. `button' A menubar button. The only difference between toggle and radio buttons is how they are displayed. But for consistency, a toggle button should be used when there is one option whose value can be turned on or off, and radio buttons should be used when there is a set of mutually exclusive options. When using a group of radio buttons, you should arrange for no more than one to be marked as selected at a time. :selected FORM Meaningful only when STYLE is `toggle', `radio' or `button'. This specifies whether the button will be in the selected or unselected state. FORM is evaluated, as for `:active'. :included FORM This can be used to control the visibility of a menu item. The form is evaluated and the menu item is only displayed if the result is non-`nil'. Note that this is different from `:active': If `:active' evaluates to `nil', the item will be displayed grayed out, while if `:included' evaluates to `nil', the item will be omitted entirely. :config SYMBOL This is an efficient shorthand for `:included (memq SYMBOL menubar-configuration)'. See the variable `menubar-configuration'. :accelerator KEY A menu accelerator is a keystroke which can be pressed while the menu is visible which will immediately activate the item. KEY must be a char or the symbol name of a key. *Note Menu Accelerators::. - Variable: menubar-configuration This variable holds a list of symbols, against which the value of the `:config' tag for each menubar item will be compared. If a menubar item has a `:config' tag, then it is omitted from the menubar if that tag is not a member of the `menubar-configuration' list. For example: ("File" :filter file-menu-filter ; file-menu-filter is a function that takes ; one argument (a list of menu items) and ; returns a list of menu items [ "Save As..." write-file] [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ] [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ] )  File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus Format of the Menubar ===================== A menubar is a list of menus, menu items, and strings. The format is similar to that of a menu, except: * The first item need not be a string, and is not treated specially. * A string consisting solely of hyphens is not treated specially. * If an element of a menubar is `nil', then it is used to represent the division between the set of menubar items which are flush-left and those which are flush-right. (Note: this isn't completely implemented yet.)  File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus Menubar ======= - Variable: current-menubar This variable holds the description of the current menubar. This may be buffer-local. When the menubar is changed, the function `set-menubar-dirty-flag' has to be called in order for the menubar to be updated on the screen. - Constant: default-menubar This variable holds the menubar description of the menubar that is visible at startup. This is the value that `current-menubar' has at startup. - Function: set-menubar-dirty-flag This function tells XEmacs that the menubar widget has to be updated. Changes to the menubar will generally not be visible until this function is called. The following convenience functions are provided for setting the menubar. They are equivalent to doing the appropriate action to change `current-menubar', and then calling `set-menubar-dirty-flag'. Note that these functions copy their argument using `copy-sequence'. - Function: set-menubar menubar This function sets the default menubar to be MENUBAR (*note Menu Format::). This is the menubar that will be visible in buffers that have not defined their own, buffer-local menubar. - Function: set-buffer-menubar menubar This function sets the buffer-local menubar to be MENUBAR. This does not change the menubar in any buffers other than the current one. Miscellaneous: - Variable: menubar-show-keybindings If true, the menubar will display keyboard equivalents. If false, only the command names will be displayed. - Variable: activate-menubar-hook Function or functions called before a menubar menu is pulled down. These functions are called with no arguments, and should interrogate and modify the value of `current-menubar' as desired. The functions on this hook are invoked after the mouse goes down, but before the menu is mapped, and may be used to activate, deactivate, add, or delete items from the menus. However, using a filter (with the `:filter' keyword in a menu description) is generally a more efficient way of accomplishing the same thing, because the filter is invoked only when the actual menu goes down. With a complex menu, there can be a quite noticeable and sometimes aggravating delay if all menu modification is implemented using the `activate-menubar-hook'. See above. These functions may return the symbol `t' to assert that they have made no changes to the menubar. If any other value is returned, the menubar is recomputed. If `t' is returned but the menubar has been changed, then the changes may not show up right away. Returning `nil' when the menubar has not changed is not so bad; more computation will be done, but redisplay of the menubar will still be performed optimally. - Variable: menu-no-selection-hook Function or functions to call when a menu or dialog box is dismissed without a selection having been made.  File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus Modifying Menus =============== The following functions are provided to modify the menubar of one of its submenus. Note that these functions modify the menu in-place, rather than copying it and making a new menu. Some of these functions take a "menu path", which is a list of strings identifying the menu to be modified. For example, `("File")' names the top-level "File" menu. `("File" "Foo")' names a hypothetical submenu of "File". Others take a "menu item path", which is similar to a menu path but also specifies a particular item to be modified. For example, `("File" "Save")' means the menu item called "Save" under the top-level "File" menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under the "Foo" submenu of "Menu". - Function: add-submenu menu-path submenu &optional before in-menu This function adds a menu to the menubar or one of its submenus. If the named menu exists already, it is changed. MENU-PATH identifies the menu under which the new menu should be inserted. If MENU-PATH is `nil', then the menu will be added to the menubar itself. SUBMENU is the new menu to add (*note Menu Format::). BEFORE, if provided, is the name of a menu before which this menu should be added, if this menu is not on its parent already. If the menu is already present, it will not be moved. If IN-MENU is present use that instead of `current-menubar' as the menu to change. - Function: add-menu-button menu-path menu-leaf &optional before in-menu This function adds a menu item to some menu, creating the menu first if necessary. If the named item exists already, it is changed. MENU-PATH identifies the menu under which the new menu item should be inserted. MENU-LEAF is a menubar leaf node (*note Menu Format::). BEFORE, if provided, is the name of a menu before which this item should be added, if this item is not on the menu already. If the item is already present, it will not be moved. If IN-MENU is present use that instead of `current-menubar' as the menu to change. - Function: delete-menu-item menu-item-path &optional from-menu This function removes the menu item specified by MENU-ITEM-PATH from the menu hierarchy. If FROM-MENU is present use that instead of `current-menubar' as the menu to change. - Function: enable-menu-item menu-item-path This function makes the menu item specified by MENU-ITEM-PATH be selectable. - Function: disable-menu-item menu-item-path This function makes the menu item specified by MENU-ITEM-PATH be unselectable. - Function: relabel-menu-item menu-item-path new-name This function changes the string of the menu item specified by MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be printed as from now on. The following function can be used to search for a particular item in a menubar specification, given a path to the item. - Function: find-menu-item menubar menu-item-path &optional parent This function searches MENUBAR for the item given by MENU-ITEM-PATH starting from PARENT (`nil' means start at the top of MENUBAR). This function returns `(ITEM . PARENT)', where PARENT is the immediate parent of the item found (a menu description), and ITEM is either a vector, list, or string, depending on the nature of the menu item. This function signals an error if the item is not found. The following deprecated functions are also documented, so that existing code can be understood. You should not use these functions in new code. - Function: add-menu menu-path menu-name menu-items &optional before This function adds a menu to the menubar or one of its submenus. If the named menu exists already, it is changed. This is obsolete; use `add-submenu' instead. MENU-PATH identifies the menu under which the new menu should be inserted. If MENU-PATH is `nil', then the menu will be added to the menubar itself. MENU-NAME is the string naming the menu to be added; MENU-ITEMS is a list of menu items, strings, and submenus. These two arguments are the same as the first and following elements of a menu description (*note Menu Format::). BEFORE, if provided, is the name of a menu before which this menu should be added, if this menu is not on its parent already. If the menu is already present, it will not be moved. - Function: add-menu-item menu-path item-name function enabled-p &optional before This function adds a menu item to some menu, creating the menu first if necessary. If the named item exists already, it is changed. This is obsolete; use `add-menu-button' instead. MENU-PATH identifies the menu under which the new menu item should be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first, second, and third elements of a menu item vector (*note Menu Format::). BEFORE, if provided, is the name of a menu item before which this item should be added, if this item is not on the menu already. If the item is already present, it will not be moved.  File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus Menu Filters ============ The following filter functions are provided for use in `default-menubar'. You may want to use them in your own menubar description. - Function: file-menu-filter menu-items This function changes the arguments and sensitivity of these File menu items: `Delete Buffer' Has the name of the current buffer appended to it. `Print Buffer' Has the name of the current buffer appended to it. `Pretty-Print Buffer' Has the name of the current buffer appended to it. `Save Buffer' Has the name of the current buffer appended to it, and is sensitive only when the current buffer is modified. `Revert Buffer' Has the name of the current buffer appended to it, and is sensitive only when the current buffer has a file. `Delete Frame' Sensitive only when there is more than one visible frame. - Function: edit-menu-filter menu-items This function changes the arguments and sensitivity of these Edit menu items: `Cut' Sensitive only when XEmacs owns the primary X Selection (if `zmacs-regions' is `t', this is equivalent to saying that there is a region selected). `Copy' Sensitive only when XEmacs owns the primary X Selection. `Clear' Sensitive only when XEmacs owns the primary X Selection. `Paste' Sensitive only when there is an owner for the X Clipboard Selection. `Undo' Sensitive only when there is undo information. While in the midst of an undo, this is changed to `Undo More'. - Function: buffers-menu-filter menu-items This function sets up the Buffers menu. *Note Buffers Menu::, for more information.  File: lispref.info, Node: Pop-Up Menus, Next: Menu Filters, Prev: Modifying Menus, Up: Menus Pop-Up Menus ============ - Function: popup-menu menu-description &optional event This function pops up a menu specified by MENU-DESCRIPTION, which is a menu description (*note Menu Format::). The menu is displayed at the current mouse position. - Function: popup-menu-up-p This function returns `t' if a pop-up menu is up, `nil' otherwise. - Variable: popup-menu-titles If true (the default), pop-up menus will have title bars at the top. Some machinery is provided that attempts to provide a higher-level mechanism onto pop-up menus. This only works if you do not redefine the binding for button3. - Command: popup-mode-menu This function pops up a menu of global and mode-specific commands. The menu is computed by combining `global-popup-menu' and `mode-popup-menu'. This is the default binding for button3. You should generally not change this binding. - Variable: global-popup-menu This holds the global popup menu. This is present in all modes. (This is `nil' by default.) - Variable: mode-popup-menu The mode-specific popup menu. Automatically buffer local. This is appended to the default items in `global-popup-menu'. - Constant: default-popup-menu This holds the default value of `mode-popup-menu'. - Variable: activate-popup-menu-hook Function or functions run before a mode-specific popup menu is made visible. These functions are called with no arguments, and should interrogate and modify the value of `global-popup-menu' or `mode-popup-menu' as desired. Note: this hook is only run if you use `popup-mode-menu' for activating the global and mode-specific commands; if you have your own binding for button3, this hook won't be run. The following convenience functions are provided for displaying pop-up menus. - Command: popup-buffer-menu event This function pops up a copy of the `Buffers' menu (from the menubar) where the mouse is clicked. It should be bound to a mouse button event. - Command: popup-menubar-menu event This function pops up a copy of menu that also appears in the menubar. It should be bound to a mouse button event.  File: lispref.info, Node: Menu Accelerators, Next: Buffers Menu, Prev: Menu Filters, Up: Menus Menu Accelerators ================= Menu accelerators are keyboard shortcuts for accessing the menubar. Accelerator keys can be specified for menus as well as for menu items. An accelerator key for a menu is used to activate that menu when it appears as a submenu of another menu. An accelerator key for a menu item is used to activate that item. * Menu: * Creating Menu Accelerators:: How to add accelerator keys to a menu. * Keyboard Menu Traversal:: How to use and modify the keys which are used to traverse the menu structure. * Menu Accelerator Functions:: Functions for working with menu accelerators.  File: lispref.info, Node: Creating Menu Accelerators, Next: Keyboard Menu Traversal, Up: Menu Accelerators Creating Menu Accelerators -------------------------- Menu accelerators are specified as part of the menubar format using the :accelerator tag to specify a key or by placing "%_" in the menu or menu item name prior to the letter which is to be used as the accelerator key. The advantage of the second method is that the menu rendering code then knows to draw an underline under that character, which is the canonical way of indicating an accelerator key to a user. For example, the command (add-submenu nil '("%_Test" ["One" (insert "1") :accelerator ?1 :active t] ["%_Two" (insert "2")] ["%_3" (insert "3")])) will add a new menu to the top level menubar. The new menu can be reached by pressing "t" while the top level menubar is active. When the menu is active, pressing "1" will activate the first item and insert the character "1" into the buffer. Pressing "2" will activate the second item and insert the character "2" into the buffer. Pressing "3" will activate the third item and insert the character "3" into the buffer. It is possible to activate the top level menubar itself using accelerator keys. *Note Menu Accelerator Functions::.  File: lispref.info, Node: Keyboard Menu Traversal, Next: Menu Accelerator Functions, Prev: Creating Menu Accelerators, Up: Menu Accelerators Keyboard Menu Traversal ----------------------- In addition to immediately activating a menu or menu item, the keyboard can be used to traverse the menus without activating items. The keyboard arrow keys, the return key and the escape key are defined to traverse the menus in a way that should be familiar to users of any of a certain family of popular PC operating systems. This behavior can be changed by modifying the bindings in menu-accelerator-map. At this point, the online help is your best bet for more information about how to modify the menu traversal keys.  File: lispref.info, Node: Menu Accelerator Functions, Prev: Keyboard Menu Traversal, Up: Menu Accelerators Menu Accelerator Functions -------------------------- - Command: accelerate-menu Make the menubar immediately active and place the cursor on the left most entry in the top level menu. Menu items can be selected as usual. - Variable: menu-accelerator-enabled Whether menu accelerator keys can cause the menubar to become active. If `menu-force' or `menu-fallback', then menu accelerator keys can be used to activate the top level menu. Once the menubar becomes active, the accelerator keys can be used regardless of the value of this variable. `menu-force' is used to indicate that the menu accelerator key takes precedence over bindings in the current keymap(s). `menu-fallback' means that bindings in the current keymap take precedence over menu accelerator keys. Thus a top level menu with an accelerator of "T" would be activated on a keypress of Meta-t if `menu-accelerator-enabled' is `menu-force'. However, if `menu-accelerator-enabled' is `menu-fallback', then Meta-t will not activate the menubar and will instead run the function transpose-words, to which it is normally bound. The default value is `nil'. See also `menu-accelerator-modifiers' and `menu-accelerator-prefix'. - Variable: menu-accelerator-map Keymap consulted to determine the commands to run in response to keypresses occurring while the menubar is active. *Note Keyboard Menu Traversal::. - Variable: menu-accelerator-modifiers A list of modifier keys which must be pressed in addition to a valid menu accelerator in order for the top level menu to be activated in response to a keystroke. The default value of `(meta)' mirrors the usage of the alt key as a menu accelerator in popular PC operating systems. The modifier keys in `menu-accelerator-modifiers' must match exactly the modifiers present in the keypress. The only exception is that the shift modifier is accepted in conjunction with alphabetic keys even if it is not a menu accelerator modifier. See also `menu-accelerator-enabled' and `menu-accelerator-prefix'. - Variable: menu-accelerator-prefix Prefix key(s) that must be typed before menu accelerators will be activated. Must be a valid key descriptor. The default value is `nil'. (setq menu-accelerator-prefix ?\C-x) (setq menu-accelerator-modifiers '(meta control)) (setq menu-accelerator-enabled 'menu-force) (add-submenu nil '("%_Test" ["One" (insert "1") :accelerator ?1 :active t] ["%_Two" (insert "2")] ["%_3" (insert "3")])) will add the menu "Test" to the top level menubar. Pressing C-x followed by C-M-T will activate the menubar and display the "Test" menu. Pressing C-M-T by itself will not activate the menubar. Neither will pressing C-x followed by anything else.  File: lispref.info, Node: Buffers Menu, Prev: Menu Accelerators, Up: Menus Buffers Menu ============ The following options control how the `Buffers' menu is displayed. This is a list of all (or a subset of) the buffers currently in existence, and is updated dynamically. - User Option: buffers-menu-max-size This user option holds the maximum number of entries which may appear on the `Buffers' menu. If this is 10, then only the ten most-recently-selected buffers will be shown. If this is `nil', then all buffers will be shown. Setting this to a large number or `nil' will slow down menu responsiveness. - Function: format-buffers-menu-line buffer This function returns a string to represent BUFFER in the `Buffers' menu. `nil' means the buffer shouldn't be listed. You can redefine this. - User Option: complex-buffers-menu-p If true, the `Buffers' menu will contain several commands, as submenus of each buffer line. If this is false, then there will be only one command: select that buffer. - User Option: buffers-menu-switch-to-buffer-function This user option holds the function to call to select a buffer from the `Buffers' menu. `switch-to-buffer' is a good choice, as is `pop-to-buffer'.  File: lispref.info, Node: Dialog Boxes, Next: Toolbar, Prev: Menus, Up: Top Dialog Boxes ************ * Menu: * Dialog Box Format:: * Dialog Box Functions::  File: lispref.info, Node: Dialog Box Format, Next: Dialog Box Functions, Up: Dialog Boxes Dialog Box Format ================= A dialog box description is a list. * The first element of the list is a string to display in the dialog box. * The rest of the elements are descriptions of the dialog box's buttons. Each one is a vector of three elements: - The first element is the text of the button. - The second element is the "callback". - The third element is `t' or `nil', whether this button is selectable. If the callback of a button is a symbol, then it must name a command. It will be invoked with `call-interactively'. If it is a list, then it is evaluated with `eval'. One (and only one) of the buttons may be `nil'. This marker means that all following buttons should be flushright instead of flushleft. The syntax, more precisely: form := command := callback := command | form active-p := name := partition := 'nil' button := '[' name callback active-p ']' dialog := '(' name [ button ]+ [ partition [ button ]+ ] ')'  File: lispref.info, Node: Dialog Box Functions, Prev: Dialog Box Format, Up: Dialog Boxes Dialog Box Functions ==================== - Function: popup-dialog-box dbox-desc This function pops up a dialog box. DBOX-DESC describes how the dialog box will appear (*note Dialog Box Format::). *Note Yes-or-No Queries::, for functions to ask a yes/no question using a dialog box.  File: lispref.info, Node: Toolbar, Next: Gutter, Prev: Dialog Boxes, Up: Top Toolbar ******* * Menu: * Toolbar Intro:: An introduction. * Creating Toolbar:: How to create a toolbar. * Toolbar Descriptor Format:: Accessing and modifying a toolbar's properties. * Specifying the Toolbar:: Setting a toolbar's contents. * Other Toolbar Variables:: Controlling the size of toolbars.  File: lispref.info, Node: Toolbar Intro, Next: Creating Toolbar, Up: Toolbar Toolbar Intro ============= A "toolbar" is a bar of icons displayed along one edge of a frame. You can view a toolbar as a series of menu shortcuts--the most common menu options can be accessed with a single click rather than a series of clicks and/or drags to select the option from a menu. Consistent with this, a help string (called the "help-echo") describing what an icon in the toolbar (called a "toolbar button") does, is displayed in the minibuffer when the mouse is over the button. In XEmacs, a toolbar can be displayed along any of the four edges of the frame, and two or more different edges can be displaying toolbars simultaneously. The contents, thickness, and visibility of the toolbars can be controlled separately, and the values can be per-buffer, per-frame, etc., using specifiers (*note Specifiers::). Normally, there is one toolbar displayed in a frame. Usually, this is the standard toolbar, but certain modes will override this and substitute their own toolbar. In some cases (e.g. the VM package), a package will supply its own toolbar along a different edge from the standard toolbar, so that both can be visible at once. This standard toolbar is usually positioned along the top of the frame, but this can be changed using `set-default-toolbar-position'. Note that, for each of the toolbar properties (contents, thickness, and visibility), there is a separate specifier for each of the four toolbar positions (top, bottom, left, and right), and an additional specifier for the "default" toolbar, i.e. the toolbar whose position is controlled by `set-default-toolbar-position'. The way this works is that `set-default-toolbar-position' arranges things so that the appropriate position-specific specifiers for the default position inherit from the corresponding default specifiers. That way, if the position-specific specifier does not give a value (which it usually doesn't), then the value from the default specifier applies. If you want to control the default toolbar, you just change the default specifiers, and everything works. A package such as VM that wants to put its own toolbar in a different location from the default just sets the position-specific specifiers, and if the user sets the default toolbar to the same position, it will just not be visible.  File: lispref.info, Node: Creating Toolbar, Next: Toolbar Descriptor Format, Prev: Toolbar Intro, Up: Toolbar Creating Toolbar ================ - Function: make-toolbar-specifier spec-list Return a new `toolbar' specifier object with the given specification list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. *Note Specifiers::, for more information about specifiers. Toolbar specifiers are used to specify the format of a toolbar. The values of the variables `default-toolbar', `top-toolbar', `left-toolbar', `right-toolbar', and `bottom-toolbar' are always toolbar specifiers. Valid toolbar instantiators are called "toolbar descriptors" and are lists of vectors. See `default-toolbar' for a description of the exact format.  File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Creating Toolbar, Up: Toolbar Toolbar Descriptor Format ========================= The contents of a toolbar are specified using a "toolbar descriptor". The format of a toolbar descriptor is a list of "toolbar button descriptors". Each toolbar button descriptor is a vector in one of the following formats: * `[GLYPH-LIST FUNCTION ENABLED-P HELP]' * `[:style 2D-OR-3D]' * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]' * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]' Optionally, one of the toolbar button descriptors may be `nil' instead of a vector; this signifies the division between the toolbar buttons that are to be displayed flush-left, and the buttons to be displayed flush-right. The first vector format above specifies a normal toolbar button; the others specify blank areas in the toolbar. For the first vector format: * GLYPH-LIST should be a list of one to six glyphs (as created by `make-glyph') or a symbol whose value is such a list. The first glyph, which must be provided, is the glyph used to display the toolbar button when it is in the "up" (not pressed) state. The optional second glyph is for displaying the button when it is in the "down" (pressed) state. The optional third glyph is for when the button is disabled. The last three glyphs are for displaying the button in the "up", "down", and "disabled" states, respectively, but are used when the user has called for captioned toolbar buttons (using `toolbar-buttons-captioned-p'). The function `toolbar-make-button-list' is useful in creating these glyph lists. * Even if you do not provide separate down-state and disabled-state glyphs, the user will still get visual feedback to indicate which state the button is in. Buttons in the up-state are displayed with a shadowed border that gives a raised appearance to the button. Buttons in the down-state are displayed with shadows that give a recessed appearance. Buttons in the disabled state are displayed with no shadows, giving a 2-d effect. * If some of the toolbar glyphs are not provided, they inherit as follows: UP: up DOWN: down -> up DISABLED: disabled -> up CAP-UP: cap-up -> up CAP-DOWN: cap-down -> cap-up -> down -> up CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up * The second element FUNCTION is a function to be called when the toolbar button is activated (i.e. when the mouse is released over the toolbar button, if the press occurred in the toolbar). It can be any form accepted by `call-interactively', since this is how it is invoked. * The third element ENABLED-P specifies whether the toolbar button is enabled (disabled buttons do nothing when they are activated, and are displayed differently; see above). It should be either a boolean or a form that evaluates to a boolean. * The fourth element HELP, if non-`nil', should be a string. This string is displayed in the echo area when the mouse passes over the toolbar button. For the other vector formats (specifying blank areas of the toolbar): * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating whether the area is displayed with shadows (giving it a raised, 3-d appearance) or without shadows (giving it a flat appearance). * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank area. If omitted, it defaults to a device-specific value (8 pixels for X devices). - Function: toolbar-make-button-list up &optional down disabled cap-up cap-down cap-disabled This function calls `make-glyph' on each arg and returns a list of the results. This is useful for setting the first argument of a toolbar button descriptor (typically, the result of this function is assigned to a symbol, which is specified as the first argument of the toolbar button descriptor). - Function: check-toolbar-button-syntax button &optional noerror Verify the syntax of entry BUTTON in a toolbar description list. If you want to verify the syntax of a toolbar description list as a whole, use `check-valid-instantiator' with a specifier type of `toolbar'.  File: lispref.info, Node: Specifying the Toolbar, Next: Other Toolbar Variables, Prev: Toolbar Descriptor Format, Up: Toolbar Specifying the Toolbar ====================== In order to specify the contents of a toolbar, set one of the specifier variables `default-toolbar', `top-toolbar', `bottom-toolbar', `left-toolbar', or `right-toolbar'. These are specifiers, which means you set them with `set-specifier' and query them with `specifier-specs' or `specifier-instance'. You will get an error if you try to set them using `setq'. The valid instantiators for these specifiers are toolbar descriptors, as described above. *Note Specifiers::, for more information. Most of the time, you will set `default-toolbar', which allows the user to choose where the toolbar should go. - Specifier: default-toolbar The position of this toolbar is specified in the function `default-toolbar-position'. If the corresponding position-specific toolbar (e.g. `top-toolbar' if `default-toolbar-position' is `top') does not specify a toolbar in a particular domain, then the value of `default-toolbar' in that domain, of any, will be used instead. Note that the toolbar at any particular position will not be displayed unless its thickness (width or height, depending on orientation) is non-zero and its visibility status is true. The thickness is controlled by the specifiers `top-toolbar-height', `bottom-toolbar-height', `left-toolbar-width', and `right-toolbar-width', and the visibility status is controlled by the specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p', `left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other Toolbar Variables::). - Function: set-default-toolbar-position position This function sets the position that the `default-toolbar' will be displayed at. Valid positions are the symbols `top', `bottom', `left' and `right'. What this actually does is set the fallback specifier for the position-specific specifier corresponding to the given position to `default-toolbar', and set the fallbacks for the other position-specific specifiers to `nil'. It also does the same thing for the position-specific thickness and visibility specifiers, which inherit from one of `default-toolbar-height' or `default-toolbar-width', and from `default-toolbar-visible-p', respectively (*note Other Toolbar Variables::). - Function: default-toolbar-position This function returns the position that the `default-toolbar' will be displayed at. You can also explicitly set a toolbar at a particular position. When redisplay determines what to display at a particular position in a particular domain (i.e. window), it first consults the position-specific toolbar. If that does not yield a toolbar descriptor, the `default-toolbar' is consulted if `default-toolbar-position' indicates this position. - Specifier: top-toolbar Specifier for the toolbar at the top of the frame. - Specifier: bottom-toolbar Specifier for the toolbar at the bottom of the frame. - Specifier: left-toolbar Specifier for the toolbar at the left edge of the frame. - Specifier: right-toolbar Specifier for the toolbar at the right edge of the frame. - Function: toolbar-specifier-p object This function returns non-`nil' if OBJECT is a toolbar specifier. Toolbar specifiers are the actual objects contained in the toolbar variables described above, and their valid instantiators are toolbar descriptors (*note Toolbar Descriptor Format::).  File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar Other Toolbar Variables ======================= The variables to control the toolbar thickness, visibility status, and captioned status are all specifiers. *Note Specifiers::. - Specifier: default-toolbar-height This specifies the height of the default toolbar, if it's oriented horizontally. The position of the default toolbar is specified by the function `set-default-toolbar-position'. If the corresponding position-specific toolbar thickness specifier (e.g. `top-toolbar-height' if `default-toolbar-position' is `top') does not specify a thickness in a particular domain (a window or a frame), then the value of `default-toolbar-height' or `default-toolbar-width' (depending on the toolbar orientation) in that domain, if any, will be used instead. - Specifier: default-toolbar-width This specifies the width of the default toolbar, if it's oriented vertically. This behaves like `default-toolbar-height'. Note that `default-toolbar-height' is only used when `default-toolbar-position' is `top' or `bottom', and `default-toolbar-width' is only used when `default-toolbar-position' is `left' or `right'. - Specifier: top-toolbar-height This specifies the height of the top toolbar. - Specifier: bottom-toolbar-height This specifies the height of the bottom toolbar. - Specifier: left-toolbar-width This specifies the width of the left toolbar. - Specifier: right-toolbar-width This specifies the width of the right toolbar. Note that all of the position-specific toolbar thickness specifiers have a fallback value of zero when they do not correspond to the default toolbar. Therefore, you will have to set a non-zero thickness value if you want a position-specific toolbar to be displayed. - Specifier: default-toolbar-visible-p This specifies whether the default toolbar is visible. The position of the default toolbar is specified by the function `set-default-toolbar-position'. If the corresponding position-specific toolbar visibility specifier (e.g. `top-toolbar-visible-p' if `default-toolbar-position' is `top') does not specify a visible-p value in a particular domain (a window or a frame), then the value of `default-toolbar-visible-p' in that domain, if any, will be used instead. - Specifier: top-toolbar-visible-p This specifies whether the top toolbar is visible. - Specifier: bottom-toolbar-visible-p This specifies whether the bottom toolbar is visible. - Specifier: left-toolbar-visible-p This specifies whether the left toolbar is visible. - Specifier: right-toolbar-visible-p This specifies whether the right toolbar is visible. `default-toolbar-visible-p' and all of the position-specific toolbar visibility specifiers have a fallback value of true. Internally, toolbar thickness and visibility specifiers are instantiated in both window and frame domains, for different purposes. The value in the domain of a frame's selected window specifies the actual toolbar thickness or visibility that you will see in that frame. The value in the domain of a frame itself specifies the toolbar thickness or visibility that is used in frame geometry calculations. Thus, for example, if you set the frame width to 80 characters and the left toolbar width for that frame to 68 pixels, then the frame will be sized to fit 80 characters plus a 68-pixel left toolbar. If you then set the left toolbar width to 0 for a particular buffer (or if that buffer does not specify a left toolbar or has a `nil' value specified for `left-toolbar-visible-p'), you will find that, when that buffer is displayed in the selected window, the window will have a width of 86 or 87 characters--the frame is sized for a 68-pixel left toolbar but the selected window specifies that the left toolbar is not visible, so it is expanded to take up the slack. - Specifier: toolbar-buttons-captioned-p Whether toolbar buttons are captioned. This affects which glyphs from a toolbar button descriptor are chosen. *Note Toolbar Descriptor Format::. You can also reset the toolbar to what it was when XEmacs started up. - Constant: initial-toolbar-spec The toolbar descriptor used to initialize `default-toolbar' at startup.  File: lispref.info, Node: Gutter, Next: Scrollbars, Prev: Toolbar, Up: Top Gutter ****** A gutter is a rectangle displayed along one edge of a frame. It can contain arbitrary text or graphics. * Menu: * Gutter Intro:: An introduction. * Creating Gutter:: How to create a gutter. * Gutter Descriptor Format:: Accessing and modifying a gutter's properties. * Specifying a Gutter:: Setting a gutter's contents. * Other Gutter Variables:: Controlling the size of gutters. * Common Gutter Widgets:: Things to put in gutters.  File: lispref.info, Node: Gutter Intro, Next: Creating Gutter, Prev: Gutter, Up: Gutter Gutter Intro ============ A "gutter" is a rectangle displayed along one edge of a frame. It can contain arbitrary text or graphics. It could be considered a generalization of a toolbar, although toolbars are not currently implemented using gutters. In XEmacs, a gutter can be displayed along any of the four edges of the frame, and two or more different edges can be displaying gutters simultaneously. The contents, thickness, and visibility of the gutters can be controlled separately, and the values can be per-buffer, per-frame, etc., using specifiers (*note Specifiers::). Normally, there is one gutter displayed in a frame. Usually, this is the default gutter, containing buffer tabs, but modes cab override this and substitute their own gutter. This default gutter is usually positioned along the top of the frame, but this can be changed using `set-default-gutter-position'. Note that, for each of the gutter properties (contents, thickness, and visibility), there is a separate specifier for each of the four gutter positions (top, bottom, left, and right), and an additional specifier for the "default" gutter, i.e. the gutter whose position is controlled by `set-default-gutter-position'. The way this works is that `set-default-gutter-position' arranges things so that the appropriate position-specific specifiers for the default position inherit from the corresponding default specifiers. That way, if the position-specific specifier does not give a value (which it usually doesn't), then the value from the default specifier applies. If you want to control the default gutter, you just change the default specifiers, and everything works. A package such as VM that wants to put its own gutter in a different location from the default just sets the position-specific specifiers, and if the user sets the default gutter to the same position, it will just not be visible.  File: lispref.info, Node: Creating Gutter, Next: Gutter Descriptor Format, Prev: Gutter Intro, Up: Gutter Creating Gutter =============== - Function: make-gutter-specifier spec-list Return a new `gutter' specifier object with the given specification list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. *Note Specifiers::, for more information about specifiers. Gutter specifiers are used to specify the format of a gutter. The values of the variables `default-gutter', `top-gutter', `left-gutter', `right-gutter', and `bottom-gutter' are always gutter specifiers. Valid gutter instantiators are called "gutter descriptors" and are either strings or property-lists of strings. See `default-gutter' for a description of the exact format. - Function: make-gutter-size-specifier spec-list Return a new `gutter-size' specifier object with the given spec list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. *Note Specifiers::, for more information about specifiers. Gutter-size specifiers are used to specify the size of a gutter. The values of the variables `default-gutter-size', `top-gutter-size', `left-gutter-size', `right-gutter-size', and `bottom-gutter-size' are always gutter-size specifiers. Valid gutter-size instantiators are either integers or the special symbol `autodetect'. If a gutter-size is set to `autodetect' them the size of the gutter will be adjusted to just accommodate the gutters contents. `autodetect' only works for top and bottom gutters. - Function: make-gutter-visible-specifier spec-list Return a new `gutter-visible' specifier object with the given spec list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. *Note Specifiers::, for more information about specifiers. Gutter-visible specifiers are used to specify the visibility of a gutter. The values of the variables `default-gutter-visible-p', `top-gutter-visible-p', `left-gutter-visible-p', `right-gutter-visible-p', and `bottom-gutter-visible-p' are always gutter-visible specifiers. Valid gutter-visible instantiators are `t', `nil' or a list of symbols. If a gutter-visible instantiator is set to a list of symbols, and the corresponding gutter specification is a property-list strings, then elements of the gutter specification will only be visible if the corresponding symbol occurs in the gutter-visible instantiator.  File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, Up: Gutter Gutter Descriptor Format ======================== The contents of a gutter are specified using a "gutter descriptor". The format of a gutter descriptor is a list of "gutter button descriptors". Each gutter button descriptor is a vector in one of the following formats: * `[GLYPH-LIST FUNCTION ENABLED-P HELP]' * `[:style 2D-OR-3D]' * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]' * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]' Optionally, one of the gutter button descriptors may be `nil' instead of a vector; this signifies the division between the gutter buttons that are to be displayed flush-left, and the buttons to be displayed flush-right. The first vector format above specifies a normal gutter button; the others specify blank areas in the gutter. For the first vector format: * GLYPH-LIST should be a list of one to six glyphs (as created by `make-glyph') or a symbol whose value is such a list. The first glyph, which must be provided, is the glyph used to display the gutter button when it is in the "up" (not pressed) state. The optional second glyph is for displaying the button when it is in the "down" (pressed) state. The optional third glyph is for when the button is disabled. The last three glyphs are for displaying the button in the "up", "down", and "disabled" states, respectively, but are used when the user has called for captioned gutter buttons (using `gutter-buttons-captioned-p'). The function `gutter-make-button-list' is useful in creating these glyph lists. * Even if you do not provide separate down-state and disabled-state glyphs, the user will still get visual feedback to indicate which state the button is in. Buttons in the up-state are displayed with a shadowed border that gives a raised appearance to the button. Buttons in the down-state are displayed with shadows that give a recessed appearance. Buttons in the disabled state are displayed with no shadows, giving a 2-d effect. * If some of the gutter glyphs are not provided, they inherit as follows: UP: up DOWN: down -> up DISABLED: disabled -> up CAP-UP: cap-up -> up CAP-DOWN: cap-down -> cap-up -> down -> up CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up * The second element FUNCTION is a function to be called when the gutter button is activated (i.e. when the mouse is released over the gutter button, if the press occurred in the gutter). It can be any form accepted by `call-interactively', since this is how it is invoked. * The third element ENABLED-P specifies whether the gutter button is enabled (disabled buttons do nothing when they are activated, and are displayed differently; see above). It should be either a boolean or a form that evaluates to a boolean. * The fourth element HELP, if non-`nil', should be a string. This string is displayed in the echo area when the mouse passes over the gutter button. For the other vector formats (specifying blank areas of the gutter): * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating whether the area is displayed with shadows (giving it a raised, 3-d appearance) or without shadows (giving it a flat appearance). * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank area. If omitted, it defaults to a device-specific value (8 pixels for X devices). - Function: gutter-make-button-list up &optional down disabled cap-up cap-down cap-disabled This function calls `make-glyph' on each arg and returns a list of the results. This is useful for setting the first argument of a gutter button descriptor (typically, the result of this function is assigned to a symbol, which is specified as the first argument of the gutter button descriptor). - Function: check-gutter-button-syntax button &optional noerror Verify the syntax of entry BUTTON in a gutter description list. If you want to verify the syntax of a gutter description list as a whole, use `check-valid-instantiator' with a specifier type of `gutter'.  File: lispref.info, Node: Specifying a Gutter, Next: Other Gutter Variables, Prev: Gutter Descriptor Format, Up: Gutter Specifying a Gutter =================== In order to specify the contents of a gutter, set one of the specifier variables `default-gutter', `top-gutter', `bottom-gutter', `left-gutter', or `right-gutter'. These are specifiers, which means you set them with `set-specifier' and query them with `specifier-specs' or `specifier-instance'. You will get an error if you try to set them using `setq'. The valid instantiators for these specifiers are gutter descriptors, as described above. *Note Specifiers::, for more information. Most of the time, you will set `default-gutter', which allows the user to choose where the gutter should go. - Specifier: default-gutter The position of this gutter is specified in the function `default-gutter-position'. If the corresponding position-specific gutter (e.g. `top-gutter' if `default-gutter-position' is `top') does not specify a gutter in a particular domain, then the value of `default-gutter' in that domain, of any, will be used instead. Note that the gutter at any particular position will not be displayed unless its thickness (width or height, depending on orientation) is non-zero and its visibility status is true. The thickness is controlled by the specifiers `top-gutter-height', `bottom-gutter-height', `left-gutter-width', and `right-gutter-width', and the visibility status is controlled by the specifiers `top-gutter-visible-p', `bottom-gutter-visible-p', `left-gutter-visible-p', and `right-gutter-visible-p' (*note Other Gutter Variables::). - Function: set-default-gutter-position position This function sets the position that the `default-gutter' will be displayed at. Valid positions are the symbols `top', `bottom', `left' and `right'. What this actually does is set the fallback specifier for the position-specific specifier corresponding to the given position to `default-gutter', and set the fallbacks for the other position-specific specifiers to `nil'. It also does the same thing for the position-specific thickness and visibility specifiers, which inherit from one of `default-gutter-height' or `default-gutter-width', and from `default-gutter-visible-p', respectively (*note Other Gutter Variables::). - Function: default-gutter-position This function returns the position that the `default-gutter' will be displayed at. You can also explicitly set a gutter at a particular position. When redisplay determines what to display at a particular position in a particular domain (i.e. window), it first consults the position-specific gutter. If that does not yield a gutter descriptor, the `default-gutter' is consulted if `default-gutter-position' indicates this position. - Specifier: top-gutter Specifier for the gutter at the top of the frame. - Specifier: bottom-gutter Specifier for the gutter at the bottom of the frame. - Specifier: left-gutter Specifier for the gutter at the left edge of the frame. - Specifier: right-gutter Specifier for the gutter at the right edge of the frame. - Function: gutter-specifier-p object This function returns non-`nil' if OBJECT is a gutter specifier. Gutter specifiers are the actual objects contained in the gutter variables described above, and their valid instantiators are gutter descriptors (*note Gutter Descriptor Format::).  File: lispref.info, Node: Other Gutter Variables, Next: Common Gutter Widgets, Prev: Specifying a Gutter, Up: Gutter Other Gutter Variables ====================== The variables to control the gutter thickness, visibility status, and captioned status are all specifiers. *Note Specifiers::. - Specifier: default-gutter-height This specifies the height of the default gutter, if it's oriented horizontally. The position of the default gutter is specified by the function `set-default-gutter-position'. If the corresponding position-specific gutter thickness specifier (e.g. `top-gutter-height' if `default-gutter-position' is `top') does not specify a thickness in a particular domain (a window or a frame), then the value of `default-gutter-height' or `default-gutter-width' (depending on the gutter orientation) in that domain, if any, will be used instead. - Specifier: default-gutter-width This specifies the width of the default gutter, if it's oriented vertically. This behaves like `default-gutter-height'. Note that `default-gutter-height' is only used when `default-gutter-position' is `top' or `bottom', and `default-gutter-width' is only used when `default-gutter-position' is `left' or `right'. - Specifier: top-gutter-height This specifies the height of the top gutter. - Specifier: bottom-gutter-height This specifies the height of the bottom gutter. - Specifier: left-gutter-width This specifies the width of the left gutter. - Specifier: right-gutter-width This specifies the width of the right gutter. Note that all of the position-specific gutter thickness specifiers have a fallback value of zero when they do not correspond to the default gutter. Therefore, you will have to set a non-zero thickness value if you want a position-specific gutter to be displayed. - Specifier: default-gutter-visible-p This specifies whether the default gutter is visible. The position of the default gutter is specified by the function `set-default-gutter-position'. If the corresponding position-specific gutter visibility specifier (e.g. `top-gutter-visible-p' if `default-gutter-position' is `top') does not specify a visible-p value in a particular domain (a window or a frame), then the value of `default-gutter-visible-p' in that domain, if any, will be used instead. - Specifier: top-gutter-visible-p This specifies whether the top gutter is visible. - Specifier: bottom-gutter-visible-p This specifies whether the bottom gutter is visible. - Specifier: left-gutter-visible-p This specifies whether the left gutter is visible. - Specifier: right-gutter-visible-p This specifies whether the right gutter is visible. `default-gutter-visible-p' and all of the position-specific gutter visibility specifiers have a fallback value of true. Internally, gutter thickness and visibility specifiers are instantiated in both window and frame domains, for different purposes. The value in the domain of a frame's selected window specifies the actual gutter thickness or visibility that you will see in that frame. The value in the domain of a frame itself specifies the gutter thickness or visibility that is used in frame geometry calculations. Thus, for example, if you set the frame width to 80 characters and the left gutter width for that frame to 68 pixels, then the frame will be sized to fit 80 characters plus a 68-pixel left gutter. If you then set the left gutter width to 0 for a particular buffer (or if that buffer does not specify a left gutter or has a `nil' value specified for `left-gutter-visible-p'), you will find that, when that buffer is displayed in the selected window, the window will have a width of 86 or 87 characters - the frame is sized for a 68-pixel left gutter but the selected window specifies that the left gutter is not visible, so it is expanded to take up the slack. - Specifier: gutter-buttons-captioned-p Whether gutter buttons are captioned. This affects which glyphs from a gutter button descriptor are chosen. *Note Gutter Descriptor Format::. You can also reset the gutter to what it was when XEmacs started up. - Constant: initial-gutter-spec The gutter descriptor used to initialize `default-gutter' at startup.  File: lispref.info, Node: Common Gutter Widgets, Prev: Other Gutter Variables, Up: Gutter Common Gutter Widgets ===================== A gutter can contain arbitrary text. So, for example, in an Info buffer you could put the title of the current node in the top gutter, and it would not scroll out of view in a long node. (This is an artificial example, since usually the node name is sufficiently descriptive, and Info puts that in the mode line.) A more common use for the gutter is to hold some kind of active widget. The buffer-tab facility, available in all XEmacs frames, creates an array of file-folder-like tabs, which the user can click with the mouse to switch buffers. W3 uses a progress-bar widget in the bottom gutter to give a visual indication of the progress of time-consuming operations like downloading. * Menu: * Buffer Tabs:: Tabbed divider index metaphor for switching buffers. * Progress Bars:: Visual indication of operation progress.  File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets Buffer Tabs ----------- Not documented yet.  File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets Progress Bars ------------- Not documented yet.  File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top Scrollbars ********** Not yet documented.  File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top Drag and Drop ************* _WARNING_: the Drag'n'Drop API is still under development and the interface may change! The current implementation is considered experimental. Drag'n'drop is a way to transfer information between multiple applications. To do this several GUIs define their own protocols. Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more. To catch all these protocols, XEmacs provides a generic API. One prime idea behind the API is to use a data interface that is transparent for all systems. The author thinks that this is best archived by using URL and MIME data, cause any internet enabled system must support these for email already. XEmacs also already provides powerful interfaces to support these types of data (tm and w3). * Menu: * Supported Protocols:: Which low-level protocols are supported. * Drop Interface:: How XEmacs handles a drop from another application. * Drag Interface:: Calls to initiate a drag from XEmacs.  File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop Supported Protocols =================== The current release of XEmacs only support a small set of Drag'n'drop protocols. Some of these only support limited options available in the API. * Menu: * OffiX DND:: A generic X based protocol. * CDE dt:: Common Desktop Environment used on suns. * MSWindows OLE:: Mr. Gates way of live. * Loose ends:: The other protocols.  File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols OffiX DND --------- _WARNING_: If you compile in OffiX, you may not be able to use multiple X displays successfully. If the two servers are from different vendors, the results may be unpredictable. The OffiX Drag'n'Drop protocol is part of a X API/Widget library created by Cesar Crusius. It is based on X-Atoms and ClientMessage events, and works with any X platform supporting them. OffiX is supported if 'offix is member of the variable dragdrop-protocols, or the feature 'offix is defined. Unfortunately it uses it's own data types. Examples are: File, Files, Exe, Link, URL, MIME. The API tries to choose the right type for the data that is dragged from XEmacs (well, not yet...). XEmacs supports both MIME and URL drags and drops using this API. No application interaction is possible while dragging is in progress. For information about the OffiX project have a look at http://leb.net/~offix/  File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols CDE dt ------ CDE stands for Common Desktop Environment. It is based on the Motif widget library. It's drag'n'drop protocol is also an abstraction of the Motif protocol (so it might be possible, that XEmacs will also support the Motif protocol soon). CDE has three different types: file, buffer, and text. XEmacs only uses file and buffer drags. The API will disallow full URL drags, only file method URLs are passed through. Buffer drags are always converted to plain text.  File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols MSWindows OLE ------------- Only allows file drags and drops.  File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols Loose ends ---------- The following protocols will be supported soon: Xdnd, Motif, Xde (if I get some specs), KDE OffiX (if KDE can find XEmacs windows). In particular Xdnd will be one of the protocols that can benefit from the XEmacs API, cause it also uses MIME types to encode dragged data.  File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop Drop Interface ============== For each activated low-level protocol, an internal routine will catch incoming drops and convert them to a dragdrop-drop type misc-user-event. This misc-user-event has its function argument set to `dragdrop-drop-dispatch' and the object contains the data of the drop (converted to URL/MIME specific data). This function will search the variable `experimental-dragdrop-drop-functions' for a function that can handle the dropped data. To modify the drop behavior, the user can modify the variable `experimental-dragdrop-drop-functions'. Each element of this list specifies a possible handler for dropped data. The first one that can handle the data will return `t' and exit. Another possibility is to set a extent-property with the same name. Extents are checked prior to the variable. The customization group `drag-n-drop' shows all variables of user interest.  File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop Drag Interface ============== This describes the drag API (not implemented yet).  File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top Major and Minor Modes ********************* A "mode" is a set of definitions that customize XEmacs and can be turned on and off while you edit. There are two varieties of modes: "major modes", which are mutually exclusive and used for editing particular kinds of text, and "minor modes", which provide features that users can enable individually. This chapter describes how to write both major and minor modes, how to indicate them in the modeline, and how they run hooks supplied by the user. For related topics such as keymaps and syntax tables, see *Note Keymaps::, and *Note Syntax Tables::. * Menu: * Major Modes:: Defining major modes. * Minor Modes:: Defining minor modes. * Modeline Format:: Customizing the text that appears in the modeline. * Hooks:: How to use hooks; how to write code that provides hooks.  File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes Major Modes =========== Major modes specialize XEmacs for editing particular kinds of text. Each buffer has only one major mode at a time. The least specialized major mode is called "Fundamental mode". This mode has no mode-specific definitions or variable settings, so each XEmacs command behaves in its default manner, and each option is in its default state. All other major modes redefine various keys and options. For example, Lisp Interaction mode provides special key bindings for (`eval-print-last-sexp'), (`lisp-indent-line'), and other keys. When you need to write several editing commands to help you perform a specialized editing task, creating a new major mode is usually a good idea. In practice, writing a major mode is easy (in contrast to writing a minor mode, which is often difficult). If the new mode is similar to an old one, it is often unwise to modify the old one to serve two purposes, since it may become harder to use and maintain. Instead, copy and rename an existing major mode definition and alter the copy--or define a "derived mode" (*note Derived Modes::). For example, Rmail Edit mode, which is in `emacs/lisp/rmailedit.el', is a major mode that is very similar to Text mode except that it provides three additional commands. Its definition is distinct from that of Text mode, but was derived from it. Rmail Edit mode is an example of a case where one piece of text is put temporarily into a different major mode so it can be edited in a different way (with ordinary XEmacs commands rather than Rmail). In such cases, the temporary major mode usually has a command to switch back to the buffer's usual mode (Rmail mode, in this case). You might be tempted to present the temporary redefinitions inside a recursive edit and restore the usual ones when the user exits; but this is a bad idea because it constrains the user's options when it is done in more than one buffer: recursive edits must be exited most-recently-entered first. Using alternative major modes avoids this limitation. *Note Recursive Editing::. The standard XEmacs Lisp library directory contains the code for several major modes, in files including `text-mode.el', `texinfo.el', `lisp-mode.el', `c-mode.el', and `rmail.el'. You can look at these libraries to see how modes are written. Text mode is perhaps the simplest major mode aside from Fundamental mode. Rmail mode is a complicated and specialized mode. * Menu: * Major Mode Conventions:: Coding conventions for keymaps, etc. * Example Major Modes:: Text mode and Lisp modes. * Auto Major Mode:: How XEmacs chooses the major mode automatically. * Mode Help:: Finding out how to use a mode. * Derived Modes:: Defining a new major mode based on another major mode.  File: lispref.info, Node: Major Mode Conventions, Next: Example Major Modes, Up: Major Modes Major Mode Conventions ---------------------- The code for existing major modes follows various coding conventions, including conventions for local keymap and syntax table initialization, global names, and hooks. Please follow these conventions when you define a new major mode: * Define a command whose name ends in `-mode', with no arguments, that switches to the new mode in the current buffer. This command should set up the keymap, syntax table, and local variables in an existing buffer without changing the buffer's text. * Write a documentation string for this command that describes the special commands available in this mode. `C-h m' (`describe-mode') in your mode will display this string. The documentation string may include the special documentation substrings, `\[COMMAND]', `\{KEYMAP}', and `\', that enable the documentation to adapt automatically to the user's own key bindings. *Note Keys in Documentation::. * The major mode command should start by calling `kill-all-local-variables'. This is what gets rid of the local variables of the major mode previously in effect. * The major mode command should set the variable `major-mode' to the major mode command symbol. This is how `describe-mode' discovers which documentation to print. * The major mode command should set the variable `mode-name' to the "pretty" name of the mode, as a string. This appears in the mode line. * Since all global names are in the same name space, all the global variables, constants, and functions that are part of the mode should have names that start with the major mode name (or with an abbreviation of it if the name is long). *Note Style Tips::. * The major mode should usually have its own keymap, which is used as the local keymap in all buffers in that mode. The major mode function should call `use-local-map' to install this local map. *Note Active Keymaps::, for more information. This keymap should be kept in a global variable named `MODENAME-mode-map'. Normally the library that defines the mode sets this variable. * The mode may have its own syntax table or may share one with other related modes. If it has its own syntax table, it should store this in a variable named `MODENAME-mode-syntax-table'. *Note Syntax Tables::. * The mode may have its own abbrev table or may share one with other related modes. If it has its own abbrev table, it should store this in a variable named `MODENAME-mode-abbrev-table'. *Note Abbrev Tables::. * Use `defvar' to set mode-related variables, so that they are not reinitialized if they already have a value. (Such reinitialization could discard customizations made by the user.) * To make a buffer-local binding for an Emacs customization variable, use `make-local-variable' in the major mode command, not `make-variable-buffer-local'. The latter function would make the variable local to every buffer in which it is subsequently set, which would affect buffers that do not use this mode. It is undesirable for a mode to have such global effects. *Note Buffer-Local Variables::. It's ok to use `make-variable-buffer-local', if you wish, for a variable used only within a single Lisp package. * Each major mode should have a "mode hook" named `MODENAME-mode-hook'. The major mode command should run that hook, with `run-hooks', as the very last thing it does. *Note Hooks::. * The major mode command may also run the hooks of some more basic modes. For example, `indented-text-mode' runs `text-mode-hook' as well as `indented-text-mode-hook'. It may run these other hooks immediately before the mode's own hook (that is, after everything else), or it may run them earlier. * If something special should be done if the user switches a buffer from this mode to any other major mode, the mode can set a local value for `change-major-mode-hook'. * If this mode is appropriate only for specially-prepared text, then the major mode command symbol should have a property named `mode-class' with value `special', put on as follows: (put 'funny-mode 'mode-class 'special) This tells XEmacs that new buffers created while the current buffer has Funny mode should not inherit Funny mode. Modes such as Dired, Rmail, and Buffer List use this feature. * If you want to make the new mode the default for files with certain recognizable names, add an element to `auto-mode-alist' to select the mode for those file names. If you define the mode command to autoload, you should add this element in the same file that calls `autoload'. Otherwise, it is sufficient to add the element in the file that contains the mode definition. *Note Auto Major Mode::. * In the documentation, you should provide a sample `autoload' form and an example of how to add to `auto-mode-alist', that users can include in their `.emacs' files. * The top-level forms in the file defining the mode should be written so that they may be evaluated more than once without adverse consequences. Even if you never load the file more than once, someone else will. - Variable: change-major-mode-hook This normal hook is run by `kill-all-local-variables' before it does anything else. This gives major modes a way to arrange for something special to be done if the user switches to a different major mode. For best results, make this variable buffer-local, so that it will disappear after doing its job and will not interfere with the subsequent major mode. *Note Hooks::.  File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes Major Mode Examples ------------------- Text mode is perhaps the simplest mode besides Fundamental mode. Here are excerpts from `text-mode.el' that illustrate many of the conventions listed above: ;; Create mode-specific tables. (defvar text-mode-syntax-table nil "Syntax table used while in text mode.") (if text-mode-syntax-table () ; Do not change the table if it is already set up. (setq text-mode-syntax-table (make-syntax-table)) (modify-syntax-entry ?\" ". " text-mode-syntax-table) (modify-syntax-entry ?\\ ". " text-mode-syntax-table) (modify-syntax-entry ?' "w " text-mode-syntax-table)) (defvar text-mode-abbrev-table nil "Abbrev table used while in text mode.") (define-abbrev-table 'text-mode-abbrev-table ()) (defvar text-mode-map nil) ; Create a mode-specific keymap. (if text-mode-map () ; Do not change the keymap if it is already set up. (setq text-mode-map (make-sparse-keymap)) (define-key text-mode-map "\t" 'tab-to-tab-stop) (define-key text-mode-map "\es" 'center-line) (define-key text-mode-map "\eS" 'center-paragraph)) Here is the complete major mode function definition for Text mode: (defun text-mode () "Major mode for editing text intended for humans to read. Special commands: \\{text-mode-map} Turning on text-mode runs the hook `text-mode-hook'." (interactive) (kill-all-local-variables) (use-local-map text-mode-map) ; This provides the local keymap. (setq mode-name "Text") ; This name goes into the modeline. (setq major-mode 'text-mode) ; This is how `describe-mode' ; finds the doc string to print. (setq local-abbrev-table text-mode-abbrev-table) (set-syntax-table text-mode-syntax-table) (run-hooks 'text-mode-hook)) ; Finally, this permits the user to ; customize the mode with a hook. The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction mode) have more features than Text mode and the code is correspondingly more complicated. Here are excerpts from `lisp-mode.el' that illustrate how these modes are written. ;; Create mode-specific table variables. (defvar lisp-mode-syntax-table nil "") (defvar emacs-lisp-mode-syntax-table nil "") (defvar lisp-mode-abbrev-table nil "") (if (not emacs-lisp-mode-syntax-table) ; Do not change the table ; if it is already set. (let ((i 0)) (setq emacs-lisp-mode-syntax-table (make-syntax-table)) ;; Set syntax of chars up to 0 to class of chars that are ;; part of symbol names but not words. ;; (The number 0 is `48' in the ASCII character set.) (while (< i ?0) (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table) (setq i (1+ i))) ... ;; Set the syntax for other characters. (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table) (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table) ... (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table) (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table) ...)) ;; Create an abbrev table for lisp-mode. (define-abbrev-table 'lisp-mode-abbrev-table ()) Much code is shared among the three Lisp modes. The following function sets various variables; it is called by each of the major Lisp mode functions: (defun lisp-mode-variables (lisp-syntax) ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode, ;; and `t' in the other two Lisp modes. (cond (lisp-syntax (if (not lisp-mode-syntax-table) ;; The Emacs Lisp mode syntax table always exists, but ;; the Lisp Mode syntax table is created the first time a ;; mode that needs it is called. This is to save space. (progn (setq lisp-mode-syntax-table (copy-syntax-table emacs-lisp-mode-syntax-table)) ;; Change some entries for Lisp mode. (modify-syntax-entry ?\| "\" " lisp-mode-syntax-table) (modify-syntax-entry ?\[ "_ " lisp-mode-syntax-table) (modify-syntax-entry ?\] "_ " lisp-mode-syntax-table))) (set-syntax-table lisp-mode-syntax-table))) (setq local-abbrev-table lisp-mode-abbrev-table) ...) Functions such as `forward-paragraph' use the value of the `paragraph-start' variable. Since Lisp code is different from ordinary text, the `paragraph-start' variable needs to be set specially to handle Lisp. Also, comments are indented in a special fashion in Lisp and the Lisp modes need their own mode-specific `comment-indent-function'. The code to set these variables is the rest of `lisp-mode-variables'. (make-local-variable 'paragraph-start) ;; Having `^' is not clean, but `page-delimiter' ;; has them too, and removing those is a pain. (setq paragraph-start (concat "^$\\|" page-delimiter)) ... (make-local-variable 'comment-indent-function) (setq comment-indent-function 'lisp-comment-indent)) Each of the different Lisp modes has a slightly different keymap. For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other Lisp modes do not. However, all Lisp modes have some commands in common. The following function adds these common commands to a given keymap. (defun lisp-mode-commands (map) (define-key map "\e\C-q" 'indent-sexp) (define-key map "\177" 'backward-delete-char-untabify) (define-key map "\t" 'lisp-indent-line)) Here is an example of using `lisp-mode-commands' to initialize a keymap, as part of the code for Emacs Lisp mode. First we declare a variable with `defvar' to hold the mode-specific keymap. When this `defvar' executes, it sets the variable to `nil' if it was void. Then we set up the keymap if the variable is `nil'. This code avoids changing the keymap or the variable if it is already set up. This lets the user customize the keymap. (defvar emacs-lisp-mode-map () "") (if emacs-lisp-mode-map () (setq emacs-lisp-mode-map (make-sparse-keymap)) (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun) (lisp-mode-commands emacs-lisp-mode-map)) Finally, here is the complete major mode function definition for Emacs Lisp mode. (defun emacs-lisp-mode () "Major mode for editing Lisp code to run in XEmacs. Commands: Delete converts tabs to spaces as it moves back. Blank lines separate paragraphs. Semicolons start comments. \\{emacs-lisp-mode-map} Entry to this mode runs the hook `emacs-lisp-mode-hook'." (interactive) (kill-all-local-variables) (use-local-map emacs-lisp-mode-map) ; This provides the local keymap. (set-syntax-table emacs-lisp-mode-syntax-table) (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode' ; finds out what to describe. (setq mode-name "Emacs-Lisp") ; This goes into the modeline. (lisp-mode-variables nil) ; This defines various variables. (run-hooks 'emacs-lisp-mode-hook)) ; This permits the user to use a ; hook to customize the mode.  File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes How XEmacs Chooses a Major Mode ------------------------------- Based on information in the file name or in the file itself, XEmacs automatically selects a major mode for the new buffer when a file is visited. - Command: fundamental-mode Fundamental mode is a major mode that is not specialized for anything in particular. Other major modes are defined in effect by comparison with this one--their definitions say what to change, starting from Fundamental mode. The `fundamental-mode' function does _not_ run any hooks; you're not supposed to customize it. (If you want Emacs to behave differently in Fundamental mode, change the _global_ state of Emacs.) - Command: normal-mode &optional find-file This function establishes the proper major mode and local variable bindings for the current buffer. First it calls `set-auto-mode', then it runs `hack-local-variables' to parse, and bind or evaluate as appropriate, any local variables. If the FIND-FILE argument to `normal-mode' is non-`nil', `normal-mode' assumes that the `find-file' function is calling it. In this case, it may process a local variables list at the end of the file and in the `-*-' line. The variable `enable-local-variables' controls whether to do so. If you run `normal-mode' interactively, the argument FIND-FILE is normally `nil'. In this case, `normal-mode' unconditionally processes any local variables list. *Note Local Variables in Files: (xemacs)File variables, for the syntax of the local variables section of a file. `normal-mode' uses `condition-case' around the call to the major mode function, so errors are caught and reported as a `File mode specification error', followed by the original error message. - User Option: enable-local-variables This variable controls processing of local variables lists in files being visited. A value of `t' means process the local variables lists unconditionally; `nil' means ignore them; anything else means ask the user what to do for each file. The default value is `t'. - Variable: ignored-local-variables This variable holds a list of variables that should not be set by a local variables list. Any value specified for one of these variables is ignored. In addition to this list, any variable whose name has a non-`nil' `risky-local-variable' property is also ignored. - User Option: enable-local-eval This variable controls processing of `Eval:' in local variables lists in files being visited. A value of `t' means process them unconditionally; `nil' means ignore them; anything else means ask the user what to do for each file. The default value is `maybe'. - Function: set-auto-mode This function selects the major mode that is appropriate for the current buffer. It may base its decision on the value of the `-*-' line, on the visited file name (using `auto-mode-alist'), or on the value of a local variable. However, this function does not look for the `mode:' local variable near the end of a file; the `hack-local-variables' function does that. *Note How Major Modes are Chosen: (xemacs)Choosing Modes. - User Option: default-major-mode This variable holds the default major mode for new buffers. The standard value is `fundamental-mode'. If the value of `default-major-mode' is `nil', XEmacs uses the (previously) current buffer's major mode for the major mode of a new buffer. However, if the major mode symbol has a `mode-class' property with value `special', then it is not used for new buffers; Fundamental mode is used instead. The modes that have this property are those such as Dired and Rmail that are useful only with text that has been specially prepared. - Function: set-buffer-major-mode buffer This function sets the major mode of BUFFER to the value of `default-major-mode'. If that variable is `nil', it uses the current buffer's major mode (if that is suitable). The low-level primitives for creating buffers do not use this function, but medium-level commands such as `switch-to-buffer' and `find-file-noselect' use it whenever they create buffers. - Variable: initial-major-mode The value of this variable determines the major mode of the initial `*scratch*' buffer. The value should be a symbol that is a major mode command name. The default value is `lisp-interaction-mode'. - Variable: auto-mode-alist This variable contains an association list of file name patterns (regular expressions; *note Regular Expressions::) and corresponding major mode functions. Usually, the file name patterns test for suffixes, such as `.el' and `.c', but this need not be the case. An ordinary element of the alist looks like `(REGEXP . MODE-FUNCTION)'. For example, (("^/tmp/fol/" . text-mode) ("\\.texinfo\\'" . texinfo-mode) ("\\.texi\\'" . texinfo-mode) ("\\.el\\'" . emacs-lisp-mode) ("\\.c\\'" . c-mode) ("\\.h\\'" . c-mode) ...) When you visit a file whose expanded file name (*note File Name Expansion::) matches a REGEXP, `set-auto-mode' calls the corresponding MODE-FUNCTION. This feature enables XEmacs to select the proper major mode for most files. If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION t)', then after calling FUNCTION, XEmacs searches `auto-mode-alist' again for a match against the portion of the file name that did not match before. This match-again feature is useful for uncompression packages: an entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file and then put the uncompressed file in the proper mode according to the name sans `.gz'. Here is an example of how to prepend several pattern pairs to `auto-mode-alist'. (You might use this sort of expression in your `.emacs' file.) (setq auto-mode-alist (append ;; File name starts with a dot. '(("/\\.[^/]*\\'" . fundamental-mode) ;; File name has no dot. ("[^\\./]*\\'" . fundamental-mode) ;; File name ends in `.C'. ("\\.C\\'" . c++-mode)) auto-mode-alist)) - Variable: interpreter-mode-alist This variable specifies major modes to use for scripts that specify a command interpreter in an `#!' line. Its value is a list of elements of the form `(INTERPRETER . MODE)'; for example, `("perl" . perl-mode)' is one element present by default. The element says to use mode MODE if the file specifies INTERPRETER. This variable is applicable only when the `auto-mode-alist' does not indicate which major mode to use. - Function: hack-local-variables &optional force This function parses, and binds or evaluates as appropriate, any local variables for the current buffer. The handling of `enable-local-variables' documented for `normal-mode' actually takes place here. The argument FORCE usually comes from the argument FIND-FILE given to `normal-mode'.  File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes Getting Help about a Major Mode ------------------------------- The `describe-mode' function is used to provide information about major modes. It is normally called with `C-h m'. The `describe-mode' function uses the value of `major-mode', which is why every major mode function needs to set the `major-mode' variable. - Command: describe-mode This function displays the documentation of the current major mode. The `describe-mode' function calls the `documentation' function using the value of `major-mode' as an argument. Thus, it displays the documentation string of the major mode function. (*Note Accessing Documentation::.) - Variable: major-mode This variable holds the symbol for the current buffer's major mode. This symbol should have a function definition that is the command to switch to that major mode. The `describe-mode' function uses the documentation string of the function as the documentation of the major mode.  File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes Defining Derived Modes ---------------------- It's often useful to define a new major mode in terms of an existing one. An easy way to do this is to use `define-derived-mode'. - Macro: define-derived-mode variant parent name docstring body... This construct defines VARIANT as a major mode command, using NAME as the string form of the mode name. The new command VARIANT is defined to call the function PARENT, then override certain aspects of that parent mode: * The new mode has its own keymap, named `VARIANT-map'. `define-derived-mode' initializes this map to inherit from `PARENT-map', if it is not already set. * The new mode has its own syntax table, kept in the variable `VARIANT-syntax-table'. `define-derived-mode' initializes this variable by copying `PARENT-syntax-table', if it is not already set. * The new mode has its own abbrev table, kept in the variable `VARIANT-abbrev-table'. `define-derived-mode' initializes this variable by copying `PARENT-abbrev-table', if it is not already set. * The new mode has its own mode hook, `VARIANT-hook', which it runs in standard fashion as the very last thing that it does. (The new mode also runs the mode hook of PARENT as part of calling PARENT.) In addition, you can specify how to override other aspects of PARENT with BODY. The command VARIANT evaluates the forms in BODY after setting up all its usual overrides, just before running `VARIANT-hook'. The argument DOCSTRING specifies the documentation string for the new mode. If you omit DOCSTRING, `define-derived-mode' generates a documentation string. Here is a hypothetical example: (define-derived-mode hypertext-mode text-mode "Hypertext" "Major mode for hypertext. \\{hypertext-mode-map}" (setq case-fold-search nil)) (define-key hypertext-mode-map [down-mouse-3] 'do-hyper-link)  File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes Minor Modes =========== A "minor mode" provides features that users may enable or disable independently of the choice of major mode. Minor modes can be enabled individually or in combination. Minor modes would be better named "Generally available, optional feature modes" except that such a name is unwieldy. A minor mode is not usually a modification of single major mode. For example, Auto Fill mode may be used in any major mode that permits text insertion. To be general, a minor mode must be effectively independent of the things major modes do. A minor mode is often much more difficult to implement than a major mode. One reason is that you should be able to activate and deactivate minor modes in any order. A minor mode should be able to have its desired effect regardless of the major mode and regardless of the other minor modes in effect. Often the biggest problem in implementing a minor mode is finding a way to insert the necessary hook into the rest of XEmacs. Minor mode keymaps make this easier than it used to be. * Menu: * Minor Mode Conventions:: Tips for writing a minor mode. * Keymaps and Minor Modes:: How a minor mode can have its own keymap.  File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes Conventions for Writing Minor Modes ----------------------------------- There are conventions for writing minor modes just as there are for major modes. Several of the major mode conventions apply to minor modes as well: those regarding the name of the mode initialization function, the names of global symbols, and the use of keymaps and other tables. In addition, there are several conventions that are specific to minor modes. * Make a variable whose name ends in `-mode' to represent the minor mode. Its value should enable or disable the mode (`nil' to disable; anything else to enable.) We call this the "mode variable". This variable is used in conjunction with the `minor-mode-alist' to display the minor mode name in the modeline. It can also enable or disable a minor mode keymap. Individual commands or hooks can also check the variable's value. If you want the minor mode to be enabled separately in each buffer, make the variable buffer-local. * Define a command whose name is the same as the mode variable. Its job is to enable and disable the mode by setting the variable. The command should accept one optional argument. If the argument is `nil', it should toggle the mode (turn it on if it is off, and off if it is on). Otherwise, it should turn the mode on if the argument is a positive integer, a symbol other than `nil' or `-', or a list whose CAR is such an integer or symbol; it should turn the mode off otherwise. Here is an example taken from the definition of `transient-mark-mode'. It shows the use of `transient-mark-mode' as a variable that enables or disables the mode's behavior, and also shows the proper way to toggle, enable or disable the minor mode based on the raw prefix argument value. (setq transient-mark-mode (if (null arg) (not transient-mark-mode) (> (prefix-numeric-value arg) 0))) * Add an element to `minor-mode-alist' for each minor mode (*note Modeline Variables::). This element should be a list of the following form: (MODE-VARIABLE STRING) Here MODE-VARIABLE is the variable that controls enabling of the minor mode, and STRING is a short string, starting with a space, to represent the mode in the modeline. These strings must be short so that there is room for several of them at once. When you add an element to `minor-mode-alist', use `assq' to check for an existing element, to avoid duplication. For example: (or (assq 'leif-mode minor-mode-alist) (setq minor-mode-alist (cons '(leif-mode " Leif") minor-mode-alist)))  File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes Keymaps and Minor Modes ----------------------- Each minor mode can have its own keymap, which is active when the mode is enabled. To set up a keymap for a minor mode, add an element to the alist `minor-mode-map-alist'. *Note Active Keymaps::. One use of minor mode keymaps is to modify the behavior of certain self-inserting characters so that they do something else as well as self-insert. In general, this is the only way to do that, since the facilities for customizing `self-insert-command' are limited to special cases (designed for abbrevs and Auto Fill mode). (Do not try substituting your own definition of `self-insert-command' for the standard one. The editor command loop handles this function specially.)  File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes Modeline Format =============== Each Emacs window (aside from minibuffer windows) includes a modeline, which displays status information about the buffer displayed in the window. The modeline contains information about the buffer, such as its name, associated file, depth of recursive editing, and the major and minor modes. This section describes how the contents of the modeline are controlled. It is in the chapter on modes because much of the information displayed in the modeline relates to the enabled major and minor modes. `modeline-format' is a buffer-local variable that holds a template used to display the modeline of the current buffer. All windows for the same buffer use the same `modeline-format' and their modelines appear the same (except for scrolling percentages and line numbers). The modeline of a window is normally updated whenever a different buffer is shown in the window, or when the buffer's modified-status changes from `nil' to `t' or vice-versa. If you modify any of the variables referenced by `modeline-format' (*note Modeline Variables::), you may want to force an update of the modeline so as to display the new information. - Function: redraw-modeline &optional all Force redisplay of the current buffer's modeline. If ALL is non-`nil', then force redisplay of all modelines. The modeline is usually displayed in inverse video. This is controlled using the `modeline' face. *Note Faces::. * Menu: * Modeline Data:: The data structure that controls the modeline. * Modeline Variables:: Variables used in that data structure. * %-Constructs:: Putting information into a modeline.  File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format The Data Structure of the Modeline ---------------------------------- The modeline contents are controlled by a data structure of lists, strings, symbols, and numbers kept in the buffer-local variable `modeline-format'. The data structure is called a "modeline construct", and it is built in recursive fashion out of simpler modeline constructs. The same data structure is used for constructing frame titles (*note Frame Titles::). - Variable: modeline-format The value of this variable is a modeline construct with overall responsibility for the modeline format. The value of this variable controls which other variables are used to form the modeline text, and where they appear. A modeline construct may be as simple as a fixed string of text, but it usually specifies how to use other variables to construct the text. Many of these variables are themselves defined to have modeline constructs as their values. The default value of `modeline-format' incorporates the values of variables such as `mode-name' and `minor-mode-alist'. Because of this, very few modes need to alter `modeline-format'. For most purposes, it is sufficient to alter the variables referenced by `modeline-format'. A modeline construct may be a string, symbol, glyph, generic specifier, list or cons cell. `STRING' A string as a modeline construct is displayed verbatim in the mode line except for "`%'-constructs". Decimal digits after the `%' specify the field width for space filling on the right (i.e., the data is left justified). *Note %-Constructs::. `SYMBOL' A symbol as a modeline construct stands for its value. The value of SYMBOL is processed as a modeline construct, in place of SYMBOL. However, the symbols `t' and `nil' are ignored; so is any symbol whose value is void. There is one exception: if the value of SYMBOL is a string, it is displayed verbatim: the `%'-constructs are not recognized. `GLYPH' A glyph is displayed as is. `GENERIC-SPECIFIER' A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands for its instance. The instance of GENERIC-SPECIFIER is computed in the current window using the equivalent of `specifier-instance' and the value is processed. `(STRING REST...) or (LIST REST...)' A list whose first element is a string or list means to process all the elements recursively and concatenate the results. This is the most common form of mode line construct. `(SYMBOL THEN ELSE)' A list whose first element is a symbol is a conditional. Its meaning depends on the value of SYMBOL. If the value is non-`nil', the second element, THEN, is processed recursively as a modeline element. But if the value of SYMBOL is `nil', the third element, ELSE, is processed recursively. You may omit ELSE; then the mode line element displays nothing if the value of SYMBOL is `nil'. `(WIDTH REST...)' A list whose first element is an integer specifies truncation or padding of the results of REST. The remaining elements REST are processed recursively as modeline constructs and concatenated together. Then the result is space filled (if WIDTH is positive) or truncated (to -WIDTH columns, if WIDTH is negative) on the right. For example, the usual way to show what percentage of a buffer is above the top of the window is to use a list like this: `(-3 "%p")'. `(EXTENT REST...)' A list whose car is an extent means the cdr of the list is processed normally but the results are displayed using the face of the extent, and mouse clicks over this section are processed using the keymap of the extent. (In addition, if the extent has a help-echo property, that string will be echoed when the mouse moves over this section.) If extents are nested, all keymaps are properly consulted when processing mouse clicks, but multiple faces are not correctly merged (only the first face is used), and lists of faces are not correctly handled. If you do alter `modeline-format' itself, the new value should use the same variables that appear in the default value (*note Modeline Variables::), rather than duplicating their contents or displaying the information in another fashion. This way, customizations made by the user or by Lisp programs (such as `display-time' and major modes) via changes to those variables remain effective. Here is an example of a `modeline-format' that might be useful for `shell-mode', since it contains the hostname and default directory. (setq modeline-format (list "" 'modeline-modified "%b--" (getenv "HOST") ; One element is not constant. ":" 'default-directory " " 'global-mode-string " %[(" 'mode-name 'modeline-process 'minor-mode-alist "%n" ")%]----" '(line-number-mode "L%l--") '(-3 . "%p") "-%-"))  File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format Variables Used in the Modeline ------------------------------ This section describes variables incorporated by the standard value of `modeline-format' into the text of the mode line. There is nothing inherently special about these variables; any other variables could have the same effects on the modeline if `modeline-format' were changed to use them. - Variable: modeline-modified This variable holds the value of the modeline construct that displays whether the current buffer is modified. The default value of `modeline-modified' is `("--%1*%1+-")'. This means that the modeline displays `--**-' if the buffer is modified, `-----' if the buffer is not modified, `--%%-' if the buffer is read only, and `--%*--' if the buffer is read only and modified. Changing this variable does not force an update of the modeline. - Variable: modeline-buffer-identification This variable identifies the buffer being displayed in the window. Its default value is `("%F: %17b")', which means that it usually displays `Emacs:' followed by seventeen characters of the buffer name. (In a terminal frame, it displays the frame name instead of `Emacs'; this has the effect of showing the frame number.) You may want to change this in modes such as Rmail that do not behave like a "normal" XEmacs. - Variable: global-mode-string This variable holds a modeline spec that appears in the mode line by default, just after the buffer name. The command `display-time' sets `global-mode-string' to refer to the variable `display-time-string', which holds a string containing the time and load information. The `%M' construct substitutes the value of `global-mode-string', but this is obsolete, since the variable is included directly in the modeline. - Variable: mode-name This buffer-local variable holds the "pretty" name of the current buffer's major mode. Each major mode should set this variable so that the mode name will appear in the modeline. - Variable: minor-mode-alist This variable holds an association list whose elements specify how the modeline should indicate that a minor mode is active. Each element of the `minor-mode-alist' should be a two-element list: (MINOR-MODE-VARIABLE MODELINE-STRING) More generally, MODELINE-STRING can be any mode line spec. It appears in the mode line when the value of MINOR-MODE-VARIABLE is non-`nil', and not otherwise. These strings should begin with spaces so that they don't run together. Conventionally, the MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil' value when that minor mode is activated. The default value of `minor-mode-alist' is: minor-mode-alist => ((vc-mode vc-mode) (abbrev-mode " Abbrev") (overwrite-mode overwrite-mode) (auto-fill-function " Fill") (defining-kbd-macro " Def") (isearch-mode isearch-mode)) `minor-mode-alist' is not buffer-local. The variables mentioned in the alist should be buffer-local if the minor mode can be enabled separately in each buffer. - Variable: modeline-process This buffer-local variable contains the modeline information on process status in modes used for communicating with subprocesses. It is displayed immediately following the major mode name, with no intervening space. For example, its value in the `*shell*' buffer is `(": %s")', which allows the shell to display its status along with the major mode as: `(Shell: run)'. Normally this variable is `nil'. - Variable: default-modeline-format This variable holds the default `modeline-format' for buffers that do not override it. This is the same as `(default-value 'modeline-format)'. The default value of `default-modeline-format' is: ("" modeline-modified modeline-buffer-identification " " global-mode-string " %[(" mode-name modeline-process minor-mode-alist "%n" ")%]----" (line-number-mode "L%l--") (-3 . "%p") "-%-") - Variable: vc-mode The variable `vc-mode', local in each buffer, records whether the buffer's visited file is maintained with version control, and, if so, which kind. Its value is `nil' for no version control, or a string that appears in the mode line.  File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format `%'-Constructs in the ModeLine ------------------------------ The following table lists the recognized `%'-constructs and what they mean. In any construct except `%%', you can add a decimal integer after the `%' to specify how many characters to display. `%b' The current buffer name, obtained with the `buffer-name' function. *Note Buffer Names::. `%f' The visited file name, obtained with the `buffer-file-name' function. *Note Buffer File Name::. `%F' The name of the selected frame. `%c' The current column number of point. `%l' The current line number of point. `%*' `%' if the buffer is read only (see `buffer-read-only'); `*' if the buffer is modified (see `buffer-modified-p'); `-' otherwise. *Note Buffer Modification::. `%+' `*' if the buffer is modified (see `buffer-modified-p'); `%' if the buffer is read only (see `buffer-read-only'); `-' otherwise. This differs from `%*' only for a modified read-only buffer. *Note Buffer Modification::. `%&' `*' if the buffer is modified, and `-' otherwise. `%s' The status of the subprocess belonging to the current buffer, obtained with `process-status'. *Note Process Information::. `%l' The current line number. `%S' The name of the selected frame; this is only meaningful under the X Window System. *Note Frame Name::. `%t' Whether the visited file is a text file or a binary file. (This is a meaningful distinction only on certain operating systems.) `%p' The percentage of the buffer text above the *top* of window, or `Top', `Bottom' or `All'. `%P' The percentage of the buffer text that is above the *bottom* of the window (which includes the text visible in the window, as well as the text above the top), plus `Top' if the top of the buffer is visible on screen; or `Bottom' or `All'. `%n' `Narrow' when narrowing is in effect; nothing otherwise (see `narrow-to-region' in *Note Narrowing::). `%C' Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'. `%[' An indication of the depth of recursive editing levels (not counting minibuffer levels): one `[' for each editing level. *Note Recursive Editing::. `%]' One `]' for each recursive editing level (not counting minibuffer levels). `%%' The character `%'--this is how to include a literal `%' in a string in which `%'-constructs are allowed. `%-' Dashes sufficient to fill the remainder of the modeline. The following two `%'-constructs are still supported, but they are obsolete, since you can get the same results with the variables `mode-name' and `global-mode-string'. `%m' The value of `mode-name'. `%M' The value of `global-mode-string'. Currently, only `display-time' modifies the value of `global-mode-string'.  File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes Hooks ===== A "hook" is a variable where you can store a function or functions to be called on a particular occasion by an existing program. XEmacs provides hooks for the sake of customization. Most often, hooks are set up in the `.emacs' file, but Lisp programs can set them also. *Note Standard Hooks::, for a list of standard hook variables. Most of the hooks in XEmacs are "normal hooks". These variables contain lists of functions to be called with no arguments. The reason most hooks are normal hooks is so that you can use them in a uniform way. You can usually tell when a hook is a normal hook, because its name ends in `-hook'. The recommended way to add a hook function to a normal hook is by calling `add-hook' (see below). The hook functions may be any of the valid kinds of functions that `funcall' accepts (*note What Is a Function::). Most normal hook variables are initially void; `add-hook' knows how to deal with this. As for abnormal hooks, those whose names end in `-function' have a value that is a single function. Those whose names end in `-hooks' have a value that is a list of functions. Any hook that is abnormal is abnormal because a normal hook won't do the job; either the functions are called with arguments, or their values are meaningful. The name shows you that the hook is abnormal and that you should look at its documentation string to see how to use it properly. Major mode functions are supposed to run a hook called the "mode hook" as the last step of initialization. This makes it easy for a user to customize the behavior of the mode, by overriding the local variable assignments already made by the mode. But hooks are used in other contexts too. For example, the hook `suspend-hook' runs just before XEmacs suspends itself (*note Suspending XEmacs::). Here's an expression that uses a mode hook to turn on Auto Fill mode when in Lisp Interaction mode: (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) The next example shows how to use a hook to customize the way XEmacs formats C code. (People often have strong personal preferences for one format or another.) Here the hook function is an anonymous lambda expression. (add-hook 'c-mode-hook (function (lambda () (setq c-indent-level 4 c-argdecl-indent 0 c-label-offset -4 c-continued-statement-indent 0 c-brace-offset 0 comment-column 40)))) (setq c++-mode-hook c-mode-hook) The final example shows how the appearance of the modeline can be modified for a particular class of buffers only. (add-hook 'text-mode-hook (function (lambda () (setq modeline-format '(modeline-modified "Emacs: %14b" " " default-directory " " global-mode-string "%[(" mode-name minor-mode-alist "%n" modeline-process ") %]---" (-3 . "%p") "-%-"))))) At the appropriate time, XEmacs uses the `run-hooks' function to run particular hooks. This function calls the hook functions you have added with `add-hooks'. - Function: run-hooks &rest hookvar This function takes one or more hook variable names as arguments, and runs each hook in turn. Each HOOKVAR argument should be a symbol that is a hook variable. These arguments are processed in the order specified. If a hook variable has a non-`nil' value, that value may be a function or a list of functions. If the value is a function (either a lambda expression or a symbol with a function definition), it is called. If it is a list, the elements are called, in order. The hook functions are called with no arguments. For example, here's how `emacs-lisp-mode' runs its mode hook: (run-hooks 'emacs-lisp-mode-hook) - Function: add-hook hook function &optional append local This function is the handy way to add function FUNCTION to hook variable HOOK. The argument FUNCTION may be any valid Lisp function with the proper number of arguments. For example, (add-hook 'text-mode-hook 'my-text-hook-function) adds `my-text-hook-function' to the hook called `text-mode-hook'. You can use `add-hook' for abnormal hooks as well as for normal hooks. It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is "asking for trouble." However, the order is predictable: normally, FUNCTION goes at the front of the hook list, so it will be executed first (barring another `add-hook' call). If the optional argument APPEND is non-`nil', the new hook function goes at the end of the hook list and will be executed last. If LOCAL is non-`nil', that says to make the new hook function local to the current buffer. Before you can do this, you must make the hook itself buffer-local by calling `make-local-hook' (*not* `make-local-variable'). If the hook itself is not buffer-local, then the value of LOCAL makes no difference--the hook function is always global. - Function: remove-hook hook function &optional local This function removes FUNCTION from the hook variable HOOK. If LOCAL is non-`nil', that says to remove FUNCTION from the local hook list instead of from the global hook list. If the hook itself is not buffer-local, then the value of LOCAL makes no difference. - Function: make-local-hook hook This function makes the hook variable HOOK local to the current buffer. When a hook variable is local, it can have local and global hook functions, and `run-hooks' runs all of them. This function works by making `t' an element of the buffer-local value. That serves as a flag to use the hook functions in the default value of the hook variable as well as those in the local value. Since `run-hooks' understands this flag, `make-local-hook' works with all normal hooks. It works for only some non-normal hooks--those whose callers have been updated to understand this meaning of `t'. Do not use `make-local-variable' directly for hook variables; it is not sufficient.  File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top Documentation ************* XEmacs Lisp has convenient on-line help facilities, most of which derive their information from the documentation strings associated with functions and variables. This chapter describes how to write good documentation strings for your Lisp programs, as well as how to write programs to access documentation. Note that the documentation strings for XEmacs are not the same thing as the XEmacs manual. Manuals have their own source files, written in the Texinfo language; documentation strings are specified in the definitions of the functions and variables they apply to. A collection of documentation strings is not sufficient as a manual because a good manual is not organized in that fashion; it is organized in terms of topics of discussion. * Menu: * Documentation Basics:: Good style for doc strings. Where to put them. How XEmacs stores them. * Accessing Documentation:: How Lisp programs can access doc strings. * Keys in Documentation:: Substituting current key bindings. * Describing Characters:: Making printable descriptions of non-printing characters and key sequences. * Help Functions:: Subroutines used by XEmacs help facilities. * Obsoleteness:: Upgrading Lisp functionality over time.  File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation Documentation Basics ==================== A documentation string is written using the Lisp syntax for strings, with double-quote characters surrounding the text of the string. This is because it really is a Lisp string object. The string serves as documentation when it is written in the proper place in the definition of a function or variable. In a function definition, the documentation string follows the argument list. In a variable definition, the documentation string follows the initial value of the variable. When you write a documentation string, make the first line a complete sentence (or two complete sentences) since some commands, such as `apropos', show only the first line of a multi-line documentation string. Also, you should not indent the second line of a documentation string, if you have one, because that looks odd when you use `C-h f' (`describe-function') or `C-h v' (`describe-variable'). *Note Documentation Tips::. Documentation strings may contain several special substrings, which stand for key bindings to be looked up in the current keymaps when the documentation is displayed. This allows documentation strings to refer to the keys for related commands and be accurate even when a user rearranges the key bindings. (*Note Accessing Documentation::.) Within the Lisp world, a documentation string is accessible through the function or variable that it describes: * The documentation for a function is stored in the function definition itself (*note Lambda Expressions::). The function `documentation' knows how to extract it. * The documentation for a variable is stored in the variable's property list under the property name `variable-documentation'. The function `documentation-property' knows how to extract it. To save space, the documentation for preloaded functions and variables (including primitive functions and autoloaded functions) is stored in the "internal doc file" `DOC'. The documentation for functions and variables loaded during the XEmacs session from byte-compiled files is stored in those very same byte-compiled files (*note Docs and Compilation::). XEmacs does not keep documentation strings in memory unless necessary. Instead, XEmacs maintains, for preloaded symbols, an integer offset into the internal doc file, and for symbols loaded from byte-compiled files, a list containing the filename of the byte-compiled file and an integer offset, in place of the documentation string. The functions `documentation' and `documentation-property' use that information to read the documentation from the appropriate file; this is transparent to the user. For information on the uses of documentation strings, see *Note Help: (xemacs)Help. The `emacs/lib-src' directory contains two utilities that you can use to print nice-looking hardcopy for the file `emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'.  File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation Access to Documentation Strings =============================== - Function: documentation-property symbol property &optional verbatim This function returns the documentation string that is recorded in SYMBOL's property list under property PROPERTY. It retrieves the text from a file if necessary, and runs `substitute-command-keys' to substitute actual key bindings. (This substitution is not done if VERBATIM is non-`nil'; the VERBATIM argument exists only as of Emacs 19.) (documentation-property 'command-line-processed 'variable-documentation) => "t once command line has been processed" (symbol-plist 'command-line-processed) => (variable-documentation 188902) - Function: documentation function &optional verbatim This function returns the documentation string of FUNCTION. It reads the text from a file if necessary. Then (unless VERBATIM is non-`nil') it calls `substitute-command-keys', to return a value containing the actual (current) key bindings. The function `documentation' signals a `void-function' error if FUNCTION has no function definition. However, it is ok if the function definition has no documentation string. In that case, `documentation' returns `nil'. Here is an example of using the two functions, `documentation' and `documentation-property', to display the documentation strings for several symbols in a `*Help*' buffer. (defun describe-symbols (pattern) "Describe the XEmacs Lisp symbols matching PATTERN. All symbols that have PATTERN in their name are described in the `*Help*' buffer." (interactive "sDescribe symbols matching: ") (let ((describe-func (function (lambda (s) ;; Print description of symbol. (if (fboundp s) ; It is a function. (princ (format "%s\t%s\n%s\n\n" s (if (commandp s) (let ((keys (where-is-internal s))) (if keys (concat "Keys: " (mapconcat 'key-description keys " ")) "Keys: none")) "Function") (or (documentation s) "not documented")))) (if (boundp s) ; It is a variable. (princ (format "%s\t%s\n%s\n\n" s (if (user-variable-p s) "Option " "Variable") (or (documentation-property s 'variable-documentation) "not documented"))))))) sym-list) ;; Build a list of symbols that match pattern. (mapatoms (function (lambda (sym) (if (string-match pattern (symbol-name sym)) (setq sym-list (cons sym sym-list)))))) ;; Display the data. (with-output-to-temp-buffer "*Help*" (mapcar describe-func (sort sym-list 'string<)) (print-help-return-message)))) The `describe-symbols' function works like `apropos', but provides more information. (describe-symbols "goal") ---------- Buffer: *Help* ---------- goal-column Option *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil. set-goal-column Command: C-x C-n Set the current horizontal position as a goal for C-n and C-p. Those commands will move to this position in the line moved to rather than trying to keep the same horizontal position. With a non-`nil' argument, clears out the goal column so that C-n and C-p resume vertical motion. The goal column is stored in the variable `goal-column'. temporary-goal-column Variable Current goal column for vertical motion. It is the column where point was at the start of current run of vertical motion commands. When the `track-eol' feature is doing its job, the value is 9999. ---------- Buffer: *Help* ---------- - Function: Snarf-documentation filename This function is used only during XEmacs initialization, just before the runnable XEmacs is dumped. It finds the file offsets of the documentation strings stored in the file FILENAME, and records them in the in-core function definitions and variable property lists in place of the actual strings. *Note Building XEmacs::. XEmacs finds the file FILENAME in the `lib-src' directory. When the dumped XEmacs is later executed, the same file is found in the directory `doc-directory'. The usual value for FILENAME is `DOC', but this can be changed by modifying the variable `internal-doc-file-name'. - Variable: internal-doc-file-name This variable holds the name of the file containing documentation strings of built-in symbols, usually `DOC'. The full pathname of the internal doc file is `(concat doc-directory internal-doc-file-name)'. - Variable: doc-directory This variable holds the name of the directory which contains the "internal doc file" that contains documentation strings for built-in and preloaded functions and variables. In most cases, this is the same as `exec-directory'. They may be different when you run XEmacs from the directory where you built it, without actually installing it. See `exec-directory' in *Note Help Functions::. In older Emacs versions, `exec-directory' was used for this. - Variable: data-directory This variable holds the name of the directory in which XEmacs finds certain system independent documentation and text files that come with XEmacs. In older Emacs versions, `exec-directory' was used for this.  File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation Substituting Key Bindings in Documentation ========================================== When documentation strings refer to key sequences, they should use the current, actual key bindings. They can do so using certain special text sequences described below. Accessing documentation strings in the usual way substitutes current key binding information for these special sequences. This works by calling `substitute-command-keys'. You can also call that function yourself. Here is a list of the special sequences and what they mean: `\[COMMAND]' stands for a key sequence that will invoke COMMAND, or `M-x COMMAND' if COMMAND has no key bindings. `\{MAPVAR}' stands for a summary of the value of MAPVAR, which should be a keymap. The summary is made by `describe-bindings'. `\' stands for no text itself. It is used for a side effect: it specifies MAPVAR as the keymap for any following `\[COMMAND]' sequences in this documentation string. `\=' quotes the following character and is discarded; this `\=\=' puts `\=' into the output, and `\=\[' puts `\[' into the output. *Please note:* Each `\' must be doubled when written in a string in XEmacs Lisp. - Function: substitute-command-keys string This function scans STRING for the above special sequences and replaces them by what they stand for, returning the result as a string. This permits display of documentation that refers accurately to the user's own customized key bindings. Here are examples of the special sequences: (substitute-command-keys "To abort recursive edit, type: \\[abort-recursive-edit]") => "To abort recursive edit, type: C-]" (substitute-command-keys "The keys that are defined for the minibuffer here are: \\{minibuffer-local-must-match-map}") => "The keys that are defined for the minibuffer here are: ? minibuffer-completion-help SPC minibuffer-complete-word TAB minibuffer-complete LFD minibuffer-complete-and-exit RET minibuffer-complete-and-exit C-g abort-recursive-edit " (substitute-command-keys "To abort a recursive edit from the minibuffer, type\ \\\\[abort-recursive-edit].") => "To abort a recursive edit from the minibuffer, type C-g." (substitute-command-keys "Substrings of the form \\=\\{MAPVAR} are replaced by summaries \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap. Substrings of the form \\=\\ specify to use the value of MAPVAR as the keymap for future \\=\\[COMMAND] substrings. \\=\\= quotes the following character and is discarded; thus, \\=\\=\\=\\= puts \\=\\= into the output, and \\=\\=\\=\\[ puts \\=\\[ into the output.") => "Substrings of the form \{MAPVAR} are replaced by summaries (made by `describe-bindings') of the value of MAPVAR, taken as a keymap. Substrings of the form \ specify to use the value of MAPVAR as the keymap for future \[COMMAND] substrings. \= quotes the following character and is discarded; thus, \=\= puts \= into the output, and \=\[ puts \[ into the output."  File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation Describing Characters for Help Messages ======================================= These functions convert events, key sequences or characters to textual descriptions. These descriptions are useful for including arbitrary text characters or key sequences in messages, because they convert non-printing and whitespace characters to sequences of printing characters. The description of a non-whitespace printing character is the character itself. - Function: key-description sequence This function returns a string containing the XEmacs standard notation for the input events in SEQUENCE. The argument SEQUENCE may be a string, vector or list. *Note Events::, for more information about valid events. See also the examples for `single-key-description', below. - Function: single-key-description key This function returns a string describing KEY in the standard XEmacs notation for keyboard input. A normal printing character appears as itself, but a control character turns into a string starting with `C-', a meta character turns into a string starting with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc. A symbol appears as the name of the symbol. An event that is a list appears as the name of the symbol in the CAR of the list. (single-key-description ?\C-x) => "C-x" (key-description "\C-x \M-y \n \t \r \f123") => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3" (single-key-description 'kp-next) => "kp-next" (single-key-description '(shift button1)) => "Sh-button1" - Function: text-char-description character This function returns a string describing CHARACTER in the standard XEmacs notation for characters that appear in text--like `single-key-description', except that control characters are represented with a leading caret (which is how control characters in XEmacs buffers are usually displayed). (text-char-description ?\C-c) => "^C" (text-char-description ?\M-m) => "M-m" (text-char-description ?\C-\M-m) => "M-^M"  File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation Help Functions ============== XEmacs provides a variety of on-line help functions, all accessible to the user as subcommands of the prefix `C-h', or on some keyboards, `help'. For more information about them, see *Note Help: (emacs)Help. Here we describe some program-level interfaces to the same information. - Command: apropos regexp &optional do-all predicate This function finds all symbols whose names contain a match for the regular expression REGEXP, and returns a list of them (*note Regular Expressions::). It also displays the symbols in a buffer named `*Help*', each with a one-line description. If DO-ALL is non-`nil', then `apropos' also shows key bindings for the functions that are found. If PREDICATE is non-`nil', it should be a function to be called on each symbol that has matched REGEXP. Only symbols for which PREDICATE returns a non-`nil' value are listed or displayed. In the first of the following examples, `apropos' finds all the symbols with names containing `exec'. In the second example, it finds and returns only those symbols that are also commands. (We don't show the output that results in the `*Help*' buffer.) (apropos "exec") => (Buffer-menu-execute command-execute exec-directory exec-path execute-extended-command execute-kbd-macro executing-kbd-macro executing-macro) (apropos "exec" nil 'commandp) => (Buffer-menu-execute execute-extended-command) `apropos' is used by various user-level commands, such as `C-h a' (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A' (`command-apropos'), which does an apropos over only those functions which are user commands. `command-apropos' calls `apropos', specifying a PREDICATE to restrict the output to symbols that are commands. The call to `apropos' looks like this: (apropos string t 'commandp) - Variable: help-map The value of this variable is a local keymap for characters following the Help key, `C-h'. - Prefix Command: help-command This symbol is not a function; its function definition is actually the keymap known as `help-map'. It is defined in `help.el' as follows: (define-key global-map "\C-h" 'help-command) (fset 'help-command help-map) - Function: print-help-return-message &optional function This function builds a string that explains how to restore the previous state of the windows after a help command. After building the message, it applies FUNCTION to it if FUNCTION is non-`nil'. Otherwise it calls `message' to display it in the echo area. This function expects to be called inside a `with-output-to-temp-buffer' special form, and expects `standard-output' to have the value bound by that special form. For an example of its use, see the long example in *Note Accessing Documentation::. - Variable: help-char The value of this variable is the help character--the character that XEmacs recognizes as meaning Help. By default, it is the character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this character, if `help-form' is non-`nil' Lisp expression, it evaluates that expression, and displays the result in a window if it is a string. `help-char' can be a character or a key description such as `help' or `(meta h)'. Usually the value of `help-form''s value is `nil'. Then the help character has no special meaning at the level of command input, and it becomes part of a key sequence in the normal way. The standard key binding of `C-h' is a prefix key for several general-purpose help features. The help character is special after prefix keys, too. If it has no binding as a subcommand of the prefix key, it runs `describe-prefix-bindings', which displays a list of all the subcommands of the prefix key. - Variable: help-form If this variable is non-`nil', its value is a form to evaluate whenever the character `help-char' is read. If evaluating the form produces a string, that string is displayed. A command that calls `next-command-event' or `next-event' probably should bind `help-form' to a non-`nil' expression while it does input. (The exception is when `C-h' is meaningful input.) Evaluating this expression should result in a string that explains what the input is for and how to enter it properly. Entry to the minibuffer binds this variable to the value of `minibuffer-help-form' (*note Minibuffer Misc::). - Variable: prefix-help-command This variable holds a function to print help for a prefix character. The function is called when the user types a prefix key followed by the help character, and the help character has no binding after that prefix. The variable's default value is `describe-prefix-bindings'. - Command: describe-prefix-bindings This function calls `describe-bindings' to display a list of all the subcommands of the prefix key of the most recent key sequence. The prefix described consists of all but the last event of that key sequence. (The last event is, presumably, the help character.) The following two functions are found in the library `helper'. They are for modes that want to provide help without relinquishing control, such as the "electric" modes. You must load that library with `(require 'helper)' in order to use them. Their names begin with `Helper' to distinguish them from the ordinary help functions. - Command: Helper-describe-bindings This command pops up a window displaying a help buffer containing a listing of all of the key bindings from both the local and global keymaps. It works by calling `describe-bindings'. - Command: Helper-help This command provides help for the current mode. It prompts the user in the minibuffer with the message `Help (Type ? for further options)', and then provides assistance in finding out what the key bindings are, and what the mode is intended for. It returns `nil'. This can be customized by changing the map `Helper-help-map'.  File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation Obsoleteness ============ As you add functionality to a package, you may at times want to replace an older function with a new one. To preserve compatibility with existing code, the older function needs to still exist; but users of that function should be told to use the newer one instead. XEmacs Lisp lets you mark a function or variable as "obsolete", and indicate what should be used instead. - Command: make-obsolete function new This function indicates that FUNCTION is an obsolete function, and the function NEW should be used instead. The byte compiler will issue a warning to this effect when it encounters a usage of the older function, and the help system will also note this in the function's documentation. NEW can also be a string (if there is not a single function with the same functionality any more), and should be a descriptive statement, such as "use FOO or BAR instead" or "this function is unnecessary". - Command: make-obsolete-variable variable new This is like `make-obsolete' but is for variables instead of functions. - Function: define-obsolete-function-alias oldfun newfun This function combines `make-obsolete' and `define-function', declaring OLDFUN to be an obsolete variant of NEWFUN and defining OLDFUN as an alias for NEWFUN. - Function: define-obsolete-variable-alias oldvar newvar This is like `define-obsolete-function-alias' but for variables. Note that you should not normally put obsoleteness information explicitly in a function or variable's doc string. The obsoleteness information that you specify using the above functions will be displayed whenever the doc string is displayed, and by adding it explicitly the result is redundancy. Also, if an obsolete function is substantially the same as a newer one but is not actually an alias, you should consider omitting the doc string entirely (use a null string `""' as the doc string). That way, the user is told about the obsoleteness and is forced to look at the documentation of the new function, making it more likely that he will use the new function. - Function: function-obsoleteness-doc function If FUNCTION is obsolete, this function returns a string describing this. This is the message that is printed out during byte compilation or in the function's documentation. If FUNCTION is not obsolete, `nil' is returned. - Function: variable-obsoleteness-doc variable This is like `function-obsoleteness-doc' but for variables. The obsoleteness information is stored internally by putting a property `byte-obsolete-info' (for functions) or `byte-obsolete-variable' (for variables) on the symbol that specifies the obsolete function or variable. For more information, see the implementation of `make-obsolete' and `make-obsolete-variable' in `lisp/bytecomp/bytecomp-runtime.el'.  File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top Files ***** In XEmacs, you can find, create, view, save, and otherwise work with files and file directories. This chapter describes most of the file-related functions of XEmacs Lisp, but a few others are described in *Note Buffers::, and those related to backups and auto-saving are described in *Note Backups and Auto-Saving::. Many of the file functions take one or more arguments that are file names. A file name is actually a string. Most of these functions expand file name arguments using `expand-file-name', so that `~' is handled correctly, as are relative file names (including `../'). These functions don't recognize environment variable substitutions such as `$HOME'. *Note File Name Expansion::. * Menu: * Visiting Files:: Reading files into Emacs buffers for editing. * Saving Buffers:: Writing changed buffers back into files. * Reading from Files:: Reading files into buffers without visiting. * Writing to Files:: Writing new files from parts of buffers. * File Locks:: Locking and unlocking files, to prevent simultaneous editing by two people. * Information about Files:: Testing existence, accessibility, size of files. * Changing File Attributes:: Renaming files, changing protection, etc. * File Names:: Decomposing and expanding file names. * Contents of Directories:: Getting a list of the files in a directory. * Create/Delete Dirs:: Creating and Deleting Directories. * Magic File Names:: Defining "magic" special handling for certain file names. * Partial Files:: Treating a section of a buffer as a file. * Format Conversion:: Conversion to and from various file formats. * Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.  File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files Visiting Files ============== Visiting a file means reading a file into a buffer. Once this is done, we say that the buffer is "visiting" that file, and call the file "the visited file" of the buffer. A file and a buffer are two different things. A file is information recorded permanently in the computer (unless you delete it). A buffer, on the other hand, is information inside of XEmacs that will vanish at the end of the editing session (or when you kill the buffer). Usually, a buffer contains information that you have copied from a file; then we say the buffer is visiting that file. The copy in the buffer is what you modify with editing commands. Such changes to the buffer do not change the file; therefore, to make the changes permanent, you must "save" the buffer, which means copying the altered buffer contents back into the file. In spite of the distinction between files and buffers, people often refer to a file when they mean a buffer and vice-versa. Indeed, we say, "I am editing a file," rather than, "I am editing a buffer that I will soon save as a file of the same name." Humans do not usually need to make the distinction explicit. When dealing with a computer program, however, it is good to keep the distinction in mind. * Menu: * Visiting Functions:: The usual interface functions for visiting. * Subroutines of Visiting:: Lower-level subroutines that they use.  File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files Functions for Visiting Files ---------------------------- This section describes the functions normally used to visit files. For historical reasons, these functions have names starting with `find-' rather than `visit-'. *Note Buffer File Name::, for functions and variables that access the visited file name of a buffer or that find an existing buffer by its visited file name. In a Lisp program, if you want to look at the contents of a file but not alter it, the fastest way is to use `insert-file-contents' in a temporary buffer. Visiting the file is not necessary and takes longer. *Note Reading from Files::. - Command: find-file filename This command selects a buffer visiting the file FILENAME, using an existing buffer if there is one, and otherwise creating a new buffer and reading the file into it. It also returns that buffer. The body of the `find-file' function is very simple and looks like this: (switch-to-buffer (find-file-noselect filename)) (See `switch-to-buffer' in *Note Displaying Buffers::.) When `find-file' is called interactively, it prompts for FILENAME in the minibuffer. - Function: find-file-noselect filename &optional nowarn This function is the guts of all the file-visiting functions. It finds or creates a buffer visiting the file FILENAME, and returns it. It uses an existing buffer if there is one, and otherwise creates a new buffer and reads the file into it. You may make the buffer current or display it in a window if you wish, but this function does not do so. When `find-file-noselect' uses an existing buffer, it first verifies that the file has not changed since it was last visited or saved in that buffer. If the file has changed, then this function asks the user whether to reread the changed file. If the user says `yes', any changes previously made in the buffer are lost. If `find-file-noselect' needs to create a buffer, and there is no file named FILENAME, it displays the message `New file' in the echo area, and leaves the buffer empty. If NOWARN is non-`nil', various warnings that XEmacs normally gives (e.g. if another buffer is already visiting FILENAME but FILENAME has been removed from disk since that buffer was created) are suppressed. The `find-file-noselect' function calls `after-find-file' after reading the file (*note Subroutines of Visiting::). That function sets the buffer major mode, parses local variables, warns the user if there exists an auto-save file more recent than the file just visited, and finishes by running the functions in `find-file-hooks'. The `find-file-noselect' function returns the buffer that is visiting the file FILENAME. (find-file-noselect "/etc/fstab") => # - Command: find-file-other-window filename This command selects a buffer visiting the file FILENAME, but does so in a window other than the selected window. It may use another existing window or split a window; see *Note Displaying Buffers::. When this command is called interactively, it prompts for FILENAME. - Command: find-file-read-only filename This command selects a buffer visiting the file FILENAME, like `find-file', but it marks the buffer as read-only. *Note Read Only Buffers::, for related functions and variables. When this command is called interactively, it prompts for FILENAME. - Command: view-file filename &optional other-window-p This command visits FILENAME in View mode, and displays it in a recursive edit, returning to the previous buffer when done. View mode is a mode that allows you to skim rapidly through the file but does not let you modify it. Entering View mode runs the normal hook `view-mode-hook'. *Note Hooks::. When `view-file' is called interactively, it prompts for FILENAME. With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in another window. - Variable: find-file-hooks The value of this variable is a list of functions to be called after a file is visited. The file's local-variables specification (if any) will have been processed before the hooks are run. The buffer visiting the file is current when the hook functions are run. This variable works just like a normal hook, but we think that renaming it would not be advisable. - Variable: find-file-not-found-hooks The value of this variable is a list of functions to be called when `find-file' or `find-file-noselect' is passed a nonexistent file name. `find-file-noselect' calls these functions as soon as it detects a nonexistent file. It calls them in the order of the list, until one of them returns non-`nil'. `buffer-file-name' is already set up. This is not a normal hook because the values of the functions are used and they may not all be called.  File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files Subroutines of Visiting ----------------------- The `find-file-noselect' function uses the `create-file-buffer' and `after-find-file' functions as subroutines. Sometimes it is useful to call them directly. - Function: create-file-buffer filename This function creates a suitably named buffer for visiting FILENAME, and returns it. It uses FILENAME (sans directory) as the name if that name is free; otherwise, it appends a string such as `<2>' to get an unused name. See also *Note Creating Buffers::. *Please note:* `create-file-buffer' does _not_ associate the new buffer with a file and does not select the buffer. It also does not use the default major mode. (create-file-buffer "foo") => # (create-file-buffer "foo") => #> (create-file-buffer "foo") => #> This function is used by `find-file-noselect'. It uses `generate-new-buffer' (*note Creating Buffers::). - Function: after-find-file &optional error warn noauto This function sets the buffer major mode, and parses local variables (*note Auto Major Mode::). It is called by `find-file-noselect' and by the default revert function (*note Reverting::). If reading the file got an error because the file does not exist, but its directory does exist, the caller should pass a non-`nil' value for ERROR. In that case, `after-find-file' issues a warning: `(New File)'. For more serious errors, the caller should usually not call `after-find-file'. If WARN is non-`nil', then this function issues a warning if an auto-save file exists and is more recent than the visited file. If NOAUTO is non-`nil', then this function does not turn on auto-save mode; otherwise, it does. The last thing `after-find-file' does is call all the functions in `find-file-hooks'.  File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files Saving Buffers ============== When you edit a file in XEmacs, you are actually working on a buffer that is visiting that file--that is, the contents of the file are copied into the buffer and the copy is what you edit. Changes to the buffer do not change the file until you "save" the buffer, which means copying the contents of the buffer into the file. - Command: save-buffer &optional backup-option This function saves the contents of the current buffer in its visited file if the buffer has been modified since it was last visited or saved. Otherwise it does nothing. `save-buffer' is responsible for making backup files. Normally, BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only if this is the first save since visiting the file. Other values for BACKUP-OPTION request the making of backup files in other circumstances: * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the `save-buffer' function marks this version of the file to be backed up when the buffer is next saved. * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the `save-buffer' function unconditionally backs up the previous version of the file before saving it. - Command: save-some-buffers &optional save-silently-p exiting This command saves some modified file-visiting buffers. Normally it asks the user about each buffer. But if SAVE-SILENTLY-P is non-`nil', it saves all the file-visiting buffers without querying the user. The optional EXITING argument, if non-`nil', requests this function to offer also to save certain other buffers that are not visiting files. These are buffers that have a non-`nil' local value of `buffer-offer-save'. (A user who says yes to saving one of these is asked to specify a file name to use.) The `save-buffers-kill-emacs' function passes a non-`nil' value for this argument. - Variable: buffer-offer-save When this variable is non-`nil' in a buffer, XEmacs offers to save the buffer on exit even if the buffer is not visiting a file. The variable is automatically local in all buffers. Normally, Mail mode (used for editing outgoing mail) sets this to `t'. - Command: write-file filename This function writes the current buffer into file FILENAME, makes the buffer visit that file, and marks it not modified. Then it renames the buffer based on FILENAME, appending a string like `<2>' if necessary to make a unique buffer name. It does most of this work by calling `set-visited-file-name' and `save-buffer'. - Variable: write-file-hooks The value of this variable is a list of functions to be called before writing out a buffer to its visited file. If one of them returns non-`nil', the file is considered already written and the rest of the functions are not called, nor is the usual code for writing the file executed. If a function in `write-file-hooks' returns non-`nil', it is responsible for making a backup file (if that is appropriate). To do so, execute the following code: (or buffer-backed-up (backup-buffer)) You might wish to save the file modes value returned by `backup-buffer' and use that to set the mode bits of the file that you write. This is what `save-buffer' normally does. Even though this is not a normal hook, you can use `add-hook' and `remove-hook' to manipulate the list. *Note Hooks::. - Variable: local-write-file-hooks This works just like `write-file-hooks', but it is intended to be made local to particular buffers. It's not a good idea to make `write-file-hooks' local to a buffer--use this variable instead. The variable is marked as a permanent local, so that changing the major mode does not alter a buffer-local value. This is convenient for packages that read "file" contents in special ways, and set up hooks to save the data in a corresponding way. - Variable: write-contents-hooks This works just like `write-file-hooks', but it is intended for hooks that pertain to the contents of the file, as opposed to hooks that pertain to where the file came from. Such hooks are usually set up by major modes, as buffer-local bindings for this variable. Switching to a new major mode always resets this variable. - Variable: after-save-hook This normal hook runs after a buffer has been saved in its visited file. - Variable: file-precious-flag If this variable is non-`nil', then `save-buffer' protects against I/O errors while saving by writing the new file to a temporary name instead of the name it is supposed to have, and then renaming it to the intended name after it is clear there are no errors. This procedure prevents problems such as a lack of disk space from resulting in an invalid file. As a side effect, backups are necessarily made by copying. *Note Rename or Copy::. Yet, at the same time, saving a precious file always breaks all hard links between the file you save and other file names. Some modes set this variable non-`nil' locally in particular buffers. - User Option: require-final-newline This variable determines whether files may be written out that do _not_ end with a newline. If the value of the variable is `t', then `save-buffer' silently adds a newline at the end of the file whenever the buffer being saved does not already end in one. If the value of the variable is non-`nil', but not `t', then `save-buffer' asks the user whether to add a newline each time the case arises. If the value of the variable is `nil', then `save-buffer' doesn't add newlines at all. `nil' is the default value, but a few major modes set it to `t' in particular buffers.  File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files Reading from Files ================== You can copy a file from the disk and insert it into a buffer using the `insert-file-contents' function. Don't use the user-level command `insert-file' in a Lisp program, as that sets the mark. - Function: insert-file-contents filename &optional visit start end replace This function inserts the contents of file FILENAME into the current buffer after point. It returns a list of the absolute file name and the length of the data inserted. An error is signaled if FILENAME is not the name of a file that can be read. The function `insert-file-contents' checks the file contents against the defined file formats, and converts the file contents if appropriate. *Note Format Conversion::. It also calls the functions in the list `after-insert-file-functions'; see *Note Saving Properties::. If VISIT is non-`nil', this function additionally marks the buffer as unmodified and sets up various fields in the buffer so that it is visiting the file FILENAME: these include the buffer's visited file name and its last save file modtime. This feature is used by `find-file-noselect' and you probably should not use it yourself. If START and END are non-`nil', they should be integers specifying the portion of the file to insert. In this case, VISIT must be `nil'. For example, (insert-file-contents filename nil 0 500) inserts the first 500 characters of a file. If the argument REPLACE is non-`nil', it means to replace the contents of the buffer (actually, just the accessible portion) with the contents of the file. This is better than simply deleting the buffer contents and inserting the whole file, because (1) it preserves some marker positions and (2) it puts less data in the undo list. If you want to pass a file name to another process so that another program can read the file, use the function `file-local-copy'; see *Note Magic File Names::.  File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files Writing to Files ================ You can write the contents of a buffer, or part of a buffer, directly to a file on disk using the `append-to-file' and `write-region' functions. Don't use these functions to write to files that are being visited; that could cause confusion in the mechanisms for visiting. - Command: append-to-file start end filename This function appends the contents of the region delimited by START and END in the current buffer to the end of file FILENAME. If that file does not exist, it is created. If that file exists it is overwritten. This function returns `nil'. An error is signaled if FILENAME specifies a nonwritable file, or a nonexistent file in a directory where files cannot be created. - Command: write-region start end filename &optional append visit This function writes the region delimited by START and END in the current buffer into the file specified by FILENAME. If START is a string, then `write-region' writes or appends that string, rather than text from the buffer. If APPEND is non-`nil', then the specified text is appended to the existing file contents (if any). If VISIT is `t', then XEmacs establishes an association between the buffer and the file: the buffer is then visiting that file. It also sets the last file modification time for the current buffer to FILENAME's modtime, and marks the buffer as not modified. This feature is used by `save-buffer', but you probably should not use it yourself. If VISIT is a string, it specifies the file name to visit. This way, you can write the data to one file (FILENAME) while recording the buffer as visiting another file (VISIT). The argument VISIT is used in the echo area message and also for file locking; VISIT is stored in `buffer-file-name'. This feature is used to implement `file-precious-flag'; don't use it yourself unless you really know what you're doing. The function `write-region' converts the data which it writes to the appropriate file formats specified by `buffer-file-format'. *Note Format Conversion::. It also calls the functions in the list `write-region-annotate-functions'; see *Note Saving Properties::. Normally, `write-region' displays a message `Wrote file FILENAME' in the echo area. If VISIT is neither `t' nor `nil' nor a string, then this message is inhibited. This feature is useful for programs that use files for internal purposes, files that the user does not need to know about.  File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files File Locks ========== When two users edit the same file at the same time, they are likely to interfere with each other. XEmacs tries to prevent this situation from arising by recording a "file lock" when a file is being modified. XEmacs can then detect the first attempt to modify a buffer visiting a file that is locked by another XEmacs process, and ask the user what to do. File locks do not work properly when multiple machines can share file systems, such as with NFS. Perhaps a better file locking system will be implemented in the future. When file locks do not work, it is possible for two users to make changes simultaneously, but XEmacs can still warn the user who saves second. Also, the detection of modification of a buffer visiting a file changed on disk catches some cases of simultaneous editing; see *Note Modification Time::. - Function: file-locked-p &optional filename This function returns `nil' if the file FILENAME is not locked by this XEmacs process. It returns `t' if it is locked by this XEmacs, and it returns the name of the user who has locked it if it is locked by someone else. (file-locked-p "foo") => nil - Function: lock-buffer &optional filename This function locks the file FILENAME, if the current buffer is modified. The argument FILENAME defaults to the current buffer's visited file. Nothing is done if the current buffer is not visiting a file, or is not modified. - Function: unlock-buffer This function unlocks the file being visited in the current buffer, if the buffer is modified. If the buffer is not modified, then the file should not be locked, so this function does nothing. It also does nothing if the current buffer is not visiting a file. - Function: ask-user-about-lock filename other-user This function is called when the user tries to modify FILENAME, but it is locked by another user named OTHER-USER. The value it returns determines what happens next: * A value of `t' says to grab the lock on the file. Then this user may edit the file and OTHER-USER loses the lock. * A value of `nil' says to ignore the lock and let this user edit the file anyway. * This function may instead signal a `file-locked' error, in which case the change that the user was about to make does not take place. The error message for this error looks like this: error--> File is locked: FILENAME OTHER-USER where FILENAME is the name of the file and OTHER-USER is the name of the user who has locked the file. The default definition of this function asks the user to choose what to do. If you wish, you can replace the `ask-user-about-lock' function with your own version that decides in another way. The code for its usual definition is in `userlock.el'.  File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files Information about Files ======================= The functions described in this section all operate on strings that designate file names. All the functions have names that begin with the word `file'. These functions all return information about actual files or directories, so their arguments must all exist as actual files or directories unless otherwise noted. * Menu: * Testing Accessibility:: Is a given file readable? Writable? * Kinds of Files:: Is it a directory? A symbolic link? * Truenames:: Eliminating symbolic links from a file name. * File Attributes:: How large is it? Any other names? Etc.  File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files Testing Accessibility --------------------- These functions test for permission to access a file in specific ways. - Function: file-exists-p filename This function returns `t' if a file named FILENAME appears to exist. This does not mean you can necessarily read the file, only that you can find out its attributes. (On Unix, this is true if the file exists and you have execute permission on the containing directories, regardless of the protection of the file itself.) If the file does not exist, or if fascist access control policies prevent you from finding the attributes of the file, this function returns `nil'. - Function: file-readable-p filename This function returns `t' if a file named FILENAME exists and you can read it. It returns `nil' otherwise. (file-readable-p "files.texi") => t (file-exists-p "/usr/spool/mqueue") => t (file-readable-p "/usr/spool/mqueue") => nil - Function: file-executable-p filename This function returns `t' if a file named FILENAME exists and you can execute it. It returns `nil' otherwise. If the file is a directory, execute permission means you can check the existence and attributes of files inside the directory, and open those files if their modes permit. - Function: file-writable-p filename This function returns `t' if the file FILENAME can be written or created by you, and `nil' otherwise. A file is writable if the file exists and you can write it. It is creatable if it does not exist, but the specified directory does exist and you can write in that directory. In the third example below, `foo' is not writable because the parent directory does not exist, even though the user could create such a directory. (file-writable-p "~/foo") => t (file-writable-p "/foo") => nil (file-writable-p "~/no-such-dir/foo") => nil - Function: file-accessible-directory-p dirname This function returns `t' if you have permission to open existing files in the directory whose name as a file is DIRNAME; otherwise (or if there is no such directory), it returns `nil'. The value of DIRNAME may be either a directory name or the file name of a directory. Example: after the following, (file-accessible-directory-p "/foo") => nil we can deduce that any attempt to read a file in `/foo/' will give an error. - Function: file-ownership-preserved-p filename This function returns `t' if deleting the file FILENAME and then creating it anew would keep the file's owner unchanged. - Function: file-newer-than-file-p filename1 filename2 This function returns `t' if the file FILENAME1 is newer than file FILENAME2. If FILENAME1 does not exist, it returns `nil'. If FILENAME2 does not exist, it returns `t'. In the following example, assume that the file `aug-19' was written on the 19th, `aug-20' was written on the 20th, and the file `no-file' doesn't exist at all. (file-newer-than-file-p "aug-19" "aug-20") => nil (file-newer-than-file-p "aug-20" "aug-19") => t (file-newer-than-file-p "aug-19" "no-file") => t (file-newer-than-file-p "no-file" "aug-19") => nil You can use `file-attributes' to get a file's last modification time as a list of two numbers. *Note File Attributes::.  File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files Distinguishing Kinds of Files ----------------------------- This section describes how to distinguish various kinds of files, such as directories, symbolic links, and ordinary files. - Function: file-symlink-p filename If the file FILENAME is a symbolic link, the `file-symlink-p' function returns the file name to which it is linked. This may be the name of a text file, a directory, or even another symbolic link, or it may be a nonexistent file name. If the file FILENAME is not a symbolic link (or there is no such file), `file-symlink-p' returns `nil'. (file-symlink-p "foo") => nil (file-symlink-p "sym-link") => "foo" (file-symlink-p "sym-link2") => "sym-link" (file-symlink-p "/bin") => "/pub/bin" - Function: file-directory-p filename This function returns `t' if FILENAME is the name of an existing directory, `nil' otherwise. (file-directory-p "~rms") => t (file-directory-p "~rms/lewis/files.texi") => nil (file-directory-p "~rms/lewis/no-such-file") => nil (file-directory-p "$HOME") => nil (file-directory-p (substitute-in-file-name "$HOME")) => t - Function: file-regular-p filename This function returns `t' if the file FILENAME exists and is a regular file (not a directory, symbolic link, named pipe, terminal, or other I/O device).  File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files Truenames --------- The "truename" of a file is the name that you get by following symbolic links until none remain, then expanding to get rid of `.' and `..' as components. Strictly speaking, a file need not have a unique truename; the number of distinct truenames a file has is equal to the number of hard links to the file. However, truenames are useful because they eliminate symbolic links as a cause of name variation. - Function: file-truename filename &optional default The function `file-truename' returns the true name of the file FILENAME. This is the name that you get by following symbolic links until none remain. If the filename is relative, DEFAULT is the directory to start with. If DEFAULT is `nil' or missing, the current buffer's value of `default-directory' is used. *Note Buffer File Name::, for related information.  File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files Other Information about Files ----------------------------- This section describes the functions for getting detailed information about a file, other than its contents. This information includes the mode bits that control access permission, the owner and group numbers, the number of names, the inode number, the size, and the times of access and modification. - Function: file-modes filename This function returns the mode bits of FILENAME, as an integer. The mode bits are also called the file permissions, and they specify access control in the usual Unix fashion. If the low-order bit is 1, then the file is executable by all users, if the second-lowest-order bit is 1, then the file is writable by all users, etc. The highest value returnable is 4095 (7777 octal), meaning that everyone has read, write, and execute permission, that the SUID bit is set for both others and group, and that the sticky bit is set. (file-modes "~/junk/diffs") => 492 ; Decimal integer. (format "%o" 492) => "754" ; Convert to octal. (set-file-modes "~/junk/diffs" 438) => nil (format "%o" 438) => "666" ; Convert to octal. % ls -l diffs -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs - Function: file-nlinks filename This functions returns the number of names (i.e., hard links) that file FILENAME has. If the file does not exist, then this function returns `nil'. Note that symbolic links have no effect on this function, because they are not considered to be names of the files they link to. % ls -l foo* -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 (file-nlinks "foo") => 2 (file-nlinks "doesnt-exist") => nil - Function: file-attributes filename This function returns a list of attributes of file FILENAME. If the specified file cannot be opened, it returns `nil'. The elements of the list, in order, are: 0. `t' for a directory, a string for a symbolic link (the name linked to), or `nil' for a text file. 1. The number of names the file has. Alternate names, also known as hard links, can be created by using the `add-name-to-file' function (*note Changing File Attributes::). 2. The file's UID. 3. The file's GID. 4. The time of last access, as a list of two integers. The first integer has the high-order 16 bits of time, the second has the low 16 bits. (This is similar to the value of `current-time'; see *Note Time of Day::.) 5. The time of last modification as a list of two integers (as above). 6. The time of last status change as a list of two integers (as above). 7. The size of the file in bytes. 8. The file's modes, as a string of ten letters or dashes, as in `ls -l'. 9. `t' if the file's GID would change if file were deleted and recreated; `nil' otherwise. 10. The file's inode number. 11. The file system number of the file system that the file is in. This element and the file's inode number together give enough information to distinguish any two files on the system--no two files can have the same values for both of these numbers. For example, here are the file attributes for `files.texi': (file-attributes "files.texi") => (nil 1 2235 75 (8489 20284) (8489 20284) (8489 20285) 14906 "-rw-rw-rw-" nil 129500 -32252) and here is how the result is interpreted: `nil' is neither a directory nor a symbolic link. `1' has only one name (the name `files.texi' in the current default directory). `2235' is owned by the user with UID 2235. `75' is in the group with GID 75. `(8489 20284)' was last accessed on Aug 19 00:09. Use `format-time-string' to ! convert this number into a time string. *Note Time Conversion::. `(8489 20284)' was last modified on Aug 19 00:09. `(8489 20285)' last had its inode changed on Aug 19 00:09. `14906' is 14906 characters long. `"-rw-rw-rw-"' has a mode of read and write access for the owner, group, and world. `nil' would retain the same GID if it were recreated. `129500' has an inode number of 129500. `-32252' is on file system number -32252.  File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files Changing File Names and Attributes ================================== The functions in this section rename, copy, delete, link, and set the modes of files. In the functions that have arguments NEWNAME and OK-IF-ALREADY-EXISTS, if a file by the name of NEWNAME already exists, the actions taken depend on the value of OK-IF-ALREADY-EXISTS: * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is `nil'. * Request confirmation if OK-IF-ALREADY-EXISTS is a number. This is what happens when the function is invoked interactively. * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS is any other value. - Command: add-name-to-file filename newname &optional ok-if-already-exists This function gives the file named FILENAME the additional name NEWNAME. This means that NEWNAME becomes a new "hard link" to FILENAME. Both these arguments must be strings. In the first part of the following example, we list two files, `foo' and `foo3'. % ls -l fo* -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 Then we evaluate the form `(add-name-to-file "~/lewis/foo" "~/lewis/foo2")'. Again we list the files. This shows two names, `foo' and `foo2'. (add-name-to-file "~/lewis/foo1" "~/lewis/foo2") => nil % ls -l fo* -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 Finally, we evaluate the following: (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t) and list the files again. Now there are three names for one file: `foo', `foo2', and `foo3'. The old contents of `foo3' are lost. (add-name-to-file "~/lewis/foo1" "~/lewis/foo3") => nil % ls -l fo* -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 This function is meaningless on non-Unix systems, where multiple names for one file are not allowed. See also `file-nlinks' in *Note File Attributes::. - Command: rename-file filename newname &optional ok-if-already-exists This command renames the file FILENAME as NEWNAME. If FILENAME has additional names aside from FILENAME, it continues to have those names. In fact, adding the name NEWNAME with `add-name-to-file' and then deleting FILENAME has the same effect as renaming, aside from momentary intermediate states. In an interactive call, this function prompts for FILENAME and NEWNAME in the minibuffer; also, it requests confirmation if NEWNAME already exists. - Command: copy-file filename newname &optional ok-if-already-exists time This command copies the file FILENAME to NEWNAME. An error is signaled if FILENAME does not exist. If TIME is non-`nil', then this functions gives the new file the same last-modified time that the old one has. (This works on only some operating systems.) In an interactive call, this function prompts for FILENAME and NEWNAME in the minibuffer; also, it requests confirmation if NEWNAME already exists. - Command: delete-file filename This command deletes the file FILENAME, like the shell command `rm FILENAME'. If the file has multiple names, it continues to exist under the other names. A suitable kind of `file-error' error is signaled if the file does not exist, or is not deletable. (On Unix, a file is deletable if its directory is writable.) See also `delete-directory' in *Note Create/Delete Dirs::. - Command: make-symbolic-link filename newname &optional ok-if-already-exists This command makes a symbolic link to FILENAME, named NEWNAME. This is like the shell command `ln -s FILENAME NEWNAME'. In an interactive call, this function prompts for FILENAME and NEWNAME in the minibuffer; also, it requests confirmation if NEWNAME already exists. - Function: set-file-modes filename mode This function sets mode bits of FILENAME to MODE (which must be an integer). Only the low 12 bits of MODE are used. - Function: set-default-file-modes mode This function sets the default file protection for new files created by XEmacs and its subprocesses. Every file created with XEmacs initially has this protection. On Unix, the default protection is the bitwise complement of the "umask" value. The argument MODE must be an integer. Only the low 9 bits of MODE are used. Saving a modified version of an existing file does not count as creating the file; it does not change the file's mode, and does not use the default file protection. - Function: default-file-modes This function returns the current default protection value. On MS-DOS, there is no such thing as an "executable" file mode bit. So Emacs considers a file executable if its name ends in `.com', `.bat' or `.exe'. This is reflected in the values returned by `file-modes' and `file-attributes'.  File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files File Names ========== Files are generally referred to by their names, in XEmacs as elsewhere. File names in XEmacs are represented as strings. The functions that operate on a file all expect a file name argument. In addition to operating on files themselves, XEmacs Lisp programs often need to operate on the names; i.e., to take them apart and to use part of a name to construct related file names. This section describes how to manipulate file names. The functions in this section do not actually access files, so they can operate on file names that do not refer to an existing file or directory. On MS-DOS, these functions understand MS-DOS file-name syntax as well as Unix syntax. This is so that all the standard Lisp libraries can specify file names in Unix syntax and work properly on all systems without change. Similarly for other operating systems. * Menu: * File Name Components:: The directory part of a file name, and the rest. * Directory Names:: A directory's name as a directory is different from its name as a file. * Relative File Names:: Some file names are relative to a current directory. * File Name Expansion:: Converting relative file names to absolute ones. * Unique File Names:: Generating names for temporary files. * File Name Completion:: Finding the completions for a given file name. * User Name Completion:: Finding the completions for a given user name.  File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names File Name Components -------------------- The operating system groups files into directories. To specify a file, you must specify the directory and the file's name within that directory. Therefore, XEmacs considers a file name as having two main parts: the "directory name" part, and the "nondirectory" part (or "file name within the directory"). Either part may be empty. Concatenating these two parts reproduces the original file name. On Unix, the directory part is everything up to and including the last slash; the nondirectory part is the rest. For some purposes, the nondirectory part is further subdivided into the name proper and the "version number". On Unix, only backup files have version numbers in their names. - Function: file-name-directory filename This function returns the directory part of FILENAME (or `nil' if FILENAME does not include a directory part). On Unix, the function returns a string ending in a slash. (file-name-directory "lewis/foo") ; Unix example => "lewis/" (file-name-directory "foo") ; Unix example => nil - Function: file-name-nondirectory filename This function returns the nondirectory part of FILENAME. (file-name-nondirectory "lewis/foo") => "foo" (file-name-nondirectory "foo") => "foo" - Function: file-name-sans-versions filename &optional keep-backup-version This function returns FILENAME without any file version numbers, backup version numbers, or trailing tildes. If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup version numbers, only true file version numbers. (file-name-sans-versions "~rms/foo.~1~") => "~rms/foo" (file-name-sans-versions "~rms/foo~") => "~rms/foo" (file-name-sans-versions "~rms/foo") => "~rms/foo" - Function: file-name-sans-extension filename This function returns FILENAME minus its "extension," if any. The extension, in a file name, is the part that starts with the last `.' in the last name component. For example, (file-name-sans-extension "foo.lose.c") => "foo.lose" (file-name-sans-extension "big.hack/foo") => "big.hack/foo"  File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names Directory Names --------------- A "directory name" is the name of a directory. A directory is a kind of file, and it has a file name, which is related to the directory name but not identical to it. (This is not quite the same as the usual Unix terminology.) These two different names for the same entity are related by a syntactic transformation. On Unix, this is simple: a directory name ends in a slash, whereas the directory's name as a file lacks that slash. The difference between a directory name and its name as a file is subtle but crucial. When an XEmacs variable or function argument is described as being a directory name, a file name of a directory is not acceptable. The following two functions convert between directory names and file names. They do nothing special with environment variable substitutions such as `$HOME', and the constructs `~', and `..'. - Function: file-name-as-directory filename This function returns a string representing FILENAME in a form that the operating system will interpret as the name of a directory. In Unix, this means appending a slash to the string. (file-name-as-directory "~rms/lewis") => "~rms/lewis/" - Function: directory-file-name dirname This function returns a string representing DIRNAME in a form that the operating system will interpret as the name of a file. On Unix, this means removing a final slash from the string. (directory-file-name "~lewis/") => "~lewis" Directory name abbreviations are useful for directories that are normally accessed through symbolic links. Sometimes the users recognize primarily the link's name as "the name" of the directory, and find it annoying to see the directory's "real" name. If you define the link name as an abbreviation for the "real" name, XEmacs shows users the abbreviation instead. If you wish to convert a directory name to its abbreviation, use this function: - Function: abbreviate-file-name filename &optional hack-homedir This function applies abbreviations from `directory-abbrev-alist' to its argument, and substitutes `~' for the user's home directory. If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for the user's home directory. - Variable: directory-abbrev-alist The variable `directory-abbrev-alist' contains an alist of abbreviations to use for file directories. Each element has the form `(FROM . TO)', and says to replace FROM with TO when it appears in a directory name. The FROM string is actually a regular expression; it should always start with `^'. The function `abbreviate-file-name' performs these substitutions. You can set this variable in `site-init.el' to describe the abbreviations appropriate for your site. Here's an example, from a system on which file system `/home/fsf' and so on are normally accessed through symbolic links named `/fsf' and so on. (("^/home/fsf" . "/fsf") ("^/home/gp" . "/gp") ("^/home/gd" . "/gd"))  File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names Absolute and Relative File Names -------------------------------- All the directories in the file system form a tree starting at the root directory. A file name can specify all the directory names starting from the root of the tree; then it is called an "absolute" file name. Or it can specify the position of the file in the tree relative to a default directory; then it is called a "relative" file name. On Unix, an absolute file name starts with a slash or a tilde (`~'), and a relative one does not. - Function: file-name-absolute-p filename This function returns `t' if file FILENAME is an absolute file name, `nil' otherwise. (file-name-absolute-p "~rms/foo") => t (file-name-absolute-p "rms/foo") => nil (file-name-absolute-p "/user/rms/foo") => t  File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names Functions that Expand Filenames ------------------------------- "Expansion" of a file name means converting a relative file name to an absolute one. Since this is done relative to a default directory, you must specify the default directory name as well as the file name to be expanded. Expansion also simplifies file names by eliminating redundancies such as `./' and `NAME/../'. - Function: expand-file-name filename &optional directory This function converts FILENAME to an absolute file name. If DIRECTORY is supplied, it is the directory to start with if FILENAME is relative. (The value of DIRECTORY should itself be an absolute directory name; it may start with `~'.) Otherwise, the current buffer's value of `default-directory' is used. For example: (expand-file-name "foo") => "/xcssun/users/rms/lewis/foo" (expand-file-name "../foo") => "/xcssun/users/rms/foo" (expand-file-name "foo" "/usr/spool/") => "/usr/spool/foo" (expand-file-name "$HOME/foo") => "/xcssun/users/rms/lewis/$HOME/foo" Filenames containing `.' or `..' are simplified to their canonical form: (expand-file-name "bar/../foo") => "/xcssun/users/rms/lewis/foo" `~/' at the beginning is expanded into the user's home directory. A `/' or `~' following a `/'. Note that `expand-file-name' does _not_ expand environment variables; only `substitute-in-file-name' does that. - Function: file-relative-name filename &optional directory This function does the inverse of expansion--it tries to return a relative name that is equivalent to FILENAME when interpreted relative to DIRECTORY. If DIRECTORY is `nil' or omitted, the value of `default-directory' is used. (file-relative-name "/foo/bar" "/foo/") => "bar") (file-relative-name "/foo/bar" "/hack/") => "../foo/bar") - Variable: default-directory The value of this buffer-local variable is the default directory for the current buffer. It should be an absolute directory name; it may start with `~'. This variable is local in every buffer. `expand-file-name' uses the default directory when its second argument is `nil'. On Unix systems, the value is always a string ending with a slash. default-directory => "/user/lewis/manual/" - Function: substitute-in-file-name filename This function replaces environment variable references in FILENAME with the environment variable values. Following standard Unix shell syntax, `$' is the prefix to substitute an environment variable value. The environment variable name is the series of alphanumeric characters (including underscores) that follow the `$'. If the character following the `$' is a `{', then the variable name is everything up to the matching `}'. Here we assume that the environment variable `HOME', which holds the user's home directory name, has value `/xcssun/users/rms'. (substitute-in-file-name "$HOME/foo") => "/xcssun/users/rms/foo" After substitution, a `/' or `~' following a `/' is taken to be the start of an absolute file name that overrides what precedes it, so everything before that `/' or `~' is deleted. For example: (substitute-in-file-name "bar/~/foo") => "~/foo" (substitute-in-file-name "/usr/local/$HOME/foo") => "/xcssun/users/rms/foo"  File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names Generating Unique File Names ---------------------------- Some programs need to write temporary files. Here is the usual way to construct a name for such a file: (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory))) Here we use `(temp-directory)' to specify a directory for temporary files--under Unix, it will normally evaluate to `"/tmp/"'. The job of `make-temp-name' is to prevent two different users or two different processes from trying to use the same name. - Function: temp-directory This function returns the name of the directory to use for temporary files. Under Unix, this will be the value of `TMPDIR', defaulting to `/tmp'. On Windows, this will be obtained from the `TEMP' or `TMP' environment variables, defaulting to `/'. Note that the `temp-directory' function does not exist under FSF Emacs. - Function: make-temp-name prefix This function generates a temporary file name starting with PREFIX. The Emacs process number forms part of the result, so there is no danger of generating a name being used by another process. (make-temp-name "/tmp/foo") => "/tmp/fooGaAQjC" In addition, this function makes an attempt to choose a name that does not specify an existing file. To make this work, PREFIX should be an absolute file name. To avoid confusion, each Lisp application should preferably use a unique PREFIX to `make-temp-name'.  File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names File Name Completion -------------------- This section describes low-level subroutines for completing a file name. For other completion functions, see *Note Completion::. - Function: file-name-all-completions partial-filename directory This function returns a list of all possible completions for files whose name starts with PARTIAL-FILENAME in directory DIRECTORY. The order of the completions is the order of the files in the directory, which is unpredictable and conveys no useful information. The argument PARTIAL-FILENAME must be a file name containing no directory part and no slash. The current buffer's default directory is prepended to DIRECTORY, if DIRECTORY is not absolute. File names which end with any member of `completion-ignored-extensions' are not considered as possible completions for PARTIAL-FILENAME unless there is no other possible completion. `completion-ignored-extensions' is not applied to the names of directories. In the following example, suppose that the current default directory, `~rms/lewis', has five files whose names begin with `f': `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'. (file-name-all-completions "f" "") => ("foo" "file~" "file.c.~2~" "file.c.~1~" "file.c") (file-name-all-completions "fo" "") => ("foo") - Function: file-name-completion partial-filename directory This function completes the file name PARTIAL-FILENAME in directory DIRECTORY. It returns the longest prefix common to all file names in directory DIRECTORY that start with PARTIAL-FILENAME. If only one match exists and PARTIAL-FILENAME matches it exactly, the function returns `t'. The function returns `nil' if directory DIRECTORY contains no name starting with PARTIAL-FILENAME. File names which end with any member of `completion-ignored-extensions' are not considered as possible completions for PARTIAL-FILENAME unless there is no other possible completion. `completion-ignored-extensions' is not applied to the names of directories. In the following example, suppose that the current default directory has five files whose names begin with `f': `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'. (file-name-completion "fi" "") => "file" (file-name-completion "file.c.~1" "") => "file.c.~1~" (file-name-completion "file.c.~1~" "") => t (file-name-completion "file.c.~3" "") => nil - User Option: completion-ignored-extensions `file-name-completion' usually ignores file names that end in any string in this list. It does not ignore them when all the possible completions end in one of these suffixes or when a buffer showing all possible completions is displayed. A typical value might look like this: completion-ignored-extensions => (".o" ".elc" "~" ".dvi")  File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names User Name Completion -------------------- This section describes low-level subroutines for completing a user name. For other completion functions, see *Note Completion::. - Function: user-name-all-completions partial-username This function returns a list of all possible completions for a user name starting with PARTIAL-USERNAME. The order of the completions is unpredictable and conveys no useful information. The argument PARTIAL-USERNAME must be a partial user name containing no tilde character and no slash. - Function: user-name-completion partial-username This function completes a user name from PARTIAL-USERNAME. It returns the longest prefix common to all user names that start with PARTIAL-USERNAME. If only one match exists and PARTIAL-USERNAME matches it exactly, the function returns `t'. The function returns `nil' if no user name starting with PARTIAL-USERNAME exists. - Function: user-name-completion-1 partial-username This function completes the partial user name PARTIAL-USERNAME, like `user-name-completion', differing only in the return value. This function returns the cons of the completion returned by `user-name-completion', and a boolean indicating whether that completion was unique.  File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files Contents of Directories ======================= A directory is a kind of file that contains other files entered under various names. Directories are a feature of the file system. XEmacs can list the names of the files in a directory as a Lisp list, or display the names in a buffer using the `ls' shell command. In the latter case, it can optionally display information about each file, depending on the value of switches passed to the `ls' command. - Function: directory-files directory &optional full-name match-regexp nosort files-only This function returns a list of the names of the files in the directory DIRECTORY. By default, the list is in alphabetical order. If FULL-NAME is non-`nil', the function returns the files' absolute file names. Otherwise, it returns just the names relative to the specified directory. If MATCH-REGEXP is non-`nil', this function returns only those file names that contain that regular expression--the other file names are discarded from the list. If NOSORT is non-`nil', `directory-files' does not sort the list, so you get the file names in no particular order. Use this if you want the utmost possible speed and don't care what order the files are processed in. If the order of processing is visible to the user, then the user will probably be happier if you do sort the names. If FILES-ONLY is the symbol `t', then only the "files" in the directory will be returned; subdirectories will be excluded. If FILES-ONLY is not `nil' and not `t', then only the subdirectories will be returned. Otherwise, if FILES-ONLY is `nil' (the default) then both files and subdirectories will be returned. (directory-files "~lewis") => ("#foo#" "#foo.el#" "." ".." "dired-mods.el" "files.texi" "files.texi.~1~") An error is signaled if DIRECTORY is not the name of a directory that can be read. - Function: insert-directory file switches &optional wildcard full-directory-p This function inserts (in the current buffer) a directory listing for directory FILE, formatted with `ls' according to SWITCHES. It leaves point after the inserted text. The argument FILE may be either a directory name or a file specification including wildcard characters. If WILDCARD is non-`nil', that means treat FILE as a file specification with wildcards. If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory and switches do not contain `-d', so that the listing should show the full contents of the directory. (The `-d' option to `ls' says to describe a directory itself rather than its contents.) This function works by running a directory listing program whose name is in the variable `insert-directory-program'. If WILDCARD is non-`nil', it also runs the shell specified by `shell-file-name', to expand the wildcards. - Variable: insert-directory-program This variable's value is the program to run to generate a directory listing for the function `insert-directory'.