X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=blobdiff_plain;f=info%2Flispref.info-4;h=114aa7a5789affa2b130efffc81e5e8e659d0f1d;hp=5f78301158259e86413e79027229e1449d1c2c07;hb=79d2db7d65205bc85d471590726d0cf3af5598e0;hpb=de1ec4b272dfa3f9ef2c9ae28a9ba67170d24da5 diff --git a/info/lispref.info-4 b/info/lispref.info-4 index 5f78301..114aa7a 100644 --- a/info/lispref.info-4 +++ b/info/lispref.info-4 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 4.0 from +This is ../info/lispref.info, produced by makeinfo version 4.6 from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,1455 +50,7022 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Specifier Type, Next: Font Instance Type, Prev: Glyph Type, Up: Window-System Types +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 -Specifier Type --------------- +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: - (not yet documented) +* 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: Font Instance Type, Next: Color Instance Type, Prev: Specifier Type, Up: Window-System Types +File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols -Font Instance Type ------------------- +OffiX DND +--------- - (not yet documented) +_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: Color Instance Type, Next: Image Instance Type, Prev: Font Instance Type, Up: Window-System Types +File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols -Color Instance Type -------------------- +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. - (not yet documented) + Buffer drags are always converted to plain text.  -File: lispref.info, Node: Image Instance Type, Next: Toolbar Button Type, Prev: Color Instance Type, Up: Window-System Types +File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols -Image Instance Type -------------------- +MSWindows OLE +------------- - (not yet documented) +Only allows file drags and drops.  -File: lispref.info, Node: Toolbar Button Type, Next: Subwindow Type, Prev: Image Instance Type, Up: Window-System Types +File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols -Toolbar Button Type -------------------- +Loose ends +---------- - (not yet documented) +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: Subwindow Type, Next: X Resource Type, Prev: Toolbar Button Type, Up: Window-System Types +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. -Subwindow Type --------------- + 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. - (not yet documented) + 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: X Resource Type, Prev: Subwindow Type, Up: Window-System Types +File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop -X Resource Type ---------------- +Drag Interface +============== - (not yet documented) +This describes the drag API (not implemented yet).  -File: lispref.info, Node: Type Predicates, Next: Equality Predicates, Prev: Window-System Types, Up: Lisp Data Types +File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top -Type Predicates -=============== +Major and Minor Modes +********************* - The XEmacs Lisp interpreter itself does not perform type checking on -the actual arguments passed to functions when they are called. It could -not do so, since function arguments in Lisp do not have declared data -types, as they do in other programming languages. It is therefore up to -the individual function to test whether each actual argument belongs to -a type that the function can use. +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. - All built-in functions do check the types of their actual arguments -when appropriate, and signal a `wrong-type-argument' error if an -argument is of the wrong type. For example, here is what happens if you -pass an argument to `+' that it cannot handle: + 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::. - (+ 2 'a) - error--> Wrong type argument: integer-or-marker-p, a +* Menu: - If you want your program to handle different types differently, you -must do explicit type checking. The most common way to check the type -of an object is to call a "type predicate" function. Emacs has a type -predicate for each type, as well as some predicates for combinations of -types. +* 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. - A type predicate function takes one argument; it returns `t' if the -argument belongs to the appropriate type, and `nil' otherwise. -Following a general Lisp convention for predicate functions, most type -predicates' names end with `p'. + +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. - Here is an example which uses the predicates `listp' to check for a -list and `symbolp' to check for a symbol. +* Menu: - (defun add-on (x) - (cond ((symbolp x) - ;; If X is a symbol, put it on LIST. - (setq list (cons x list))) - ((listp x) - ;; If X is a list, add its elements to LIST. - (setq list (append x list))) - (t - ;; We only handle symbols and lists. - (error "Invalid argument %s in add-on" x)))) +* 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. - Here is a table of predefined type predicates, in alphabetical order, -with references to further information. + +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::. -`annotationp' - *Note annotationp: Annotation Primitives. + +File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes -`arrayp' - *Note arrayp: Array Functions. +Major Mode Examples +------------------- -`atom' - *Note atom: List-related Predicates. +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. -`bit-vector-p' - *Note bit-vector-p: Bit Vector Functions. + +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)'. -`bitp' - *Note bitp: Bit Vector Functions. + For example, -`boolean-specifier-p' - *Note boolean-specifier-p: Specifier Types. + (("^/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'. -`buffer-glyph-p' - *Note buffer-glyph-p: Glyph Types. + +File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes -`buffer-live-p' - *Note buffer-live-p: Killing Buffers. +Getting Help about a Major Mode +------------------------------- -`bufferp' - *Note bufferp: Buffer Basics. +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. -`button-event-p' - *Note button-event-p: Event Predicates. + - Command: describe-mode + This function displays the documentation of the current major mode. -`button-press-event-p' - *Note button-press-event-p: Event Predicates. + 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::.) -`button-release-event-p' - *Note button-release-event-p: Event Predicates. + - 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. -`case-table-p' - *Note case-table-p: Case Tables. + +File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes -`char-int-p' - *Note char-int-p: Character Codes. +Defining Derived Modes +---------------------- -`char-or-char-int-p' - *Note char-or-char-int-p: Character Codes. +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'. -`char-or-string-p' - *Note char-or-string-p: Predicates for Strings. + - 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. -`char-table-p' - *Note char-table-p: Char Tables. + The new command VARIANT is defined to call the function PARENT, + then override certain aspects of that parent mode: -`characterp' - *Note characterp: Predicates for Characters. + * 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. -`color-instance-p' - *Note color-instance-p: Colors. + * 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. -`color-pixmap-image-instance-p' - *Note color-pixmap-image-instance-p: Image Instance Types. + * 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. -`color-specifier-p' - *Note color-specifier-p: Specifier Types. + * 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.) -`commandp' - *Note commandp: Interactive Call. + 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'. -`compiled-function-p' - *Note compiled-function-p: Compiled-Function Type. + The argument DOCSTRING specifies the documentation string for the + new mode. If you omit DOCSTRING, `define-derived-mode' generates + a documentation string. -`console-live-p' - *Note console-live-p: Connecting to a Console or Device. + Here is a hypothetical example: -`consolep' - *Note consolep: Consoles and Devices. + (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) -`consp' - *Note consp: List-related Predicates. + +File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes -`database-live-p' - *Note database-live-p: Connecting to a Database. +Minor Modes +=========== -`databasep' - *Note databasep: Databases. +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. -`device-live-p' - *Note device-live-p: Connecting to a Console or Device. + 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. -`device-or-frame-p' - *Note device-or-frame-p: Basic Device Functions. + 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. -`devicep' - *Note devicep: Consoles and Devices. + 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. -`eval-event-p' - *Note eval-event-p: Event Predicates. +* Menu: -`event-live-p' - *Note event-live-p: Event Predicates. +* Minor Mode Conventions:: Tips for writing a minor mode. +* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -`eventp' - *Note eventp: Events. + +File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes -`extent-live-p' - *Note extent-live-p: Creating and Modifying Extents. +Conventions for Writing Minor Modes +----------------------------------- -`extentp' - *Note extentp: Extents. +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. -`face-boolean-specifier-p' - *Note face-boolean-specifier-p: Specifier Types. + In addition, there are several conventions that are specific to +minor modes. -`facep' - *Note facep: Basic Face Functions. + * 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". -`floatp' - *Note floatp: Predicates on Numbers. + 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. -`font-instance-p' - *Note font-instance-p: Fonts. + If you want the minor mode to be enabled separately in each buffer, + make the variable buffer-local. -`font-specifier-p' - *Note font-specifier-p: Specifier Types. + * 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. -`frame-live-p' - *Note frame-live-p: Deleting Frames. + 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. -`framep' - *Note framep: Frames. + 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. -`functionp' - (not yet documented) + (setq transient-mark-mode + (if (null arg) (not transient-mark-mode) + (> (prefix-numeric-value arg) 0))) -`generic-specifier-p' - *Note generic-specifier-p: Specifier Types. + * Add an element to `minor-mode-alist' for each minor mode (*note + Modeline Variables::). This element should be a list of the + following form: -`glyphp' - *Note glyphp: Glyphs. + (MODE-VARIABLE STRING) -`hash-table-p' - *Note hash-table-p: Hash Tables. + 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. -`icon-glyph-p' - *Note icon-glyph-p: Glyph Types. + When you add an element to `minor-mode-alist', use `assq' to check + for an existing element, to avoid duplication. For example: -`image-instance-p' - *Note image-instance-p: Images. + (or (assq 'leif-mode minor-mode-alist) + (setq minor-mode-alist + (cons '(leif-mode " Leif") minor-mode-alist))) -`image-specifier-p' - *Note image-specifier-p: Specifier Types. + +File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes -`integer-char-or-marker-p' - *Note integer-char-or-marker-p: Predicates on Markers. +Keymaps and Minor Modes +----------------------- -`integer-or-char-p' - *Note integer-or-char-p: Predicates for Characters. +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::. -`integer-or-marker-p' - *Note integer-or-marker-p: Predicates on Markers. + 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.) -`integer-specifier-p' - *Note integer-specifier-p: Specifier Types. + +File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes -`integerp' - *Note integerp: Predicates on Numbers. +Modeline Format +=============== -`itimerp' - (not yet documented) +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. -`key-press-event-p' - *Note key-press-event-p: Event Predicates. + 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. -`keymapp' - *Note keymapp: Creating Keymaps. + `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). -`keywordp' - (not yet documented) + 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. -`listp' - *Note listp: List-related Predicates. + - Function: redraw-modeline &optional all + Force redisplay of the current buffer's modeline. If ALL is + non-`nil', then force redisplay of all modelines. -`markerp' - *Note markerp: Predicates on Markers. + The modeline is usually displayed in inverse video. This is +controlled using the `modeline' face. *Note Faces::. -`misc-user-event-p' - *Note misc-user-event-p: Event Predicates. +* Menu: -`mono-pixmap-image-instance-p' - *Note mono-pixmap-image-instance-p: Image Instance Types. +* Modeline Data:: The data structure that controls the modeline. +* Modeline Variables:: Variables used in that data structure. +* %-Constructs:: Putting information into a modeline. -`motion-event-p' - *Note motion-event-p: Event Predicates. + +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") + "-%-")) -`mouse-event-p' - *Note mouse-event-p: Event Predicates. + +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. -`natnum-specifier-p' - *Note natnum-specifier-p: Specifier Types. + +File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format -`natnump' - *Note natnump: Predicates on Numbers. +`%'-Constructs in the ModeLine +------------------------------ -`nlistp' - *Note nlistp: List-related Predicates. +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. -`nothing-image-instance-p' - *Note nothing-image-instance-p: Image Instance Types. +`%b' + The current buffer name, obtained with the `buffer-name' function. + *Note Buffer Names::. -`number-char-or-marker-p' - *Note number-char-or-marker-p: Predicates on Markers. +`%f' + The visited file name, obtained with the `buffer-file-name' + function. *Note Buffer File Name::. -`number-or-marker-p' - *Note number-or-marker-p: Predicates on Markers. +`%F' + The name of the selected frame. -`numberp' - *Note numberp: Predicates on Numbers. +`%c' + The current column number of point. -`pointer-glyph-p' - *Note pointer-glyph-p: Glyph Types. +`%l' + The current line number of point. -`pointer-image-instance-p' - *Note pointer-image-instance-p: Image Instance Types. +`%*' + `%' if the buffer is read only (see `buffer-read-only'); + `*' if the buffer is modified (see `buffer-modified-p'); + `-' otherwise. *Note Buffer Modification::. -`process-event-p' - *Note process-event-p: Event Predicates. +`%+' + `*' 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::. -`processp' - *Note processp: Processes. +`%&' + `*' if the buffer is modified, and `-' otherwise. -`range-table-p' - *Note range-table-p: Range Tables. +`%s' + The status of the subprocess belonging to the current buffer, + obtained with `process-status'. *Note Process Information::. -`ringp' - (not yet documented) +`%l' + The current line number. -`sequencep' - *Note sequencep: Sequence Functions. +`%S' + The name of the selected frame; this is only meaningful under the + X Window System. *Note Frame Name::. -`specifierp' - *Note specifierp: Specifiers. +`%t' + Whether the visited file is a text file or a binary file. (This + is a meaningful distinction only on certain operating systems.) -`stringp' - *Note stringp: Predicates for Strings. +`%p' + The percentage of the buffer text above the *top* of window, or + `Top', `Bottom' or `All'. -`subrp' - *Note subrp: Function Cells. +`%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'. -`subwindow-image-instance-p' - *Note subwindow-image-instance-p: Image Instance Types. +`%n' + `Narrow' when narrowing is in effect; nothing otherwise (see + `narrow-to-region' in *Note Narrowing::). -`subwindowp' - *Note subwindowp: Subwindows. +`%C' + Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'. -`symbolp' - *Note symbolp: Symbols. +`%[' + An indication of the depth of recursive editing levels (not + counting minibuffer levels): one `[' for each editing level. + *Note Recursive Editing::. -`syntax-table-p' - *Note syntax-table-p: Syntax Tables. +`%]' + One `]' for each recursive editing level (not counting minibuffer + levels). -`text-image-instance-p' - *Note text-image-instance-p: Image Instance Types. +`%%' + The character `%'--this is how to include a literal `%' in a + string in which `%'-constructs are allowed. -`timeout-event-p' - *Note timeout-event-p: Event Predicates. +`%-' + Dashes sufficient to fill the remainder of the modeline. -`toolbar-button-p' - *Note toolbar-button-p: Toolbar. + 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'. -`toolbar-specifier-p' - *Note toolbar-specifier-p: Toolbar. +`%m' + The value of `mode-name'. -`user-variable-p' - *Note user-variable-p: Defining Variables. +`%M' + The value of `global-mode-string'. Currently, only `display-time' + modifies the value of `global-mode-string'. -`vectorp' - *Note vectorp: Vectors. + +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. -`weak-list-p' - *Note weak-list-p: Weak Lists. + +File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top -`window-configuration-p' - *Note window-configuration-p: Window Configurations. +Documentation +************* -`window-live-p' - *Note window-live-p: Deleting Windows. +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. -`windowp' - *Note windowp: Basic Windows. + 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. - The most general way to check the type of an object is to call the -function `type-of'. Recall that each object belongs to one and only -one primitive type; `type-of' tells you which one (*note Lisp Data -Types::). But `type-of' knows nothing about non-primitive types. In -most cases, it is more convenient to use type predicates than `type-of'. +* Menu: - - Function: type-of object - This function returns a symbol naming the primitive type of - OBJECT. The value is one of `bit-vector', `buffer', `char-table', - `character', `charset', `coding-system', `cons', `color-instance', - `compiled-function', `console', `database', `device', `event', - `extent', `face', `float', `font-instance', `frame', `glyph', - `hash-table', `image-instance', `integer', `keymap', `marker', - `process', `range-table', `specifier', `string', `subr', - `subwindow', `symbol', `toolbar-button', `tooltalk-message', - `tooltalk-pattern', `vector', `weak-list', `window', - `window-configuration', or `x-resource'. +* 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. - (type-of 1) - => integer - (type-of 'nil) - => symbol - (type-of '()) ; `()' is `nil'. - => symbol - (type-of '(x)) - => cons + +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: Equality Predicates, Prev: Type Predicates, Up: Lisp Data Types +File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation -Equality Predicates -=================== +Access to Documentation Strings +=============================== - Here we describe two functions that test for equality between any two -objects. Other functions test equality between objects of specific -types, e.g., strings. For these predicates, see the appropriate chapter -describing the data type. - - - Function: eq object1 object2 - This function returns `t' if OBJECT1 and OBJECT2 are the same - object, `nil' otherwise. The "same object" means that a change in - one will be reflected by the same change in the other. - - `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same - value. Also, since symbol names are normally unique, if the - arguments are symbols with the same name, they are `eq'. For - other types (e.g., lists, vectors, strings), two arguments with - the same contents or elements are not necessarily `eq' to each - other: they are `eq' only if they are the same object. - - (The `make-symbol' function returns an uninterned symbol that is - not interned in the standard `obarray'. When uninterned symbols - are in use, symbol names are no longer unique. Distinct symbols - with the same name are not `eq'. *Note Creating Symbols::.) - - NOTE: Under XEmacs 19, characters are really just integers, and - thus characters and integers are `eq'. Under XEmacs 20, it was - necessary to preserve remnants of this in function such as `old-eq' - in order to maintain byte-code compatibility. Byte code compiled - under any Emacs 19 will automatically have calls to `eq' mapped to - `old-eq' when executed under XEmacs 20. - - (eq 'foo 'foo) - => t - - (eq 456 456) - => t - - (eq "asdf" "asdf") - => nil - - (eq '(1 (2 (3))) '(1 (2 (3)))) - => nil - - (setq foo '(1 (2 (3)))) - => (1 (2 (3))) - (eq foo foo) - => t - (eq foo '(1 (2 (3)))) - => nil - - (eq [(1 2) 3] [(1 2) 3]) - => nil - - (eq (point-marker) (point-marker)) - => nil + - 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." - - Function: old-eq object1 object2 - This function exists under XEmacs 20 and is exactly like `eq' - except that it suffers from the char-int confoundance disease. In - other words, it returns `t' if given a character and the - equivalent integer, even though the objects are of different types! - You should _not_ ever call this function explicitly in your code. - However, be aware that all calls to `eq' in byte code compiled - under version 19 map to `old-eq' in XEmacs 20. (Likewise for - `old-equal', `old-memq', `old-member', `old-assq' and - `old-assoc'.) - - ;; Remember, this does not apply under XEmacs 19. - ?A - => ?A - (char-int ?A) - => 65 - (old-eq ?A 65) - => t ; Eek, we've been infected. - (eq ?A 65) - => nil ; We are still healthy. - - - Function: equal object1 object2 - This function returns `t' if OBJECT1 and OBJECT2 have equal - components, `nil' otherwise. Whereas `eq' tests if its arguments - are the same object, `equal' looks inside nonidentical arguments - to see if their elements are the same. So, if two objects are - `eq', they are `equal', but the converse is not always true. - - (equal 'foo 'foo) - => t - - (equal 456 456) - => t - - (equal "asdf" "asdf") - => t - (eq "asdf" "asdf") - => nil - - (equal '(1 (2 (3))) '(1 (2 (3)))) - => t - (eq '(1 (2 (3))) '(1 (2 (3)))) - => nil - - (equal [(1 2) 3] [(1 2) 3]) - => t - (eq [(1 2) 3] [(1 2) 3]) - => nil - - (equal (point-marker) (point-marker)) - => t + +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) - (eq (point-marker) (point-marker)) - => nil + (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'. - Comparison of strings is case-sensitive. + +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'. - Note that in FSF GNU Emacs, comparison of strings takes into - account their text properties, and you have to use `string-equal' - if you want only the strings themselves compared. This difference - does not exist in XEmacs; `equal' and `string-equal' always return - the same value on the same strings. + +File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top - (equal "asdf" "ASDF") - => nil +Files +***** - Two distinct buffers are never `equal', even if their contents are - the same. +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::. - The test for equality is implemented recursively, and circular lists -may therefore cause infinite recursion (leading to an error). + 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: Numbers, Next: Strings and Characters, Prev: Lisp Data Types, Up: Top +File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files -Numbers -******* +Visiting Files +============== - XEmacs supports two numeric data types: "integers" and "floating -point numbers". Integers are whole numbers such as -3, 0, #b0111, -#xFEED, #o744. Their values are exact. The number prefixes `#b', -`#o', and `#x' are supported to represent numbers in binary, octal, and -hexadecimal notation (or radix). Floating point numbers are numbers -with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be -expressed in exponential notation: 1.5e2 equals 150; in this example, -`e2' stands for ten to the second power, and is multiplied by 1.5. -Floating point values are not exact; they have a fixed, limited amount -of precision. +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: -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. +* Visiting Functions:: The usual interface functions for visiting. +* Subroutines of Visiting:: Lower-level subroutines that they use.  -File: lispref.info, Node: Integer Basics, Next: Float Basics, Up: Numbers +File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files -Integer Basics -============== +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)) - The range of values for an integer depends on the machine. The -minimum range is -134217728 to 134217727 (28 bits; i.e., -2**27 to -2**27 - 1), but some machines may provide a wider range. Many examples -in this chapter assume an integer has 28 bits. + (See `switch-to-buffer' in *Note Displaying Buffers::.) - The Lisp reader reads an integer as a sequence of digits with -optional initial sign and optional final period. + When `find-file' is called interactively, it prompts for FILENAME + in the minibuffer. - 1 ; The integer 1. - 1. ; The integer 1. - +1 ; Also the integer 1. - -1 ; The integer -1. - 268435457 ; Also the integer 1, due to overflow. - 0 ; The integer 0. - -0 ; The integer 0. + - 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. - To understand how various functions work on integers, especially the -bitwise operators (*note Bitwise Operations::), it is often helpful to -view the numbers in their binary form. + 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. - In 28-bit binary, the decimal integer 5 looks like this: + 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. - 0000 0000 0000 0000 0000 0000 0101 + 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. -(We have inserted spaces between groups of 4 bits, and two spaces -between groups of 8 bits, to make the binary integer easier to read.) + 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 integer -1 looks like this: + The `find-file-noselect' function returns the buffer that is + visiting the file FILENAME. - 1111 1111 1111 1111 1111 1111 1111 + (find-file-noselect "/etc/fstab") + => # --1 is represented as 28 ones. (This is called "two's complement" -notation.) + - 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::. - The negative integer, -5, is creating by subtracting 4 from -1. In -binary, the decimal integer 4 is 100. Consequently, -5 looks like this: + When this command is called interactively, it prompts for FILENAME. - 1111 1111 1111 1111 1111 1111 1011 + - 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. - In this implementation, the largest 28-bit binary integer is the -decimal integer 134,217,727. In binary, it looks like this: + When this command is called interactively, it prompts for FILENAME. - 0111 1111 1111 1111 1111 1111 1111 + - 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::. - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 134,217,727, the value is the -negative integer -134,217,728: + When `view-file' is called interactively, it prompts for FILENAME. - (+ 1 134217727) - => -134217728 - => 1000 0000 0000 0000 0000 0000 0000 + With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in + another window. - Many of the following functions accept markers for arguments as well -as integers. (*Note Markers::.) More precisely, the actual arguments -to such functions may be either integers or markers, which is why we -often give these arguments the name INT-OR-MARKER. When the argument -value is a marker, its position value is used and its buffer is ignored. + - 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: Float Basics, Next: Predicates on Numbers, Prev: Integer Basics, Up: Numbers +File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files -Floating Point Basics -===================== +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") + => #> - XEmacs supports floating point numbers. The precise range of -floating point numbers is machine-specific; it is the same as the range -of the C data type `double' on the machine in question. + This function is used by `find-file-noselect'. It uses + `generate-new-buffer' (*note Creating Buffers::). - The printed representation for floating point numbers requires either -a decimal point (with at least one digit following), an exponent, or -both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4' -are five ways of writing a floating point number whose value is 1500. -They are all equivalent. You can also use a minus sign to write -negative floating point numbers, as in `-1.0'. + - 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::). - Most modern computers support the IEEE floating point standard, which -provides for positive infinity and negative infinity as floating point -values. It also provides for a class of values called NaN or -"not-a-number"; numerical functions return such values in cases where -there is no correct answer. For example, `(sqrt -1.0)' returns a NaN. -For practical purposes, there's no significant difference between -different NaN values in XEmacs Lisp, and there's no rule for precisely -which NaN value should be used in a particular case, so this manual -doesn't try to distinguish them. XEmacs Lisp has no read syntax for -NaNs or infinities; perhaps we should create a syntax in the future. + 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'. - You can use `logb' to extract the binary exponent of a floating -point number (or estimate the logarithm of an integer): + 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. - - Function: logb number - This function returns the binary exponent of NUMBER. More - precisely, the value is the logarithm of NUMBER base 2, rounded - down to an integer. + 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: Predicates on Numbers, Next: Comparison of Numbers, Prev: Float Basics, Up: Numbers +File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files -Type Predicates for Numbers -=========================== +Reading from Files +================== - The functions in this section test whether the argument is a number -or whether it is a certain sort of number. The functions `integerp' -and `floatp' can take any type of Lisp object as argument (the -predicates would not be of much use otherwise); but the `zerop' -predicate requires a number as its argument. See also -`integer-or-marker-p', `integer-char-or-marker-p', `number-or-marker-p' -and `number-char-or-marker-p', in *Note Predicates on Markers::. +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: floatp object - This predicate tests whether its argument is a floating point - number and returns `t' if so, `nil' otherwise. + - 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. - `floatp' does not exist in Emacs versions 18 and earlier. + 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::. - - Function: integerp object - This predicate tests whether its argument is an integer, and - returns `t' if so, `nil' otherwise. + 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. - - Function: numberp object - This predicate tests whether its argument is a number (either - integer or floating point), and returns `t' if so, `nil' otherwise. + 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, - - Function: natnump object - The `natnump' predicate (whose name comes from the phrase - "natural-number-p") tests to see whether its argument is a - nonnegative integer, and returns `t' if so, `nil' otherwise. 0 is - considered non-negative. + (insert-file-contents filename nil 0 500) - - Function: zerop number - This predicate tests whether its argument is zero, and returns `t' - if so, `nil' otherwise. The argument must be a number. + inserts the first 500 characters of a file. - These two forms are equivalent: `(zerop x)' == `(= x 0)'. + 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: Comparison of Numbers, Next: Numeric Conversions, Prev: Predicates on Numbers, Up: Numbers +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. -Comparison of Numbers -===================== + +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. - To test numbers for numerical equality, you should normally use `=', -not `eq'. There can be many distinct floating point number objects -with the same numeric value. If you use `eq' to compare them, then you -test whether two values are the same _object_. By contrast, `=' -compares only the numeric values of the objects. - - At present, each integer value has a unique Lisp object in XEmacs -Lisp. Therefore, `eq' is equivalent to `=' where integers are -concerned. It is sometimes convenient to use `eq' for comparing an -unknown value with an integer, because `eq' does not report an error if -the unknown value is not a number--it accepts arguments of any type. -By contrast, `=' signals an error if the arguments are not numbers or -markers. However, it is a good idea to use `=' if you can, even for -comparing integers, just in case we change the representation of -integers in a future XEmacs version. - - There is another wrinkle: because floating point arithmetic is not -exact, it is often a bad idea to check for equality of two floating -point values. Usually it is better to test for approximate equality. -Here's a function to do this: - - (defconst fuzz-factor 1.0e-6) - (defun approx-equal (x y) - (or (and (= x 0) (= y 0)) - (< (/ (abs (- x y)) - (max (abs x) (abs y))) - fuzz-factor))) - - Common Lisp note: Comparing numbers in Common Lisp always requires - `=' because Common Lisp implements multi-word integers, and two - distinct integer objects can have the same numeric value. XEmacs - Lisp can have just one integer object for any given value because - it has a limited range of integer values. - - In addition to numbers, all of the following functions also accept -characters and markers as arguments, and treat them as their number -equivalents. - - - Function: = number &rest more-numbers - This function returns `t' if all of its arguments are numerically - equal, `nil' otherwise. - - (= 5) + 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 - (= 5 6) - => nil - (= 5 5.0) + (file-exists-p "/usr/spool/mqueue") => t - (= 5 5 6) + (file-readable-p "/usr/spool/mqueue") => nil - - Function: /= number &rest more-numbers - This function returns `t' if no two arguments are numerically - equal, `nil' otherwise. - - (/= 5 6) + - 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 - (/= 5 5 6) + (file-writable-p "/foo") + => nil + (file-writable-p "~/no-such-dir/foo") => nil - (/= 5 6 1) - => t - - Function: < number &rest more-numbers - This function returns `t' if the sequence of its arguments is - monotonically increasing, `nil' otherwise. + - 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. - (< 5 6) - => t - (< 5 6 6) + Example: after the following, + + (file-accessible-directory-p "/foo") => nil - (< 5 6 7) - => t - - Function: <= number &rest more-numbers - This function returns `t' if the sequence of its arguments is - monotonically nondecreasing, `nil' otherwise. + 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. - (<= 5 6) + (file-newer-than-file-p "aug-19" "aug-20") + => nil + (file-newer-than-file-p "aug-20" "aug-19") => t - (<= 5 6 6) + (file-newer-than-file-p "aug-19" "no-file") => t - (<= 5 6 5) + (file-newer-than-file-p "no-file" "aug-19") => nil - - Function: > number &rest more-numbers - This function returns `t' if the sequence of its arguments is - monotonically decreasing, `nil' otherwise. + You can use `file-attributes' to get a file's last modification + time as a list of two numbers. *Note File Attributes::. - - Function: >= number &rest more-numbers - This function returns `t' if the sequence of its arguments is - monotonically nonincreasing, `nil' otherwise. + +File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files - - Function: max number &rest more-numbers - This function returns the largest of its arguments. +Distinguishing Kinds of Files +----------------------------- - (max 20) - => 20 - (max 1 2.5) - => 2.5 - (max 1 3 2.5) - => 3 +This section describes how to distinguish various kinds of files, such +as directories, symbolic links, and ordinary files. - - Function: min number &rest more-numbers - This function returns the smallest of its arguments. + - 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. - (min -4 1) - => -4 + If the file FILENAME is not a symbolic link (or there is no such + file), `file-symlink-p' returns `nil'. - -File: lispref.info, Node: Numeric Conversions, Next: Arithmetic Operations, Prev: Comparison of Numbers, Up: Numbers + (file-symlink-p "foo") + => nil + (file-symlink-p "sym-link") + => "foo" + (file-symlink-p "sym-link2") + => "sym-link" + (file-symlink-p "/bin") + => "/pub/bin" -Numeric Conversions -=================== - To convert an integer to floating point, use the function `float'. + - 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: float number - This returns NUMBER converted to floating point. If NUMBER is - already a floating point number, `float' returns it unchanged. + - 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). - There are four functions to convert floating point numbers to -integers; they differ in how they round. These functions accept -integer arguments also, and return such arguments unchanged. + +File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files - - Function: truncate number - This returns NUMBER, converted to an integer by rounding towards - zero. +Truenames +--------- - - Function: floor number &optional divisor - This returns NUMBER, converted to an integer by rounding downward - (towards negative infinity). +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. - If DIVISOR is specified, NUMBER is divided by DIVISOR before the - floor is taken; this is the division operation that corresponds to - `mod'. An `arith-error' results if DIVISOR is 0. + - 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. - - Function: ceiling number - This returns NUMBER, converted to an integer by rounding upward - (towards positive infinity). + 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. - - Function: round number - This returns NUMBER, converted to an integer by rounding towards - the nearest integer. Rounding a value equidistant between two - integers may choose the integer closer to zero, or it may prefer - an even integer, depending on your machine. + *Note Buffer File Name::, for related information.  -File: lispref.info, Node: Arithmetic Operations, Next: Rounding Operations, Prev: Numeric Conversions, Up: Numbers +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 -Arithmetic Operations -===================== + - Function: file-attributes filename + This function returns a list of attributes of file FILENAME. If + the specified file cannot be opened, it returns `nil'. - XEmacs Lisp provides the traditional four arithmetic operations: -addition, subtraction, multiplication, and division. Remainder and -modulus functions supplement the division functions. The functions to -add or subtract 1 are provided because they are traditional in Lisp and -commonly used. + The elements of the list, in order, are: - All of these functions except `%' return a floating point value if -any argument is floating. + 0. `t' for a directory, a string for a symbolic link (the name + linked to), or `nil' for a text file. - It is important to note that in XEmacs Lisp, arithmetic functions do -not check for overflow. Thus `(1+ 134217727)' may evaluate to --134217728, depending on your hardware. + 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::). - - Function: 1+ number - This function returns NUMBER plus one. NUMBER may be a number, - character or marker. Markers and characters are converted to - integers. + 2. The file's UID. - For example, + 3. The file's GID. - (setq foo 4) - => 4 - (1+ foo) - => 5 + 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::.) - This function is not analogous to the C operator `++'--it does not - increment a variable. It just computes a sum. Thus, if we - continue, + 5. The time of last modification as a list of two integers (as + above). - foo - => 4 + 6. The time of last status change as a list of two integers (as + above). - If you want to increment the variable, you must use `setq', like - this: + 7. The size of the file in bytes. - (setq foo (1+ foo)) - => 5 - - Now that the `cl' package is always available from lisp code, a - more convenient and natural way to increment a variable is - `(incf foo)'. - - - Function: 1- number - This function returns NUMBER minus one. NUMBER may be a number, - character or marker. Markers and characters are converted to - integers. - - - Function: abs number - This returns the absolute value of NUMBER. - - - Function: + &rest numbers - This function adds its arguments together. When given no - arguments, `+' returns 0. - - If any of the arguments are characters or markers, they are first - converted to integers. - - (+) - => 0 - (+ 1) - => 1 - (+ 1 2 3 4) - => 10 - - - Function: - &optional number &rest other-numbers - The `-' function serves two purposes: negation and subtraction. - When `-' has a single argument, the value is the negative of the - argument. When there are multiple arguments, `-' subtracts each of - the OTHER-NUMBERS from NUMBER, cumulatively. If there are no - arguments, an error is signaled. - - If any of the arguments are characters or markers, they are first - converted to integers. - - (- 10 1 2 3 4) - => 0 - (- 10) - => -10 - (-) - => 0 - - - Function: * &rest numbers - This function multiplies its arguments together, and returns the - product. When given no arguments, `*' returns 1. - - If any of the arguments are characters or markers, they are first - converted to integers. - - (*) - => 1 - (* 1) - => 1 - (* 1 2 3 4) - => 24 + 8. The file's modes, as a string of ten letters or dashes, as in + `ls -l'. - - Function: / dividend &rest divisors - The `/' function serves two purposes: inversion and division. When - `/' has a single argument, the value is the inverse of the - argument. When there are multiple arguments, `/' divides DIVIDEND - by each of the DIVISORS, cumulatively, returning the quotient. If - there are no arguments, an error is signaled. - - If none of the arguments are floats, then the result is an integer. - This means the result has to be rounded. On most machines, the - result is rounded towards zero after each division, but some - machines may round differently with negative arguments. This is - because the Lisp function `/' is implemented using the C division - operator, which also permits machine-dependent rounding. As a - practical matter, all known machines round in the standard fashion. - - If any of the arguments are characters or markers, they are first - converted to integers. - - If you divide by 0, an `arith-error' error is signaled. (*Note - Errors::.) - - (/ 6 2) - => 3 - (/ 5 2) - => 2 - (/ 25 3 2) - => 4 - (/ 3.0) - => 0.3333333333333333 - (/ -17 6) - => -2 + 9. `t' if the file's GID would change if file were deleted and + recreated; `nil' otherwise. - The result of `(/ -17 6)' could in principle be -3 on some - machines. + 10. The file's inode number. - - Function: % dividend divisor - This function returns the integer remainder after division of - DIVIDEND by DIVISOR. The arguments must be integers or markers. + 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 negative arguments, the remainder is in principle - machine-dependent since the quotient is; but in practice, all - known machines behave alike. + For example, here are the file attributes for `files.texi': - An `arith-error' results if DIVISOR is 0. + (file-attributes "files.texi") + => (nil + 1 + 2235 + 75 + (8489 20284) + (8489 20284) + (8489 20285) + 14906 + "-rw-rw-rw-" + nil + 129500 + -32252) - (% 9 4) - => 1 - (% -9 4) - => -1 - (% 9 -4) - => 1 - (% -9 -4) - => -1 + and here is how the result is interpreted: - For any two integers DIVIDEND and DIVISOR, + `nil' + is neither a directory nor a symbolic link. - (+ (% DIVIDEND DIVISOR) - (* (/ DIVIDEND DIVISOR) DIVISOR)) + `1' + has only one name (the name `files.texi' in the current + default directory). - always equals DIVIDEND. + `2235' + is owned by the user with UID 2235. - - Function: mod dividend divisor - This function returns the value of DIVIDEND modulo DIVISOR; in - other words, the remainder after division of DIVIDEND by DIVISOR, - but with the same sign as DIVISOR. The arguments must be numbers - or markers. + `75' + is in the group with GID 75. - Unlike `%', `mod' returns a well-defined result for negative - arguments. It also permits floating point arguments; it rounds the - quotient downward (towards minus infinity) to an integer, and uses - that quotient to compute the remainder. + `(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::. - An `arith-error' results if DIVISOR is 0. + `(8489 20284)' + was last modified on Aug 19 00:09. - (mod 9 4) - => 1 - (mod -9 4) - => 3 - (mod 9 -4) - => -3 - (mod -9 -4) - => -1 - (mod 5.5 2.5) - => .5 + `(8489 20285)' + last had its inode changed on Aug 19 00:09. - For any two numbers DIVIDEND and DIVISOR, + `14906' + is 14906 characters long. - (+ (mod DIVIDEND DIVISOR) - (* (floor DIVIDEND DIVISOR) DIVISOR)) + `"-rw-rw-rw-"' + has a mode of read and write access for the owner, group, and + world. - always equals DIVIDEND, subject to rounding error if either - argument is floating point. For `floor', see *Note Numeric - Conversions::. + `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: Rounding Operations, Next: Bitwise Operations, Prev: Arithmetic Operations, Up: Numbers +File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files -Rounding Operations -=================== +Changing File Names and Attributes +================================== - The functions `ffloor', `fceiling', `fround' and `ftruncate' take a -floating point argument and return a floating point result whose value -is a nearby integer. `ffloor' returns the nearest integer below; -`fceiling', the nearest integer above; `ftruncate', the nearest integer -in the direction towards zero; `fround', the nearest integer. +The functions in this section rename, copy, delete, link, and set the +modes of files. - - Function: ffloor number - This function rounds NUMBER to the next lower integral value, and - returns that value as a floating point number. + 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: - - Function: fceiling number - This function rounds NUMBER to the next higher integral value, and - returns that value as a floating point number. + * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is + `nil'. - - Function: ftruncate number - This function rounds NUMBER towards zero to an integral value, and - returns that value as a floating point number. + * Request confirmation if OK-IF-ALREADY-EXISTS is a number. This is + what happens when the function is invoked interactively. - - Function: fround number - This function rounds NUMBER to the nearest integral value, and - returns that value as a floating point number. + * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS + is any other value. - -File: lispref.info, Node: Bitwise Operations, Next: Math Functions, Prev: Rounding Operations, Up: Numbers + - 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. -Bitwise Operations on Integers -============================== + In the first part of the following example, we list two files, + `foo' and `foo3'. - In a computer, an integer is represented as a binary number, a -sequence of "bits" (digits which are either zero or one). A bitwise -operation acts on the individual bits of such a sequence. For example, -"shifting" moves the whole sequence left or right one or more places, -reproducing the same pattern "moved over". + % 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 - The bitwise operations in XEmacs Lisp apply only to integers. + 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'. - - Function: lsh integer1 count - `lsh', which is an abbreviation for "logical shift", shifts the - bits in INTEGER1 to the left COUNT places, or to the right if - COUNT is negative, bringing zeros into the vacated bits. If COUNT - is negative, `lsh' shifts zeros into the leftmost - (most-significant) bit, producing a positive result even if - INTEGER1 is negative. Contrast this with `ash', below. + (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) - Here are two examples of `lsh', shifting a pattern of bits one - place to the left. We show only the low-order eight bits of the - binary pattern; the rest are all zero. + and list the files again. Now there are three names for one file: + `foo', `foo2', and `foo3'. The old contents of `foo3' are lost. - (lsh 5 1) - => 10 - ;; Decimal 5 becomes decimal 10. - 00000101 => 00001010 + (add-name-to-file "~/lewis/foo1" "~/lewis/foo3") + => nil - (lsh 7 1) - => 14 - ;; Decimal 7 becomes decimal 14. - 00000111 => 00001110 + % 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 - As the examples illustrate, shifting the pattern of bits one place - to the left produces a number that is twice the value of the - previous number. + This function is meaningless on non-Unix systems, where multiple + names for one file are not allowed. - Shifting a pattern of bits two places to the left produces results - like this (with 8-bit binary numbers): + See also `file-nlinks' in *Note File Attributes::. - (lsh 3 2) - => 12 - ;; Decimal 3 becomes decimal 12. - 00000011 => 00001100 + - Command: rename-file filename newname &optional ok-if-already-exists + This command renames the file FILENAME as NEWNAME. - On the other hand, shifting one place to the right looks like this: + 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. - (lsh 6 -1) - => 3 - ;; Decimal 6 becomes decimal 3. - 00000110 => 00000011 - - (lsh 5 -1) - => 2 - ;; Decimal 5 becomes decimal 2. - 00000101 => 00000010 + In an interactive call, this function prompts for FILENAME and + NEWNAME in the minibuffer; also, it requests confirmation if + NEWNAME already exists. - As the example illustrates, shifting one place to the right - divides the value of a positive integer by two, rounding downward. + - 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. - The function `lsh', like all XEmacs Lisp arithmetic functions, does - not check for overflow, so shifting left can discard significant - bits and change the sign of the number. For example, left shifting - 134,217,727 produces -2 on a 28-bit machine: + 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.) - (lsh 134217727 1) ; left shift - => -2 + In an interactive call, this function prompts for FILENAME and + NEWNAME in the minibuffer; also, it requests confirmation if + NEWNAME already exists. - In binary, in the 28-bit implementation, the argument looks like - this: + - 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. - ;; Decimal 134,217,727 - 0111 1111 1111 1111 1111 1111 1111 + 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.) - which becomes the following when left shifted: + See also `delete-directory' in *Note Create/Delete Dirs::. - ;; Decimal -2 - 1111 1111 1111 1111 1111 1111 1110 + - 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'. - - Function: ash integer1 count - `ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left - COUNT places, or to the right if COUNT is negative. + In an interactive call, this function prompts for FILENAME and + NEWNAME in the minibuffer; also, it requests confirmation if + NEWNAME already exists. - `ash' gives the same results as `lsh' except when INTEGER1 and - COUNT are both negative. In that case, `ash' puts ones in the - empty bit positions on the left, while `lsh' puts zeros in those - bit positions. + - 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. - Thus, with `ash', shifting the pattern of bits one place to the - right looks like this: + - 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. - (ash -6 -1) => -3 - ;; Decimal -6 becomes decimal -3. - 1111 1111 1111 1111 1111 1111 1010 - => - 1111 1111 1111 1111 1111 1111 1101 + The argument MODE must be an integer. Only the low 9 bits of MODE + are used. - In contrast, shifting the pattern of bits one place to the right - with `lsh' looks like this: + 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. - (lsh -6 -1) => 134217725 - ;; Decimal -6 becomes decimal 134,217,725. - 1111 1111 1111 1111 1111 1111 1010 - => - 0111 1111 1111 1111 1111 1111 1101 + - Function: default-file-modes + This function returns the current default protection value. - Here are other examples: + 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'. - ; 28-bit binary values - - (lsh 5 2) ; 5 = 0000 0000 0000 0000 0000 0000 0101 - => 20 ; = 0000 0000 0000 0000 0000 0001 0100 - (ash 5 2) - => 20 - (lsh -5 2) ; -5 = 1111 1111 1111 1111 1111 1111 1011 - => -20 ; = 1111 1111 1111 1111 1111 1110 1100 - (ash -5 2) - => -20 - (lsh 5 -2) ; 5 = 0000 0000 0000 0000 0000 0000 0101 - => 1 ; = 0000 0000 0000 0000 0000 0000 0001 - (ash 5 -2) - => 1 - (lsh -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011 - => 4194302 ; = 0011 1111 1111 1111 1111 1111 1110 - (ash -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011 - => -2 ; = 1111 1111 1111 1111 1111 1111 1110 - - - Function: logand &rest ints-or-markers - This function returns the "logical and" of the arguments: the Nth - bit is set in the result if, and only if, the Nth bit is set in - all the arguments. ("Set" means that the value of the bit is 1 - rather than 0.) - - For example, using 4-bit binary numbers, the "logical and" of 13 - and 12 is 12: 1101 combined with 1100 produces 1100. In both the - binary numbers, the leftmost two bits are set (i.e., they are - 1's), so the leftmost two bits of the returned value are set. - However, for the rightmost two bits, each is zero in at least one - of the arguments, so the rightmost two bits of the returned value - are 0's. - - Therefore, - - (logand 13 12) - => 12 - - If `logand' is not passed any argument, it returns a value of -1. - This number is an identity element for `logand' because its binary - representation consists entirely of ones. If `logand' is passed - just one argument, it returns that argument. - - ; 28-bit binary values - - (logand 14 13) ; 14 = 0000 0000 0000 0000 0000 0000 1110 - ; 13 = 0000 0000 0000 0000 0000 0000 1101 - => 12 ; 12 = 0000 0000 0000 0000 0000 0000 1100 - - (logand 14 13 4) ; 14 = 0000 0000 0000 0000 0000 0000 1110 - ; 13 = 0000 0000 0000 0000 0000 0000 1101 - ; 4 = 0000 0000 0000 0000 0000 0000 0100 - => 4 ; 4 = 0000 0000 0000 0000 0000 0000 0100 - - (logand) - => -1 ; -1 = 1111 1111 1111 1111 1111 1111 1111 + +File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files - - Function: logior &rest ints-or-markers - This function returns the "inclusive or" of its arguments: the Nth - bit is set in the result if, and only if, the Nth bit is set in at - least one of the arguments. If there are no arguments, the result - is zero, which is an identity element for this operation. If - `logior' is passed just one argument, it returns that argument. +File Names +========== - ; 28-bit binary values - - (logior 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100 - ; 5 = 0000 0000 0000 0000 0000 0000 0101 - => 13 ; 13 = 0000 0000 0000 0000 0000 0000 1101 - - (logior 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100 - ; 5 = 0000 0000 0000 0000 0000 0000 0101 - ; 7 = 0000 0000 0000 0000 0000 0000 0111 - => 15 ; 15 = 0000 0000 0000 0000 0000 0000 1111 - - - Function: logxor &rest ints-or-markers - This function returns the "exclusive or" of its arguments: the Nth - bit is set in the result if, and only if, the Nth bit is set in an - odd number of the arguments. If there are no arguments, the - result is 0, which is an identity element for this operation. If - `logxor' is passed just one argument, it returns that argument. - - ; 28-bit binary values - - (logxor 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100 - ; 5 = 0000 0000 0000 0000 0000 0000 0101 - => 9 ; 9 = 0000 0000 0000 0000 0000 0000 1001 - - (logxor 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100 - ; 5 = 0000 0000 0000 0000 0000 0000 0101 - ; 7 = 0000 0000 0000 0000 0000 0000 0111 - => 14 ; 14 = 0000 0000 0000 0000 0000 0000 1110 +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. - - Function: lognot integer - This function returns the logical complement of its argument: the - Nth bit is one in the result if, and only if, the Nth bit is zero - in INTEGER, and vice-versa. +* Menu: - (lognot 5) - => -6 - ;; 5 = 0000 0000 0000 0000 0000 0000 0101 - ;; becomes - ;; -6 = 1111 1111 1111 1111 1111 1111 1010 +* 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: Math Functions, Next: Random Numbers, Prev: Bitwise Operations, Up: Numbers +File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names -Standard Mathematical Functions -=============================== +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. - These mathematical functions are available if floating point is -supported (which is the normal state of affairs). They allow integers -as well as floating point numbers as arguments. + 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. - - Function: sin number - - Function: cos number - - Function: tan number - These are the ordinary trigonometric functions, with argument - measured in radians. + 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: asin number - The value of `(asin NUMBER)' is a number between -pi/2 and pi/2 - (inclusive) whose sine is NUMBER; if, however, NUMBER is out of - range (outside [-1, 1]), then the result is a NaN. + - 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. - - Function: acos number - The value of `(acos NUMBER)' is a number between 0 and pi - (inclusive) whose cosine is NUMBER; if, however, NUMBER is out of - range (outside [-1, 1]), then the result is a NaN. + (file-name-as-directory "~rms/lewis") + => "~rms/lewis/" - - Function: atan number &optional number2 - The value of `(atan NUMBER)' is a number between -pi/2 and pi/2 - (exclusive) whose tangent is NUMBER. + - 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. - If optional argument NUMBER2 is supplied, the function returns - `atan2(NUMBER,NUMBER2)'. + (directory-file-name "~lewis/") + => "~lewis" - - Function: sinh number - - Function: cosh number - - Function: tanh number - These are the ordinary hyperbolic trigonometric functions. + 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. - - Function: asinh number - - Function: acosh number - - Function: atanh number - These are the inverse hyperbolic trigonometric functions. + If you wish to convert a directory name to its abbreviation, use this +function: - - Function: exp number - This is the exponential function; it returns e to the power - NUMBER. e is a fundamental mathematical constant also called the - base of natural logarithms. + - 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. - - Function: log number &optional base - This function returns the logarithm of NUMBER, with base BASE. If - you don't specify BASE, the base E is used. If NUMBER is - negative, the result is a NaN. + If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for + the user's home directory. - - Function: log10 number - This function returns the logarithm of NUMBER, with base 10. If - NUMBER is negative, the result is a NaN. `(log10 X)' == `(log X - 10)', at least approximately. - - Function: expt x y - This function returns X raised to power Y. If both arguments are - integers and Y is positive, the result is an integer; in this - case, it is truncated to fit the range of possible integer values. + - 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. - - Function: sqrt number - This returns the square root of NUMBER. If NUMBER is negative, - the value is a NaN. + You can set this variable in `site-init.el' to describe the + abbreviations appropriate for your site. - - Function: cube-root number - This returns the cube root of NUMBER. + 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: Random Numbers, Prev: Math Functions, Up: Numbers +File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names -Random Numbers -============== +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. - A deterministic computer program cannot generate true random numbers. -For most purposes, "pseudo-random numbers" suffice. A series of -pseudo-random numbers is generated in a deterministic fashion. The -numbers are not truly random, but they have certain properties that -mimic a random series. For example, all possible values occur equally -often in a pseudo-random series. + - 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 `/'. - In XEmacs, pseudo-random numbers are generated from a "seed" number. -Starting from any given seed, the `random' function always generates -the same sequence of numbers. XEmacs always starts with the same seed -value, so the sequence of values of `random' is actually the same in -each XEmacs run! For example, in one operating system, the first call -to `(random)' after you start XEmacs always returns -1457731, and the -second one always returns -7692030. This repeatability is helpful for -debugging. + Note that the `temp-directory' function does not exist under FSF + Emacs. - If you want truly unpredictable random numbers, execute `(random -t)'. This chooses a new seed based on the current time of day and on -XEmacs's process ID number. + - 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. - - Function: random &optional limit - This function returns a pseudo-random integer. Repeated calls - return a series of pseudo-random integers. + (make-temp-name "/tmp/foo") + => "/tmp/fooGaAQjC" - If LIMIT is a positive integer, the value is chosen to be - nonnegative and less than LIMIT. + 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. - If LIMIT is `t', it means to choose a new seed based on the - current time of day and on XEmacs's process ID number. + To avoid confusion, each Lisp application should preferably use a + unique PREFIX to `make-temp-name'. - On some machines, any integer representable in Lisp may be the - result of `random'. On other machines, the result can never be - larger than a certain maximum or less than a certain (negative) - minimum. + +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: Strings and Characters, Next: Lists, Prev: Numbers, Up: Top +File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names -Strings and Characters -********************** +User Name Completion +-------------------- - A string in XEmacs Lisp is an array that contains an ordered sequence -of characters. Strings are used as names of symbols, buffers, and -files, to send messages to users, to hold text being copied between -buffers, and for many other purposes. Because strings are so important, -XEmacs Lisp has many functions expressly for manipulating them. XEmacs -Lisp programs use strings more often than individual characters. +This section describes low-level subroutines for completing a user +name. For other completion functions, see *Note Completion::. -* Menu: + - 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. -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Predicates for Characters:: Testing whether an object is a character. -* Character Codes:: Each character has an equivalent integer. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting characters or strings and vice versa. -* Modifying Strings:: Changing characters in a string. -* String Properties:: Additional information attached to strings. -* Formatting Strings:: `format': XEmacs's analog of `printf'. -* Character Case:: Case conversion functions. -* Case Tables:: Customizing case conversion. -* Char Tables:: Mapping from characters to Lisp objects. + - 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'.