1 This is ../info/lispref.info, produced by makeinfo version 4.8 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
55 35.8.7 User Name Completion
56 ---------------------------
58 This section describes low-level subroutines for completing a user
59 name. For other completion functions, see *Note Completion::.
61 -- Function: user-name-all-completions partial-username
62 This function returns a list of all possible completions for a
63 user name starting with PARTIAL-USERNAME. The order of the
64 completions is unpredictable and conveys no useful information.
66 The argument PARTIAL-USERNAME must be a partial user name
67 containing no tilde character and no slash.
69 -- Function: user-name-completion partial-username
70 This function completes a user name from PARTIAL-USERNAME. It
71 returns the longest prefix common to all user names that start with
74 If only one match exists and PARTIAL-USERNAME matches it exactly,
75 the function returns `t'. The function returns `nil' if no user
76 name starting with PARTIAL-USERNAME exists.
78 -- Function: user-name-completion-1 partial-username
79 This function completes the partial user name PARTIAL-USERNAME,
80 like `user-name-completion', differing only in the return value.
81 This function returns the cons of the completion returned by
82 `user-name-completion', and a boolean indicating whether that
83 completion was unique.
86 File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
88 35.9 Contents of Directories
89 ============================
91 A directory is a kind of file that contains other files entered under
92 various names. Directories are a feature of the file system.
94 XEmacs can list the names of the files in a directory as a Lisp list,
95 or display the names in a buffer using the `ls' shell command. In the
96 latter case, it can optionally display information about each file,
97 depending on the value of switches passed to the `ls' command.
99 -- Function: directory-files directory &optional full-name
100 match-regexp nosort files-only
101 This function returns a list of the names of the files in the
102 directory DIRECTORY. By default, the list is in alphabetical
105 If FULL-NAME is non-`nil', the function returns the files'
106 absolute file names. Otherwise, it returns just the names
107 relative to the specified directory.
109 If MATCH-REGEXP is non-`nil', this function returns only those
110 file names that contain that regular expression--the other file
111 names are discarded from the list.
113 If NOSORT is non-`nil', `directory-files' does not sort the list,
114 so you get the file names in no particular order. Use this if you
115 want the utmost possible speed and don't care what order the files
116 are processed in. If the order of processing is visible to the
117 user, then the user will probably be happier if you do sort the
120 If FILES-ONLY is the symbol `t', then only the "files" in the
121 directory will be returned; subdirectories will be excluded. If
122 FILES-ONLY is not `nil' and not `t', then only the subdirectories
123 will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
124 then both files and subdirectories will be returned.
126 (directory-files "~lewis")
127 => ("#foo#" "#foo.el#" "." ".."
128 "dired-mods.el" "files.texi"
131 An error is signaled if DIRECTORY is not the name of a directory
134 -- Function: insert-directory file switches &optional wildcard
136 This function inserts (in the current buffer) a directory listing
137 for directory FILE, formatted with `ls' according to SWITCHES. It
138 leaves point after the inserted text.
140 The argument FILE may be either a directory name or a file
141 specification including wildcard characters. If WILDCARD is
142 non-`nil', that means treat FILE as a file specification with
145 If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
146 and switches do not contain `-d', so that the listing should show
147 the full contents of the directory. (The `-d' option to `ls' says
148 to describe a directory itself rather than its contents.)
150 This function works by running a directory listing program whose
151 name is in the variable `insert-directory-program'. If WILDCARD is
152 non-`nil', it also runs the shell specified by `shell-file-name',
153 to expand the wildcards.
155 -- Variable: insert-directory-program
156 This variable's value is the program to run to generate a
157 directory listing for the function `insert-directory'.
160 File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
162 35.10 Creating and Deleting Directories
163 =======================================
165 Most XEmacs Lisp file-manipulation functions get errors when used on
166 files that are directories. For example, you cannot delete a directory
167 with `delete-file'. These special functions exist to create and delete
170 -- Command: make-directory dirname &optional parents
171 This function creates a directory named DIRNAME. Interactively,
172 the default choice of directory to create is the current default
173 directory for file names. That is useful when you have visited a
174 file in a nonexistent directory.
176 Non-interactively, optional argument PARENTS says whether to
177 create parent directories if they don't exist. (Interactively, this
180 -- Command: delete-directory dirname
181 This function deletes the directory named DIRNAME. The function
182 `delete-file' does not work for files that are directories; you
183 must use `delete-directory' in that case.
186 File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
188 35.11 Making Certain File Names "Magic"
189 =======================================
191 You can implement special handling for certain file names. This is
192 called making those names "magic". You must supply a regular
193 expression to define the class of names (all those that match the
194 regular expression), plus a handler that implements all the primitive
195 XEmacs file operations for file names that do match.
197 The variable `file-name-handler-alist' holds a list of handlers,
198 together with regular expressions that determine when to apply each
199 handler. Each element has this form:
203 All the XEmacs primitives for file access and file name transformation
204 check the given file name against `file-name-handler-alist'. If the
205 file name matches REGEXP, the primitives handle that file by calling
208 The first argument given to HANDLER is the name of the primitive;
209 the remaining arguments are the arguments that were passed to that
210 operation. (The first of these arguments is typically the file name
211 itself.) For example, if you do this:
213 (file-exists-p FILENAME)
215 and FILENAME has handler HANDLER, then HANDLER is called like this:
217 (funcall HANDLER 'file-exists-p FILENAME)
219 Here are the operations that a magic file name handler gets to
222 `add-name-to-file', `copy-file', `delete-directory', `delete-file',
223 `diff-latest-backup-file', `directory-file-name', `directory-files',
224 `dired-compress-file', `dired-uncache', `expand-file-name',
225 `file-accessible-directory-p', `file-attributes', `file-directory-p',
226 `file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
227 `file-name-all-completions', `file-name-as-directory',
228 `file-name-completion', `file-name-directory', `file-name-nondirectory',
229 `file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
230 `file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
231 `get-file-buffer', `insert-directory', `insert-file-contents', `load',
232 `make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
233 `set-visited-file-modtime', `unhandled-file-name-directory',
234 `verify-visited-file-modtime', `write-region'.
236 Handlers for `insert-file-contents' typically need to clear the
237 buffer's modified flag, with `(set-buffer-modified-p nil)', if the
238 VISIT argument is non-`nil'. This also has the effect of unlocking the
239 buffer if it is locked.
241 The handler function must handle all of the above operations, and
242 possibly others to be added in the future. It need not implement all
243 these operations itself--when it has nothing special to do for a
244 certain operation, it can reinvoke the primitive, to handle the
245 operation "in the usual way". It should always reinvoke the primitive
246 for an operation it does not recognize. Here's one way to do this:
248 (defun my-file-handler (operation &rest args)
249 ;; First check for the specific operations
250 ;; that we have special handling for.
251 (cond ((eq operation 'insert-file-contents) ...)
252 ((eq operation 'write-region) ...)
254 ;; Handle any operation we don't know about.
255 (t (let ((inhibit-file-name-handlers
256 (cons 'my-file-handler
257 (and (eq inhibit-file-name-operation operation)
258 inhibit-file-name-handlers)))
259 (inhibit-file-name-operation operation))
260 (apply operation args)))))
262 When a handler function decides to call the ordinary Emacs primitive
263 for the operation at hand, it needs to prevent the primitive from
264 calling the same handler once again, thus leading to an infinite
265 recursion. The example above shows how to do this, with the variables
266 `inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
267 careful to use them exactly as shown above; the details are crucial for
268 proper behavior in the case of multiple handlers, and for operations
269 that have two file names that may each have handlers.
271 -- Variable: inhibit-file-name-handlers
272 This variable holds a list of handlers whose use is presently
273 inhibited for a certain operation.
275 -- Variable: inhibit-file-name-operation
276 The operation for which certain handlers are presently inhibited.
278 -- Function: find-file-name-handler filename &optional operation
279 This function returns the handler function for file name FILENAME,
280 or `nil' if there is none. The argument OPERATION should be the
281 operation to be performed on the file--the value you will pass to
282 the handler as its first argument when you call it. The operation
283 is needed for comparison with `inhibit-file-name-operation'.
285 -- Function: file-local-copy filename
286 This function copies file FILENAME to an ordinary non-magic file,
287 if it isn't one already.
289 If FILENAME specifies a "magic" file name, which programs outside
290 Emacs cannot directly read or write, this copies the contents to
291 an ordinary file and returns that file's name.
293 If FILENAME is an ordinary file name, not magic, then this function
294 does nothing and returns `nil'.
296 -- Function: unhandled-file-name-directory filename
297 This function returns the name of a directory that is not magic.
298 It uses the directory part of FILENAME if that is not magic.
299 Otherwise, it asks the handler what to do.
301 This is useful for running a subprocess; every subprocess must
302 have a non-magic directory to serve as its current directory, and
303 this function is a good way to come up with one.
306 File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
313 * Intro to Partial Files::
314 * Creating a Partial File::
315 * Detached Partial Files::
318 File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
320 35.12.1 Intro to Partial Files
321 ------------------------------
323 A "partial file" is a section of a buffer (called the "master buffer")
324 that is placed in its own buffer and treated as its own file. Changes
325 made to the partial file are not reflected in the master buffer until
326 the partial file is "saved" using the standard buffer save commands.
327 Partial files can be "reverted" (from the master buffer) just like
328 normal files. When a file part is active on a master buffer, that
329 section of the master buffer is marked as read-only. Two file parts on
330 the same master buffer are not allowed to overlap. Partial file
331 buffers are indicated by the words `File Part' in the modeline.
333 The master buffer knows about all the partial files that are active
334 on it, and thus killing or reverting the master buffer will be handled
335 properly. When the master buffer is saved, if there are any unsaved
336 partial files active on it then the user will be given the opportunity
337 to first save these files.
339 When a partial file buffer is first modified, the master buffer is
340 automatically marked as modified so that saving the master buffer will
344 File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
346 35.12.2 Creating a Partial File
347 -------------------------------
349 -- Command: make-file-part &optional start end name buffer
350 Make a file part on buffer BUFFER out of the region. Call it
351 NAME. This command creates a new buffer containing the contents
352 of the region and marks the buffer as referring to the specified
353 buffer, called the "master buffer". When the file-part buffer is
354 saved, its changes are integrated back into the master buffer.
355 When the master buffer is deleted, all file parts are deleted with
358 When called from a function, expects four arguments, START, END,
359 NAME, and BUFFER, all of which are optional and default to the
360 beginning of BUFFER, the end of BUFFER, a name generated from
361 BUFFER's name, and the current buffer, respectively.
364 File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
366 35.12.3 Detached Partial Files
367 ------------------------------
369 Every partial file has an extent in the master buffer associated with it
370 (called the "master extent"), marking where in the master buffer the
371 partial file begins and ends. If the text in master buffer that is
372 contained by the extent is deleted, then the extent becomes "detached",
373 meaning that it no longer refers to a specific region of the master
374 buffer. This can happen either when the text is deleted directly or
375 when the master buffer is reverted. Neither of these should happen in
376 normal usage because the master buffer should generally not be edited
379 Before doing any operation that references a partial file's master
380 extent, XEmacs checks to make sure that the extent is not detached. If
381 this is the case, XEmacs warns the user of this and the master extent is
382 deleted out of the master buffer, disconnecting the file part. The file
383 part's filename is cleared and thus must be explicitly specified if the
384 detached file part is to be saved.
387 File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
389 35.13 File Format Conversion
390 ============================
392 The variable `format-alist' defines a list of "file formats", which
393 describe textual representations used in files for the data (text,
394 text-properties, and possibly other information) in an Emacs buffer.
395 Emacs performs format conversion if appropriate when reading and writing
398 -- Variable: format-alist
399 This list contains one format definition for each defined file
402 Each format definition is a list of this form:
404 (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
406 Here is what the elements in a format definition mean:
409 The name of this format.
412 A documentation string for the format.
415 A regular expression which is used to recognize files represented
419 A function to call to decode data in this format (to convert file
420 data into the usual Emacs data representation).
422 The FROM-FN is called with two args, BEGIN and END, which specify
423 the part of the buffer it should convert. It should convert the
424 text by editing it in place. Since this can change the length of
425 the text, FROM-FN should return the modified end position.
427 One responsibility of FROM-FN is to make sure that the beginning
428 of the file no longer matches REGEXP. Otherwise it is likely to
432 A function to call to encode data in this format (to convert the
433 usual Emacs data representation into this format).
435 The TO-FN is called with two args, BEGIN and END, which specify
436 the part of the buffer it should convert. There are two ways it
437 can do the conversion:
439 * By editing the buffer in place. In this case, TO-FN should
440 return the end-position of the range of text, as modified.
442 * By returning a list of annotations. This is a list of
443 elements of the form `(POSITION . STRING)', where POSITION is
444 an integer specifying the relative position in the text to be
445 written, and STRING is the annotation to add there. The list
446 must be sorted in order of position when TO-FN returns it.
448 When `write-region' actually writes the text from the buffer
449 to the file, it intermixes the specified annotations at the
450 corresponding positions. All this takes place without
451 modifying the buffer.
454 A flag, `t' if the encoding function modifies the buffer, and
455 `nil' if it works by returning a list of annotations.
458 A mode function to call after visiting a file converted from this
461 The function `insert-file-contents' automatically recognizes file
462 formats when it reads the specified file. It checks the text of the
463 beginning of the file against the regular expressions of the format
464 definitions, and if it finds a match, it calls the decoding function for
465 that format. Then it checks all the known formats over again. It
466 keeps checking them until none of them is applicable.
468 Visiting a file, with `find-file-noselect' or the commands that use
469 it, performs conversion likewise (because it calls
470 `insert-file-contents'); it also calls the mode function for each
471 format that it decodes. It stores a list of the format names in the
472 buffer-local variable `buffer-file-format'.
474 -- Variable: buffer-file-format
475 This variable states the format of the visited file. More
476 precisely, this is a list of the file format names that were
477 decoded in the course of visiting the current buffer's file. It
478 is always local in all buffers.
480 When `write-region' writes data into a file, it first calls the
481 encoding functions for the formats listed in `buffer-file-format', in
482 the order of appearance in the list.
484 -- Command: format-write-file file format
485 This command writes the current buffer contents into the file FILE
486 in format FORMAT, and makes that format the default for future
487 saves of the buffer. The argument FORMAT is a list of format
490 -- Command: format-find-file file format
491 This command finds the file FILE, converting it according to
492 format FORMAT. It also makes FORMAT the default if the buffer is
495 The argument FORMAT is a list of format names. If FORMAT is
496 `nil', no conversion takes place. Interactively, typing just
497 <RET> for FORMAT specifies `nil'.
499 -- Command: format-insert-file file format &optional start end
500 This command inserts the contents of file FILE, converting it
501 according to format FORMAT. If START and END are non-`nil', they
502 specify which part of the file to read, as in
503 `insert-file-contents' (*note Reading from Files::).
505 The return value is like what `insert-file-contents' returns: a
506 list of the absolute file name and the length of the data inserted
509 The argument FORMAT is a list of format names. If FORMAT is
510 `nil', no conversion takes place. Interactively, typing just
511 <RET> for FORMAT specifies `nil'.
513 -- Variable: auto-save-file-format
514 This variable specifies the format to use for auto-saving. Its
515 value is a list of format names, just like the value of
516 `buffer-file-format'; but it is used instead of
517 `buffer-file-format' for writing auto-save files. This variable
518 is always local in all buffers.
521 File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
523 35.14 Files and MS-DOS
524 ======================
526 Emacs on MS-DOS makes a distinction between text files and binary
527 files. This is necessary because ordinary text files on MS-DOS use a
528 two character sequence between lines: carriage-return and linefeed
529 (CRLF). Emacs expects just a newline character (a linefeed) between
530 lines. When Emacs reads or writes a text file on MS-DOS, it needs to
531 convert the line separators. This means it needs to know which files
532 are text files and which are binary. It makes this decision when
533 visiting a file, and records the decision in the variable
534 `buffer-file-type' for use when the file is saved.
536 *Note MS-DOS Subprocesses::, for a related feature for subprocesses.
538 -- Variable: buffer-file-type
539 This variable, automatically local in each buffer, records the
540 file type of the buffer's visited file. The value is `nil' for
541 text, `t' for binary.
543 -- Function: find-buffer-file-type filename
544 This function determines whether file FILENAME is a text file or a
545 binary file. It returns `nil' for text, `t' for binary.
547 -- User Option: file-name-buffer-file-type-alist
548 This variable holds an alist for distinguishing text files from
549 binary files. Each element has the form (REGEXP . TYPE), where
550 REGEXP is matched against the file name, and TYPE may be is `nil'
551 for text, `t' for binary, or a function to call to compute which.
552 If it is a function, then it is called with a single argument (the
553 file name) and should return `t' or `nil'.
555 -- User Option: default-buffer-file-type
556 This variable specifies the default file type for files whose names
557 don't indicate anything in particular. Its value should be `nil'
558 for text, or `t' for binary.
560 -- Command: find-file-text filename
561 Like `find-file', but treat the file as text regardless of its
564 -- Command: find-file-binary filename
565 Like `find-file', but treat the file as binary regardless of its
569 File: lispref.info, Node: Backups and Auto-Saving, Next: Buffers, Prev: Files, Up: Top
571 36 Backups and Auto-Saving
572 **************************
574 Backup files and auto-save files are two methods by which XEmacs tries
575 to protect the user from the consequences of crashes or of the user's
576 own errors. Auto-saving preserves the text from earlier in the current
577 editing session; backup files preserve file contents prior to the
582 * Backup Files:: How backup files are made; how their names are chosen.
583 * Auto-Saving:: How auto-save files are made; how their names are chosen.
584 * Reverting:: `revert-buffer', and how to customize what it does.
587 File: lispref.info, Node: Backup Files, Next: Auto-Saving, Up: Backups and Auto-Saving
592 A "backup file" is a copy of the old contents of a file you are
593 editing. XEmacs makes a backup file the first time you save a buffer
594 into its visited file. Normally, this means that the backup file
595 contains the contents of the file as it was before the current editing
596 session. The contents of the backup file normally remain unchanged once
599 Backups are usually made by renaming the visited file to a new name.
600 Optionally, you can specify that backup files should be made by copying
601 the visited file. This choice makes a difference for files with
602 multiple names; it also can affect whether the edited file remains owned
603 by the original owner or becomes owned by the user editing it.
605 By default, XEmacs makes a single backup file for each file edited.
606 You can alternatively request numbered backups; then each new backup
607 file gets a new name. You can delete old numbered backups when you
608 don't want them any more, or XEmacs can delete them automatically.
612 * Making Backups:: How XEmacs makes backup files, and when.
613 * Rename or Copy:: Two alternatives: renaming the old file or copying it.
614 * Numbered Backups:: Keeping multiple backups for each source file.
615 * Backup Names:: How backup file names are computed; customization.
618 File: lispref.info, Node: Making Backups, Next: Rename or Copy, Up: Backup Files
620 36.1.1 Making Backup Files
621 --------------------------
623 -- Function: backup-buffer
624 This function makes a backup of the file visited by the current
625 buffer, if appropriate. It is called by `save-buffer' before
626 saving the buffer the first time.
628 -- Variable: buffer-backed-up
629 This buffer-local variable indicates whether this buffer's file has
630 been backed up on account of this buffer. If it is non-`nil', then
631 the backup file has been written. Otherwise, the file should be
632 backed up when it is next saved (if backups are enabled). This is
633 a permanent local; `kill-local-variables' does not alter it.
635 -- User Option: make-backup-files
636 This variable determines whether or not to make backup files. If
637 it is non-`nil', then XEmacs creates a backup of each file when it
638 is saved for the first time--provided that `backup-inhibited' is
641 The following example shows how to change the `make-backup-files'
642 variable only in the `RMAIL' buffer and not elsewhere. Setting it
643 `nil' stops XEmacs from making backups of the `RMAIL' file, which
644 may save disk space. (You would put this code in your `.emacs'
647 (add-hook 'rmail-mode-hook
651 (setq make-backup-files nil))))
653 -- Variable: backup-enable-predicate
654 This variable's value is a function to be called on certain
655 occasions to decide whether a file should have backup files. The
656 function receives one argument, a file name to consider. If the
657 function returns `nil', backups are disabled for that file.
658 Otherwise, the other variables in this section say whether and how
661 The default value is this:
664 (or (< (length name) 5)
665 (not (string-equal "/tmp/"
666 (substring name 0 5)))))
668 -- Variable: backup-inhibited
669 If this variable is non-`nil', backups are inhibited. It records
670 the result of testing `backup-enable-predicate' on the visited file
671 name. It can also coherently be used by other mechanisms that
672 inhibit backups based on which file is visited. For example, VC
673 sets this variable non-`nil' to prevent making backups for files
674 managed with a version control system.
676 This is a permanent local, so that changing the major mode does
677 not lose its value. Major modes should not set this
678 variable--they should set `make-backup-files' instead.
681 File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files
683 36.1.2 Backup by Renaming or by Copying?
684 ----------------------------------------
686 There are two ways that XEmacs can make a backup file:
688 * XEmacs can rename the original file so that it becomes a backup
689 file, and then write the buffer being saved into a new file.
690 After this procedure, any other names (i.e., hard links) of the
691 original file now refer to the backup file. The new file is owned
692 by the user doing the editing, and its group is the default for
693 new files written by the user in that directory.
695 * XEmacs can copy the original file into a backup file, and then
696 overwrite the original file with new contents. After this
697 procedure, any other names (i.e., hard links) of the original file
698 still refer to the current version of the file. The file's owner
699 and group will be unchanged.
701 The first method, renaming, is the default.
703 The variable `backup-by-copying', if non-`nil', says to use the
704 second method, which is to copy the original file and overwrite it with
705 the new buffer contents. The variable `file-precious-flag', if
706 non-`nil', also has this effect (as a sideline of its main
707 significance). *Note Saving Buffers::.
709 -- Variable: backup-by-copying
710 If this variable is non-`nil', XEmacs always makes backup files by
713 The following two variables, when non-`nil', cause the second method
714 to be used in certain special cases. They have no effect on the
715 treatment of files that don't fall into the special cases.
717 -- Variable: backup-by-copying-when-linked
718 If this variable is non-`nil', XEmacs makes backups by copying for
719 files with multiple names (hard links).
721 This variable is significant only if `backup-by-copying' is `nil',
722 since copying is always used when that variable is non-`nil'.
724 -- Variable: backup-by-copying-when-mismatch
725 If this variable is non-`nil', XEmacs makes backups by copying in
726 cases where renaming would change either the owner or the group of
729 The value has no effect when renaming would not alter the owner or
730 group of the file; that is, for files which are owned by the user
731 and whose group matches the default for a new file created there
734 This variable is significant only if `backup-by-copying' is `nil',
735 since copying is always used when that variable is non-`nil'.
738 File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
740 36.1.3 Making and Deleting Numbered Backup Files
741 ------------------------------------------------
743 If a file's name is `foo', the names of its numbered backup versions
744 are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
745 `foo.~3~', ..., `foo.~259~', and so on.
747 -- User Option: version-control
748 This variable controls whether to make a single non-numbered backup
749 file or multiple numbered backups.
752 Make numbered backups if the visited file already has
753 numbered backups; otherwise, do not.
756 Do not make numbered backups.
759 Make numbered backups.
761 The use of numbered backups ultimately leads to a large number of
762 backup versions, which must then be deleted. XEmacs can do this
763 automatically or it can ask the user whether to delete them.
765 -- User Option: kept-new-versions
766 The value of this variable is the number of newest versions to keep
767 when a new numbered backup is made. The newly made backup is
768 included in the count. The default value is 2.
770 -- User Option: kept-old-versions
771 The value of this variable is the number of oldest versions to keep
772 when a new numbered backup is made. The default value is 2.
774 If there are backups numbered 1, 2, 3, 5, and 7, and both of these
775 variables have the value 2, then the backups numbered 1 and 2 are kept
776 as old versions and those numbered 5 and 7 are kept as new versions;
777 backup version 3 is excess. The function `find-backup-file-name'
778 (*note Backup Names::) is responsible for determining which backup
779 versions to delete, but does not delete them itself.
781 -- User Option: delete-old-versions
782 If this variable is non-`nil', then saving a file deletes excess
783 backup versions silently. Otherwise, it asks the user whether to
786 -- User Option: dired-kept-versions
787 This variable specifies how many of the newest backup versions to
788 keep in the Dired command `.' (`dired-clean-directory'). That's
789 the same thing `kept-new-versions' specifies when you make a new
790 backup file. The default value is 2.
793 File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files
795 36.1.4 Naming Backup Files
796 --------------------------
798 The functions in this section are documented mainly because you can
799 customize the naming conventions for backup files by redefining them.
800 If you change one, you probably need to change the rest.
802 -- Function: backup-file-name-p filename
803 This function returns a non-`nil' value if FILENAME is a possible
804 name for a backup file. A file with the name FILENAME need not
805 exist; the function just checks the name.
807 (backup-file-name-p "foo")
809 (backup-file-name-p "foo~")
812 The standard definition of this function is as follows:
814 (defun backup-file-name-p (file)
815 "Return non-nil if FILE is a backup file \
816 name (numeric or not)..."
817 (string-match "~$" file))
819 Thus, the function returns a non-`nil' value if the file name ends
820 with a `~'. (We use a backslash to split the documentation
821 string's first line into two lines in the text, but produce just
822 one line in the string itself.)
824 This simple expression is placed in a separate function to make it
825 easy to redefine for customization.
827 -- Function: make-backup-file-name filename
828 This function returns a string that is the name to use for a
829 non-numbered backup file for file FILENAME. On Unix, this is just
830 FILENAME with a tilde appended.
832 The standard definition of this function is as follows:
834 (defun make-backup-file-name (file)
835 "Create the non-numeric backup file name for FILE.
839 You can change the backup-file naming convention by redefining this
840 function. The following example redefines `make-backup-file-name'
841 to prepend a `.' in addition to appending a tilde:
843 (defun make-backup-file-name (filename)
844 (concat "." filename "~"))
846 (make-backup-file-name "backups.texi")
849 -- Function: find-backup-file-name filename
850 This function computes the file name for a new backup file for
851 FILENAME. It may also propose certain existing backup files for
852 deletion. `find-backup-file-name' returns a list whose CAR is the
853 name for the new backup file and whose CDR is a list of backup
854 files whose deletion is proposed.
856 Two variables, `kept-old-versions' and `kept-new-versions',
857 determine which backup versions should be kept. This function
858 keeps those versions by excluding them from the CDR of the value.
859 *Note Numbered Backups::.
861 In this example, the value says that `~rms/foo.~5~' is the name to
862 use for the new backup file, and `~rms/foo.~3~' is an "excess"
863 version that the caller should consider deleting now.
865 (find-backup-file-name "~rms/foo")
866 => ("~rms/foo.~5~" "~rms/foo.~3~")
868 -- Function: file-newest-backup filename
869 This function returns the name of the most recent backup file for
870 FILENAME, or `nil' if that file has no backup files.
872 Some file comparison commands use this function so that they can
873 automatically compare a file with its most recent backup.
876 File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving
881 XEmacs periodically saves all files that you are visiting; this is
882 called "auto-saving". Auto-saving prevents you from losing more than a
883 limited amount of work if the system crashes. By default, auto-saves
884 happen every 300 keystrokes, or after around 30 seconds of idle time.
885 *Note Auto-Save: (xemacs)Auto Save, for information on auto-save for
886 users. Here we describe the functions used to implement auto-saving
887 and the variables that control them.
889 -- Variable: buffer-auto-save-file-name
890 This buffer-local variable is the name of the file used for
891 auto-saving the current buffer. It is `nil' if the buffer should
894 buffer-auto-save-file-name
895 => "/xcssun/users/rms/lewis/#files.texi#"
897 -- Command: auto-save-mode arg
898 When used interactively without an argument, this command is a
899 toggle switch: it turns on auto-saving of the current buffer if it
900 is off, and vice-versa. With an argument ARG, the command turns
901 auto-saving on if the value of ARG is `t', a nonempty list, or a
902 positive integer. Otherwise, it turns auto-saving off.
904 -- Function: auto-save-file-name-p filename
905 This function returns a non-`nil' value if FILENAME is a string
906 that could be the name of an auto-save file. It works based on
907 knowledge of the naming convention for auto-save files: a name that
908 begins and ends with hash marks (`#') is a possible auto-save file
909 name. The argument FILENAME should not contain a directory part.
911 (make-auto-save-file-name)
912 => "/xcssun/users/rms/lewis/#files.texi#"
913 (auto-save-file-name-p "#files.texi#")
915 (auto-save-file-name-p "files.texi")
918 The standard definition of this function is as follows:
920 (defun auto-save-file-name-p (filename)
921 "Return non-nil if FILENAME can be yielded by..."
922 (string-match "^#.*#$" filename))
924 This function exists so that you can customize it if you wish to
925 change the naming convention for auto-save files. If you redefine
926 it, be sure to redefine the function `make-auto-save-file-name'
929 -- Function: make-auto-save-file-name &optional filename
930 This function returns the file name to use for auto-saving the
931 current buffer. This is just the file name with hash marks (`#')
932 appended and prepended to it. This function does not look at the
933 variable `auto-save-visited-file-name' (described below); you
934 should check that before calling this function.
936 (make-auto-save-file-name)
937 => "/xcssun/users/rms/lewis/#backup.texi#"
939 The standard definition of this function is as follows:
941 (defun make-auto-save-file-name ()
942 "Return file name to use for auto-saves \
947 (file-name-directory buffer-file-name)
949 (file-name-nondirectory buffer-file-name)
952 (concat "#%" (buffer-name) "#"))))
954 This exists as a separate function so that you can redefine it to
955 customize the naming convention for auto-save files. Be sure to
956 change `auto-save-file-name-p' in a corresponding way.
958 -- Variable: auto-save-visited-file-name
959 If this variable is non-`nil', XEmacs auto-saves buffers in the
960 files they are visiting. That is, the auto-save is done in the
961 same file that you are editing. Normally, this variable is `nil',
962 so auto-save files have distinct names that are created by
963 `make-auto-save-file-name'.
965 When you change the value of this variable, the value does not take
966 effect until the next time auto-save mode is reenabled in any given
967 buffer. If auto-save mode is already enabled, auto-saves continue
968 to go in the same file name until `auto-save-mode' is called again.
970 -- Function: recent-auto-save-p
971 This function returns `t' if the current buffer has been
972 auto-saved since the last time it was read in or saved.
974 -- Function: set-buffer-auto-saved
975 This function marks the current buffer as auto-saved. The buffer
976 will not be auto-saved again until the buffer text is changed
977 again. The function returns `nil'.
979 -- User Option: auto-save-interval
980 The value of this variable is the number of characters that XEmacs
981 reads from the keyboard between auto-saves. Each time this many
982 more characters are read, auto-saving is done for all buffers in
985 -- User Option: auto-save-timeout
986 The value of this variable is the number of seconds of idle time
987 that should cause auto-saving. Each time the user pauses for this
988 long, XEmacs auto-saves any buffers that need it. (Actually, the
989 specified timeout is multiplied by a factor depending on the size
990 of the current buffer.)
992 -- Variable: auto-save-hook
993 This normal hook is run whenever an auto-save is about to happen.
995 -- User Option: auto-save-default
996 If this variable is non-`nil', buffers that are visiting files
997 have auto-saving enabled by default. Otherwise, they do not.
999 -- Command: do-auto-save &optional no-message current-only
1000 This function auto-saves all buffers that need to be auto-saved.
1001 It saves all buffers for which auto-saving is enabled and that
1002 have been changed since the previous auto-save.
1004 Normally, if any buffers are auto-saved, a message that says
1005 `Auto-saving...' is displayed in the echo area while auto-saving is
1006 going on. However, if NO-MESSAGE is non-`nil', the message is
1009 If CURRENT-ONLY is non-`nil', only the current buffer is
1012 -- Function: delete-auto-save-file-if-necessary
1013 This function deletes the current buffer's auto-save file if
1014 `delete-auto-save-files' is non-`nil'. It is called every time a
1017 -- Variable: delete-auto-save-files
1018 This variable is used by the function
1019 `delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs
1020 deletes auto-save files when a true save is done (in the visited
1021 file). This saves disk space and unclutters your directory.
1023 -- Function: rename-auto-save-file
1024 This function adjusts the current buffer's auto-save file name if
1025 the visited file name has changed. It also renames an existing
1026 auto-save file. If the visited file name has not changed, this
1027 function does nothing.
1029 -- Variable: buffer-saved-size
1030 The value of this buffer-local variable is the length of the
1031 current buffer as of the last time it was read in, saved, or
1032 auto-saved. This is used to detect a substantial decrease in
1033 size, and turn off auto-saving in response.
1035 If it is -1, that means auto-saving is temporarily shut off in this
1036 buffer due to a substantial deletion. Explicitly saving the buffer
1037 stores a positive value in this variable, thus reenabling
1038 auto-saving. Turning auto-save mode off or on also alters this
1041 -- Variable: auto-save-list-file-name
1042 This variable (if non-`nil') specifies a file for recording the
1043 names of all the auto-save files. Each time XEmacs does
1044 auto-saving, it writes two lines into this file for each buffer
1045 that has auto-saving enabled. The first line gives the name of
1046 the visited file (it's empty if the buffer has none), and the
1047 second gives the name of the auto-save file.
1049 If XEmacs exits normally, it deletes this file. If XEmacs
1050 crashes, you can look in the file to find all the auto-save files
1051 that might contain work that was otherwise lost. The
1052 `recover-session' command uses these files.
1054 The default name for this file is in your home directory and
1055 starts with `.saves-'. It also contains the XEmacs process ID and
1059 File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving
1064 If you have made extensive changes to a file and then change your mind
1065 about them, you can get rid of them by reading in the previous version
1066 of the file with the `revert-buffer' command. *Note Reverting a
1067 Buffer: (xemacs)Reverting.
1069 -- Command: revert-buffer &optional check-auto-save noconfirm
1071 This command replaces the buffer text with the text of the visited
1072 file on disk. This action undoes all changes since the file was
1075 If the argument CHECK-AUTO-SAVE is non-`nil', and the latest
1076 auto-save file is more recent than the visited file,
1077 `revert-buffer' asks the user whether to use that instead.
1078 Otherwise, it always uses the text of the visited file itself.
1079 Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix
1082 Normally, `revert-buffer' asks for confirmation before it changes
1083 the buffer; but if the argument NOCONFIRM is non-`nil',
1084 `revert-buffer' does not ask for confirmation.
1086 Optional third argument PRESERVE-MODES non-`nil' means don't alter
1087 the files modes. Normally we reinitialize them using
1090 Reverting tries to preserve marker positions in the buffer by
1091 using the replacement feature of `insert-file-contents'. If the
1092 buffer contents and the file contents are identical before the
1093 revert operation, reverting preserves all the markers. If they
1094 are not identical, reverting does change the buffer; then it
1095 preserves the markers in the unchanged text (if any) at the
1096 beginning and end of the buffer. Preserving any additional
1097 markers would be problematical.
1099 You can customize how `revert-buffer' does its work by setting these
1100 variables--typically, as buffer-local variables.
1102 -- Variable: revert-buffer-function
1103 The value of this variable is the function to use to revert this
1104 buffer. If non-`nil', it is called as a function with no
1105 arguments to do the work of reverting. If the value is `nil',
1106 reverting works the usual way.
1108 Modes such as Dired mode, in which the text being edited does not
1109 consist of a file's contents but can be regenerated in some other
1110 fashion, give this variable a buffer-local value that is a
1111 function to regenerate the contents.
1113 -- Variable: revert-buffer-insert-file-contents-function
1114 The value of this variable, if non-`nil', is the function to use to
1115 insert the updated contents when reverting this buffer. The
1116 function receives two arguments: first the file name to use;
1117 second, `t' if the user has asked to read the auto-save file.
1119 -- Variable: before-revert-hook
1120 This normal hook is run by `revert-buffer' before actually
1121 inserting the modified contents--but only if
1122 `revert-buffer-function' is `nil'.
1124 Font Lock mode uses this hook to record that the buffer contents
1125 are no longer fontified.
1127 -- Variable: after-revert-hook
1128 This normal hook is run by `revert-buffer' after actually inserting
1129 the modified contents--but only if `revert-buffer-function' is
1132 Font Lock mode uses this hook to recompute the fonts for the
1133 updated buffer contents.
1136 File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top
1141 A "buffer" is a Lisp object containing text to be edited. Buffers are
1142 used to hold the contents of files that are being visited; there may
1143 also be buffers that are not visiting files. While several buffers may
1144 exist at one time, exactly one buffer is designated the "current
1145 buffer" at any time. Most editing commands act on the contents of the
1146 current buffer. Each buffer, including the current buffer, may or may
1147 not be displayed in any window.
1151 * Buffer Basics:: What is a buffer?
1152 * Current Buffer:: Designating a buffer as current
1153 so primitives will access its contents.
1154 * Buffer Names:: Accessing and changing buffer names.
1155 * Buffer File Name:: The buffer file name indicates which file is visited.
1156 * Buffer Modification:: A buffer is "modified" if it needs to be saved.
1157 * Modification Time:: Determining whether the visited file was changed
1158 ``behind XEmacs's back''.
1159 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
1160 * The Buffer List:: How to look at all the existing buffers.
1161 * Creating Buffers:: Functions that create buffers.
1162 * Killing Buffers:: Buffers exist until explicitly killed.
1163 * Indirect Buffers:: An indirect buffer shares text with some other buffer.
1166 File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
1171 A "buffer" is a Lisp object containing text to be edited. Buffers are
1172 used to hold the contents of files that are being visited; there may
1173 also be buffers that are not visiting files. While several buffers may
1174 exist at one time, exactly one buffer is designated the "current
1175 buffer" at any time. Most editing commands act on the contents of the
1176 current buffer. Each buffer, including the current buffer, may or may
1177 not be displayed in any windows.
1179 Buffers in Emacs editing are objects that have distinct names and hold
1180 text that can be edited. Buffers appear to Lisp programs as a special
1181 data type. You can think of the contents of a buffer as an extendible
1182 string; insertions and deletions may occur in any part of the buffer.
1185 A Lisp buffer object contains numerous pieces of information. Some
1186 of this information is directly accessible to the programmer through
1187 variables, while other information is accessible only through
1188 special-purpose functions. For example, the visited file name is
1189 directly accessible through a variable, while the value of point is
1190 accessible only through a primitive function.
1192 Buffer-specific information that is directly accessible is stored in
1193 "buffer-local" variable bindings, which are variable values that are
1194 effective only in a particular buffer. This feature allows each buffer
1195 to override the values of certain variables. Most major modes override
1196 variables such as `fill-column' or `comment-column' in this way. For
1197 more information about buffer-local variables and functions related to
1198 them, see *Note Buffer-Local Variables::.
1200 For functions and variables related to visiting files in buffers, see
1201 *Note Visiting Files:: and *Note Saving Buffers::. For functions and
1202 variables related to the display of buffers in windows, see *Note
1203 Buffers and Windows::.
1205 -- Function: bufferp object
1206 This function returns `t' if OBJECT is a buffer, `nil' otherwise.
1209 File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
1211 37.2 The Current Buffer
1212 =======================
1214 There are, in general, many buffers in an Emacs session. At any time,
1215 one of them is designated as the "current buffer". This is the buffer
1216 in which most editing takes place, because most of the primitives for
1217 examining or changing text in a buffer operate implicitly on the
1218 current buffer (*note Text::). Normally the buffer that is displayed on
1219 the screen in the selected window is the current buffer, but this is not
1220 always so: a Lisp program can designate any buffer as current
1221 temporarily in order to operate on its contents, without changing what
1222 is displayed on the screen.
1224 The way to designate a current buffer in a Lisp program is by calling
1225 `set-buffer'. The specified buffer remains current until a new one is
1228 When an editing command returns to the editor command loop, the
1229 command loop designates the buffer displayed in the selected window as
1230 current, to prevent confusion: the buffer that the cursor is in when
1231 Emacs reads a command is the buffer that the command will apply to.
1232 (*Note Command Loop::.) Therefore, `set-buffer' is not the way to
1233 switch visibly to a different buffer so that the user can edit it. For
1234 this, you must use the functions described in *Note Displaying
1237 However, Lisp functions that change to a different current buffer
1238 should not depend on the command loop to set it back afterwards.
1239 Editing commands written in XEmacs Lisp can be called from other
1240 programs as well as from the command loop. It is convenient for the
1241 caller if the subroutine does not change which buffer is current
1242 (unless, of course, that is the subroutine's purpose). Therefore, you
1243 should normally use `set-buffer' within a `save-excursion' that will
1244 restore the current buffer when your function is done (*note
1245 Excursions::). Here is an example, the code for the command
1246 `append-to-buffer' (with the documentation string abridged):
1248 (defun append-to-buffer (buffer start end)
1249 "Append to specified buffer the text of the region.
1251 (interactive "BAppend to buffer: \nr")
1252 (let ((oldbuf (current-buffer)))
1254 (set-buffer (get-buffer-create buffer))
1255 (insert-buffer-substring oldbuf start end))))
1257 This function binds a local variable to the current buffer, and then
1258 `save-excursion' records the values of point, the mark, and the
1259 original buffer. Next, `set-buffer' makes another buffer current.
1260 Finally, `insert-buffer-substring' copies the string from the original
1261 current buffer to the new current buffer.
1263 If the buffer appended to happens to be displayed in some window,
1264 the next redisplay will show how its text has changed. Otherwise, you
1265 will not see the change immediately on the screen. The buffer becomes
1266 current temporarily during the execution of the command, but this does
1267 not cause it to be displayed.
1269 If you make local bindings (with `let' or function arguments) for a
1270 variable that may also have buffer-local bindings, make sure that the
1271 same buffer is current at the beginning and at the end of the local
1272 binding's scope. Otherwise you might bind it in one buffer and unbind
1273 it in another! There are two ways to do this. In simple cases, you may
1274 see that nothing ever changes the current buffer within the scope of the
1275 binding. Otherwise, use `save-excursion' to make sure that the buffer
1276 current at the beginning is current again whenever the variable is
1279 It is not reliable to change the current buffer back with
1280 `set-buffer', because that won't do the job if a quit happens while the
1281 wrong buffer is current. Here is what _not_ to do:
1283 (let (buffer-read-only
1284 (obuf (current-buffer)))
1289 Using `save-excursion', as shown below, handles quitting, errors, and
1290 `throw', as well as ordinary evaluation.
1292 (let (buffer-read-only)
1297 -- Function: current-buffer
1298 This function returns the current buffer.
1301 => #<buffer buffers.texi>
1303 -- Function: set-buffer buffer-or-name
1304 This function makes BUFFER-OR-NAME the current buffer. It does
1305 not display the buffer in the currently selected window or in any
1306 other window, so the user cannot necessarily see the buffer. But
1307 Lisp programs can in any case work on it.
1309 BUFFER-OR-NAME must be a buffer or the name of an existing
1310 buffer-else an error is signaled. This function returns the buffer
1311 identified by BUFFER-OR-NAME.
1314 File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
1319 Each buffer has a unique name, which is a string. Many of the
1320 functions that work on buffers accept either a buffer or a buffer name
1321 as an argument. Any argument called BUFFER-OR-NAME is of this sort,
1322 and an error is signaled if it is neither a string nor a buffer. Any
1323 argument called BUFFER must be an actual buffer object, not a name.
1325 Buffers that are ephemeral and generally uninteresting to the user
1326 have names starting with a space, so that the `list-buffers' and
1327 `buffer-menu' commands don't mention them. A name starting with space
1328 also initially disables recording undo information; see *Note Undo::.
1330 -- Function: buffer-name &optional buffer
1331 This function returns the name of BUFFER as a string. If BUFFER
1332 is not supplied, it defaults to the current buffer.
1334 If `buffer-name' returns `nil', it means that BUFFER has been
1335 killed. *Note Killing Buffers::.
1340 (setq foo (get-buffer "temp"))
1349 -- Command: rename-buffer newname &optional unique
1350 This function renames the current buffer to NEWNAME. An error is
1351 signaled if NEWNAME is not a string, or if there is already a
1352 buffer with that name. The function returns `nil'.
1354 Ordinarily, `rename-buffer' signals an error if NEWNAME is already
1355 in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
1356 make a name that is not in use. Interactively, you can make
1357 UNIQUE non-`nil' with a numeric prefix argument.
1359 One application of this command is to rename the `*shell*' buffer
1360 to some other name, thus making it possible to create a second
1361 shell buffer under the name `*shell*'.
1363 -- Function: get-buffer buffer-or-name
1364 This function returns the buffer named BUFFER-OR-NAME. If
1365 BUFFER-OR-NAME is a string and there is no buffer with that name,
1366 the value is `nil'. If BUFFER-OR-NAME is actually a buffer, it is
1367 returned as given. (That is not very useful, so the argument is
1368 usually a name.) For example:
1370 (setq b (get-buffer "lewis"))
1374 (get-buffer "Frazzle-nots")
1377 See also the function `get-buffer-create' in *Note Creating
1380 -- Function: generate-new-buffer-name starting-name &optional ignore
1381 This function returns a name that would be unique for a new
1382 buffer--but does not create the buffer. It starts with
1383 STARTING-NAME, and produces a name not currently in use for any
1384 buffer by appending a number inside of `<...>'.
1386 If IGNORE is given, it specifies a name that is okay to use (if it
1387 is in the sequence to be tried), even if a buffer with that name
1390 See the related function `generate-new-buffer' in *Note Creating
1394 File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
1396 37.4 Buffer File Name
1397 =====================
1399 The "buffer file name" is the name of the file that is visited in that
1400 buffer. When a buffer is not visiting a file, its buffer file name is
1401 `nil'. Most of the time, the buffer name is the same as the
1402 nondirectory part of the buffer file name, but the buffer file name and
1403 the buffer name are distinct and can be set independently. *Note
1406 -- Function: buffer-file-name &optional buffer
1407 This function returns the absolute file name of the file that
1408 BUFFER is visiting. If BUFFER is not visiting any file,
1409 `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
1410 defaults to the current buffer.
1412 (buffer-file-name (other-buffer))
1413 => "/usr/user/lewis/manual/files.texi"
1415 -- Variable: buffer-file-name
1416 This buffer-local variable contains the name of the file being
1417 visited in the current buffer, or `nil' if it is not visiting a
1418 file. It is a permanent local, unaffected by
1419 `kill-local-variables'.
1422 => "/usr/user/lewis/manual/buffers.texi"
1424 It is risky to change this variable's value without doing various
1425 other things. See the definition of `set-visited-file-name' in
1426 `files.el'; some of the things done there, such as changing the
1427 buffer name, are not strictly necessary, but others are essential
1428 to avoid confusing XEmacs.
1430 -- Variable: buffer-file-truename
1431 This buffer-local variable holds the truename of the file visited
1432 in the current buffer, or `nil' if no file is visited. It is a
1433 permanent local, unaffected by `kill-local-variables'. *Note
1436 -- Variable: buffer-file-number
1437 This buffer-local variable holds the file number and directory
1438 device number of the file visited in the current buffer, or `nil'
1439 if no file or a nonexistent file is visited. It is a permanent
1440 local, unaffected by `kill-local-variables'. *Note Truenames::.
1442 The value is normally a list of the form `(FILENUM DEVNUM)'. This
1443 pair of numbers uniquely identifies the file among all files
1444 accessible on the system. See the function `file-attributes', in
1445 *Note File Attributes::, for more information about them.
1447 -- Function: get-file-buffer filename
1448 This function returns the buffer visiting file FILENAME. If there
1449 is no such buffer, it returns `nil'. The argument FILENAME, which
1450 must be a string, is expanded (*note File Name Expansion::), then
1451 compared against the visited file names of all live buffers.
1453 (get-file-buffer "buffers.texi")
1454 => #<buffer buffers.texi>
1456 In unusual circumstances, there can be more than one buffer
1457 visiting the same file name. In such cases, this function returns
1458 the first such buffer in the buffer list.
1460 -- Command: set-visited-file-name filename
1461 If FILENAME is a non-empty string, this function changes the name
1462 of the file visited in current buffer to FILENAME. (If the buffer
1463 had no visited file, this gives it one.) The _next time_ the
1464 buffer is saved it will go in the newly-specified file. This
1465 command marks the buffer as modified, since it does not (as far as
1466 XEmacs knows) match the contents of FILENAME, even if it matched
1467 the former visited file.
1469 If FILENAME is `nil' or the empty string, that stands for "no
1470 visited file". In this case, `set-visited-file-name' marks the
1471 buffer as having no visited file.
1473 When the function `set-visited-file-name' is called interactively,
1474 it prompts for FILENAME in the minibuffer.
1476 See also `clear-visited-file-modtime' and
1477 `verify-visited-file-modtime' in *Note Buffer Modification::.
1479 -- Variable: list-buffers-directory
1480 This buffer-local variable records a string to display in a buffer
1481 listing in place of the visited file name, for buffers that don't
1482 have a visited file name. Dired buffers use this variable.
1485 File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
1487 37.5 Buffer Modification
1488 ========================
1490 XEmacs keeps a flag called the "modified flag" for each buffer, to
1491 record whether you have changed the text of the buffer. This flag is
1492 set to `t' whenever you alter the contents of the buffer, and cleared
1493 to `nil' when you save it. Thus, the flag shows whether there are
1494 unsaved changes. The flag value is normally shown in the modeline
1495 (*note Modeline Variables::), and controls saving (*note Saving
1496 Buffers::) and auto-saving (*note Auto-Saving::).
1498 Some Lisp programs set the flag explicitly. For example, the
1499 function `set-visited-file-name' sets the flag to `t', because the text
1500 does not match the newly-visited file, even if it is unchanged from the
1501 file formerly visited.
1503 The functions that modify the contents of buffers are described in
1506 -- Function: buffer-modified-p &optional buffer
1507 This function returns `t' if the buffer BUFFER has been modified
1508 since it was last read in from a file or saved, or `nil'
1509 otherwise. If BUFFER is not supplied, the current buffer is
1512 -- Function: set-buffer-modified-p flag &optional buffer
1513 This function marks BUFFER as modified if FLAG is non-`nil', or as
1514 unmodified if the flag is `nil'. BUFFER defaults to the current
1517 Another effect of calling this function is to cause unconditional
1518 redisplay of the modeline for the current buffer. In fact, the
1519 function `redraw-modeline' works by doing this:
1521 (set-buffer-modified-p (buffer-modified-p))
1523 -- Command: not-modified &optional arg
1524 This command marks the current buffer as unmodified, and not
1525 needing to be saved. (If ARG is non-`nil', the buffer is instead
1526 marked as modified.) Don't use this function in programs, since it
1527 prints a message in the echo area; use `set-buffer-modified-p'
1530 -- Function: buffer-modified-tick &optional buffer
1531 This function returns BUFFER`s modification-count. This is a
1532 counter that increments every time the buffer is modified. If
1533 BUFFER is `nil' (or omitted), the current buffer is used.
1536 File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
1538 37.6 Comparison of Modification Time
1539 ====================================
1541 Suppose that you visit a file and make changes in its buffer, and
1542 meanwhile the file itself is changed on disk. At this point, saving the
1543 buffer would overwrite the changes in the file. Occasionally this may
1544 be what you want, but usually it would lose valuable information.
1545 XEmacs therefore checks the file's modification time using the functions
1546 described below before saving the file.
1548 -- Function: verify-visited-file-modtime buffer
1549 This function compares what BUFFER has recorded for the
1550 modification time of its visited file against the actual
1551 modification time of the file as recorded by the operating system.
1552 The two should be the same unless some other process has written
1553 the file since XEmacs visited or saved it.
1555 The function returns `t' if the last actual modification time and
1556 XEmacs's recorded modification time are the same, `nil' otherwise.
1558 -- Function: clear-visited-file-modtime
1559 This function clears out the record of the last modification time
1560 of the file being visited by the current buffer. As a result, the
1561 next attempt to save this buffer will not complain of a
1562 discrepancy in file modification times.
1564 This function is called in `set-visited-file-name' and other
1565 exceptional places where the usual test to avoid overwriting a
1566 changed file should not be done.
1568 -- Function: visited-file-modtime
1569 This function returns the buffer's recorded last file modification
1570 time, as a list of the form `(HIGH . LOW)'. (This is the same
1571 format that `file-attributes' uses to return time values; see
1572 *Note File Attributes::.)
1574 -- Function: set-visited-file-modtime &optional time
1575 This function updates the buffer's record of the last modification
1576 time of the visited file, to the value specified by TIME if TIME
1577 is not `nil', and otherwise to the last modification time of the
1580 If TIME is not `nil', it should have the form `(HIGH . LOW)' or
1581 `(HIGH LOW)', in either case containing two integers, each of
1582 which holds 16 bits of the time.
1584 This function is useful if the buffer was not read from the file
1585 normally, or if the file itself has been changed for some known
1588 -- Function: ask-user-about-supersession-threat filename
1589 This function is used to ask a user how to proceed after an
1590 attempt to modify an obsolete buffer visiting file FILENAME. An
1591 "obsolete buffer" is an unmodified buffer for which the associated
1592 file on disk is newer than the last save-time of the buffer. This
1593 means some other program has probably altered the file.
1595 Depending on the user's answer, the function may return normally,
1596 in which case the modification of the buffer proceeds, or it may
1597 signal a `file-supersession' error with data `(FILENAME)', in which
1598 case the proposed buffer modification is not allowed.
1600 This function is called automatically by XEmacs on the proper
1601 occasions. It exists so you can customize XEmacs by redefining it.
1602 See the file `userlock.el' for the standard definition.
1604 See also the file locking mechanism in *Note File Locks::.
1607 File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
1609 37.7 Read-Only Buffers
1610 ======================
1612 If a buffer is "read-only", then you cannot change its contents,
1613 although you may change your view of the contents by scrolling and
1616 Read-only buffers are used in two kinds of situations:
1618 * A buffer visiting a write-protected file is normally read-only.
1620 Here, the purpose is to show the user that editing the buffer with
1621 the aim of saving it in the file may be futile or undesirable.
1622 The user who wants to change the buffer text despite this can do
1623 so after clearing the read-only flag with `C-x C-q'.
1625 * Modes such as Dired and Rmail make buffers read-only when altering
1626 the contents with the usual editing commands is probably a mistake.
1628 The special commands of these modes bind `buffer-read-only' to
1629 `nil' (with `let') or bind `inhibit-read-only' to `t' around the
1630 places where they change the text.
1632 -- Variable: buffer-read-only
1633 This buffer-local variable specifies whether the buffer is
1634 read-only. The buffer is read-only if this variable is non-`nil'.
1636 -- Variable: inhibit-read-only
1637 If this variable is non-`nil', then read-only buffers and read-only
1638 characters may be modified. Read-only characters in a buffer are
1639 those that have non-`nil' `read-only' properties (either text
1640 properties or extent properties). *Note Extent Properties::, for
1641 more information about text properties and extent properties.
1643 If `inhibit-read-only' is `t', all `read-only' character
1644 properties have no effect. If `inhibit-read-only' is a list, then
1645 `read-only' character properties have no effect if they are members
1646 of the list (comparison is done with `eq').
1648 -- Command: toggle-read-only &optional arg
1649 This command changes whether the current buffer is read-only.
1650 Interactively, if a prefix arg ARG is supplied, set the current
1651 buffer read only if and only if ARG is positive.
1653 This command is intended for interactive use only; don't use it in
1654 programs. At any given point in a program, you should know
1655 whether you want the read-only flag on or off; so you can set
1656 `buffer-read-only' explicitly to the proper value, `t' or `nil'.
1658 -- Function: barf-if-buffer-read-only &optional buffer start end
1659 This function signals a `buffer-read-only' error if BUFFER is
1660 read-only. BUFFER defaults to the current buffer. *Note
1661 Interactive Call::, for another way to signal an error if the
1662 current buffer is read-only.
1664 If optional argument START is non-`nil', all extents in the buffer
1665 which overlap that part of the buffer are checked to ensure none
1666 has a `read-only' property. (Extents that lie completely within the
1667 range, however, are not checked.) END defaults to the value of
1670 If START and END are equal, the range checked is [START, END]
1671 (i.e. closed on both ends); otherwise, the range checked is
1672 (START, END) \(open on both ends), except that extents that lie
1673 completely within [START, END] are not checked. See
1674 `extent-in-region-p' for a fuller discussion.
1677 File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
1679 37.8 The Buffer List
1680 ====================
1682 The "buffer list" is a list of all live buffers. Creating a buffer
1683 adds it to this list, and killing a buffer deletes it. The order of
1684 the buffers in the list is based primarily on how recently each buffer
1685 has been displayed in the selected window. Buffers move to the front
1686 of the list when they are selected and to the end when they are buried.
1687 Several functions, notably `other-buffer', use this ordering. A
1688 buffer list displayed for the user also follows this order.
1690 Every frame has its own order for the buffer list. Switching to a
1691 new buffer inside of a particular frame changes the buffer list order
1692 for that frame, but does not affect the buffer list order of any other
1693 frames. In addition, there is a global, non-frame buffer list order
1694 that is independent of the buffer list orders for any particular frame.
1696 Note that the different buffer lists all contain the same elements.
1697 It is only the order of those elements that is different.
1699 -- Function: buffer-list &optional frame
1700 This function returns a list of all buffers, including those whose
1701 names begin with a space. The elements are actual buffers, not
1702 their names. The order of the list is specific to FRAME, which
1703 defaults to the current frame. If FRAME is `t', the global,
1704 non-frame ordering is returned instead.
1707 => (#<buffer buffers.texi>
1708 #<buffer *Minibuf-1*> #<buffer buffer.c>
1709 #<buffer *Help*> #<buffer TAGS>)
1711 ;; Note that the name of the minibuffer
1712 ;; begins with a space!
1713 (mapcar (function buffer-name) (buffer-list))
1714 => ("buffers.texi" " *Minibuf-1*"
1715 "buffer.c" "*Help*" "TAGS")
1717 Buffers appear earlier in the list if they were current more
1720 This list is a copy of a list used inside XEmacs; modifying it has
1721 no effect on the buffers.
1723 -- Function: other-buffer &optional buffer-or-name frame visible-ok
1724 This function returns the first buffer in the buffer list other
1725 than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
1726 (FRAME defaults to the current frame. If FRAME is `t', then the
1727 global, non-frame ordering is used.) Usually this is the buffer
1728 most recently shown in the selected window, aside from
1729 BUFFER-OR-NAME. Buffers are moved to the front of the list when
1730 they are selected and to the end when they are buried. Buffers
1731 whose names start with a space are not considered.
1733 If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
1734 `other-buffer' returns the first buffer on the buffer list that is
1735 not visible in any window in a visible frame.
1737 If the selected frame has a non-`nil' `buffer-predicate' property,
1738 then `other-buffer' uses that predicate to decide which buffers to
1739 consider. It calls the predicate once for each buffer, and if the
1740 value is `nil', that buffer is ignored. *Note X Frame
1743 If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
1744 visible in any window on any visible frame, except as a last
1745 resort. If VISIBLE-OK is non-`nil', then it does not matter
1746 whether a buffer is displayed somewhere or not.
1748 If no suitable buffer exists, the buffer `*scratch*' is returned
1749 (and created, if necessary).
1751 Note that in FSF Emacs 19, there is no FRAME argument, and
1752 VISIBLE-OK is the second argument instead of the third.
1754 -- Command: list-buffers &optional files-only
1755 This function displays a listing of the names of existing buffers.
1756 It clears the buffer `*Buffer List*', then inserts the listing
1757 into that buffer and displays it in a window. `list-buffers' is
1758 intended for interactive use, and is described fully in `The XEmacs
1759 Reference Manual'. It returns `nil'.
1761 -- Command: bury-buffer &optional buffer-or-name before
1762 This function puts BUFFER-OR-NAME at the end of the buffer list
1763 without changing the order of any of the other buffers on the list.
1764 This buffer therefore becomes the least desirable candidate for
1765 `other-buffer' to return.
1767 If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
1768 current buffer. In addition, if the buffer is displayed in the
1769 selected window, this switches to some other buffer (obtained using
1770 `other-buffer') in the selected window. But if the buffer is
1771 displayed in some other window, it remains displayed there.
1773 If you wish to replace a buffer in all the windows that display
1774 it, use `replace-buffer-in-windows'. *Note Buffers and Windows::.
1777 File: lispref.info, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers
1779 37.9 Creating Buffers
1780 =====================
1782 This section describes the two primitives for creating buffers.
1783 `get-buffer-create' creates a buffer if it finds no existing buffer
1784 with the specified name; `generate-new-buffer' always creates a new
1785 buffer and gives it a unique name.
1787 Other functions you can use to create buffers include
1788 `with-output-to-temp-buffer' (*note Temporary Displays::) and
1789 `create-file-buffer' (*note Visiting Files::). Starting a subprocess
1790 can also create a buffer (*note Processes::).
1792 -- Function: get-buffer-create name
1793 This function returns a buffer named NAME. It returns an existing
1794 buffer with that name, if one exists; otherwise, it creates a new
1795 buffer. The buffer does not become the current buffer--this
1796 function does not change which buffer is current.
1798 An error is signaled if NAME is not a string.
1800 (get-buffer-create "foo")
1803 The major mode for the new buffer is set to Fundamental mode. The
1804 variable `default-major-mode' is handled at a higher level. *Note
1807 -- Function: generate-new-buffer name
1808 This function returns a newly created, empty buffer, but does not
1809 make it current. If there is no buffer named NAME, then that is
1810 the name of the new buffer. If that name is in use, this function
1811 adds suffixes of the form `<N>' to NAME, where N is an integer.
1812 It tries successive integers starting with 2 until it finds an
1815 An error is signaled if NAME is not a string.
1817 (generate-new-buffer "bar")
1819 (generate-new-buffer "bar")
1821 (generate-new-buffer "bar")
1824 The major mode for the new buffer is set to Fundamental mode. The
1825 variable `default-major-mode' is handled at a higher level. *Note
1828 See the related function `generate-new-buffer-name' in *Note
1832 File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers
1834 37.10 Killing Buffers
1835 =====================
1837 "Killing a buffer" makes its name unknown to XEmacs and makes its text
1838 space available for other use.
1840 The buffer object for the buffer that has been killed remains in
1841 existence as long as anything refers to it, but it is specially marked
1842 so that you cannot make it current or display it. Killed buffers retain
1843 their identity, however; two distinct buffers, when killed, remain
1844 distinct according to `eq'.
1846 If you kill a buffer that is current or displayed in a window, XEmacs
1847 automatically selects or displays some other buffer instead. This means
1848 that killing a buffer can in general change the current buffer.
1849 Therefore, when you kill a buffer, you should also take the precautions
1850 associated with changing the current buffer (unless you happen to know
1851 that the buffer being killed isn't current). *Note Current Buffer::.
1853 If you kill a buffer that is the base buffer of one or more indirect
1854 buffers, the indirect buffers are automatically killed as well.
1856 The `buffer-name' of a killed buffer is `nil'. To test whether a
1857 buffer has been killed, you can either use this feature or the function
1860 -- Function: buffer-live-p object
1861 This function returns `t' if OBJECT is an editor buffer that has
1862 not been deleted, `nil' otherwise.
1864 -- Command: kill-buffer buffer-or-name
1865 This function kills the buffer BUFFER-OR-NAME, freeing all its
1866 memory for use as space for other buffers. (Emacs version 18 and
1867 older was unable to return the memory to the operating system.)
1868 It returns `nil'. The argument BUFFER-OR-NAME may be a buffer or
1871 Any processes that have this buffer as the `process-buffer' are
1872 sent the `SIGHUP' signal, which normally causes them to terminate.
1873 (The basic meaning of `SIGHUP' is that a dialup line has been
1874 disconnected.) *Note Deleting Processes::.
1876 If the buffer is visiting a file and contains unsaved changes,
1877 `kill-buffer' asks the user to confirm before the buffer is killed.
1878 It does this even if not called interactively. To prevent the
1879 request for confirmation, clear the modified flag before calling
1880 `kill-buffer'. *Note Buffer Modification::.
1882 Killing a buffer that is already dead has no effect.
1884 (kill-buffer "foo.unchanged")
1886 (kill-buffer "foo.changed")
1888 ---------- Buffer: Minibuffer ----------
1889 Buffer foo.changed modified; kill anyway? (yes or no) yes
1890 ---------- Buffer: Minibuffer ----------
1894 -- Variable: kill-buffer-query-functions
1895 After confirming unsaved changes, `kill-buffer' calls the functions
1896 in the list `kill-buffer-query-functions', in order of appearance,
1897 with no arguments. The buffer being killed is the current buffer
1898 when they are called. The idea is that these functions ask for
1899 confirmation from the user for various nonstandard reasons. If
1900 any of them returns `nil', `kill-buffer' spares the buffer's life.
1902 -- Variable: kill-buffer-hook
1903 This is a normal hook run by `kill-buffer' after asking all the
1904 questions it is going to ask, just before actually killing the
1905 buffer. The buffer to be killed is current when the hook
1906 functions run. *Note Hooks::.
1908 -- Variable: buffer-offer-save
1909 This variable, if non-`nil' in a particular buffer, tells
1910 `save-buffers-kill-emacs' and `save-some-buffers' to offer to save
1911 that buffer, just as they offer to save file-visiting buffers. The
1912 variable `buffer-offer-save' automatically becomes buffer-local
1913 when set for any reason. *Note Buffer-Local Variables::.
1916 File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers
1918 37.11 Indirect Buffers
1919 ======================
1921 An "indirect buffer" shares the text of some other buffer, which is
1922 called the "base buffer" of the indirect buffer. In some ways it is
1923 the analogue, for buffers, of a symbolic link among files. The base
1924 buffer may not itself be an indirect buffer. One base buffer may have
1925 several "indirect children".
1927 The text of the indirect buffer is always identical to the text of
1928 its base buffer; changes made by editing either one are visible
1929 immediately in the other.
1931 But in all other respects, the indirect buffer and its base buffer
1932 are completely separate. They have different names, different values of
1933 point and mark, different narrowing, different markers and extents
1934 (though inserting or deleting text in either buffer relocates the
1935 markers and extents for both), different major modes, and different
1936 local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not
1937 automatically share text properties among themselves and their base
1940 An indirect buffer cannot visit a file, but its base buffer can. If
1941 you try to save the indirect buffer, that actually works by saving the
1944 Killing an indirect buffer has no effect on its base buffer. Killing
1945 the base buffer kills all its indirect children.
1947 -- Command: make-indirect-buffer base-buffer name
1948 This creates an indirect buffer named NAME whose base buffer is
1949 BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string.
1951 If BASE-BUFFER is an indirect buffer, its base buffer is used as
1952 the base for the new buffer.
1954 (make-indirect-buffer "*scratch*" "indirect")
1955 => #<buffer "indirect">
1957 -- Function: buffer-base-buffer &optional buffer
1958 This function returns the base buffer of BUFFER. If BUFFER is not
1959 indirect, the value is `nil'. Otherwise, the value is another
1960 buffer, which is never an indirect buffer. If BUFFER is not
1961 supplied, it defaults to the current buffer.
1963 (buffer-base-buffer (get-buffer "indirect"))
1964 => #<buffer "*scratch*">
1966 -- Function: buffer-indirect-children &optional buffer
1967 This function returns a list of all indirect buffers whose base
1968 buffer is BUFFER. If BUFFER is indirect, the return value will
1969 always be `nil'; see `make-indirect-buffer'. If BUFFER is not
1970 supplied, it defaults to the current buffer.
1972 (buffer-indirect-children (get-buffer "*scratch*"))
1973 => (#<buffer "indirect">)
1976 File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top
1981 This chapter describes most of the functions and variables related to
1982 Emacs windows. See *Note Display::, for information on how text is
1983 displayed in windows.
1987 * Basic Windows:: Basic information on using windows.
1988 * Splitting Windows:: Splitting one window into two windows.
1989 * Deleting Windows:: Deleting a window gives its space to other windows.
1990 * Selecting Windows:: The selected window is the one that you edit in.
1991 * Cyclic Window Ordering:: Moving around the existing windows.
1992 * Buffers and Windows:: Each window displays the contents of a buffer.
1993 * Displaying Buffers:: Higher-lever functions for displaying a buffer
1994 and choosing a window for it.
1995 * Choosing Window:: How to choose a window for displaying a buffer.
1996 * Window Point:: Each window has its own location of point.
1997 * Window Start:: The display-start position controls which text
1998 is on-screen in the window.
1999 * Vertical Scrolling:: Moving text up and down in the window.
2000 * Horizontal Scrolling:: Moving text sideways on the window.
2001 * Size of Window:: Accessing the size of a window.
2002 * Position of Window:: Accessing the position of a window.
2003 * Resizing Windows:: Changing the size of a window.
2004 * Window Configurations:: Saving and restoring the state of the screen.
2007 File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows
2009 38.1 Basic Concepts of Emacs Windows
2010 ====================================
2012 A "window" in XEmacs is the physical area of the screen in which a
2013 buffer is displayed. The term is also used to refer to a Lisp object
2014 that represents that screen area in XEmacs Lisp. It should be clear
2015 from the context which is meant.
2017 XEmacs groups windows into frames. A frame represents an area of
2018 screen available for XEmacs to use. Each frame always contains at least
2019 one window, but you can subdivide it vertically or horizontally into
2020 multiple nonoverlapping Emacs windows.
2022 In each frame, at any time, one and only one window is designated as
2023 "selected within the frame". The frame's cursor appears in that
2024 window. At any time, one frame is the selected frame; and the window
2025 selected within that frame is "the selected window". The selected
2026 window's buffer is usually the current buffer (except when `set-buffer'
2027 has been used). *Note Current Buffer::.
2029 For practical purposes, a window exists only while it is displayed in
2030 a frame. Once removed from the frame, the window is effectively deleted
2031 and should not be used, _even though there may still be references to
2032 it_ from other Lisp objects. Restoring a saved window configuration is
2033 the only way for a window no longer on the screen to come back to life.
2034 (*Note Deleting Windows::.)
2036 Each window has the following attributes:
2044 * window edges with respect to the frame or screen
2046 * the buffer it displays
2048 * position within the buffer at the upper left of the window
2050 * amount of horizontal scrolling, in columns
2056 * how recently the window was selected
2058 Users create multiple windows so they can look at several buffers at
2059 once. Lisp libraries use multiple windows for a variety of reasons, but
2060 most often to display related information. In Rmail, for example, you
2061 can move through a summary buffer in one window while the other window
2062 shows messages one at a time as they are reached.
2064 The meaning of "window" in XEmacs is similar to what it means in the
2065 context of general-purpose window systems such as X, but not identical.
2066 The X Window System places X windows on the screen; XEmacs uses one or
2067 more X windows as frames, and subdivides them into Emacs windows. When
2068 you use XEmacs on a character-only terminal, XEmacs treats the whole
2069 terminal screen as one frame.
2071 Most window systems support arbitrarily located overlapping windows.
2072 In contrast, Emacs windows are "tiled"; they never overlap, and
2073 together they fill the whole screen or frame. Because of the way in
2074 which XEmacs creates new windows and resizes them, you can't create
2075 every conceivable tiling of windows on an Emacs frame. *Note Splitting
2076 Windows::, and *Note Size of Window::.
2078 *Note Display::, for information on how the contents of the window's
2079 buffer are displayed in the window.
2081 -- Function: windowp object
2082 This function returns `t' if OBJECT is a window.
2085 File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows
2087 38.2 Splitting Windows
2088 ======================
2090 The functions described here are the primitives used to split a window
2091 into two windows. Two higher level functions sometimes split a window,
2092 but not always: `pop-to-buffer' and `display-buffer' (*note Displaying
2095 The functions described here do not accept a buffer as an argument.
2096 The two "halves" of the split window initially display the same buffer
2097 previously visible in the window that was split.
2099 -- Function: one-window-p &optional nomini which-frames which-devices
2100 This function returns non-`nil' if there is only one window. The
2101 argument NOMINI, if non-`nil', means don't count the minibuffer
2102 even if it is active; otherwise, the minibuffer window is
2103 included, if active, in the total number of windows which is
2104 compared against one.
2106 The remaining arguments controls which set of windows are counted,
2107 as with `next-window'.
2109 -- Command: split-window &optional window size horizontal
2110 This function splits WINDOW into two windows. The original window
2111 WINDOW remains the selected window, but occupies only part of its
2112 former screen area. The rest is occupied by a newly created
2113 window which is returned as the value of this function.
2115 If HORIZONTAL is non-`nil', then WINDOW splits into two side by
2116 side windows. The original window WINDOW keeps the leftmost SIZE
2117 columns, and gives the rest of the columns to the new window.
2118 Otherwise, it splits into windows one above the other, and WINDOW
2119 keeps the upper SIZE lines and gives the rest of the lines to the
2120 new window. The original window is therefore the left-hand or
2121 upper of the two, and the new window is the right-hand or lower.
2123 If WINDOW is omitted or `nil', then the selected window is split.
2124 If SIZE is omitted or `nil', then WINDOW is divided evenly into
2125 two parts. (If there is an odd line, it is allocated to the new
2126 window.) When `split-window' is called interactively, all its
2127 arguments are `nil'.
2129 The following example starts with one window on a frame that is 50
2130 lines high by 80 columns wide; then the window is split.
2132 (setq w (selected-window))
2133 => #<window 8 on windows.texi>
2134 (window-edges) ; Edges in order:
2135 => (0 0 80 50) ; left-top-right-bottom
2137 ;; Returns window created
2138 (setq w2 (split-window w 15))
2139 => #<window 28 on windows.texi>
2141 => (0 15 80 50) ; Bottom window;
2144 => (0 0 80 15) ; Top window
2146 The frame looks like this:
2158 Next, the top window is split horizontally:
2160 (setq w3 (split-window w 35 t))
2161 => #<window 32 on windows.texi>
2163 => (35 0 80 15) ; Left edge at column 35
2165 => (0 0 35 15) ; Right edge at column 35
2167 => (0 15 80 50) ; Bottom window unchanged
2169 Now, the screen looks like this:
2182 Normally, Emacs indicates the border between two side-by-side
2183 windows with a scroll bar (*note Scroll Bars: X Frame Properties.)
2184 or `|' characters. The display table can specify alternative
2185 border characters; see *Note Display Tables::.
2187 -- Command: split-window-vertically &optional size
2188 This function splits the selected window into two windows, one
2189 above the other, leaving the selected window with SIZE lines.
2191 This function is simply an interface to `split-window'. Here is
2192 the complete function definition for it:
2194 (defun split-window-vertically (&optional arg)
2195 "Split current window into two windows, one above the other."
2197 (split-window nil (and arg (prefix-numeric-value arg))))
2199 -- Command: split-window-horizontally &optional size
2200 This function splits the selected window into two windows
2201 side-by-side, leaving the selected window with SIZE columns.
2203 This function is simply an interface to `split-window'. Here is
2204 the complete definition for `split-window-horizontally' (except for
2205 part of the documentation string):
2207 (defun split-window-horizontally (&optional arg)
2208 "Split selected window into two windows, side by side..."
2210 (split-window nil (and arg (prefix-numeric-value arg)) t))
2213 File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows
2215 38.3 Deleting Windows
2216 =====================
2218 A window remains visible on its frame unless you "delete" it by calling
2219 certain functions that delete windows. A deleted window cannot appear
2220 on the screen, but continues to exist as a Lisp object until there are
2221 no references to it. There is no way to cancel the deletion of a
2222 window aside from restoring a saved window configuration (*note Window
2223 Configurations::). Restoring a window configuration also deletes any
2224 windows that aren't part of that configuration.
2226 When you delete a window, the space it took up is given to one
2227 adjacent sibling. (In Emacs version 18, the space was divided evenly
2228 among all the siblings.)
2230 -- Function: window-live-p window
2231 This function returns `nil' if WINDOW is deleted, and `t'
2234 *Warning:* Erroneous information or fatal errors may result from
2235 using a deleted window as if it were live.
2237 -- Command: delete-window &optional window force
2238 This function removes WINDOW from the display. If WINDOW is
2239 omitted, then the selected window is deleted. If window is the
2240 only one on its frame, the frame is deleted as well.
2242 Normally, you cannot delete the last non-minibuffer-only frame
2243 (you must use `save-buffers-kill-emacs' or `kill-emacs'); an error
2244 is signaled instead. However, if optional second argument FORCE is
2245 non-`nil', you can delete the last frame. (This will automatically
2246 call `save-buffers-kill-emacs'.)
2248 This function returns `nil'.
2250 When `delete-window' is called interactively, the selected window
2253 -- Command: delete-other-windows &optional window
2254 This function makes WINDOW the only window on its frame, by
2255 deleting the other windows in that frame. If WINDOW is omitted or
2256 `nil', then the selected window is used by default.
2258 The result is `nil'.
2260 -- Command: delete-windows-on buffer &optional which-frames
2262 This function deletes all windows showing BUFFER. If there are no
2263 windows showing BUFFER, it does nothing.
2265 `delete-windows-on' operates frame by frame. If a frame has
2266 several windows showing different buffers, then those showing
2267 BUFFER are removed, and the others expand to fill the space. If
2268 all windows in some frame are showing BUFFER (including the case
2269 where there is only one window), then the frame reverts to having a
2270 single window showing another buffer chosen with `other-buffer'.
2271 *Note The Buffer List::.
2273 The argument WHICH-FRAMES controls which frames to operate on:
2276 Delete all windows showing BUFFER in any frame.
2279 Delete only windows showing BUFFER in the selected frame.
2282 Delete all windows showing BUFFER in any visible frame.
2285 Delete all windows showing BUFFER in any visible frame.
2288 If it is a frame, delete all windows showing BUFFER in that
2291 *Warning:* This is similar to, but not identical to, the meaning
2292 of the WHICH-FRAMES argument to `next-window'; the meanings of
2293 `nil' and `t' are reversed.
2295 The optional argument WHICH-DEVICES further clarifies on which
2296 devices to search for frames as specified by WHICH-FRAMES. This
2297 value is only meaningful if WHICH-FRAMES is not `t'.
2300 Consider all devices on the selected console.
2303 Consider only the one device DEVICE.
2306 Consider all devices on CONSOLE.
2309 Consider all devices with device type DEVICE-TYPE.
2312 Consider all devices on window system consoles.
2315 Consider all devices without restriction.
2317 This function always returns `nil'.
2320 File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows
2322 38.4 Selecting Windows
2323 ======================
2325 When a window is selected, the buffer in the window becomes the current
2326 buffer, and the cursor will appear in it.
2328 -- Function: selected-window &optional device
2329 This function returns the selected window. This is the window in
2330 which the cursor appears and to which many commands apply. Each
2331 separate device can have its own selected window, which is
2332 remembered as focus changes from device to device. Optional
2333 argument DEVICE specifies which device to return the selected
2334 window for, and defaults to the selected device.
2336 -- Function: select-window window &optional norecord
2337 This function makes WINDOW the selected window. The cursor then
2338 appears in WINDOW (on redisplay). The buffer being displayed in
2339 WINDOW is immediately designated the current buffer.
2341 If optional argument NORECORD is non-`nil' then the global and
2342 per-frame buffer orderings are not modified, as by the function
2345 The return value is WINDOW.
2347 (setq w (next-window))
2349 => #<window 65 on windows.texi>
2351 -- Special Form: save-selected-window forms...
2352 This special form records the selected window, executes FORMS in
2353 sequence, then restores the earlier selected window. It does not
2354 save or restore anything about the sizes, arrangement or contents
2355 of windows; therefore, if the FORMS change them, the changes are
2358 The following functions choose one of the windows on the screen,
2359 offering various criteria for the choice.
2361 -- Function: get-lru-window &optional which-frames which-devices
2362 This function returns the window least recently "used" (that is,
2363 selected). The selected window is always the most recently used
2366 The selected window can be the least recently used window if it is
2367 the only window. A newly created window becomes the least
2368 recently used window until it is selected. A minibuffer window is
2371 By default, only the windows in the selected frame are considered.
2372 The optional argument WHICH-FRAMES changes this behavior. Here
2373 are the possible values and their meanings:
2376 Consider all the windows in the selected windows's frame,
2377 plus the minibuffer used by that frame even if it lies in
2381 Consider all windows in all existing frames.
2384 Consider all windows in all visible frames. (To get useful
2385 results, you must ensure WINDOW is in a visible frame.)
2388 Consider all windows in all visible or iconified frames.
2391 Consider all windows on frame FRAME.
2394 Consider precisely the windows in the selected window's
2395 frame, and no others.
2397 The optional argument WHICH-DEVICES further clarifies on which
2398 devices to search for frames as specified by WHICH-FRAMES. This
2399 value is only meaningful if WHICH-FRAMES is non-`nil'.
2402 Consider all devices on the selected console.
2405 Consider only the one device DEVICE.
2408 Consider all devices on CONSOLE.
2411 Consider all devices with device type DEVICE-TYPE.
2414 Consider all devices on window system consoles.
2417 Consider all devices without restriction.
2420 -- Function: get-largest-window &optional which-frames which-devices
2421 This function returns the window with the largest area (height
2422 times width). If there are no side-by-side windows, then this is
2423 the window with the most lines. A minibuffer window is never a
2426 If there are two windows of the same size, then the function
2427 returns the window that is first in the cyclic ordering of windows
2428 (see following section), starting from the selected window.
2430 The remaining arguments control which set of windows are
2431 considered. See `next-window', above.
2434 File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows
2436 38.5 Cyclic Ordering of Windows
2437 ===============================
2439 When you use the command `C-x o' (`other-window') to select the next
2440 window, it moves through all the windows on the screen in a specific
2441 cyclic order. For any given configuration of windows, this order never
2442 varies. It is called the "cyclic ordering of windows".
2444 This ordering generally goes from top to bottom, and from left to
2445 right. But it may go down first or go right first, depending on the
2446 order in which the windows were split.
2448 If the first split was vertical (into windows one above each other),
2449 and then the subwindows were split horizontally, then the ordering is
2450 left to right in the top of the frame, and then left to right in the
2451 next lower part of the frame, and so on. If the first split was
2452 horizontal, the ordering is top to bottom in the left part, and so on.
2453 In general, within each set of siblings at any level in the window tree,
2454 the order is left to right, or top to bottom.
2456 -- Function: next-window &optional window minibuf which-frames
2458 This function returns the window following WINDOW in the cyclic
2459 ordering of windows. This is the window that `C-x o' would select
2460 if typed when WINDOW is selected. If WINDOW is the only window
2461 visible, then this function returns WINDOW. If omitted, WINDOW
2462 defaults to the selected window.
2464 The value of the argument MINIBUF determines whether the
2465 minibuffer is included in the window order. Normally, when
2466 MINIBUF is `nil', the minibuffer is included if it is currently
2467 active; this is the behavior of `C-x o'. (The minibuffer window
2468 is active while the minibuffer is in use. *Note Minibuffers::.)
2470 If MINIBUF is `t', then the cyclic ordering includes the
2471 minibuffer window even if it is not active.
2473 If MINIBUF is neither `t' nor `nil', then the minibuffer window is
2474 not included even if it is active.
2476 By default, only the windows in the selected frame are considered.
2477 The optional argument WHICH-FRAMES changes this behavior. Here
2478 are the possible values and their meanings:
2481 Consider all the windows in WINDOW's frame, plus the
2482 minibuffer used by that frame even if it lies in some other
2486 Consider all windows in all existing frames.
2489 Consider all windows in all visible frames. (To get useful
2490 results, you must ensure WINDOW is in a visible frame.)
2493 Consider all windows in all visible or iconified frames.
2496 Consider all windows on frame FRAME.
2499 Consider precisely the windows in WINDOW's frame, and no
2502 The optional argument WHICH-DEVICES further clarifies on which
2503 devices to search for frames as specified by WHICH-FRAMES. This
2504 value is only meaningful if WHICH-FRAMES is non-`nil'.
2507 Consider all devices on the selected console.
2510 Consider only the one device DEVICE.
2513 Consider all devices on CONSOLE.
2516 Consider all devices with device type DEVICE-TYPE.
2519 Consider all devices on window system consoles.
2522 Consider all devices without restriction.
2524 If you use consistent values for MINIBUF, WHICH-FRAMES, and
2525 WHICH-DEVICES, you can use `next-window' to iterate through the
2526 entire cycle of acceptable windows, eventually ending up back at
2527 the window you started with. `previous-window' traverses the same
2528 cycle, in the reverse order.
2530 This example assumes there are two windows, both displaying the
2531 buffer `windows.texi':
2534 => #<window 56 on windows.texi>
2535 (next-window (selected-window))
2536 => #<window 52 on windows.texi>
2537 (next-window (next-window (selected-window)))
2538 => #<window 56 on windows.texi>
2540 -- Function: previous-window &optional window minibuf which-frames
2542 This function returns the window preceding WINDOW in the cyclic
2543 ordering of windows. The other arguments specify which windows to
2544 include in the cycle, as in `next-window'.
2546 -- Command: other-window count &optional which-frames which-devices
2547 This function selects the COUNTth following window in the cyclic
2548 order. If COUNT is negative, then it selects the -COUNTth
2549 preceding window. It returns `nil'.
2551 In an interactive call, COUNT is the numeric prefix argument.
2553 The other arguments specify which windows to include in the cycle,
2554 as in `next-window'.
2556 -- Function: walk-windows function &optional minibuf which-frames
2558 This function cycles through all windows, calling `function' once
2559 for each window with the window as its sole argument.
2561 The other arguments specify which windows to cycle through, as in
2565 File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
2567 38.6 Buffers and Windows
2568 ========================
2570 This section describes low-level functions to examine windows or to
2571 display buffers in windows in a precisely controlled fashion. *Note
2572 Displaying Buffers::, for related functions that find a window to use
2573 and specify a buffer for it. The functions described there are easier
2574 to use than these, but they employ heuristics in choosing or creating a
2575 window; use these functions when you need complete control.
2577 -- Function: set-window-buffer window buffer-or-name &optional norecord
2578 This function makes WINDOW display BUFFER-OR-NAME as its contents.
2579 BUFFER-OR-NAME can be a buffer or a buffer name.
2581 With non-`nil' optional argument NORECORD, do not modify the
2582 global or per-frame buffer ordering.
2584 This function returns `nil'.
2586 (set-window-buffer (selected-window) "foo")
2589 -- Function: window-buffer &optional window
2590 This function returns the buffer that WINDOW is displaying. If
2591 WINDOW is omitted, this function returns the buffer for the
2595 => #<buffer windows.texi>
2597 -- Function: get-buffer-window buffer-or-name &optional which-frames
2599 This function returns a window currently displaying
2600 BUFFER-OR-NAME, or `nil' if there is none. If there are several
2601 such windows, then the function returns the first one in the
2602 cyclic ordering of windows, starting from the selected window.
2603 *Note Cyclic Window Ordering::.
2605 The remaining arguments control which windows to consider. They
2606 have the same meaning as for `next-window'.
2609 File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
2611 38.7 Displaying Buffers in Windows
2612 ==================================
2614 In this section we describe convenient functions that choose a window
2615 automatically and use it to display a specified buffer. These functions
2616 can also split an existing window in certain circumstances. We also
2617 describe variables that parameterize the heuristics used for choosing a
2618 window. *Note Buffers and Windows::, for low-level functions that give
2619 you more precise control.
2621 Do not use the functions in this section in order to make a buffer
2622 current so that a Lisp program can access or modify it; they are too
2623 drastic for that purpose, since they change the display of buffers in
2624 windows, which is gratuitous and will surprise the user. Instead, use
2625 `set-buffer' (*note Current Buffer::) and `save-excursion' (*note
2626 Excursions::), which designate buffers as current for programmed access
2627 without affecting the display of buffers in windows.
2629 -- Command: switch-to-buffer buffer-or-name &optional norecord
2630 This function makes BUFFER-OR-NAME the current buffer, and also
2631 displays the buffer in the selected window. This means that a
2632 human can see the buffer and subsequent keyboard commands will
2633 apply to it. Contrast this with `set-buffer', which makes
2634 BUFFER-OR-NAME the current buffer but does not display it in the
2635 selected window. *Note Current Buffer::.
2637 If BUFFER-OR-NAME does not identify an existing buffer, then a new
2638 buffer by that name is created. The major mode for the new buffer
2639 is set according to the variable `default-major-mode'. *Note Auto
2642 Normally the specified buffer is put at the front of the buffer
2643 list. This affects the operation of `other-buffer'. However, if
2644 NORECORD is non-`nil', this is not done. *Note The Buffer List::.
2646 The `switch-to-buffer' function is often used interactively, as
2647 the binding of `C-x b'. It is also used frequently in programs.
2648 It always returns `nil'.
2650 -- Command: switch-to-buffer-other-window buffer-or-name
2651 This function makes BUFFER-OR-NAME the current buffer and displays
2652 it in a window not currently selected. It then selects that
2653 window. The handling of the buffer is the same as in
2656 The currently selected window is absolutely never used to do the
2657 job. If it is the only window, then it is split to make a
2658 distinct window for this purpose. If the selected window is
2659 already displaying the buffer, then it continues to do so, but
2660 another window is nonetheless found to display it in as well.
2662 -- Function: pop-to-buffer buffer-or-name &optional other-window
2664 This function makes BUFFER-OR-NAME the current buffer and switches
2665 to it in some window, preferably not the window previously
2666 selected. The "popped-to" window becomes the selected window
2669 If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
2670 looks for a window in any visible frame already displaying the
2671 buffer; if there is one, it returns that window and makes it be
2672 selected within its frame. If there is none, it creates a new
2673 frame and displays the buffer in it.
2675 If `pop-up-frames' is `nil', then `pop-to-buffer' operates
2676 entirely within the selected frame. (If the selected frame has
2677 just a minibuffer, `pop-to-buffer' operates within the most
2678 recently selected frame that was not just a minibuffer.)
2680 If the variable `pop-up-windows' is non-`nil', windows may be
2681 split to create a new window that is different from the original
2682 window. For details, see *Note Choosing Window::.
2684 If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
2685 another window even if BUFFER-OR-NAME is already visible in the
2686 selected window. Thus BUFFER-OR-NAME could end up displayed in
2687 two windows. On the other hand, if BUFFER-OR-NAME is already
2688 displayed in the selected window and OTHER-WINDOW is `nil', then
2689 the selected window is considered sufficient display for
2690 BUFFER-OR-NAME, so that nothing needs to be done.
2692 All the variables that affect `display-buffer' affect
2693 `pop-to-buffer' as well. *Note Choosing Window::.
2695 If BUFFER-OR-NAME is a string that does not name an existing
2696 buffer, a buffer by that name is created. The major mode for the
2697 new buffer is set according to the variable `default-major-mode'.
2698 *Note Auto Major Mode::.
2700 If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
2702 An example use of this function is found at the end of *Note
2705 -- Command: replace-buffer-in-windows buffer &optional which-frames
2707 This function replaces BUFFER with some other buffer in all
2708 windows displaying it. The other buffer used is chosen with
2709 `other-buffer'. In the usual applications of this function, you
2710 don't care which other buffer is used; you just want to make sure
2711 that BUFFER is no longer displayed.
2713 The optional arguments WHICH-FRAMES and WHICH-DEVICES have the
2714 same meaning as with `delete-windows-on'.
2716 This function returns `nil'.
2719 File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
2721 38.8 Choosing a Window for Display
2722 ==================================
2724 This section describes the basic facility that chooses a window to
2725 display a buffer in--`display-buffer'. All the higher-level functions
2726 and commands use this subroutine. Here we describe how to use
2727 `display-buffer' and how to customize it.
2729 -- Command: display-buffer buffer-or-name &optional not-this-window
2731 This command makes BUFFER-OR-NAME appear in some window, like
2732 `pop-to-buffer', but it does not select that window and does not
2733 make the buffer current. The identity of the selected window is
2734 unaltered by this function.
2736 BUFFER-OR-NAME can be a buffer or the name of one.
2738 If NOT-THIS-WINDOW is non-`nil', it means to display the specified
2739 buffer in a window other than the selected one, even if it is
2740 already on display in the selected window. This can cause the
2741 buffer to appear in two windows at once. Otherwise, if
2742 BUFFER-OR-NAME is already being displayed in any window, that is
2743 good enough, so this function does nothing.
2745 If OVERRIDE-FRAME is non-`nil', display on that frame instead of
2746 the current frame (or the dedicated frame).
2748 `display-buffer' returns the window chosen to display
2751 Precisely how `display-buffer' finds or creates a window depends on
2752 the variables described below.
2754 A window can be marked as "dedicated" to a particular buffer. Then
2755 XEmacs will not automatically change which buffer appears in the
2756 window, such as `display-buffer' might normally do.
2758 -- Function: window-dedicated-p window
2759 This function returns WINDOW's dedicated object, usually `t' or
2762 -- Function: set-window-buffer-dedicated window buffer
2763 This function makes WINDOW display BUFFER and be dedicated to that
2764 buffer. Then XEmacs will not automatically change which buffer
2765 appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
2766 not be dedicated (but doesn't change which buffer appears in it
2769 -- User Option: pop-up-windows
2770 This variable controls whether `display-buffer' makes new windows.
2771 If it is non-`nil' and there is only one window, then that window
2772 is split. If it is `nil', then `display-buffer' does not split
2773 the single window, but uses it whole.
2775 -- User Option: split-height-threshold
2776 This variable determines when `display-buffer' may split a window,
2777 if there are multiple windows. `display-buffer' always splits the
2778 largest window if it has at least this many lines. If the largest
2779 window is not this tall, it is split only if it is the sole window
2780 and `pop-up-windows' is non-`nil'.
2782 -- User Option: pop-up-frames
2783 This variable controls whether `display-buffer' makes new frames.
2784 If it is non-`nil', `display-buffer' looks for an existing window
2785 already displaying the desired buffer, on any visible frame. If
2786 it finds one, it returns that window. Otherwise it makes a new
2787 frame. The variables `pop-up-windows' and
2788 `split-height-threshold' do not matter if `pop-up-frames' is
2791 If `pop-up-frames' is `nil', then `display-buffer' either splits a
2792 window or reuses one.
2794 *Note Frames::, for more information.
2796 -- Variable: pop-up-frame-function
2797 This variable specifies how to make a new frame if `pop-up-frames'
2800 Its value should be a function of no arguments. When
2801 `display-buffer' makes a new frame, it does so by calling that
2802 function, which should return a frame. The default value of the
2803 variable is a function that creates a frame using properties from
2804 `pop-up-frame-plist'.
2806 -- Variable: pop-up-frame-plist
2807 This variable holds a plist specifying frame properties used when
2808 `display-buffer' makes a new frame. *Note Frame Properties::, for
2809 more information about frame properties.
2811 -- Variable: special-display-buffer-names
2812 A list of buffer names for buffers that should be displayed
2813 specially. If the buffer's name is in this list, `display-buffer'
2814 handles the buffer specially.
2816 By default, special display means to give the buffer a dedicated
2819 If an element is a list, instead of a string, then the CAR of the
2820 list is the buffer name, and the rest of the list says how to
2821 create the frame. There are two possibilities for the rest of the
2822 list. It can be a plist, specifying frame properties, or it can
2823 contain a function and arguments to give to it. (The function's
2824 first argument is always the buffer to be displayed; the arguments
2825 from the list come after that.)
2827 -- Variable: special-display-regexps
2828 A list of regular expressions that specify buffers that should be
2829 displayed specially. If the buffer's name matches any of the
2830 regular expressions in this list, `display-buffer' handles the
2833 By default, special display means to give the buffer a dedicated
2836 If an element is a list, instead of a string, then the CAR of the
2837 list is the regular expression, and the rest of the list says how
2838 to create the frame. See above, under
2839 `special-display-buffer-names'.
2841 -- Variable: special-display-function
2842 This variable holds the function to call to display a buffer
2843 specially. It receives the buffer as an argument, and should
2844 return the window in which it is displayed.
2846 The default value of this variable is
2847 `special-display-popup-frame'.
2849 -- Function: special-display-popup-frame buffer
2850 This function makes BUFFER visible in a frame of its own. If
2851 BUFFER is already displayed in a window in some frame, it makes
2852 the frame visible and raises it, to use that window. Otherwise, it
2853 creates a frame that will be dedicated to BUFFER.
2855 This function uses an existing window displaying BUFFER whether or
2856 not it is in a frame of its own; but if you set up the above
2857 variables in your init file, before BUFFER was created, then
2858 presumably the window was previously made by this function.
2860 -- User Option: special-display-frame-plist
2861 This variable holds frame properties for
2862 `special-display-popup-frame' to use when it creates a frame.
2864 -- Variable: same-window-buffer-names
2865 A list of buffer names for buffers that should be displayed in the
2866 selected window. If the buffer's name is in this list,
2867 `display-buffer' handles the buffer by switching to it in the
2870 -- Variable: same-window-regexps
2871 A list of regular expressions that specify buffers that should be
2872 displayed in the selected window. If the buffer's name matches
2873 any of the regular expressions in this list, `display-buffer'
2874 handles the buffer by switching to it in the selected window.
2876 -- Variable: display-buffer-function
2877 This variable is the most flexible way to customize the behavior of
2878 `display-buffer'. If it is non-`nil', it should be a function
2879 that `display-buffer' calls to do the work. The function should
2880 accept two arguments, the same two arguments that `display-buffer'
2881 received. It should choose or create a window, display the
2882 specified buffer, and then return the window.
2884 This hook takes precedence over all the other options and hooks
2887 A window can be marked as "dedicated" to its buffer. Then
2888 `display-buffer' does not try to use that window.
2890 -- Function: window-dedicated-p window
2891 This function returns `t' if WINDOW is marked as dedicated;
2894 -- Function: set-window-dedicated-p window flag
2895 This function marks WINDOW as dedicated if FLAG is non-`nil', and
2896 nondedicated otherwise.
2899 File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows
2901 38.9 Windows and Point
2902 ======================
2904 Each window has its own value of point, independent of the value of
2905 point in other windows displaying the same buffer. This makes it useful
2906 to have multiple windows showing one buffer.
2908 * The window point is established when a window is first created; it
2909 is initialized from the buffer's point, or from the window point
2910 of another window opened on the buffer if such a window exists.
2912 * Selecting a window sets the value of point in its buffer to the
2913 window's value of point. Conversely, deselecting a window sets
2914 the window's value of point from that of the buffer. Thus, when
2915 you switch between windows that display a given buffer, the point
2916 value for the selected window is in effect in the buffer, while
2917 the point values for the other windows are stored in those windows.
2919 * As long as the selected window displays the current buffer, the
2920 window's point and the buffer's point always move together; they
2923 * *Note Positions::, for more details on buffer positions.
2925 As far as the user is concerned, point is where the cursor is, and
2926 when the user switches to another buffer, the cursor jumps to the
2927 position of point in that buffer.
2929 -- Function: window-point &optional window
2930 This function returns the current position of point in WINDOW.
2931 For a non-selected window, this is the value point would have (in
2932 that window's buffer) if that window were selected.
2934 When WINDOW is the selected window and its buffer is also the
2935 current buffer, the value returned is the same as the value of
2936 point in that buffer.
2938 Strictly speaking, it would be more correct to return the
2939 "top-level" value of point, outside of any `save-excursion' forms.
2940 But that value is hard to find.
2942 -- Function: set-window-point window position
2943 This function positions point in WINDOW at position POSITION in
2947 File: lispref.info, Node: Window Start, Next: Vertical Scrolling, Prev: Window Point, Up: Windows
2949 38.10 The Window Start Position
2950 ===============================
2952 Each window contains a marker used to keep track of a buffer position
2953 that specifies where in the buffer display should start. This position
2954 is called the "display-start" position of the window (or just the
2955 "start"). The character after this position is the one that appears at
2956 the upper left corner of the window. It is usually, but not
2957 inevitably, at the beginning of a text line.
2959 -- Function: window-start &optional window
2960 This function returns the display-start position of window WINDOW.
2961 If WINDOW is `nil', the selected window is used. For example,
2966 When you create a window, or display a different buffer in it, the
2967 display-start position is set to a display-start position recently
2968 used for the same buffer, or 1 if the buffer doesn't have any.
2970 For a realistic example, see the description of `count-lines' in
2973 -- Function: window-end &optional window guarantee
2974 This function returns the position of the end of the display in
2975 window WINDOW. If WINDOW is `nil', the selected window is used.
2977 Simply changing the buffer text or setting `window-start' does not
2978 update the value that `window-end' returns. The value is updated
2979 only when Emacs redisplays and redisplay actually finishes.
2981 If the last redisplay of WINDOW was preempted, and did not finish,
2982 Emacs does not know the position of the end of display in that
2983 window. In that case, this function returns a value that is not
2984 correct. In a future version, `window-end' will return `nil' in
2987 If optional arg GUARANTEE is non-`nil', the return value is
2988 guaranteed to be the same as `window-end' would return at the end
2989 of the next full redisplay assuming nothing else changes in the
2990 meantime. This function is potentially much slower with this flag
2994 -- Function: set-window-start window position &optional noforce
2995 This function sets the display-start position of WINDOW to
2996 POSITION in WINDOW's buffer. It returns POSITION.
2998 The display routines insist that the position of point be visible
2999 when a buffer is displayed. Normally, they change the
3000 display-start position (that is, scroll the window) whenever
3001 necessary to make point visible. However, if you specify the
3002 start position with this function using `nil' for NOFORCE, it
3003 means you want display to start at POSITION even if that would put
3004 the location of point off the screen. If this does place point
3005 off screen, the display routines move point to the left margin on
3006 the middle line in the window.
3008 For example, if point is 1 and you set the start of the window
3009 to 2, then point would be "above" the top of the window. The
3010 display routines will automatically move point if it is still 1
3011 when redisplay occurs. Here is an example:
3013 ;; Here is what `foo' looks like before executing
3014 ;; the `set-window-start' expression.
3016 ---------- Buffer: foo ----------
3017 -!-This is the contents of buffer foo.
3023 ---------- Buffer: foo ----------
3027 (1+ (window-start)))
3030 ;; Here is what `foo' looks like after executing
3031 ;; the `set-window-start' expression.
3032 ---------- Buffer: foo ----------
3033 his is the contents of buffer foo.
3039 ---------- Buffer: foo ----------
3041 If NOFORCE is non-`nil', and POSITION would place point off screen
3042 at the next redisplay, then redisplay computes a new window-start
3043 position that works well with point, and thus POSITION is not used.
3045 -- Function: pos-visible-in-window-p &optional position window
3046 This function returns `t' if POSITION is within the range of text
3047 currently visible on the screen in WINDOW. It returns `nil' if
3048 POSITION is scrolled vertically out of view. The argument
3049 POSITION defaults to the current position of point; WINDOW, to the
3050 selected window. Here is an example:
3052 (or (pos-visible-in-window-p
3053 (point) (selected-window))
3056 The `pos-visible-in-window-p' function considers only vertical
3057 scrolling. If POSITION is out of view only because WINDOW has
3058 been scrolled horizontally, `pos-visible-in-window-p' returns `t'.
3059 *Note Horizontal Scrolling::.
3062 File: lispref.info, Node: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Window Start, Up: Windows
3064 38.11 Vertical Scrolling
3065 ========================
3067 Vertical scrolling means moving the text up or down in a window. It
3068 works by changing the value of the window's display-start location. It
3069 may also change the value of `window-point' to keep it on the screen.
3071 In the commands `scroll-up' and `scroll-down', the directions "up"
3072 and "down" refer to the motion of the text in the buffer at which you
3073 are looking through the window. Imagine that the text is written on a
3074 long roll of paper and that the scrolling commands move the paper up
3075 and down. Thus, if you are looking at text in the middle of a buffer
3076 and repeatedly call `scroll-down', you will eventually see the
3077 beginning of the buffer.
3079 Some people have urged that the opposite convention be used: they
3080 imagine that the window moves over text that remains in place. Then
3081 "down" commands would take you to the end of the buffer. This view is
3082 more consistent with the actual relationship between windows and the
3083 text in the buffer, but it is less like what the user sees. The
3084 position of a window on the terminal does not move, and short scrolling
3085 commands clearly move the text up or down on the screen. We have chosen
3086 names that fit the user's point of view.
3088 The scrolling functions (aside from `scroll-other-window') have
3089 unpredictable results if the current buffer is different from the buffer
3090 that is displayed in the selected window. *Note Current Buffer::.
3092 -- Command: scroll-up &optional lines
3093 This function scrolls the text in the selected window upward LINES
3094 lines. If LINES is negative, scrolling is actually downward.
3096 If LINES is `nil' (or omitted), then the length of scroll is
3097 `next-screen-context-lines' lines less than the usable height of
3098 the window (not counting its modeline).
3100 `scroll-up' returns `nil'.
3102 -- Command: scroll-down &optional lines
3103 This function scrolls the text in the selected window downward
3104 LINES lines. If LINES is negative, scrolling is actually upward.
3106 If LINES is omitted or `nil', then the length of the scroll is
3107 `next-screen-context-lines' lines less than the usable height of
3108 the window (not counting its mode line).
3110 `scroll-down' returns `nil'.
3112 -- Command: scroll-other-window &optional lines
3113 This function scrolls the text in another window upward LINES
3114 lines. Negative values of LINES, or `nil', are handled as in
3117 You can specify a buffer to scroll with the variable
3118 `other-window-scroll-buffer'. When the selected window is the
3119 minibuffer, the next window is normally the one at the top left
3120 corner. You can specify a different window to scroll with the
3121 variable `minibuffer-scroll-window'. This variable has no effect
3122 when any other window is selected. *Note Minibuffer Misc::.
3124 When the minibuffer is active, it is the next window if the
3125 selected window is the one at the bottom right corner. In this
3126 case, `scroll-other-window' attempts to scroll the minibuffer. If
3127 the minibuffer contains just one line, it has nowhere to scroll
3128 to, so the line reappears after the echo area momentarily displays
3129 the message "Beginning of buffer".
3131 -- Variable: other-window-scroll-buffer
3132 If this variable is non-`nil', it tells `scroll-other-window'
3133 which buffer to scroll.
3135 -- User Option: scroll-step
3136 This variable controls how scrolling is done automatically when
3137 point moves off the screen. If the value is zero, then redisplay
3138 scrolls the text to center point vertically in the window. If the
3139 value is a positive integer N, then redisplay brings point back on
3140 screen by scrolling N lines in either direction, if possible;
3141 otherwise, it centers point. The default value is zero.
3143 -- User Option: scroll-conservatively
3144 This variable controls how many lines Emacs tries to scroll before
3145 recentering. If you set it to a small number, then when you move
3146 point a short distance off the screen, XEmacs will scroll the
3147 screen just far enough to bring point back on screen, provided
3148 that does not exceed `scroll-conservatively' lines. This variable
3149 overrides the redisplay preemption.
3151 -- User Option: next-screen-context-lines
3152 The value of this variable is the number of lines of continuity to
3153 retain when scrolling by full screens. For example, `scroll-up'
3154 with an argument of `nil' scrolls so that this many lines at the
3155 bottom of the window appear instead at the top. The default value
3158 -- Command: recenter &optional location window
3159 This function scrolls WINDOW (which defaults to the selected
3160 window) to put the text where point is located at a specified
3161 vertical position within the window.
3163 If LOCATION is a nonnegative number, it puts the line containing
3164 point LOCATION lines down from the top of the window. If LOCATION
3165 is a negative number, then it counts upward from the bottom of the
3166 window, so that -1 stands for the last usable line in the window.
3167 If LOCATION is a non-`nil' list, then it stands for the line in
3168 the middle of the window.
3170 If LOCATION is `nil', `recenter' puts the line containing point in
3171 the middle of the window, then clears and redisplays the entire
3174 When `recenter' is called interactively, LOCATION is the raw
3175 prefix argument. Thus, typing `C-u' as the prefix sets the
3176 LOCATION to a non-`nil' list, while typing `C-u 4' sets LOCATION
3177 to 4, which positions the current line four lines from the top.
3179 With an argument of zero, `recenter' positions the current line at
3180 the top of the window. This action is so handy that some people
3181 make a separate key binding to do this. For example,
3183 (defun line-to-top-of-window ()
3184 "Scroll current line to top of window.
3185 Replaces three keystroke sequence C-u 0 C-l."
3189 (global-set-key [kp-multiply] 'line-to-top-of-window)
3192 File: lispref.info, Node: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows
3194 38.12 Horizontal Scrolling
3195 ==========================
3197 Because we read English first from top to bottom and second from left
3198 to right, horizontal scrolling is not like vertical scrolling. Vertical
3199 scrolling involves selection of a contiguous portion of text to display.
3200 Horizontal scrolling causes part of each line to go off screen. The
3201 amount of horizontal scrolling is therefore specified as a number of
3202 columns rather than as a position in the buffer. It has nothing to do
3203 with the display-start position returned by `window-start'.
3205 Usually, no horizontal scrolling is in effect; then the leftmost
3206 column is at the left edge of the window. In this state, scrolling to
3207 the right is meaningless, since there is no data to the left of the
3208 screen to be revealed by it; so this is not allowed. Scrolling to the
3209 left is allowed; it scrolls the first columns of text off the edge of
3210 the window and can reveal additional columns on the right that were
3211 truncated before. Once a window has a nonzero amount of leftward
3212 horizontal scrolling, you can scroll it back to the right, but only so
3213 far as to reduce the net horizontal scroll to zero. There is no limit
3214 to how far left you can scroll, but eventually all the text will
3215 disappear off the left edge.
3217 -- Command: scroll-left &optional count
3218 This function scrolls the selected window COUNT columns to the
3219 left (or to the right if COUNT is negative). The return value is
3220 the total amount of leftward horizontal scrolling in effect after
3221 the change--just like the value returned by `window-hscroll'
3224 -- Command: scroll-right &optional count
3225 This function scrolls the selected window COUNT columns to the
3226 right (or to the left if COUNT is negative). The return value is
3227 the total amount of leftward horizontal scrolling in effect after
3228 the change--just like the value returned by `window-hscroll'
3231 Once you scroll a window as far right as it can go, back to its
3232 normal position where the total leftward scrolling is zero,
3233 attempts to scroll any farther right have no effect.
3235 -- Function: window-hscroll &optional window
3236 This function returns the total leftward horizontal scrolling of
3237 WINDOW--the number of columns by which the text in WINDOW is
3238 scrolled left past the left margin.
3240 The value is never negative. It is zero when no horizontal
3241 scrolling has been done in WINDOW (which is usually the case).
3243 If WINDOW is `nil', the selected window is used.
3252 -- Function: set-window-hscroll window columns
3253 This function sets the number of columns from the left margin that
3254 WINDOW is scrolled to the value of COLUMNS. The argument COLUMNS
3255 should be zero or positive; if not, it is taken as zero.
3257 The value returned is COLUMNS.
3259 (set-window-hscroll (selected-window) 10)
3262 Here is how you can determine whether a given position POSITION is
3263 off the screen due to horizontal scrolling:
3265 (defun hscroll-on-screen (window position)
3267 (goto-char position)
3269 (>= (- (current-column) (window-hscroll window)) 0)
3270 (< (- (current-column) (window-hscroll window))
3271 (window-width window)))))
3274 File: lispref.info, Node: Size of Window, Next: Position of Window, Prev: Horizontal Scrolling, Up: Windows
3276 38.13 The Size of a Window
3277 ==========================
3279 An Emacs window is rectangular, and its size information consists of
3280 the height (in lines or pixels) and the width (in character positions
3281 or pixels). The modeline is included in the height. The pixel width
3282 and height values include scrollbars and margins, while the
3283 line/character-position values do not.
3285 Note that the height in lines, and the width in characters, are
3286 determined by dividing the corresponding pixel value by the height or
3287 width of the default font in that window (if this is a variable-width
3288 font, the average width is used). The resulting values may or may not
3289 represent the actual number of lines in the window, or the actual number
3290 of character positions in any particular line, esp. if there are pixmaps
3291 or various different fonts in the window.
3293 The following functions return size information about a window:
3295 -- Function: window-height &optional window
3296 This function returns the number of lines in WINDOW, including its
3297 modeline but not including the horizontal scrollbar, if any (this
3298 is different from `window-pixel-height'). If WINDOW is `nil', the
3299 function uses the selected window.
3303 (split-window-vertically)
3304 => #<window on "windows.texi" 0x679b>
3308 -- Function: window-width &optional window
3309 This function returns the number of columns in WINDOW, not
3310 including any left margin, right margin, or vertical scrollbar
3311 (this is different from `window-pixel-width'). If WINDOW is
3312 `nil', the function uses the selected window.
3318 (split-window-horizontally)
3319 => #<window on "windows.texi" 0x7538>
3323 Note that after splitting the window into two side-by-side windows,
3324 the width of each window is less the half the width of the original
3325 window because a vertical scrollbar appeared between the windows,
3326 occupying two columns worth of space. Also, the height shrunk by one
3327 because horizontal scrollbars appeared that weren't there before.
3328 (Horizontal scrollbars appear only when lines are truncated, not when
3329 they wrap. This is usually the case for horizontally split windows but
3330 not for full-frame windows. You can change this using the variables
3331 `truncate-lines' and `truncate-partial-width-windows'.)
3333 -- Function: window-pixel-height &optional window
3334 This function returns the height of WINDOW in pixels, including
3335 its modeline and horizontal scrollbar, if any. If WINDOW is
3336 `nil', the function uses the selected window.
3338 (window-pixel-height)
3340 (split-window-vertically)
3341 => #<window on "windows.texi" 0x68a6>
3342 (window-pixel-height)
3345 -- Function: window-pixel-width &optional window
3346 This function returns the width of WINDOW in pixels, including any
3347 left margin, right margin, or vertical scrollbar that may be
3348 displayed alongside it. If WINDOW is `nil', the function uses the
3351 (window-pixel-width)
3353 (window-pixel-height)
3355 (split-window-horizontally)
3356 => #<window on "windows.texi" 0x7538>
3357 (window-pixel-width)
3359 (window-pixel-height)
3362 -- Function: window-text-area-pixel-height &optional window
3363 This function returns the height in pixels of the text displaying
3364 portion of WINDOW, which defaults to the selected window. Unlike
3365 `window-pixel-height', the space occupied by the modeline and
3366 horizontal scrollbar, if any, is not counted.
3368 -- Function: window-text-area-pixel-width &optional window
3369 This function returns the width in pixels of the text displaying
3370 portion of WINDOW, which defaults to the selected window. Unlike
3371 `window-pixel-width', the space occupied by the vertical scrollbar
3372 and divider, if any, is not counted.
3374 -- Function: window-displayed-text-pixel-height &optional window
3376 This function returns the height in pixels of the text displayed in
3377 WINDOW, which defaults to the selected window. Unlike
3378 `window-text-area-pixel-height', any blank space below the end of
3379 the buffer is not included. If optional argument NOCLIPPED is
3380 non-`nil', any space occupied by clipped lines will not be
3384 File: lispref.info, Node: Position of Window, Next: Resizing Windows, Prev: Size of Window, Up: Windows
3386 38.14 The Position of a Window
3387 ==============================
3389 XEmacs provides functions to determine the absolute location of windows
3390 within a frame, and the relative location of a window in comparison to
3391 other windows in the same frame.
3393 -- Function: window-pixel-edges &optional window
3394 This function returns a list of the pixel edge coordinates of
3395 WINDOW. If WINDOW is `nil', the selected window is used.
3397 The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements
3398 relative to 0, 0 at the top left corner of WINDOW's frame. The
3399 element RIGHT of the value is one more than the rightmost pixel
3400 used by WINDOW (including any left margin, right margin, or
3401 vertical scrollbar displayed alongside it), and BOTTOM is one more
3402 than the bottommost pixel used by WINDOW (including any modeline
3403 or horizontal scrollbar displayed above or below it). The frame
3404 area does not include any frame menubars, toolbars, or gutters
3405 that may be displayed; thus, for example, if there is only one
3406 window on the frame, the values for LEFT and TOP will always be 0.
3408 If WINDOW is at the upper left corner of its frame, RIGHT and
3409 BOTTOM are the same as the values returned by
3410 `(window-pixel-width)' and `(window-pixel-height)' respectively,
3411 and LEFT and TOP are zero.
3413 There is no longer a function `window-edges' because it does not
3414 make sense in a world with variable-width and variable-height lines, as
3415 are allowed in XEmacs.
3417 -- Function: window-highest-p window
3418 This function returns non-`nil' if WINDOW is along the top of its
3421 -- Function: window-lowest-p window
3422 This function returns non-`nil' if WINDOW is along the bottom of
3425 -- Function: window-text-area-pixel-edges &optional window
3426 This function allows one to determine the location of the
3427 text-displaying portion of WINDOW, which defaults to the selected
3428 window, with respect to the top left corner of the window. It
3429 returns a list of integer pixel positions `(left top right
3430 bottom)', all relative to `(0,0)' at the top left corner of the
3434 File: lispref.info, Node: Resizing Windows, Next: Window Configurations, Prev: Position of Window, Up: Windows
3436 38.15 Changing the Size of a Window
3437 ===================================
3439 The window size functions fall into two classes: high-level commands
3440 that change the size of windows and low-level functions that access
3441 window size. XEmacs does not permit overlapping windows or gaps between
3442 windows, so resizing one window affects other windows.
3444 -- Command: enlarge-window count &optional horizontal window
3445 This function makes the selected window COUNT lines taller,
3446 stealing lines from neighboring windows. It takes the lines from
3447 one window at a time until that window is used up, then takes from
3448 another. If a window from which lines are stolen shrinks below
3449 `window-min-height' lines, that window disappears.
3451 If HORIZONTAL is non-`nil', this function makes WINDOW wider by
3452 COUNT columns, stealing columns instead of lines. If a window
3453 from which columns are stolen shrinks below `window-min-width'
3454 columns, that window disappears.
3456 If the requested size would exceed that of the window's frame,
3457 then the function makes the window occupy the entire height (or
3458 width) of the frame.
3460 If COUNT is negative, this function shrinks the window by -COUNT
3461 lines or columns. If that makes the window smaller than the
3462 minimum size (`window-min-height' and `window-min-width'),
3463 `enlarge-window' deletes the window.
3465 If WINDOW is non-`nil', it specifies a window to change instead of
3466 the selected window.
3468 `enlarge-window' returns `nil'.
3470 -- Command: enlarge-window-horizontally columns
3471 This function makes the selected window COLUMNS wider. It could
3472 be defined as follows:
3474 (defun enlarge-window-horizontally (columns)
3475 (enlarge-window columns t))
3477 -- Command: enlarge-window-pixels count &optional side window
3478 This function makes the selected window COUNT pixels larger. When
3479 called from Lisp, optional second argument SIDE non-`nil' means to
3480 grow sideways COUNT pixels, and optional third argument WINDOW
3481 specifies the window to change instead of the selected window.
3483 -- Command: shrink-window count &optional horizontal window
3484 This function is like `enlarge-window' but negates the argument
3485 COUNT, making the selected window smaller by giving lines (or
3486 columns) to the other windows. If the window shrinks below
3487 `window-min-height' or `window-min-width', then it disappears.
3489 If COUNT is negative, the window is enlarged by -COUNT lines or
3492 If WINDOW is non-`nil', it specifies a window to change instead of
3493 the selected window.
3495 -- Command: shrink-window-horizontally columns
3496 This function makes the selected window COLUMNS narrower. It
3497 could be defined as follows:
3499 (defun shrink-window-horizontally (columns)
3500 (shrink-window columns t))
3502 -- Command: shrink-window-pixels count &optional side window
3503 This function makes the selected window COUNT pixels smaller.
3504 When called from Lisp, optional second argument SIDE non-`nil'
3505 means to shrink sideways COUNT pixels, and optional third argument
3506 WINDOW specifies the window to change instead of the selected
3509 The following two variables constrain the window-size-changing
3510 functions to a minimum height and width.
3512 -- User Option: window-min-height
3513 The value of this variable determines how short a window may become
3514 before it is automatically deleted. Making a window smaller than
3515 `window-min-height' automatically deletes it, and no window may be
3516 created shorter than this. The absolute minimum height is two
3517 (allowing one line for the mode line, and one line for the buffer
3518 display). Actions that change window sizes reset this variable to
3519 two if it is less than two. The default value is 4.
3521 -- User Option: window-min-width
3522 The value of this variable determines how narrow a window may
3523 become before it automatically deleted. Making a window smaller
3524 than `window-min-width' automatically deletes it, and no window
3525 may be created narrower than this. The absolute minimum width is
3526 one; any value below that is ignored. The default value is 10.
3528 -- Variable: window-size-change-functions
3529 This variable holds a list of functions to be called if the size
3530 of any window changes for any reason. The functions are called
3531 just once per redisplay, and just once for each frame on which
3532 size changes have occurred.
3534 Each function receives the frame as its sole argument. There is no
3535 direct way to find out which windows changed size, or precisely
3536 how; however, if your size-change function keeps track, after each
3537 change, of the windows that interest you, you can figure out what
3538 has changed by comparing the old size data with the new.
3540 Creating or deleting windows counts as a size change, and therefore
3541 causes these functions to be called. Changing the frame size also
3542 counts, because it changes the sizes of the existing windows.
3544 It is not a good idea to use `save-window-excursion' in these
3545 functions, because that always counts as a size change, and it
3546 would cause these functions to be called over and over. In most
3547 cases, `save-selected-window' is what you need here.
3550 File: lispref.info, Node: Window Configurations, Prev: Resizing Windows, Up: Windows
3552 38.16 Window Configurations
3553 ===========================
3555 A "window configuration" records the entire layout of a frame--all
3556 windows, their sizes, which buffers they contain, what part of each
3557 buffer is displayed, and the values of point and the mark. You can
3558 bring back an entire previous layout by restoring a window
3559 configuration previously saved.
3561 If you want to record all frames instead of just one, use a frame
3562 configuration instead of a window configuration. *Note Frame
3565 -- Function: current-window-configuration &optional frame
3566 This function returns a new object representing the current window
3567 configuration of FRAME, namely the number of windows, their sizes
3568 and current buffers, which window is the selected window, and for
3569 each window the displayed buffer, the display-start position, and
3570 the positions of point and the mark. An exception is made for
3571 point in the current buffer, whose value is not saved.
3573 FRAME defaults to the selected frame.
3575 -- Function: set-window-configuration configuration
3576 This function restores the configuration of XEmacs's windows and
3577 buffers to the state specified by CONFIGURATION. The argument
3578 CONFIGURATION must be a value that was previously returned by
3579 `current-window-configuration'.
3581 This function always counts as a window size change and triggers
3582 execution of the `window-size-change-functions'. (It doesn't know
3583 how to tell whether the new configuration actually differs from
3586 Here is a way of using this function to get the same effect as
3587 `save-window-excursion':
3589 (let ((config (current-window-configuration)))
3591 (progn (split-window-vertically nil)
3593 (set-window-configuration config)))
3595 -- Special Form: save-window-excursion forms...
3596 This special form records the window configuration, executes FORMS
3597 in sequence, then restores the earlier window configuration. The
3598 window configuration includes the value of point and the portion
3599 of the buffer that is visible. It also includes the choice of
3600 selected window. However, it does not include the value of point
3601 in the current buffer; use `save-excursion' if you wish to
3604 Don't use this construct when `save-selected-window' is all you
3607 Exit from `save-window-excursion' always triggers execution of the
3608 `window-size-change-functions'. (It doesn't know how to tell
3609 whether the restored configuration actually differs from the one in
3610 effect at the end of the FORMS.)
3612 The return value is the value of the final form in FORMS. For
3616 => #<window 25 on control.texi>
3617 (setq w (selected-window))
3618 => #<window 19 on control.texi>
3619 (save-window-excursion
3620 (delete-other-windows w)
3621 (switch-to-buffer "foo")
3624 ;; The frame is now split again.
3626 -- Function: window-configuration-p object
3627 This function returns `t' if OBJECT is a window configuration.
3629 Primitives to look inside of window configurations would make sense,
3630 but none are implemented. It is not clear they are useful enough to be
3634 File: lispref.info, Node: Frames, Next: Consoles and Devices, Prev: Windows, Up: Top
3639 A FRAME is a rectangle on the screen that contains one or more XEmacs
3640 windows (*note Windows::). A frame initially contains a single main
3641 window (plus perhaps an echo area), which you can subdivide vertically
3642 or horizontally into smaller windows. Each window is associated with a
3643 modeline (*note Modeline Format::), and optionally two scrollbars
3644 (*note Scrollbars::). By default the vertical scrollbar is on, the
3645 horizontal scrollbar is off.
3647 The frame may also contain menubars (*note Menubar::), toolbars
3648 (*note Toolbar Intro::), and gutters (*note Gutter Intro::). By default
3649 there is one of each at the top of the frame, with menubar topmost,
3650 toolbar next, and gutter lowest, immediately above the windows.
3651 (Warning: the gutter is a new, experimental, and unstable feature of
3652 XEmacs version 21.2.)
3654 When XEmacs runs on a text-only terminal, it starts with one "TTY
3655 frame". If you create additional ones, XEmacs displays one and only
3656 one at any given time--on the terminal screen, of course.
3658 When XEmacs communicates directly with an X server, it does not have
3659 a TTY frame; instead, it starts with a single "X window frame". It can
3660 display multiple X window frames at the same time, each in its own X
3663 -- Function: framep object
3664 This predicate returns `t' if OBJECT is a frame, and `nil'
3669 * Creating Frames:: Creating additional frames.
3670 * Frame Properties:: Controlling frame size, position, font, etc.
3671 * Frame Titles:: Automatic updating of frame titles.
3672 * Deleting Frames:: Frames last until explicitly deleted.
3673 * Finding All Frames:: How to examine all existing frames.
3674 * Frames and Windows:: A frame contains windows;
3675 display of text always works through windows.
3676 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
3677 * Input Focus:: Specifying the selected frame.
3678 * Visibility of Frames:: Frames may be visible or invisible, or icons.
3679 * Raising and Lowering:: Raising a frame makes it hide other X windows;
3680 lowering it makes the others hide them.
3681 * Frame Configurations:: Saving the state of all frames.
3682 * Frame Hooks:: Hooks for customizing frame behavior.
3684 *Note Display::, for related information.
3687 File: lispref.info, Node: Creating Frames, Next: Frame Properties, Up: Frames
3689 39.1 Creating Frames
3690 ====================
3692 To create a new frame, call the function `make-frame'.
3694 -- Command: make-frame &optional props device
3695 This function creates a new frame on DEVICE, if DEVICE permits
3696 creation of frames. (An X server does; an ordinary terminal does
3697 not (yet).) DEVICE defaults to the selected device if omitted.
3698 *Note Consoles and Devices::.
3700 The argument PROPS is a property list (a list of alternating
3701 keyword-value specifications) of properties for the new frame. (An
3702 alist is accepted for backward compatibility but should not be
3703 passed in.) Any properties not mentioned in PROPS default
3704 according to the value of the variable `default-frame-plist'. For
3705 X devices, properties not specified in `default-frame-plist'
3706 default in turn from `default-x-frame-plist' and, if not specified
3707 there, from the X resources. For TTY devices,
3708 `default-tty-frame-plist' is consulted as well as
3709 `default-frame-plist'.
3711 The set of possible properties depends in principle on what kind of
3712 window system XEmacs uses to display its frames. *Note X Frame
3713 Properties::, for documentation of individual properties you can
3714 specify when creating an X window frame.
3717 File: lispref.info, Node: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames
3719 39.2 Frame Properties
3720 =====================
3722 A frame has many properties that control its appearance and behavior.
3723 Just what properties a frame has depends on which display mechanism it
3726 Frame properties exist for the sake of window systems. A terminal
3727 frame has few properties, mostly for compatibility's sake; only the
3728 height, width and `buffer-predicate' properties really do something.
3732 * Property Access:: How to change a frame's properties.
3733 * Initial Properties:: Specifying frame properties when you make a frame.
3734 * X Frame Properties:: List of frame properties.
3735 * Size and Position:: Changing the size and position of a frame.
3736 * Frame Name:: The name of a frame (as opposed to its title).
3739 File: lispref.info, Node: Property Access, Next: Initial Properties, Up: Frame Properties
3741 39.2.1 Access to Frame Properties
3742 ---------------------------------
3744 These functions let you read and change the properties of a frame.
3746 -- Function: frame-properties &optional frame
3747 This function returns a plist listing all the properties of FRAME
3750 -- Function: frame-property frame property &optional default
3751 This function returns FRAME's value for the property PROPERTY, or
3752 DEFAULT if there is no such property.
3754 -- Function: set-frame-properties frame plist
3755 This function alters the properties of frame FRAME based on the
3756 elements of property list PLIST. If you don't mention a property
3757 in PLIST, its value doesn't change.
3759 -- Function: set-frame-property frame property value
3760 This function sets the property PROPERTY of frame FRAME to the
3764 File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties
3766 39.2.2 Initial Frame Properties
3767 -------------------------------
3769 You can specify the properties for the initial startup frame by setting
3770 `initial-frame-plist' in your `.emacs' file.
3772 -- Variable: initial-frame-plist
3773 This variable's value is a plist of alternating property-value
3774 pairs used when creating the initial X window frame.
3776 XEmacs creates the initial frame before it reads your `~/.emacs'
3777 file. After reading that file, XEmacs checks
3778 `initial-frame-plist', and applies the property settings in the
3779 altered value to the already created initial frame.
3781 If these settings affect the frame geometry and appearance, you'll
3782 see the frame appear with the wrong ones and then change to the
3783 specified ones. If that bothers you, you can specify the same
3784 geometry and appearance with X resources; those do take affect
3785 before the frame is created. *Note X Resources: (xemacs)Resources
3788 X resource settings typically apply to all frames. If you want to
3789 specify some X resources solely for the sake of the initial frame,
3790 and you don't want them to apply to subsequent frames, here's how
3791 to achieve this: specify properties in `default-frame-plist' to
3792 override the X resources for subsequent frames; then, to prevent
3793 these from affecting the initial frame, specify the same
3794 properties in `initial-frame-plist' with values that match the X
3797 If these properties specify a separate minibuffer-only frame via a
3798 `minibuffer' property of `nil', and you have not yet created one,
3799 XEmacs creates one for you.
3801 -- Variable: minibuffer-frame-plist
3802 This variable's value is a plist of properties used when creating
3803 an initial minibuffer-only frame--if such a frame is needed,
3804 according to the properties for the main initial frame.
3806 -- Variable: default-frame-plist
3807 This is a plist specifying default values of frame properties for
3808 subsequent XEmacs frames (not the initial ones).
3810 See also `special-display-frame-plist', in *Note Choosing Window::.
3812 If you use options that specify window appearance when you invoke
3813 XEmacs, they take effect by adding elements to `default-frame-plist'.
3814 One exception is `-geometry', which adds the specified position to
3815 `initial-frame-plist' instead. *Note Command Arguments:
3816 (xemacs)Command Arguments.
3819 File: lispref.info, Node: X Frame Properties, Next: Size and Position, Prev: Initial Properties, Up: Frame Properties
3821 39.2.3 X Window Frame Properties
3822 --------------------------------
3824 Just what properties a frame has depends on what display mechanism it
3825 uses. Here is a table of the properties of an X window frame; of these,
3826 `name', `height', `width', and `buffer-predicate' provide meaningful
3827 information in non-X frames.
3830 The name of the frame. Most window managers display the frame's
3831 name in the frame's border, at the top of the frame. If you don't
3832 specify a name, and you have more than one frame, XEmacs sets the
3833 frame name based on the buffer displayed in the frame's selected
3836 If you specify the frame name explicitly when you create the
3837 frame, the name is also used (instead of the name of the XEmacs
3838 executable) when looking up X resources for the frame.
3841 The display on which to open this frame. It should be a string of
3842 the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
3846 The screen position of the left edge, in pixels, with respect to
3847 the left edge of the screen. The value may be a positive number
3848 POS, or a list of the form `(+ POS)' which permits specifying a
3851 A negative number -POS, or a list of the form `(- POS)', actually
3852 specifies the position of the right edge of the window with
3853 respect to the right edge of the screen. A positive value of POS
3854 counts toward the left. If the property is a negative integer
3855 -POS then POS is positive!
3858 The screen position of the top edge, in pixels, with respect to the
3859 top edge of the screen. The value may be a positive number POS,
3860 or a list of the form `(+ POS)' which permits specifying a
3863 A negative number -POS, or a list of the form `(- POS)', actually
3864 specifies the position of the bottom edge of the window with
3865 respect to the bottom edge of the screen. A positive value of POS
3866 counts toward the top. If the property is a negative integer -POS
3867 then POS is positive!
3870 The screen position of the left edge _of the frame's icon_, in
3871 pixels, counting from the left edge of the screen. This takes
3872 effect if and when the frame is iconified.
3875 The screen position of the top edge _of the frame's icon_, in
3876 pixels, counting from the top edge of the screen. This takes
3877 effect if and when the frame is iconified.
3880 Non-`nil' if the screen position of the frame was explicitly
3881 requested by the user (for example, with the `-geometry' option).
3882 Nothing automatically makes this property non-`nil'; it is up to
3883 Lisp programs that call `make-frame' to specify this property as
3884 well as specifying the `left' and `top' properties.
3887 The height of the frame contents, in characters. (To get the
3888 height in pixels, call `frame-pixel-height'; see *Note Size and
3892 The width of the frame contents, in characters. (To get the
3893 height in pixels, call `frame-pixel-width'; see *Note Size and
3897 The number of the X window for the frame.
3900 Whether this frame has its own minibuffer. The value `t' means
3901 yes, `nil' means no, `only' means this frame is just a minibuffer.
3902 If the value is a minibuffer window (in some other frame), the
3903 new frame uses that minibuffer. (Minibuffer-only and
3904 minibuffer-less frames are not yet implemented in XEmacs.)
3907 The buffer-predicate function for this frame. The function
3908 `other-buffer' uses this predicate (from the selected frame) to
3909 decide which buffers it should consider, if the predicate is not
3910 `nil'. It calls the predicate with one arg, a buffer, once for
3911 each buffer; if the predicate returns a non-`nil' value, it
3912 considers that buffer.
3915 The width of the vertical scroll bar, in pixels.
3918 The color for the cursor that shows point.
3921 The color for the border of the frame.
3924 The width in pixels of the window border.
3926 `internal-border-width'
3927 The distance in pixels between text and border.
3930 If non-`nil', this frame's window is never split automatically.
3933 The space in pixels between adjacent lines of text. (Not currently
3937 Whether the frame has a modeline.
3940 File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Properties, Up: Frame Properties
3942 39.2.4 Frame Size And Position
3943 ------------------------------
3945 You can read or change the size and position of a frame using the frame
3946 properties `left', `top', `height', and `width'. Whatever geometry
3947 properties you don't specify are chosen by the window manager in its
3950 Here are some special features for working with sizes and positions:
3952 -- Function: set-frame-position frame left top
3953 This function sets the position of the top left corner of FRAME to
3954 LEFT and TOP. These arguments are measured in pixels, and count
3955 from the top left corner of the screen. Negative property values
3956 count up or rightward from the top left corner of the screen.
3958 -- Function: frame-height &optional frame
3959 -- Function: frame-width &optional frame
3960 These functions return the height and width of FRAME, measured in
3961 lines and columns. If you don't supply FRAME, they use the
3964 -- Function: frame-pixel-height &optional frame
3965 -- Function: frame-pixel-width &optional frame
3966 These functions return the height and width of FRAME, measured in
3967 pixels. If you don't supply FRAME, they use the selected frame.
3969 -- Function: set-frame-size frame cols rows &optional pretend
3970 This function sets the size of FRAME, measured in characters; COLS
3971 and ROWS specify the new width and height. (If PRETEND is
3972 non-`nil', it means that redisplay should act as if the frame's
3973 size is COLS by ROWS, but the actual size of the frame should not
3974 be changed. You should not normally use this option.)
3976 You can also use the functions `set-frame-height' and
3977 `set-frame-width' to set the height and width individually. The frame
3978 is the first argument and the size (in rows or columns) is the second.
3979 (There is an optional third argument, PRETEND, which has the same
3980 purpose as the corresponding argument in `set-frame-size'.)
3983 File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Properties
3985 39.2.5 The Name of a Frame (As Opposed to Its Title)
3986 ----------------------------------------------------
3988 Under X, every frame has a name, which is not the same as the title of
3989 the frame. A frame's name is used to look up its resources and does
3990 not normally change over the lifetime of a frame. It is perfectly
3991 allowable, and quite common, for multiple frames to have the same name.
3993 -- Function: frame-name &optional frame
3994 This function returns the name of FRAME, which defaults to the
3995 selected frame if not specified. The name of a frame can also be
3996 obtained from the frame's properties. *Note Frame Properties::.
3998 -- Variable: default-frame-name
3999 This variable holds the default name to assign to newly-created
4000 frames. This can be overridden by arguments to `make-frame'. This
4004 File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
4009 Every frame has a title; most window managers display the frame title at
4010 the top of the frame. You can specify an explicit title with the
4011 `name' frame property. But normally you don't specify this explicitly,
4012 and XEmacs computes the title automatically.
4014 XEmacs computes the frame title based on a template stored in the
4015 variable `frame-title-format'.
4017 -- Variable: frame-title-format
4018 This variable specifies how to compute a title for a frame when
4019 you have not explicitly specified one.
4021 The variable's value is actually a modeline construct, just like
4022 `modeline-format'. *Note Modeline Data::.
4024 -- Variable: frame-icon-title-format
4025 This variable specifies how to compute the title for an iconified
4026 frame, when you have not explicitly specified the frame title.
4027 This title appears in the icon itself.
4029 -- Function: x-set-frame-icon-pixmap frame pixmap &optional mask
4030 This function sets the icon of the given frame to the given image
4031 instance, which should be an image instance object (as returned by
4032 `make-image-instance'), a glyph object (as returned by
4033 `make-glyph'), or `nil'. If a glyph object is given, the glyph
4034 will be instantiated on the frame to produce an image instance
4037 If the given image instance has a mask, that will be used as the
4038 icon mask; however, not all window managers support this.
4040 The window manager is also not required to support color pixmaps,
4041 only bitmaps (one plane deep).
4043 If the image instance does not have a mask, then the optional
4044 third argument may be the image instance to use as the mask (it
4045 must be one plane deep). *Note Glyphs::.
4048 File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
4050 39.4 Deleting Frames
4051 ====================
4053 Frames remain potentially visible until you explicitly "delete" them.
4054 A deleted frame cannot appear on the screen, but continues to exist as
4055 a Lisp object until there are no references to it.
4057 -- Command: delete-frame &optional frame force
4058 This function deletes the frame FRAME. By default, FRAME is the
4061 A frame may not be deleted if its minibuffer is used by other
4062 frames. Normally, you cannot delete the last non-minibuffer-only
4063 frame (you must use `save-buffers-kill-emacs' or `kill-emacs').
4064 However, if optional second argument FORCE is non-`nil', you can
4065 delete the last frame. (This will automatically call
4066 `save-buffers-kill-emacs'.)
4068 -- Function: frame-live-p frame
4069 The function `frame-live-p' returns non-`nil' if the frame FRAME
4070 has not been deleted.
4073 File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
4075 39.5 Finding All Frames
4076 =======================
4078 -- Function: frame-list
4079 The function `frame-list' returns a list of all the frames that
4080 have not been deleted. It is analogous to `buffer-list' for
4081 buffers. The list that you get is newly created, so modifying the
4082 list doesn't have any effect on the internals of XEmacs.
4084 -- Function: device-frame-list &optional device
4085 This function returns a list of all frames on DEVICE. If DEVICE
4086 is `nil', the selected device will be used.
4088 -- Function: visible-frame-list &optional device
4089 This function returns a list of just the currently visible frames.
4090 If DEVICE is specified only frames on that device will be returned.
4091 *Note Visibility of Frames::. (TTY frames always count as
4092 "visible", even though only the selected one is actually
4095 -- Function: next-frame &optional frame which-frames which-devices
4096 The function `next-frame' lets you cycle conveniently through all
4097 the frames from an arbitrary starting point. It returns the "next"
4098 frame after FRAME in the cycle. If FRAME defaults to the selected
4101 The second argument, WHICH-FRAMES, says which frames to consider:
4104 Consider only frames that are visible.
4107 Consider only frames that are iconic.
4110 Consider only frames that are invisible (this is different
4114 Consider frames that are visible or iconic.
4117 Consider frames that are invisible or iconic.
4120 Consider all frames except minibuffer-only ones.
4123 Like `visible' but omits minibuffer-only frames.
4126 Like `iconic' but omits minibuffer-only frames.
4129 Like `invisible' but omits minibuffer-only frames.
4131 `visible-iconic-nomini'
4132 Like `visible-iconic' but omits minibuffer-only frames.
4134 `invisible-iconic-nomini'
4135 Like `invisible-iconic' but omits minibuffer-only frames.
4138 Identical to `nomini'.
4141 Consider only the window WINDOW's frame and any frame now
4142 using WINDOW as the minibuffer.
4145 Consider all frames.
4147 The optional argument WHICH-DEVICES further clarifies on which
4148 devices to search for frames as specified by WHICH-FRAMES.
4151 Consider all devices on the selected console.
4154 Consider only the one device DEVICE.
4157 Consider all devices on CONSOLE.
4160 Consider all devices with device type DEVICE-TYPE.
4163 Consider all devices on window system consoles.
4166 Consider all devices without restriction.
4168 -- Function: previous-frame &optional frame which-frames which-devices
4169 Like `next-frame', but cycles through all frames in the opposite
4172 See also `next-window' and `previous-window', in *Note Cyclic Window
4176 File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
4178 39.6 Frames and Windows
4179 =======================
4181 Each window is part of one and only one frame; you can get the frame
4182 with `window-frame'.
4184 -- Function: frame-root-window &optional frame
4185 This returns the root window of frame FRAME. FRAME defaults to
4186 the selected frame if not specified.
4188 -- Function: window-frame &optional window
4189 This function returns the frame that WINDOW is on. WINDOW
4190 defaults to the selected window if omitted.
4192 All the non-minibuffer windows in a frame are arranged in a cyclic
4193 order. The order runs from the frame's top window, which is at the
4194 upper left corner, down and to the right, until it reaches the window at
4195 the lower right corner (always the minibuffer window, if the frame has
4196 one), and then it moves back to the top.
4198 -- Function: frame-highest-window &optional frame position
4199 This function returns the topmost, leftmost window of frame FRAME
4200 at position POSITION.
4202 If omitted, FRAME defaults to the currently selected frame.
4204 POSITION is used to distinguish between multiple windows that abut
4205 the top of the frame: 0 means the leftmost window abutting the top
4206 of the frame, 1 the next-leftmost, etc. POSITION can also be less
4207 than zero: -1 means the rightmost window abutting the top of the
4208 frame, -2 the next-rightmost, etc. If omitted, POSITION defaults
4209 to 0, i.e. the leftmost highest window. If there is no window at
4210 the given POSITION, `nil' is returned.
4212 The following three functions work similarly.
4214 -- Function: frame-lowest-window &optional frame position
4215 This function returns the lowest window on FRAME which is at
4218 -- Function: frame-leftmost-window &optional frame position
4219 This function returns the leftmost window on FRAME which is at
4222 -- Function: frame-rightmost-window &optional frame position
4223 This function returns the rightmost window on FRAME which is at
4226 At any time, exactly one window on any frame is "selected within the
4227 frame". The significance of this designation is that selecting the
4228 frame also selects this window. You can get the frame's current
4229 selected window with `frame-selected-window'.
4231 -- Function: frame-selected-window &optional frame
4232 This function returns the window on FRAME that is selected within
4233 FRAME. FRAME defaults to the selected frame if not specified.
4235 Conversely, selecting a window for XEmacs with `select-window' also
4236 makes that window selected within its frame. *Note Selecting Windows::.
4238 Another function that (usually) returns one of the windows in a
4239 frame is `minibuffer-window'. *Note Minibuffer Misc::.
4242 File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
4244 39.7 Minibuffers and Frames
4245 ===========================
4247 Normally, each frame has its own minibuffer window at the bottom, which
4248 is used whenever that frame is selected. If the frame has a minibuffer,
4249 you can get it with `minibuffer-window' (*note Minibuffer Misc::).
4251 However, you can also create a frame with no minibuffer. Such a
4252 frame must use the minibuffer window of some other frame. When you
4253 create the frame, you can specify explicitly the minibuffer window to
4254 use (in some other frame). If you don't, then the minibuffer is found
4255 in the frame which is the value of the variable
4256 `default-minibuffer-frame'. Its value should be a frame which does
4259 -- Variable: default-minibuffer-frame
4260 This variable specifies the frame to use for the minibuffer
4264 File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames
4269 At any time, one frame in XEmacs is the "selected frame". The selected
4270 window always resides on the selected frame. As the focus moves from
4271 device to device, the selected frame on each device is remembered and
4272 restored when the focus moves back to that device.
4274 -- Function: selected-frame &optional device
4275 This function returns the selected frame on DEVICE. If DEVICE is
4276 not specified, the selected device will be used. If no frames
4277 exist on the device, `nil' is returned.
4279 The X server normally directs keyboard input to the X window that the
4280 mouse is in. Some window managers use mouse clicks or keyboard events
4281 to "shift the focus" to various X windows, overriding the normal
4282 behavior of the server.
4284 Lisp programs can switch frames "temporarily" by calling the
4285 function `select-frame'. This does not override the window manager;
4286 rather, it escapes from the window manager's control until that control
4287 is somehow reasserted.
4289 When using a text-only terminal, there is no window manager;
4290 therefore, `select-frame' is the only way to switch frames, and the
4291 effect lasts until overridden by a subsequent call to `select-frame'.
4292 Only the selected terminal frame is actually displayed on the terminal.
4293 Each terminal screen except for the initial one has a number, and the
4294 number of the selected frame appears in the mode line after the word
4295 `XEmacs' (*note Modeline Variables::).
4297 -- Function: select-frame frame
4298 This function selects frame FRAME, temporarily disregarding the
4299 focus of the X server if any. The selection of FRAME lasts until
4300 the next time the user does something to select a different frame,
4301 or until the next time this function is called.
4303 Note that `select-frame' does not actually cause the window-system
4304 focus to be set to this frame, or the `select-frame-hook' or
4305 `deselect-frame-hook' to be run, until the next time that XEmacs is
4306 waiting for an event.
4308 Also note that when the variable `focus-follows-mouse' is
4309 non-`nil', the frame selection is temporary and is reverted when
4310 the current command terminates, much like the buffer selected by
4311 `set-buffer'. In order to effect a permanent focus change use
4314 -- Function: focus-frame frame
4315 This function selects FRAME and gives it the window system focus.
4316 The operation of `focus-frame' is not affected by the value of
4317 `focus-follows-mouse'.
4319 -- Special Form: save-selected-frame forms...
4320 This special form records the selected frame, executes FORMS in
4321 sequence, then restores the earlier selected frame. The value
4322 returned is the value of the last form.
4324 -- Special Form: with-selected-frame frame forms...
4325 This special form records the selected frame, then selects FRAME
4326 and executes FORMS in sequence. After the last form is finished,
4327 the earlier selected frame is restored. The value returned is the
4328 value of the last form.
4331 File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
4333 39.9 Visibility of Frames
4334 =========================
4336 An frame on a window system may be "visible", "invisible", or
4337 "iconified". If it is visible, you can see its contents. If it is
4338 iconified, the frame's contents do not appear on the screen, but an icon
4339 does. If the frame is invisible, it doesn't show on the screen, not
4342 Visibility is meaningless for TTY frames, since only the selected
4343 one is actually displayed in any case.
4345 -- Function: make-frame-visible &optional frame
4346 This function makes frame FRAME visible. If you omit FRAME, it
4347 makes the selected frame visible.
4349 -- Function: make-frame-invisible &optional frame force
4350 This function makes frame FRAME invisible.
4352 -- Command: iconify-frame &optional frame
4353 This function iconifies frame FRAME.
4355 -- Function: Command deiconify-frame &optional frame
4356 This function de-iconifies frame FRAME. Under a window system,
4357 this is equivalent to `make-frame-visible'.
4359 -- Function: frame-visible-p &optional frame
4360 This returns whether FRAME is currently "visible" (actually in use
4361 for display). A frame that is not visible is not updated, and, if
4362 it works through a window system, may not show at all.
4364 -- Function: frame-iconified-p &optional frame
4365 This returns whether FRAME is iconified. Not all window managers
4366 use icons; some merely unmap the window, so this function is not
4367 the inverse of `frame-visible-p'. It is possible for a frame to
4368 not be visible and not be iconified either. However, if the frame
4369 is iconified, it will not be visible. (Under FSF Emacs, the
4370 functionality of this function is obtained through
4373 -- Function: frame-totally-visible-p &optional frame
4374 This returns whether FRAME is not obscured by any other X windows.
4375 On TTY frames, this is the same as `frame-visible-p'.
4378 File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
4380 39.10 Raising and Lowering Frames
4381 =================================
4383 The X Window System uses a desktop metaphor. Part of this metaphor is
4384 the idea that windows are stacked in a notional third dimension
4385 perpendicular to the screen surface, and thus ordered from "highest" to
4386 "lowest". Where two windows overlap, the one higher up covers the one
4387 underneath. Even a window at the bottom of the stack can be seen if no
4388 other window overlaps it.
4390 A window's place in this ordering is not fixed; in fact, users tend
4391 to change the order frequently. "Raising" a window means moving it
4392 "up", to the top of the stack. "Lowering" a window means moving it to
4393 the bottom of the stack. This motion is in the notional third
4394 dimension only, and does not change the position of the window on the
4397 You can raise and lower XEmacs's X windows with these functions:
4399 -- Command: raise-frame &optional frame
4400 This function raises frame FRAME.
4402 -- Command: lower-frame &optional frame
4403 This function lowers frame FRAME.
4405 You can also specify auto-raise (raising automatically when a frame
4406 is selected) or auto-lower (lowering automatically when it is
4407 deselected). Under X, most ICCCM-compliant window managers will have
4408 an option to do this for you, but the following variables are provided
4409 in case you're using a broken WM. (Under FSF Emacs, the same
4410 functionality is provided through the `auto-raise' and `auto-lower'
4413 -- Variable: auto-raise-frame
4414 This variable's value is `t' if frames will be raised to the top
4417 -- Variable: auto-lower-frame
4418 This variable's value is `t' if frames will be lowered to the
4419 bottom when no longer selected.
4421 Auto-raising and auto-lowering is implemented through functions
4422 attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
4423 Hooks::). Under normal circumstances, you should not call these
4426 -- Function: default-select-frame-hook
4427 This hook function implements the `auto-raise-frame' variable; it
4428 is for use as the value of `select-frame-hook'.
4430 -- Function: default-deselect-frame-hook
4431 This hook function implements the `auto-lower-frame' variable; it
4432 is for use as the value of `deselect-frame-hook'.
4435 File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames
4437 39.11 Frame Configurations
4438 ==========================
4440 A "frame configuration" records the current arrangement of frames, all
4441 their properties, and the window configuration of each one.
4443 -- Function: current-frame-configuration
4444 This function returns a frame configuration list that describes
4445 the current arrangement of frames and their contents.
4447 -- Function: set-frame-configuration configuration &optional nodelete
4448 This function restores the state of frames described by
4449 CONFIGURATION, which should be the return value from a previous
4450 call to `current-frame-configuration'.
4452 Each frame listed in CONFIGURATION has its position, size, window
4453 configuration, and other properties set as specified in
4456 Ordinarily, this function deletes all existing frames not listed in
4457 CONFIGURATION. But if optional second argument NODELETE is
4458 non-`nil', the unwanted frames are iconified instead.
4461 File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames
4463 39.12 Hooks for Customizing Frame Behavior
4464 ==========================================
4466 XEmacs provides many hooks that are called at various times during a
4467 frame's lifetime. *Note Hooks::.
4469 -- Variable: create-frame-hook
4470 This hook is called each time a frame is created. The functions
4471 are called with one argument, the newly-created frame.
4473 -- Variable: delete-frame-hook
4474 This hook is called each time a frame is deleted. The functions
4475 are called with one argument, the about-to-be-deleted frame.
4477 -- Variable: select-frame-hook
4478 This is a normal hook that is run just after a frame is selected.
4479 The function `default-select-frame-hook', which implements
4480 auto-raising (*note Raising and Lowering::), is normally attached
4483 Note that calling `select-frame' does not necessarily set the
4484 focus: The actual window-system focus will not be changed until
4485 the next time that XEmacs is waiting for an event, and even then,
4486 the window manager may refuse the focus-change request.
4488 -- Variable: deselect-frame-hook
4489 This is a normal hook that is run just before a frame is deselected
4490 (and another frame is selected). The function
4491 `default-deselect-frame-hook', which implements auto-lowering
4492 (*note Raising and Lowering::), is normally attached to this hook.
4494 -- Variable: map-frame-hook
4495 This hook is called each time a frame is mapped (i.e. made
4496 visible). The functions are called with one argument, the newly
4499 -- Variable: unmap-frame-hook
4500 This hook is called each time a frame is unmapped (i.e. made
4501 invisible or iconified). The functions are called with one
4502 argument, the newly unmapped frame.
4505 File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top
4507 40 Consoles and Devices
4508 ***********************
4510 A "console" is an object representing a single input connection to
4511 XEmacs, such as an X display or a TTY connection. It is possible for
4512 XEmacs to have frames on multiple consoles at once (even on
4513 heterogeneous types--you can simultaneously have a frame on an X
4514 display and a TTY connection). Normally, there is only one console in
4517 A "device" is an object representing a single output device, such as
4518 a particular screen on an X display. (Usually there is exactly one
4519 device per X console connection, but there may be more than one if you
4520 have a multi-headed X display. For TTY connections, there is always
4521 exactly one device per console.)
4523 Each device has one or more "frames" in which text can be displayed.
4524 For X displays and the like, a frame corresponds to the normal
4525 window-system concept of a window. Frames can overlap, be displayed at
4526 various locations within the display, be resized, etc. For TTY, only
4527 one frame can be displayed at a time, and it occupies the entire TTY
4530 However, you can still define multiple frames and switch between
4531 them. Their contents are entirely separate from each other. These
4532 sorts of frames resemble the "virtual console" capability provided
4533 under Linux or the multiple screens provided by the multiplexing program
4534 `screen' under Unix.
4536 When you start up XEmacs, an initial console and device are created
4537 to receive input and display frames on. This will either be an X
4538 display or a TTY connection, depending on what mode you started XEmacs
4539 in (this is determined by the `DISPLAY' environment variable, the
4540 `-nw', `-t' and `-display' command-line options, etc.).
4542 You can connect to other X displays and TTY connections by creating
4543 new console objects, and to other X screens on an existing display by
4544 creating new device objects, as described below. Many functions (for
4545 example the frame-creation functions) take an optional device argument
4546 specifying which device the function pertains to. If the argument is
4547 omitted, it defaults to the selected device (see below).
4549 -- Function: consolep object
4550 This returns non-`nil' if OBJECT is a console.
4552 -- Function: devicep object
4553 This returns non-`nil' if OBJECT is a device.
4557 * Basic Console Functions:: Functions for working with consoles.
4558 * Basic Device Functions:: Functions for working with devices.
4559 * Console Types and Device Classes::
4560 I/O and color characteristics.
4561 * Connecting to a Console or Device::
4562 * The Selected Console and Device::
4563 * Console and Device I/O:: Controlling input and output.
4566 File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices
4568 40.1 Basic Console Functions
4569 ============================
4571 -- Function: console-list
4572 This function returns a list of all existing consoles.
4574 -- Function: console-device-list &optional console
4575 This function returns a list of all devices on CONSOLE. If
4576 CONSOLE is `nil', the selected console will be used.
4579 File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices
4581 40.2 Basic Device Functions
4582 ===========================
4584 -- Function: device-list
4585 This function returns a list of all existing devices.
4587 -- Function: device-or-frame-p object
4588 This function returns non-`nil' if OBJECT is a device or frame.
4589 This function is useful because devices and frames are similar in
4590 many respects and many functions can operate on either one.
4592 -- Function: device-frame-list &optional device
4593 This function returns a list of all frames on DEVICE. DEVICE
4594 defaults to the currently selected device.
4596 -- Function: frame-device &optional frame
4597 This function returns the device that FRAME is on. FRAME defaults
4598 to the currently selected frame.
4601 File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices
4603 40.3 Console Types and Device Classes
4604 =====================================
4606 Every device is of a particular "type", which describes how the
4607 connection to that device is made and how the device operates, and a
4608 particular "class", which describes other characteristics of the device
4609 (currently, the color capabilities of the device).
4611 The currently-defined device types are
4614 A connection to an X display (such as `willow:0').
4617 A connection to a tty (such as `/dev/ttyp3').
4620 A stdio connection. This describes a device for which input and
4621 output is only possible in a stream-like fashion, such as when
4622 XEmacs in running in batch mode. The very first device created by
4623 XEmacs is a terminal device and is used to print out messages of
4624 various sorts (for example, the help message when you use the
4625 `-help' command-line option).
4627 The currently-defined device classes are
4632 A grayscale device (a device that can display multiple shades of
4633 gray, but no color).
4636 A device that can only display two colors (e.g. black and white).
4638 -- Function: device-type &optional device
4639 This function returns the type of DEVICE. This is a symbol whose
4640 name is one of the device types mentioned above. DEVICE defaults
4641 to the selected device.
4643 -- Function: device-or-frame-type device-or-frame
4644 This function returns the type of DEVICE-OR-FRAME.
4646 -- Function: device-class &optional device
4647 This function returns the class (color behavior) of DEVICE. This
4648 is a symbol whose name is one of the device classes mentioned
4651 -- Function: valid-device-type-p device-type
4652 This function returns whether DEVICE-TYPE (which should be a
4653 symbol) specifies a valid device type.
4655 -- Function: valid-device-class-p device-class
4656 This function returns whether DEVICE-CLASS (which should be a
4657 symbol) specifies a valid device class.
4659 -- Variable: terminal-device
4660 This variable holds the initial terminal device object, which
4661 represents XEmacs's stdout.
4664 File: lispref.info, Node: Connecting to a Console or Device, Next: The Selected Console and Device, Prev: Console Types and Device Classes, Up: Consoles and Devices
4666 40.4 Connecting to a Console or Device
4667 ======================================
4669 -- Function: make-device type connection &optional props
4670 This function creates a new device.
4672 The following two functions create devices of specific types and are
4673 written in terms of `make-device'.
4675 -- Function: make-tty-device &optional tty terminal-type
4676 This function creates a new tty device on TTY. This also creates
4677 the tty's first frame. TTY should be a string giving the name of
4678 a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
4679 returned by the `tty' command issued from the Unix shell. A value
4680 of `nil' means use the stdin and stdout as passed to XEmacs from
4681 the shell. If TERMINAL-TYPE is non-`nil', it should be a string
4682 specifying the type of the terminal attached to the specified tty.
4683 If it is `nil', the terminal type will be inferred from the
4684 `TERM' environment variable.
4686 -- Function: make-x-device &optional display argv-list
4687 This function creates a new device connected to DISPLAY. Optional
4688 argument ARGV-LIST is a list of strings describing command line
4691 -- Function: delete-device device &optional force
4692 This function deletes DEVICE, permanently eliminating it from use.
4693 This disconnects XEmacs's connection to the device.
4695 -- Variable: create-device-hook
4696 This variable, if non-`nil', should contain a list of functions,
4697 which are called when a device is created.
4699 -- Variable: delete-device-hook
4700 This variable, if non-`nil', should contain a list of functions,
4701 which are called when a device is deleted.
4703 -- Function: console-live-p object
4704 This function returns non-`nil' if OBJECT is a console that has
4707 -- Function: device-live-p object
4708 This function returns non-`nil' if OBJECT is a device that has not
4711 -- Function: device-x-display device
4712 This function returns the X display which DEVICE is connected to,
4713 if DEVICE is an X device.
4716 File: lispref.info, Node: The Selected Console and Device, Next: Console and Device I/O, Prev: Connecting to a Console or Device, Up: Consoles and Devices
4718 40.5 The Selected Console and Device
4719 ====================================
4721 -- Function: select-console console
4722 This function selects the console CONSOLE. Subsequent editing
4723 commands apply to its selected device, selected frame, and selected
4724 window. The selection of CONSOLE lasts until the next time the
4725 user does something to select a different console, or until the
4726 next time this function is called.
4728 -- Function: selected-console
4729 This function returns the console which is currently active.
4731 -- Function: select-device device
4732 This function selects the device DEVICE.
4734 -- Function: selected-device &optional console
4735 This function returns the device which is currently active. If
4736 optional CONSOLE is non-`nil', this function returns the device
4737 that would be currently active if CONSOLE were the selected
4741 File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
4743 40.6 Console and Device I/O
4744 ===========================
4746 -- Function: console-disable-input console
4747 This function disables input on console CONSOLE.
4749 -- Function: console-enable-input console
4750 This function enables input on console CONSOLE.
4752 Each device has a "baud rate" value associated with it. On most
4753 systems, changing this value will affect the amount of padding and
4754 other strategic decisions made during redisplay.
4756 -- Function: device-baud-rate &optional device
4757 This function returns the output baud rate of DEVICE.
4759 -- Function: set-device-baud-rate device rate
4760 This function sets the output baud rate of DEVICE to RATE.
4763 File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
4768 A "position" is the index of a character in the text of a buffer. More
4769 precisely, a position identifies the place between two characters (or
4770 before the first character, or after the last character), so we can
4771 speak of the character before or after a given position. However, we
4772 often speak of the character "at" a position, meaning the character
4773 after that position.
4775 Positions are usually represented as integers starting from 1, but
4776 can also be represented as "markers"--special objects that relocate
4777 automatically when text is inserted or deleted so they stay with the
4778 surrounding characters. *Note Markers::.
4782 * Point:: The special position where editing takes place.
4783 * Motion:: Changing point.
4784 * Excursions:: Temporary motion and buffer changes.
4785 * Narrowing:: Restricting editing to a portion of the buffer.
4788 File: lispref.info, Node: Point, Next: Motion, Up: Positions
4793 "Point" is a special buffer position used by many editing commands,
4794 including the self-inserting typed characters and text insertion
4795 functions. Other commands move point through the text to allow editing
4796 and insertion at different places.
4798 Like other positions, point designates a place between two characters
4799 (or before the first character, or after the last character), rather
4800 than a particular character. Usually terminals display the cursor over
4801 the character that immediately follows point; point is actually before
4802 the character on which the cursor sits.
4804 The value of point is a number between 1 and the buffer size plus 1.
4805 If narrowing is in effect (*note Narrowing::), then point is constrained
4806 to fall within the accessible portion of the buffer (possibly at one end
4809 Each buffer has its own value of point, which is independent of the
4810 value of point in other buffers. Each window also has a value of point,
4811 which is independent of the value of point in other windows on the same
4812 buffer. This is why point can have different values in various windows
4813 that display the same buffer. When a buffer appears in only one window,
4814 the buffer's point and the window's point normally have the same value,
4815 so the distinction is rarely important. *Note Window Point::, for more
4818 -- Function: point &optional buffer
4819 This function returns the value of point in BUFFER, as an integer.
4820 BUFFER defaults to the current buffer if omitted.
4825 -- Function: point-min &optional buffer
4826 This function returns the minimum accessible value of point in
4827 BUFFER. This is normally 1, but if narrowing is in effect, it is
4828 the position of the start of the region that you narrowed to.
4829 (*Note Narrowing::.) BUFFER defaults to the current buffer if
4832 -- Function: point-max &optional buffer
4833 This function returns the maximum accessible value of point in
4834 BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
4835 in effect, in which case it is the position of the end of the
4836 region that you narrowed to. (*note Narrowing::). BUFFER defaults
4837 to the current buffer if omitted.
4839 -- Function: buffer-end flag &optional buffer
4840 This function returns `(point-min buffer)' if FLAG is less than 1,
4841 `(point-max buffer)' otherwise. The argument FLAG must be a
4842 number. BUFFER defaults to the current buffer if omitted.
4844 -- Function: buffer-size &optional buffer
4845 This function returns the total number of characters in BUFFER.
4846 In the absence of any narrowing (*note Narrowing::), `point-max'
4847 returns a value one larger than this. BUFFER defaults to the
4848 current buffer if omitted.
4855 -- Variable: buffer-saved-size
4856 The value of this buffer-local variable is the former length of the
4857 current buffer, as of the last time it was read in, saved or
4861 File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
4866 Motion functions change the value of point, either relative to the
4867 current value of point, relative to the beginning or end of the buffer,
4868 or relative to the edges of the selected window. *Note Point::.
4872 * Character Motion:: Moving in terms of characters.
4873 * Word Motion:: Moving in terms of words.
4874 * Buffer End Motion:: Moving to the beginning or end of the buffer.
4875 * Text Lines:: Moving in terms of lines of text.
4876 * Screen Lines:: Moving in terms of lines as displayed.
4877 * List Motion:: Moving by parsing lists and sexps.
4878 * Skipping Characters:: Skipping characters belonging to a certain set.
4881 File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
4883 41.2.1 Motion by Characters
4884 ---------------------------
4886 These functions move point based on a count of characters. `goto-char'
4887 is the fundamental primitive; the other functions use that.
4889 -- Command: goto-char position &optional buffer
4890 This function sets point in `buffer' to the value POSITION. If
4891 POSITION is less than 1, it moves point to the beginning of the
4892 buffer. If POSITION is greater than the length of the buffer, it
4893 moves point to the end. BUFFER defaults to the current buffer if
4896 If narrowing is in effect, POSITION still counts from the
4897 beginning of the buffer, but point cannot go outside the accessible
4898 portion. If POSITION is out of range, `goto-char' moves point to
4899 the beginning or the end of the accessible portion.
4901 When this function is called interactively, POSITION is the
4902 numeric prefix argument, if provided; otherwise it is read from the
4905 `goto-char' returns POSITION.
4907 -- Command: forward-char &optional count buffer
4908 This function moves point COUNT characters forward, towards the
4909 end of the buffer (or backward, towards the beginning of the
4910 buffer, if COUNT is negative). If the function attempts to move
4911 point past the beginning or end of the buffer (or the limits of
4912 the accessible portion, when narrowing is in effect), an error is
4913 signaled with error code `beginning-of-buffer' or `end-of-buffer'.
4914 BUFFER defaults to the current buffer if omitted.
4916 In an interactive call, COUNT is the numeric prefix argument.
4918 -- Command: backward-char &optional count buffer
4919 This function moves point COUNT characters backward, towards the
4920 beginning of the buffer (or forward, towards the end of the
4921 buffer, if COUNT is negative). If the function attempts to move
4922 point past the beginning or end of the buffer (or the limits of
4923 the accessible portion, when narrowing is in effect), an error is
4924 signaled with error code `beginning-of-buffer' or `end-of-buffer'.
4925 BUFFER defaults to the current buffer if omitted.
4927 In an interactive call, COUNT is the numeric prefix argument.
4930 File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
4932 41.2.2 Motion by Words
4933 ----------------------
4935 These functions for parsing words use the syntax table to decide
4936 whether a given character is part of a word. *Note Syntax Tables::.
4938 -- Command: forward-word &optional count buffer
4939 This function moves point forward COUNT words (or backward if
4940 COUNT is negative). Normally it returns `t'. If this motion
4941 encounters the beginning or end of the buffer, or the limits of the
4942 accessible portion when narrowing is in effect, point stops there
4943 and the value is `nil'.
4945 COUNT defaults to `1' and BUFFER defaults to the current buffer.
4947 In an interactive call, COUNT is set to the numeric prefix
4950 -- Command: backward-word &optional count buffer
4951 This function is just like `forward-word', except that it moves
4952 backward until encountering the front of a word, rather than
4953 forward. BUFFER defaults to the current buffer if omitted.
4955 In an interactive call, COUNT is set to the numeric prefix
4958 -- Variable: words-include-escapes
4959 This variable affects the behavior of `forward-word' and everything
4960 that uses it. If it is non-`nil', then characters in the "escape"
4961 and "character quote" syntax classes count as part of words.
4962 Otherwise, they do not.
4965 File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
4967 41.2.3 Motion to an End of the Buffer
4968 -------------------------------------
4970 To move point to the beginning of the buffer, write:
4972 (goto-char (point-min))
4974 Likewise, to move to the end of the buffer, use:
4976 (goto-char (point-max))
4978 Here are two commands that users use to do these things. They are
4979 documented here to warn you not to use them in Lisp programs, because
4980 they set the mark and display messages in the echo area.
4982 -- Command: beginning-of-buffer &optional count
4983 This function moves point to the beginning of the buffer (or the
4984 limits of the accessible portion, when narrowing is in effect),
4985 setting the mark at the previous position. If COUNT is non-`nil',
4986 then it puts point COUNT tenths of the way from the beginning of
4989 In an interactive call, COUNT is the numeric prefix argument, if
4990 provided; otherwise COUNT defaults to `nil'.
4992 Don't use this function in Lisp programs!
4994 -- Command: end-of-buffer &optional count
4995 This function moves point to the end of the buffer (or the limits
4996 of the accessible portion, when narrowing is in effect), setting
4997 the mark at the previous position. If COUNT is non-`nil', then it
4998 puts point COUNT tenths of the way from the end of the buffer.
5000 In an interactive call, COUNT is the numeric prefix argument, if
5001 provided; otherwise COUNT defaults to `nil'.
5003 Don't use this function in Lisp programs!
5006 File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
5008 41.2.4 Motion by Text Lines
5009 ---------------------------
5011 Text lines are portions of the buffer delimited by newline characters,
5012 which are regarded as part of the previous line. The first text line
5013 begins at the beginning of the buffer, and the last text line ends at
5014 the end of the buffer whether or not the last character is a newline.
5015 The division of the buffer into text lines is not affected by the width
5016 of the window, by line continuation in display, or by how tabs and
5017 control characters are displayed.
5019 -- Command: goto-line line
5020 This function moves point to the front of the LINEth line,
5021 counting from line 1 at beginning of the buffer. If LINE is less
5022 than 1, it moves point to the beginning of the buffer. If LINE is
5023 greater than the number of lines in the buffer, it moves point to
5024 the end of the buffer--that is, the _end of the last line_ of the
5025 buffer. This is the only case in which `goto-line' does not
5026 necessarily move to the beginning of a line.
5028 If narrowing is in effect, then LINE still counts from the
5029 beginning of the buffer, but point cannot go outside the accessible
5030 portion. So `goto-line' moves point to the beginning or end of the
5031 accessible portion, if the line number specifies an inaccessible
5034 The return value of `goto-line' is the difference between LINE and
5035 the line number of the line to which point actually was able to
5036 move (in the full buffer, before taking account of narrowing).
5037 Thus, the value is positive if the scan encounters the real end of
5038 the buffer. The value is zero if scan encounters the end of the
5039 accessible portion but not the real end of the buffer.
5041 In an interactive call, LINE is the numeric prefix argument if one
5042 has been provided. Otherwise LINE is read in the minibuffer.
5044 -- Command: beginning-of-line &optional count buffer
5045 This function moves point to the beginning of the current line.
5046 With an argument COUNT not `nil' or 1, it moves forward COUNT-1
5047 lines and then to the beginning of the line. BUFFER defaults to
5048 the current buffer if omitted.
5050 If this function reaches the end of the buffer (or of the
5051 accessible portion, if narrowing is in effect), it positions point
5052 there. No error is signaled.
5054 -- Command: end-of-line &optional count buffer
5055 This function moves point to the end of the current line. With an
5056 argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
5057 then to the end of the line. BUFFER defaults to the current
5060 If this function reaches the end of the buffer (or of the
5061 accessible portion, if narrowing is in effect), it positions point
5062 there. No error is signaled.
5064 -- Command: forward-line &optional count buffer
5065 This function moves point forward COUNT lines, to the beginning of
5066 the line. If COUNT is negative, it moves point -COUNT lines
5067 backward, to the beginning of a line. If COUNT is zero, it moves
5068 point to the beginning of the current line. BUFFER defaults to
5069 the current buffer if omitted.
5071 If `forward-line' encounters the beginning or end of the buffer (or
5072 of the accessible portion) before finding that many lines, it sets
5073 point there. No error is signaled.
5075 `forward-line' returns the difference between COUNT and the number
5076 of lines actually moved. If you attempt to move down five lines
5077 from the beginning of a buffer that has only three lines, point
5078 stops at the end of the last line, and the value will be 2.
5080 In an interactive call, COUNT is the numeric prefix argument.
5082 -- Function: count-lines start end &optional
5083 ignore-invisible-lines-flag
5084 This function returns the number of lines between the positions
5085 START and END in the current buffer. If START and END are equal,
5086 then it returns 0. Otherwise it returns at least 1, even if START
5087 and END are on the same line. This is because the text between
5088 them, considered in isolation, must contain at least one line
5091 With optional IGNORE-INVISIBLE-LINES-FLAG non-`nil', lines
5092 collapsed with selective-display are excluded from the line count.
5094 *N.B.* The expression to return the current line number is not
5097 (1+ (count-lines 1 (point-at-bol)))
5099 Here is an example of using `count-lines':
5101 (defun current-line ()
5102 "Return the vertical position of point..."
5103 (+ (count-lines (window-start) (point))
5104 (if (= (current-column) 0) 1 0)
5107 Also see the functions `bolp' and `eolp' in *Note Near Point::.
5108 These functions do not move point, but test whether it is already at the
5109 beginning or end of a line.
5112 File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
5114 41.2.5 Motion by Screen Lines
5115 -----------------------------
5117 The line functions in the previous section count text lines, delimited
5118 only by newline characters. By contrast, these functions count screen
5119 lines, which are defined by the way the text appears on the screen. A
5120 text line is a single screen line if it is short enough to fit the width
5121 of the selected window, but otherwise it may occupy several screen
5124 In some cases, text lines are truncated on the screen rather than
5125 continued onto additional screen lines. In these cases,
5126 `vertical-motion' moves point much like `forward-line'. *Note
5129 Because the width of a given string depends on the flags that control
5130 the appearance of certain characters, `vertical-motion' behaves
5131 differently, for a given piece of text, depending on the buffer it is
5132 in, and even on the selected window (because the width, the truncation
5133 flag, and display table may vary between windows). *Note Usual
5136 These functions scan text to determine where screen lines break, and
5137 thus take time proportional to the distance scanned. If you intend to
5138 use them heavily, Emacs provides caches which may improve the
5139 performance of your code. *Note cache-long-line-scans: Text Lines.
5141 -- Function: vertical-motion count &optional window pixels
5142 This function moves point to the start of the frame line COUNT
5143 frame lines down from the frame line containing point. If COUNT
5144 is negative, it moves up instead. The optional second argument
5145 WINDOW may be used to specify a window other than the selected
5146 window in which to perform the motion.
5148 Normally, `vertical-motion' returns the number of lines moved. The
5149 value may be less in absolute value than COUNT if the beginning or
5150 end of the buffer was reached. If the optional third argument,
5151 PIXELS is non-`nil', the vertical pixel height of the motion which
5152 took place is returned instead of the actual number of lines
5153 moved. A motion of zero lines returns the height of the current
5156 Note that `vertical-motion' sets WINDOW's buffer's point, not
5157 WINDOW's point. (This differs from FSF Emacs, which buggily always
5158 sets current buffer's point, regardless of WINDOW.)
5160 -- Function: vertical-motion-pixels count &optional window how
5161 This function moves point to the start of the frame line PIXELS
5162 vertical pixels down from the frame line containing point, or up if
5163 PIXELS is negative. The optional second argument WINDOW is the
5164 window to move in, and defaults to the selected window. The
5165 optional third argument HOW specifies the stopping condition. A
5166 negative integer indicates that the motion should be no more than
5167 PIXELS. A positive value indicates that the motion should be at
5168 least PIXELS. Any other value indicates that the motion should be
5169 as close as possible to PIXELS.
5171 -- Command: move-to-window-line count &optional window
5172 This function moves point with respect to the text currently
5173 displayed in WINDOW, which defaults to the selected window. It
5174 moves point to the beginning of the screen line COUNT screen lines
5175 from the top of the window. If COUNT is negative, that specifies a
5176 position -COUNT lines from the bottom (or the last line of the
5177 buffer, if the buffer ends above the specified screen position).
5179 If COUNT is `nil', then point moves to the beginning of the line
5180 in the middle of the window. If the absolute value of COUNT is
5181 greater than the size of the window, then point moves to the place
5182 that would appear on that screen line if the window were tall
5183 enough. This will probably cause the next redisplay to scroll to
5184 bring that location onto the screen.
5186 In an interactive call, COUNT is the numeric prefix argument.
5188 The value returned is the window line number point has moved to,
5189 with the top line in the window numbered 0.
5192 File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
5194 41.2.6 Moving over Balanced Expressions
5195 ---------------------------------------
5197 Here are several functions concerned with balanced-parenthesis
5198 expressions (also called "sexps" in connection with moving across them
5199 in XEmacs). The syntax table controls how these functions interpret
5200 various characters; see *Note Syntax Tables::. *Note Parsing
5201 Expressions::, for lower-level primitives for scanning sexps or parts of
5202 sexps. For user-level commands, see *Note Lists and Sexps:
5203 (xemacs)Lists and Sexps.
5205 -- Command: forward-list &optional arg
5206 This function moves forward across ARG balanced groups of
5207 parentheses. (Other syntactic entities such as words or paired
5208 string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
5209 is negative, move backward across that many groups of parentheses.
5211 -- Command: backward-list &optional count
5212 This function moves backward across COUNT balanced groups of
5213 parentheses. (Other syntactic entities such as words or paired
5214 string quotes are ignored.) COUNT defaults to 1 if omitted. If
5215 COUNT is negative, move forward across that many groups of
5218 -- Command: up-list &optional count
5219 This function moves forward out of COUNT levels of parentheses. A
5220 negative argument means move backward but still to a less deep
5223 -- Command: down-list &optional count
5224 This function moves forward into COUNT levels of parentheses. A
5225 negative argument means move backward but still go deeper in
5226 parentheses (-COUNT levels).
5228 -- Command: forward-sexp &optional count
5229 This function moves forward across COUNT balanced expressions.
5230 Balanced expressions include both those delimited by parentheses
5231 and other kinds, such as words and string constants. COUNT
5232 defaults to 1 if omitted. If COUNT is negative, move backward
5233 across that many balanced expressions. For example,
5235 ---------- Buffer: foo ----------
5236 (concat-!- "foo " (car x) y z)
5237 ---------- Buffer: foo ----------
5242 ---------- Buffer: foo ----------
5243 (concat "foo " (car x) y-!- z)
5244 ---------- Buffer: foo ----------
5246 -- Command: backward-sexp &optional count
5247 This function moves backward across COUNT balanced expressions.
5248 COUNT defaults to 1 if omitted. If COUNT is negative, move
5249 forward across that many balanced expressions.
5251 -- Command: beginning-of-defun &optional count
5252 This function moves back to the COUNTth beginning of a defun. If
5253 COUNT is negative, this actually moves forward, but it still moves
5254 to the beginning of a defun, not to the end of one. COUNT
5255 defaults to 1 if omitted.
5257 -- Command: end-of-defun &optional count
5258 This function moves forward to the COUNTth end of a defun. If
5259 COUNT is negative, this actually moves backward, but it still
5260 moves to the end of a defun, not to the beginning of one. COUNT
5261 defaults to 1 if omitted.
5263 -- User Option: defun-prompt-regexp
5264 If non-`nil', this variable holds a regular expression that
5265 specifies what text can appear before the open-parenthesis that
5266 starts a defun. That is to say, a defun begins on a line that
5267 starts with a match for this regular expression, followed by a
5268 character with open-parenthesis syntax.
5271 File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
5273 41.2.7 Skipping Characters
5274 --------------------------
5276 The following two functions move point over a specified set of
5277 characters. For example, they are often used to skip whitespace. For
5278 related functions, see *Note Motion and Syntax::.
5280 -- Function: skip-chars-forward character-set &optional limit buffer
5281 This function moves point in BUFFER forward, skipping over a given
5282 set of characters. It examines the character following point,
5283 then advances point if the character matches CHARACTER-SET. This
5284 continues until it reaches a character that does not match. The
5285 function returns `nil'. BUFFER defaults to the current buffer if
5288 The argument CHARACTER-SET is like the inside of a `[...]' in a
5289 regular expression except that `]' is never special and `\' quotes
5290 `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
5291 stopping before the first non-letter, and `"^a-zA-Z'" skips
5292 non-letters stopping before the first letter. *Note Regular
5295 If LIMIT is supplied (it must be a number or a marker), it
5296 specifies the maximum position in the buffer that point can be
5297 skipped to. Point will stop at or before LIMIT.
5299 In the following example, point is initially located directly
5300 before the `T'. After the form is evaluated, point is located at
5301 the end of that line (between the `t' of `hat' and the newline).
5302 The function skips all letters and spaces, but not newlines.
5304 ---------- Buffer: foo ----------
5305 I read "-!-The cat in the hat
5307 ---------- Buffer: foo ----------
5309 (skip-chars-forward "a-zA-Z ")
5312 ---------- Buffer: foo ----------
5313 I read "The cat in the hat-!-
5315 ---------- Buffer: foo ----------
5317 -- Function: skip-chars-backward character-set &optional limit buffer
5318 This function moves point backward, skipping characters that match
5319 CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
5320 except for the direction of motion.
5323 File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
5328 It is often useful to move point "temporarily" within a localized
5329 portion of the program, or to switch buffers temporarily. This is
5330 called an "excursion", and it is done with the `save-excursion' special
5331 form. This construct saves the current buffer and its values of point
5332 and the mark so they can be restored after the completion of the
5335 The forms for saving and restoring the configuration of windows are
5336 described elsewhere (see *Note Window Configurations:: and *note Frame
5339 -- Special Form: save-excursion forms...
5340 The `save-excursion' special form saves the identity of the current
5341 buffer and the values of point and the mark in it, evaluates
5342 FORMS, and finally restores the buffer and its saved values of
5343 point and the mark. All three saved values are restored even in
5344 case of an abnormal exit via `throw' or error (*note Nonlocal
5347 The `save-excursion' special form is the standard way to switch
5348 buffers or move point within one part of a program and avoid
5349 affecting the rest of the program. It is used more than 500 times
5350 in the Lisp sources of XEmacs.
5352 `save-excursion' does not save the values of point and the mark for
5353 other buffers, so changes in other buffers remain in effect after
5354 `save-excursion' exits.
5356 Likewise, `save-excursion' does not restore window-buffer
5357 correspondences altered by functions such as `switch-to-buffer'.
5358 One way to restore these correspondences, and the selected window,
5359 is to use `save-window-excursion' inside `save-excursion' (*note
5360 Window Configurations::).
5362 The value returned by `save-excursion' is the result of the last of
5363 FORMS, or `nil' if no FORMS are given.
5368 (let ((old-buf (current-buffer))
5369 (old-pnt (point-marker))
5370 (old-mark (copy-marker (mark-marker))))
5373 (set-buffer old-buf)
5375 (set-marker (mark-marker) old-mark)))
5377 -- Special Form: save-current-buffer forms...
5378 This special form is similar to `save-excursion' but it only saves
5379 and restores the current buffer. Beginning with XEmacs 20.3,
5380 `save-current-buffer' is a primitive.
5382 -- Special Form: with-current-buffer buffer forms...
5383 This special form evaluates FORMS with BUFFER as the current
5384 buffer. It returns the value of the last form.
5386 -- Special Form: with-temp-file filename forms...
5387 This special form creates a new buffer, evaluates FORMS there, and
5388 writes the buffer to FILENAME. It returns the value of the last
5391 -- Special Form: save-selected-window forms...
5392 This special form is similar to `save-excursion' but it saves and
5393 restores the selected window and nothing else.
5396 File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
5401 "Narrowing" means limiting the text addressable by XEmacs editing
5402 commands to a limited range of characters in a buffer. The text that
5403 remains addressable is called the "accessible portion" of the buffer.
5405 Narrowing is specified with two buffer positions which become the
5406 beginning and end of the accessible portion. For most editing commands
5407 and most Emacs primitives, these positions replace the values of the
5408 beginning and end of the buffer. While narrowing is in effect, no text
5409 outside the accessible portion is displayed, and point cannot move
5410 outside the accessible portion.
5412 Values such as positions or line numbers, which usually count from
5413 the beginning of the buffer, do so despite narrowing, but the functions
5414 which use them refuse to operate on text that is inaccessible.
5416 The commands for saving buffers are unaffected by narrowing; they
5417 save the entire buffer regardless of any narrowing.
5419 -- Command: narrow-to-region start end &optional buffer
5420 This function sets the accessible portion of BUFFER to start at
5421 START and end at END. Both arguments should be character
5422 positions. BUFFER defaults to the current buffer if omitted.
5424 In an interactive call, START and END are set to the bounds of the
5425 current region (point and the mark, with the smallest first).
5427 -- Command: narrow-to-page &optional move-count
5428 This function sets the accessible portion of the current buffer to
5429 include just the current page. An optional first argument
5430 MOVE-COUNT non-`nil' means to move forward or backward by
5431 MOVE-COUNT pages and then narrow. The variable `page-delimiter'
5432 specifies where pages start and end (*note Standard Regexps::).
5434 In an interactive call, MOVE-COUNT is set to the numeric prefix
5437 -- Command: widen &optional buffer
5438 This function cancels any narrowing in BUFFER, so that the entire
5439 contents are accessible. This is called "widening". It is
5440 equivalent to the following expression:
5442 (narrow-to-region 1 (1+ (buffer-size)))
5444 BUFFER defaults to the current buffer if omitted.
5446 -- Special Form: save-restriction body...
5447 This special form saves the current bounds of the accessible
5448 portion, evaluates the BODY forms, and finally restores the saved
5449 bounds, thus restoring the same state of narrowing (or absence
5450 thereof) formerly in effect. The state of narrowing is restored
5451 even in the event of an abnormal exit via `throw' or error (*note
5452 Nonlocal Exits::). Therefore, this construct is a clean way to
5453 narrow a buffer temporarily.
5455 The value returned by `save-restriction' is that returned by the
5456 last form in BODY, or `nil' if no body forms were given.
5458 *Caution:* it is easy to make a mistake when using the
5459 `save-restriction' construct. Read the entire description here
5462 If BODY changes the current buffer, `save-restriction' still
5463 restores the restrictions on the original buffer (the buffer whose
5464 restrictions it saved from), but it does not restore the identity
5465 of the current buffer.
5467 `save-restriction' does _not_ restore point and the mark; use
5468 `save-excursion' for that. If you use both `save-restriction' and
5469 `save-excursion' together, `save-excursion' should come first (on
5470 the outside). Otherwise, the old point value would be restored
5471 with temporary narrowing still in effect. If the old point value
5472 were outside the limits of the temporary narrowing, this would
5473 fail to restore it accurately.
5475 The `save-restriction' special form records the values of the
5476 beginning and end of the accessible portion as distances from the
5477 beginning and end of the buffer. In other words, it records the
5478 amount of inaccessible text before and after the accessible
5481 This method yields correct results if BODY does further narrowing.
5482 However, `save-restriction' can become confused if the body widens
5483 and then make changes outside the range of the saved narrowing.
5484 When this is what you want to do, `save-restriction' is not the
5485 right tool for the job. Here is what you must use instead:
5487 (let ((start (point-min-marker))
5488 (end (point-max-marker)))
5492 (set-buffer (marker-buffer start))
5493 (narrow-to-region start end))))
5495 Here is a simple example of correct use of `save-restriction':
5497 ---------- Buffer: foo ----------
5498 This is the contents of foo
5499 This is the contents of foo
5500 This is the contents of foo-!-
5501 ---------- Buffer: foo ----------
5507 (narrow-to-region 1 (point))
5508 (goto-char (point-min))
5509 (replace-string "foo" "bar")))
5511 ---------- Buffer: foo ----------
5512 This is the contents of bar
5513 This is the contents of bar
5514 This is the contents of foo-!-
5515 ---------- Buffer: foo ----------
5518 File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
5523 A "marker" is a Lisp object used to specify a position in a buffer
5524 relative to the surrounding text. A marker changes its offset from the
5525 beginning of the buffer automatically whenever text is inserted or
5526 deleted, so that it stays with the two characters on either side of it.
5530 * Overview of Markers:: The components of a marker, and how it relocates.
5531 * Predicates on Markers:: Testing whether an object is a marker.
5532 * Creating Markers:: Making empty markers or markers at certain places.
5533 * Information from Markers:: Finding the marker's buffer or character position.
5534 * Changing Markers:: Moving the marker to a new buffer or position.
5535 * The Mark:: How ``the mark'' is implemented with a marker.
5536 * The Region:: How to access ``the region''.
5539 File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
5541 42.1 Overview of Markers
5542 ========================
5544 A marker specifies a buffer and a position in that buffer. The marker
5545 can be used to represent a position in the functions that require one,
5546 just as an integer could be used. *Note Positions::, for a complete
5547 description of positions.
5549 A marker has two attributes: the marker position, and the marker
5550 buffer. The marker position is an integer that is equivalent (at a
5551 given time) to the marker as a position in that buffer. But the
5552 marker's position value can change often during the life of the marker.
5553 Insertion and deletion of text in the buffer relocate the marker. The
5554 idea is that a marker positioned between two characters remains between
5555 those two characters despite insertion and deletion elsewhere in the
5556 buffer. Relocation changes the integer equivalent of the marker.
5558 Deleting text around a marker's position leaves the marker between
5559 the characters immediately before and after the deleted text. Inserting
5560 text at the position of a marker normally leaves the marker in front of
5561 the new text--unless it is inserted with `insert-before-markers' (*note
5564 Insertion and deletion in a buffer must check all the markers and
5565 relocate them if necessary. This slows processing in a buffer with a
5566 large number of markers. For this reason, it is a good idea to make a
5567 marker point nowhere if you are sure you don't need it any more.
5568 Unreferenced markers are garbage collected eventually, but until then
5569 will continue to use time if they do point somewhere.
5571 Because it is common to perform arithmetic operations on a marker
5572 position, most of the arithmetic operations (including `+' and `-')
5573 accept markers as arguments. In such cases, the marker stands for its
5576 Note that you can use extents to achieve the same functionality, and
5577 more, as markers. (Markers were defined before extents, which is why
5578 they both continue to exist.) A zero-length extent with the
5579 `detachable' property removed is almost identical to a marker. (*Note
5580 Extent Endpoints::, for more information on zero-length extents.)
5584 * In order to get marker-like behavior in a zero-length extent, the
5585 `detachable' property must be removed (otherwise, the extent will
5586 disappear when text near it is deleted) and exactly one endpoint
5587 must be closed (if both endpoints are closed, the extent will
5588 expand to contain text inserted where it is located).
5590 * If a zero-length extent has the `end-open' property but not the
5591 `start-open' property (this is the default), text inserted at the
5592 extent's location causes the extent to move forward, just like a
5595 * If a zero-length extent has the `start-open' property but not the
5596 `end-open' property, text inserted at the extent's location causes
5597 the extent to remain before the text, like what happens to markers
5598 when `insert-before-markers' is used.
5600 * Markers end up after or before inserted text depending on whether
5601 `insert' or `insert-before-markers' was called. These functions
5602 do not affect zero-length extents differently; instead, the
5603 presence or absence of the `start-open' and `end-open' extent
5604 properties determines this, as just described.
5606 * Markers are automatically removed from a buffer when they are no
5607 longer in use. Extents remain around until explicitly removed
5610 * Many functions are provided for listing the extents in a buffer or
5611 in a region of a buffer. No such functions exist for markers.
5613 Here are examples of creating markers, setting markers, and moving
5616 ;; Make a new marker that initially does not point anywhere:
5617 (setq m1 (make-marker))
5618 => #<marker in no buffer>
5620 ;; Set `m1' to point between the 99th and 100th characters
5621 ;; in the current buffer:
5623 => #<marker at 100 in markers.texi>
5625 ;; Now insert one character at the beginning of the buffer:
5626 (goto-char (point-min))
5631 ;; `m1' is updated appropriately.
5633 => #<marker at 101 in markers.texi>
5635 ;; Two markers that point to the same position
5636 ;; are not `eq', but they are `equal'.
5637 (setq m2 (copy-marker m1))
5638 => #<marker at 101 in markers.texi>
5644 ;; When you are finished using a marker, make it point nowhere.
5646 => #<marker in no buffer>
5649 File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
5651 42.2 Predicates on Markers
5652 ==========================
5654 You can test an object to see whether it is a marker, or whether it is
5655 either an integer or a marker or either an integer, a character, or a
5656 marker. The latter tests are useful in connection with the arithmetic
5657 functions that work with any of markers, integers, or characters.
5659 -- Function: markerp object
5660 This function returns `t' if OBJECT is a marker, `nil' otherwise.
5661 Note that integers are not markers, even though many functions
5662 will accept either a marker or an integer.
5664 -- Function: integer-or-marker-p object
5665 This function returns `t' if OBJECT is an integer or a marker,
5668 -- Function: integer-char-or-marker-p object
5669 This function returns `t' if OBJECT is an integer, a character, or
5670 a marker, `nil' otherwise.
5672 -- Function: number-or-marker-p object
5673 This function returns `t' if OBJECT is a number (either kind) or a
5674 marker, `nil' otherwise.
5676 -- Function: number-char-or-marker-p object
5677 This function returns `t' if OBJECT is a number (either kind), a
5678 character, or a marker, `nil' otherwise.
5681 File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
5683 42.3 Functions That Create Markers
5684 ==================================
5686 When you create a new marker, you can make it point nowhere, or point
5687 to the present position of point, or to the beginning or end of the
5688 accessible portion of the buffer, or to the same place as another given
5691 -- Function: make-marker
5692 This functions returns a newly created marker that does not point
5696 => #<marker in no buffer>
5698 -- Function: point-marker &optional dont-copy-p buffer
5699 This function returns a marker that points to the present position
5700 of point in BUFFER, which defaults to the current buffer. *Note
5701 Point::. For an example, see `copy-marker', below.
5703 Internally, a marker corresponding to point is always maintained.
5704 Normally the marker returned by `point-marker' is a copy; you may
5705 modify it with reckless abandon. However, if optional argument
5706 DONT-COPY-P is non-`nil', then the real point-marker is returned;
5707 modifying the position of this marker will move point. It is
5708 illegal to change the buffer of it, or make it point nowhere.
5710 -- Function: point-min-marker &optional buffer
5711 This function returns a new marker that points to the beginning of
5712 the accessible portion of BUFFER, which defaults to the current
5713 buffer. This will be the beginning of the buffer unless narrowing
5714 is in effect. *Note Narrowing::.
5716 -- Function: point-max-marker &optional buffer
5717 This function returns a new marker that points to the end of the
5718 accessible portion of BUFFER, which defaults to the current
5719 buffer. This will be the end of the buffer unless narrowing is in
5720 effect. *Note Narrowing::.
5722 Here are examples of this function and `point-min-marker', shown in
5723 a buffer containing a version of the source file for the text of
5727 => #<marker at 1 in markers.texi>
5729 => #<marker at 15573 in markers.texi>
5731 (narrow-to-region 100 200)
5734 => #<marker at 100 in markers.texi>
5736 => #<marker at 200 in markers.texi>
5738 -- Function: copy-marker marker-or-integer &optional marker-type
5739 If passed a marker as its argument, `copy-marker' returns a new
5740 marker that points to the same place and the same buffer as does
5741 MARKER-OR-INTEGER. If passed an integer as its argument,
5742 `copy-marker' returns a new marker that points to position
5743 MARKER-OR-INTEGER in the current buffer.
5745 If passed an integer argument less than 1, `copy-marker' returns a
5746 new marker that points to the beginning of the current buffer. If
5747 passed an integer argument greater than the length of the buffer,
5748 `copy-marker' returns a new marker that points to the end of the
5751 An error is signaled if MARKER-OR-INTEGER is neither a marker nor
5754 Optional second argument MARKER-TYPE specifies the insertion type
5755 of the new marker; see `marker-insertion-type'.
5757 (setq p (point-marker))
5758 => #<marker at 2139 in markers.texi>
5760 (setq q (copy-marker p))
5761 => #<marker at 2139 in markers.texi>
5773 => #<marker at 3000 in markers.texi>
5778 (setq p (point-marker t))
5779 => #<marker at 2139 in markers.texi>
5782 => #<marker at 3000 in markers.texi>
5788 => #<marker at 1 in markers.texi>
5791 => #<marker at 7572 in markers.texi>
5794 File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
5796 42.4 Information from Markers
5797 =============================
5799 This section describes the functions for accessing the components of a
5802 -- Function: marker-position marker
5803 This function returns the position that MARKER points to, or `nil'
5804 if it points nowhere.
5806 -- Function: marker-buffer marker
5807 This function returns the buffer that MARKER points into, or `nil'
5808 if it points nowhere.
5810 (setq m (make-marker))
5811 => #<marker in no buffer>
5817 (set-marker m 3770 (current-buffer))
5818 => #<marker at 3770 in markers.texi>
5820 => #<buffer markers.texi>
5824 Two distinct markers are considered `equal' (even though not `eq')
5825 to each other if they have the same position and buffer, or if they
5829 File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
5831 42.5 Changing Marker Positions
5832 ==============================
5834 This section describes how to change the position of an existing
5835 marker. When you do this, be sure you know whether the marker is used
5836 outside of your program, and, if so, what effects will result from
5837 moving it--otherwise, confusing things may happen in other parts of
5840 -- Function: set-marker marker position &optional buffer
5841 This function moves MARKER to POSITION in BUFFER. If BUFFER is
5842 not provided, it defaults to the current buffer.
5844 POSITION can be a marker, an integer or `nil'. If POSITION is an
5845 integer, `set-marker' moves MARKER to point before the POSITIONth
5846 character in BUFFER. If POSITION is `nil', MARKER is made to
5847 point nowhere. Then it no longer slows down editing in any
5848 buffer. If POSITION is less than 1, MARKER is moved to the
5849 beginning of BUFFER. If POSITION is greater than the size of
5850 BUFFER, MARKER is moved to the end of BUFFER.
5852 The value returned is MARKER.
5854 (setq m (point-marker))
5855 => #<marker at 4714 in markers.texi>
5857 => #<marker at 55 in markers.texi>
5858 (setq b (get-buffer "foo"))
5861 => #<marker at 1 in foo>
5863 -- Function: move-marker marker position &optional buffer
5864 This is another name for `set-marker'.
5867 File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
5872 One special marker in each buffer is designated "the mark". It records
5873 a position for the user for the sake of commands such as `C-w' and `C-x
5874 <TAB>'. Lisp programs should set the mark only to values that have a
5875 potential use to the user, and never for their own internal purposes.
5876 For example, the `replace-regexp' command sets the mark to the value of
5877 point before doing any replacements, because this enables the user to
5878 move back there conveniently after the replace is finished.
5880 Once the mark "exists" in a buffer, it normally never ceases to
5881 exist. However, it may become "inactive", and usually does so after
5882 each command (other than simple motion commands and some commands that
5883 explicitly activate the mark). When the mark is active, the region
5884 between point and the mark is called the "active region" and is
5885 highlighted specially.
5887 Many commands are designed so that when called interactively they
5888 operate on the text between point and the mark. Such commands work
5889 only when an active region exists, i.e. when the mark is active. (The
5890 reason for this is to prevent you from accidentally deleting or
5891 changing large chunks of your text.) If you are writing such a command,
5892 don't examine the mark directly; instead, use `interactive' with the
5893 `r' specification. This provides the values of point and the mark as
5894 arguments to the command in an interactive call, but permits other Lisp
5895 programs to specify arguments explicitly, and automatically signals an
5896 error if the command is called interactively when no active region
5897 exists. *Note Interactive Codes::.
5899 Each buffer has its own value of the mark that is independent of the
5900 value of the mark in other buffers. (When a buffer is created, the mark
5901 exists but does not point anywhere. We consider this state as "the
5902 absence of a mark in that buffer.") However, only one active region can
5903 exist at a time. Activating the mark in one buffer automatically
5904 deactivates an active mark in any other buffer. Note that the user can
5905 explicitly activate a mark at any time by using the command
5906 `activate-region' (normally bound to `M-C-z') or by using the command
5907 `exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
5908 side effect of activating the mark.
5910 Some people do not like active regions, so they disable this behavior
5911 by setting the variable `zmacs-regions' to `nil'. This makes the mark
5912 always active (except when a buffer is just created and the mark points
5913 nowhere), and turns off the highlighting of the region between point
5914 and the mark. Commands that explicitly retrieve the value of the mark
5915 should make sure that they behave correctly and consistently
5916 irrespective of the setting of `zmacs-regions'; some primitives are
5917 provided to ensure this behavior.
5919 In addition to the mark, each buffer has a "mark ring" which is a
5920 list of markers containing previous values of the mark. When editing
5921 commands change the mark, they should normally save the old value of the
5922 mark on the mark ring. The variable `mark-ring-max' specifies the
5923 maximum number of entries in the mark ring; once the list becomes this
5924 long, adding a new element deletes the last element.
5926 -- Function: mark &optional force buffer
5927 This function returns BUFFER's mark position as an integer.
5928 BUFFER defaults to the current buffer if omitted.
5930 If the mark is inactive, `mark' normally returns `nil'. However,
5931 if FORCE is non-`nil', then `mark' returns the mark position
5932 anyway--or `nil', if the mark is not yet set for the buffer.
5934 (Remember that if `zmacs-regions' is `nil', the mark is always
5935 active as long as it exists, and the FORCE argument will have no
5938 If you are using this in an editing command, you are most likely
5939 making a mistake; see the documentation of `set-mark' below.
5941 -- Function: mark-marker &optional force buffer
5942 This function returns BUFFER's mark. BUFFER defaults to the
5943 current buffer if omitted. This is the very marker that records
5944 the mark location inside XEmacs, not a copy. Therefore, changing
5945 this marker's position will directly affect the position of the
5946 mark. Don't do it unless that is the effect you want.
5948 If the mark is inactive, `mark-marker' normally returns `nil'.
5949 However, if FORCE is non-`nil', then `mark-marker' returns the
5951 (setq m (mark-marker))
5952 => #<marker at 3420 in markers.texi>
5954 => #<marker at 100 in markers.texi>
5956 => #<marker at 100 in markers.texi>
5958 Like any marker, this marker can be set to point at any buffer you
5959 like. We don't recommend that you make it point at any buffer
5960 other than the one of which it is the mark. If you do, it will
5961 yield perfectly consistent, but rather odd, results.
5963 -- Function: set-mark position &optional buffer
5964 This function sets `buffer''s mark to POSITION, and activates the
5965 mark. BUFFER defaults to the current buffer if omitted. The old
5966 value of the mark is _not_ pushed onto the mark ring.
5968 *Please note:* Use this function only if you want the user to see
5969 that the mark has moved, and you want the previous mark position to
5970 be lost. Normally, when a new mark is set, the old one should go
5971 on the `mark-ring'. For this reason, most applications should use
5972 `push-mark' and `pop-mark', not `set-mark'.
5974 Novice XEmacs Lisp programmers often try to use the mark for the
5975 wrong purposes. The mark saves a location for the user's
5976 convenience. An editing command should not alter the mark unless
5977 altering the mark is part of the user-level functionality of the
5978 command. (And, in that case, this effect should be documented.)
5979 To remember a location for internal use in the Lisp program, store
5980 it in a Lisp variable. For example:
5982 (let ((start (point)))
5984 (delete-region start (point))).
5986 -- Command: exchange-point-and-mark &optional dont-activate-region
5987 This function exchanges the positions of point and the mark. It
5988 is intended for interactive use. The mark is also activated
5989 unless DONT-ACTIVATE-REGION is non-`nil'.
5991 -- Function: push-mark &optional position nomsg activate buffer
5992 This function sets BUFFER's mark to POSITION, and pushes a copy of
5993 the previous mark onto `mark-ring'. BUFFER defaults to the
5994 current buffer if omitted. If POSITION is `nil', then the value
5995 of point is used. `push-mark' returns `nil'.
5997 If the last global mark pushed was not in BUFFER, also push
5998 POSITION on the global mark ring (see below).
6000 The function `push-mark' normally _does not_ activate the mark.
6001 To do that, specify `t' for the argument ACTIVATE.
6003 A `Mark set' message is displayed unless NOMSG is non-`nil'.
6005 -- Function: pop-mark
6006 This function pops off the top element of `mark-ring' and makes
6007 that mark become the buffer's actual mark. This does not move
6008 point in the buffer, and it does nothing if `mark-ring' is empty.
6009 It deactivates the mark.
6011 The return value is not meaningful.
6013 -- Variable: mark-ring
6014 The value of this buffer-local variable is the list of saved former
6015 marks of the current buffer, most recent first.
6018 => (#<marker at 11050 in markers.texi>
6019 #<marker at 10832 in markers.texi>
6022 -- User Option: mark-ring-max
6023 The value of this variable is the maximum size of `mark-ring'. If
6024 more marks than this are pushed onto the `mark-ring', `push-mark'
6025 discards an old mark when it adds a new one.
6027 In additional to a per-buffer mark ring, there is a "global mark
6028 ring". Marks are pushed onto the global mark ring the first time you
6029 set a mark after switching buffers.
6031 -- Variable: global-mark-ring
6032 The value of this variable is the list of saved former global
6033 marks, most recent first.
6035 -- User Option: mark-ring-max
6036 The value of this variable is the maximum size of
6037 `global-mark-ring'. If more marks than this are pushed onto the
6038 `global-mark-ring', `push-mark' discards an old mark when it adds
6041 -- Command: pop-global-mark
6042 This function pops a mark off the global mark ring and jumps to
6046 File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
6051 The text between point and the mark is known as "the region". Various
6052 functions operate on text delimited by point and the mark, but only
6053 those functions specifically related to the region itself are described
6056 When `zmacs-regions' is non-`nil' (this is the default), the concept
6057 of an "active region" exists. The region is active when the
6058 corresponding mark is active. Note that only one active region at a
6059 time can exist--i.e. only one buffer's region is active at a time.
6060 *Note The Mark::, for more information about active regions.
6062 -- User Option: zmacs-regions
6063 If non-`nil' (the default), active regions are used. *Note The
6064 Mark::, for a detailed explanation of what this means.
6066 A number of functions are provided for explicitly determining the
6067 bounds of the region and whether it is active. Few programs need to use
6068 these functions, however. A command designed to operate on a region
6069 should normally use `interactive' with the `r' specification to find
6070 the beginning and end of the region. This lets other Lisp programs
6071 specify the bounds explicitly as arguments and automatically respects
6072 the user's setting for `zmacs-regions'. (*Note Interactive Codes::.)
6074 -- Function: region-beginning &optional buffer
6075 This function returns the position of the beginning of BUFFER's
6076 region (as an integer). This is the position of either point or
6077 the mark, whichever is smaller. BUFFER defaults to the current
6080 If the mark does not point anywhere, an error is signaled. Note
6081 that this function ignores whether the region is active.
6083 -- Function: region-end &optional buffer
6084 This function returns the position of the end of BUFFER's region
6085 (as an integer). This is the position of either point or the mark,
6086 whichever is larger. BUFFER defaults to the current buffer if
6089 If the mark does not point anywhere, an error is signaled. Note
6090 that this function ignores whether the region is active.
6092 -- Function: region-exists-p
6093 This function is non-`nil' if the region exists. If active regions
6094 are in use (i.e. `zmacs-regions' is true), this means that the
6095 region is active. Otherwise, this means that the user has pushed
6096 a mark in this buffer at some point in the past. If this function
6097 returns `nil', a function that uses the `r' interactive
6098 specification will cause an error when called interactively.
6100 -- Function: region-active-p
6101 If `zmacs-regions' is true, this is equivalent to
6102 `region-exists-p'. Otherwise, this function always returns false.
6103 This function is used by commands such as
6104 `fill-paragraph-or-region' and `capitalize-region-or-word', which
6105 operate either on the active region or on something else (e.g. the
6106 word or paragraph at point).
6108 -- Variable: zmacs-region-stays
6109 If a command sets this variable to true, the currently active
6110 region will remain activated when the command finishes. (Normally
6111 the region is deactivated when each command terminates.) If
6112 `zmacs-regions' is false, however, this has no effect. Under
6113 normal circumstances, you do not need to set this; use the
6114 interactive specification `_' instead, if you want the region to
6117 -- Function: zmacs-activate-region
6118 This function activates the region in the current buffer (this is
6119 equivalent to activating the current buffer's mark). This will
6120 normally also highlight the text in the active region and set
6121 `zmacs-region-stays' to `t'. (If `zmacs-regions' is false,
6122 however, this function has no effect.)
6124 -- Function: zmacs-deactivate-region
6125 This function deactivates the region in the current buffer (this is
6126 equivalent to deactivating the current buffer's mark). This will
6127 normally also unhighlight the text in the active region and set
6128 `zmacs-region-stays' to `nil'. (If `zmacs-regions' is false,
6129 however, this function has no effect.)
6131 -- Function: zmacs-update-region
6132 This function updates the active region, if it's currently active.
6133 (If there is no active region, this function does nothing.) This
6134 has the effect of updating the highlighting on the text in the
6135 region; but you should never need to call this except under rather
6136 strange circumstances. The command loop automatically calls it
6137 when appropriate. Calling this function will call the hook
6138 `zmacs-update-region-hook', if the region is active.
6140 -- Variable: zmacs-activate-region-hook
6141 This normal hook is called when a region becomes active. (Usually
6142 this happens as a result of a command that activates the region,
6143 such as `set-mark-command', `activate-region', or
6144 `exchange-point-and-mark'.) Note that calling
6145 `zmacs-activate-region' will call this hook, even if the region is
6146 already active. If `zmacs-regions' is false, however, this hook
6147 will never get called under any circumstances.
6149 -- Variable: zmacs-deactivate-region-hook
6150 This normal hook is called when an active region becomes inactive.
6151 (Calling `zmacs-deactivate-region' when the region is inactive will
6152 _not_ cause this hook to be called.) If `zmacs-regions' is false,
6153 this hook will never get called.
6155 -- Variable: zmacs-update-region-hook
6156 This normal hook is called when an active region is "updated" by
6157 `zmacs-update-region'. This normally gets called at the end of
6158 each command that sets `zmacs-region-stays' to `t', indicating
6159 that the region should remain activated. The motion commands do
6163 File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
6168 This chapter describes the functions that deal with the text in a
6169 buffer. Most examine, insert, or delete text in the current buffer,
6170 often in the vicinity of point. Many are interactive. All the
6171 functions that change the text provide for undoing the changes (*note
6174 Many text-related functions operate on a region of text defined by
6175 two buffer positions passed in arguments named START and END. These
6176 arguments should be either markers (*note Markers::) or numeric
6177 character positions (*note Positions::). The order of these arguments
6178 does not matter; it is all right for START to be the end of the region
6179 and END the beginning. For example, `(delete-region 1 10)' and
6180 `(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
6181 signaled if either START or END is outside the accessible portion of
6182 the buffer. In an interactive call, point and the mark are used for
6185 Throughout this chapter, "text" refers to the characters in the
6186 buffer, together with their properties (when relevant).
6190 * Near Point:: Examining text in the vicinity of point.
6191 * Buffer Contents:: Examining text in a general fashion.
6192 * Comparing Text:: Comparing substrings of buffers.
6193 * Insertion:: Adding new text to a buffer.
6194 * Commands for Insertion:: User-level commands to insert text.
6195 * Deletion:: Removing text from a buffer.
6196 * User-Level Deletion:: User-level commands to delete text.
6197 * The Kill Ring:: Where removed text sometimes is saved for later use.
6198 * Undo:: Undoing changes to the text of a buffer.
6199 * Maintaining Undo:: How to enable and disable undo information.
6200 How to control how much information is kept.
6201 * Filling:: Functions for explicit filling.
6202 * Margins:: How to specify margins for filling commands.
6203 * Auto Filling:: How auto-fill mode is implemented to break lines.
6204 * Sorting:: Functions for sorting parts of the buffer.
6205 * Columns:: Computing horizontal positions, and using them.
6206 * Indentation:: Functions to insert or adjust indentation.
6207 * Case Changes:: Case conversion of parts of the buffer.
6208 * Text Properties:: Assigning Lisp property lists to text characters.
6209 * Substitution:: Replacing a given character wherever it appears.
6210 * Registers:: How registers are implemented. Accessing the text or
6211 position stored in a register.
6212 * Transposition:: Swapping two portions of a buffer.
6213 * Change Hooks:: Supplying functions to be run when text is changed.
6214 * Transformations:: MD5 and base64 support.
6217 File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
6219 43.1 Examining Text Near Point
6220 ==============================
6222 Many functions are provided to look at the characters around point.
6223 Several simple functions are described here. See also `looking-at' in
6224 *Note Regexp Search::.
6226 Many of these functions take an optional BUFFER argument. In all
6227 such cases, the current buffer will be used if this argument is
6228 omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
6229 usually did not have these optional BUFFER arguments and always
6230 operated on the current buffer.)
6232 -- Function: char-after &optional position buffer
6233 This function returns the character in the buffer at (i.e.,
6234 immediately after) position POSITION. If POSITION is out of range
6235 for this purpose, either before the beginning of the buffer, or at
6236 or beyond the end, then the value is `nil'. The default for
6237 POSITION is point. If optional argument BUFFER is `nil', the
6238 current buffer is assumed.
6240 In the following example, assume that the first character in the
6243 (char-to-string (char-after 1))
6246 -- Function: char-before &optional position buffer
6247 This function returns the character in the current buffer
6248 immediately before position POSITION. If POSITION is out of range
6249 for this purpose, either at or before the beginning of the buffer,
6250 or beyond the end, then the value is `nil'. The default for
6251 POSITION is point. If optional argument BUFFER is `nil', the
6252 current buffer is assumed.
6254 -- Function: following-char &optional buffer
6255 This function returns the character following point in the buffer.
6256 This is similar to `(char-after (point))'. However, if point is at
6257 the end of the buffer, then the result of `following-char' is 0.
6258 If optional argument BUFFER is `nil', the current buffer is
6261 Remember that point is always between characters, and the terminal
6262 cursor normally appears over the character following point.
6263 Therefore, the character returned by `following-char' is the
6264 character the cursor is over.
6266 In this example, point is between the `a' and the `c'.
6268 ---------- Buffer: foo ----------
6269 Gentlemen may cry ``Pea-!-ce! Peace!,''
6270 but there is no peace.
6271 ---------- Buffer: foo ----------
6273 (char-to-string (preceding-char))
6275 (char-to-string (following-char))
6278 -- Function: preceding-char &optional buffer
6279 This function returns the character preceding point in the buffer.
6280 See above, under `following-char', for an example. If point is at
6281 the beginning of the buffer, `preceding-char' returns 0. If
6282 optional argument BUFFER is `nil', the current buffer is assumed.
6284 -- Function: bobp &optional buffer
6285 This function returns `t' if point is at the beginning of the
6286 buffer. If narrowing is in effect, this means the beginning of the
6287 accessible portion of the text. If optional argument BUFFER is
6288 `nil', the current buffer is assumed. See also `point-min' in
6291 -- Function: eobp &optional buffer
6292 This function returns `t' if point is at the end of the buffer.
6293 If narrowing is in effect, this means the end of accessible
6294 portion of the text. If optional argument BUFFER is `nil', the
6295 current buffer is assumed. See also `point-max' in *Note Point::.
6297 -- Function: bolp &optional buffer
6298 This function returns `t' if point is at the beginning of a line.
6299 If optional argument BUFFER is `nil', the current buffer is
6300 assumed. *Note Text Lines::. The beginning of the buffer (or its
6301 accessible portion) always counts as the beginning of a line.
6303 -- Function: eolp &optional buffer
6304 This function returns `t' if point is at the end of a line. The
6305 end of the buffer is always considered the end of a line. If
6306 optional argument BUFFER is `nil', the current buffer is assumed.
6307 The end of the buffer (or of its accessible portion) is always
6308 considered the end of a line.
6311 File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
6313 43.2 Examining Buffer Contents
6314 ==============================
6316 This section describes two functions that allow a Lisp program to
6317 convert any portion of the text in the buffer into a string.
6319 -- Function: buffer-substring start end &optional buffer
6320 -- Function: buffer-string start end &optional buffer
6321 These functions are equivalent and return a string containing a
6322 copy of the text of the region defined by positions START and END
6323 in the buffer. If the arguments are not positions in the
6324 accessible portion of the buffer, `buffer-substring' signals an
6325 `args-out-of-range' error. If optional argument BUFFER is `nil',
6326 the current buffer is assumed.
6328 If the region delineated by START and END contains duplicable
6329 extents, they will be remembered in the string. *Note Duplicable
6332 It is not necessary for START to be less than END; the arguments
6333 can be given in either order. But most often the smaller argument
6336 ---------- Buffer: foo ----------
6337 This is the contents of buffer foo
6339 ---------- Buffer: foo ----------
6341 (buffer-substring 1 10)
6343 (buffer-substring (point-max) 10)
6344 => "he contents of buffer foo
6348 File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
6353 This function lets you compare portions of the text in a buffer, without
6354 copying them into strings first.
6356 -- Function: compare-buffer-substrings buffer1 start1 end1 buffer2
6358 This function lets you compare two substrings of the same buffer
6359 or two different buffers. The first three arguments specify one
6360 substring, giving a buffer and two positions within the buffer.
6361 The last three arguments specify the other substring in the same
6362 way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
6365 The value is negative if the first substring is less, positive if
6366 the first is greater, and zero if they are equal. The absolute
6367 value of the result is one plus the index of the first differing
6368 characters within the substrings.
6370 This function ignores case when comparing characters if
6371 `case-fold-search' is non-`nil'. It always ignores text
6374 Suppose the current buffer contains the text `foobarbar
6375 haha!rara!'; then in this example the two substrings are `rbar '
6376 and `rara!'. The value is 2 because the first substring is greater
6377 at the second character.
6379 (compare-buffer-substring nil 6 11 nil 16 21)
6383 File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
6388 "Insertion" means adding new text to a buffer. The inserted text goes
6389 at point--between the character before point and the character after
6392 Insertion relocates markers that point at positions after the
6393 insertion point, so that they stay with the surrounding text (*note
6394 Markers::). When a marker points at the place of insertion, insertion
6395 normally doesn't relocate the marker, so that it points to the
6396 beginning of the inserted text; however, certain special functions such
6397 as `insert-before-markers' relocate such markers to point after the
6400 Some insertion functions leave point before the inserted text, while
6401 other functions leave it after. We call the former insertion "after
6402 point" and the latter insertion "before point".
6404 If a string with non-`nil' extent data is inserted, the remembered
6405 extents will also be inserted. *Note Duplicable Extents::.
6407 Insertion functions signal an error if the current buffer is
6410 These functions copy text characters from strings and buffers along
6411 with their properties. The inserted characters have exactly the same
6412 properties as the characters they were copied from. By contrast,
6413 characters specified as separate arguments, not part of a string or
6414 buffer, inherit their text properties from the neighboring text.
6416 -- Function: insert &rest args
6417 This function inserts the strings and/or characters ARGS into the
6418 current buffer, at point, moving point forward. In other words, it
6419 inserts the text before point. An error is signaled unless all
6420 ARGS are either strings or characters. The value is `nil'.
6422 -- Function: insert-before-markers &rest args
6423 This function inserts the strings and/or characters ARGS into the
6424 current buffer, at point, moving point forward. An error is
6425 signaled unless all ARGS are either strings or characters. The
6428 This function is unlike the other insertion functions in that it
6429 relocates markers initially pointing at the insertion point, to
6430 point after the inserted text.
6432 -- Function: insert-string string &optional buffer
6433 This function inserts STRING into BUFFER before point. BUFFER
6434 defaults to the current buffer if omitted. This function is
6435 chiefly useful if you want to insert a string in a buffer other
6436 than the current one (otherwise you could just use `insert').
6438 -- Function: insert-char character &optional count ignored buffer
6439 This function inserts COUNT instances of CHARACTER into BUFFER
6440 before point. COUNT must be a number, and CHARACTER must be a
6443 If optional argument BUFFER is `nil', the current buffer is
6444 assumed. (In FSF Emacs, the third argument is called INHERIT and
6445 refers to text properties. In XEmacs, it is always ignored.)
6447 This function always returns `nil'.
6449 -- Function: insert-buffer-substring from-buffer-or-name &optional
6451 This function inserts a portion of buffer FROM-BUFFER-OR-NAME
6452 (which must already exist) into the current buffer before point.
6453 The text inserted is the region from START and END. (These
6454 arguments default to the beginning and end of the accessible
6455 portion of that buffer.) This function returns `nil'.
6457 In this example, the form is executed with buffer `bar' as the
6458 current buffer. We assume that buffer `bar' is initially empty.
6460 ---------- Buffer: foo ----------
6461 We hold these truths to be self-evident, that all
6462 ---------- Buffer: foo ----------
6464 (insert-buffer-substring "foo" 1 20)
6467 ---------- Buffer: bar ----------
6468 We hold these truth-!-
6469 ---------- Buffer: bar ----------
6472 File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
6474 43.5 User-Level Insertion Commands
6475 ==================================
6477 This section describes higher-level commands for inserting text,
6478 commands intended primarily for the user but useful also in Lisp
6481 -- Command: insert-buffer from-buffer-or-name
6482 This command inserts the entire contents of FROM-BUFFER-OR-NAME
6483 (which must exist) into the current buffer after point. It leaves
6484 the mark after the inserted text. The value is `nil'.
6486 -- Command: self-insert-command count
6487 This command inserts the last character typed; it does so COUNT
6488 times, before point, and returns `nil'. Most printing characters
6489 are bound to this command. In routine use, `self-insert-command'
6490 is the most frequently called function in XEmacs, but programs
6491 rarely use it except to install it on a keymap.
6493 In an interactive call, COUNT is the numeric prefix argument.
6495 This command calls `auto-fill-function' whenever that is non-`nil'
6496 and the character inserted is a space or a newline (*note Auto
6499 This command performs abbrev expansion if Abbrev mode is enabled
6500 and the inserted character does not have word-constituent syntax.
6501 (*Note Abbrevs::, and *Note Syntax Class Table::.)
6503 This is also responsible for calling `blink-paren-function' when
6504 the inserted character has close parenthesis syntax (*note
6507 -- Command: newline &optional count
6508 This command inserts newlines into the current buffer before point.
6509 If COUNT is supplied, that many newline characters are inserted.
6511 This function calls `auto-fill-function' if the current column
6512 number is greater than the value of `fill-column' and COUNT is
6513 `nil'. Typically what `auto-fill-function' does is insert a
6514 newline; thus, the overall result in this case is to insert two
6515 newlines at different places: one at point, and another earlier in
6516 the line. `newline' does not auto-fill if COUNT is non-`nil'.
6518 This command indents to the left margin if that is not zero.
6521 The value returned is `nil'. In an interactive call, COUNT is the
6522 numeric prefix argument.
6524 -- Command: split-line
6525 This command splits the current line, moving the portion of the
6526 line after point down vertically so that it is on the next line
6527 directly below where it was before. Whitespace is inserted as
6528 needed at the beginning of the lower line, using the `indent-to'
6529 function. `split-line' returns the position of point.
6531 Programs hardly ever use this function.
6533 -- Variable: overwrite-mode
6534 This variable controls whether overwrite mode is in effect: a
6535 non-`nil' value enables the mode. It is automatically made
6536 buffer-local when set in any fashion.
6539 File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
6544 Deletion means removing part of the text in a buffer, without saving it
6545 in the kill ring (*note The Kill Ring::). Deleted text can't be
6546 yanked, but can be reinserted using the undo mechanism (*note Undo::).
6547 Some deletion functions do save text in the kill ring in some special
6550 All of the deletion functions operate on the current buffer, and all
6551 return a value of `nil'.
6553 -- Command: erase-buffer &optional buffer
6554 This function deletes the entire text of BUFFER, leaving it empty.
6555 If the buffer is read-only, it signals a `buffer-read-only'
6556 error. Otherwise, it deletes the text without asking for any
6557 confirmation. It returns `nil'. BUFFER defaults to the current
6560 Normally, deleting a large amount of text from a buffer inhibits
6561 further auto-saving of that buffer "because it has shrunk".
6562 However, `erase-buffer' does not do this, the idea being that the
6563 future text is not really related to the former text, and its size
6564 should not be compared with that of the former text.
6566 -- Command: delete-region start end &optional buffer
6567 This command deletes the text in BUFFER in the region defined by
6568 START and END. The value is `nil'. If optional argument BUFFER
6569 is `nil', the current buffer is assumed.
6571 -- Command: delete-char &optional count killp
6572 This command deletes COUNT characters directly after point, or
6573 before point if COUNT is negative. COUNT defaults to `1'. If
6574 KILLP is non-`nil', then it saves the deleted characters in the
6577 In an interactive call, COUNT is the numeric prefix argument, and
6578 KILLP is the unprocessed prefix argument. Therefore, if a prefix
6579 argument is supplied, the text is saved in the kill ring. If no
6580 prefix argument is supplied, then one character is deleted, but
6581 not saved in the kill ring.
6583 The value returned is always `nil'.
6585 -- Command: delete-backward-char &optional count killp
6586 This command deletes COUNT characters directly before point, or
6587 after point if COUNT is negative. COUNT defaults to 1. If KILLP
6588 is non-`nil', then it saves the deleted characters in the kill
6591 In an interactive call, COUNT is the numeric prefix argument, and
6592 KILLP is the unprocessed prefix argument. Therefore, if a prefix
6593 argument is supplied, the text is saved in the kill ring. If no
6594 prefix argument is supplied, then one character is deleted, but
6595 not saved in the kill ring.
6597 The value returned is always `nil'.
6599 -- Command: backward-delete-char-untabify count &optional killp
6600 This command deletes COUNT characters backward, changing tabs into
6601 spaces. When the next character to be deleted is a tab, it is
6602 first replaced with the proper number of spaces to preserve
6603 alignment and then one of those spaces is deleted instead of the
6604 tab. If KILLP is non-`nil', then the command saves the deleted
6605 characters in the kill ring.
6607 Conversion of tabs to spaces happens only if COUNT is positive.
6608 If it is negative, exactly -COUNT characters after point are
6611 In an interactive call, COUNT is the numeric prefix argument, and
6612 KILLP is the unprocessed prefix argument. Therefore, if a prefix
6613 argument is supplied, the text is saved in the kill ring. If no
6614 prefix argument is supplied, then one character is deleted, but
6615 not saved in the kill ring.
6617 The value returned is always `nil'.
6620 File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
6622 43.7 User-Level Deletion Commands
6623 =================================
6625 This section describes higher-level commands for deleting text,
6626 commands intended primarily for the user but useful also in Lisp
6629 -- Command: delete-horizontal-space
6630 This function deletes all spaces and tabs around point. It returns
6633 In the following examples, we call `delete-horizontal-space' four
6634 times, once on each line, with point between the second and third
6635 characters on the line each time.
6637 ---------- Buffer: foo ----------
6642 ---------- Buffer: foo ----------
6644 (delete-horizontal-space) ; Four times.
6647 ---------- Buffer: foo ----------
6652 ---------- Buffer: foo ----------
6654 -- Command: delete-indentation &optional join-following-p
6655 This function joins the line point is on to the previous line,
6656 deleting any whitespace at the join and in some cases replacing it
6657 with one space. If JOIN-FOLLOWING-P is non-`nil',
6658 `delete-indentation' joins this line to the following line
6659 instead. The value is `nil'.
6661 If there is a fill prefix, and the second of the lines being joined
6662 starts with the prefix, then `delete-indentation' deletes the fill
6663 prefix before joining the lines. *Note Margins::.
6665 In the example below, point is located on the line starting
6666 `events', and it makes no difference if there are trailing spaces
6667 in the preceding line.
6669 ---------- Buffer: foo ----------
6670 When in the course of human
6671 -!- events, it becomes necessary
6672 ---------- Buffer: foo ----------
6674 (delete-indentation)
6677 ---------- Buffer: foo ----------
6678 When in the course of human-!- events, it becomes necessary
6679 ---------- Buffer: foo ----------
6681 After the lines are joined, the function `fixup-whitespace' is
6682 responsible for deciding whether to leave a space at the junction.
6684 -- Command: fixup-whitespace
6685 This function replaces all the white space surrounding point with
6686 either one space or no space, according to the context. It
6689 At the beginning or end of a line, the appropriate amount of space
6690 is none. Before a character with close parenthesis syntax, or
6691 after a character with open parenthesis or expression-prefix
6692 syntax, no space is also appropriate. Otherwise, one space is
6693 appropriate. *Note Syntax Class Table::.
6695 In the example below, `fixup-whitespace' is called the first time
6696 with point before the word `spaces' in the first line. For the
6697 second invocation, point is directly after the `('.
6699 ---------- Buffer: foo ----------
6700 This has too many -!-spaces
6701 This has too many spaces at the start of (-!- this list)
6702 ---------- Buffer: foo ----------
6709 ---------- Buffer: foo ----------
6710 This has too many spaces
6711 This has too many spaces at the start of (this list)
6712 ---------- Buffer: foo ----------
6714 -- Command: just-one-space
6715 This command replaces any spaces and tabs around point with a
6716 single space. It returns `nil'.
6718 -- Command: delete-blank-lines
6719 This function deletes blank lines surrounding point. If point is
6720 on a blank line with one or more blank lines before or after it,
6721 then all but one of them are deleted. If point is on an isolated
6722 blank line, then it is deleted. If point is on a nonblank line,
6723 the command deletes all blank lines following it.
6725 A blank line is defined as a line containing only tabs and spaces.
6727 `delete-blank-lines' returns `nil'.
6730 File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
6735 "Kill" functions delete text like the deletion functions, but save it
6736 so that the user can reinsert it by "yanking". Most of these functions
6737 have `kill-' in their name. By contrast, the functions whose names
6738 start with `delete-' normally do not save text for yanking (though they
6739 can still be undone); these are "deletion" functions.
6741 Most of the kill commands are primarily for interactive use, and are
6742 not described here. What we do describe are the functions provided for
6743 use in writing such commands. You can use these functions to write
6744 commands for killing text. When you need to delete text for internal
6745 purposes within a Lisp function, you should normally use deletion
6746 functions, so as not to disturb the kill ring contents. *Note
6749 Killed text is saved for later yanking in the "kill ring". This is
6750 a list that holds a number of recent kills, not just the last text
6751 kill. We call this a "ring" because yanking treats it as having
6752 elements in a cyclic order. The list is kept in the variable
6753 `kill-ring', and can be operated on with the usual functions for lists;
6754 there are also specialized functions, described in this section, that
6757 Some people think this use of the word "kill" is unfortunate, since
6758 it refers to operations that specifically _do not_ destroy the entities
6759 "killed". This is in sharp contrast to ordinary life, in which death
6760 is permanent and "killed" entities do not come back to life.
6761 Therefore, other metaphors have been proposed. For example, the term
6762 "cut ring" makes sense to people who, in pre-computer days, used
6763 scissors and paste to cut up and rearrange manuscripts. However, it
6764 would be difficult to change the terminology now.
6768 * Kill Ring Concepts:: What text looks like in the kill ring.
6769 * Kill Functions:: Functions that kill text.
6770 * Yank Commands:: Commands that access the kill ring.
6771 * Low-Level Kill Ring:: Functions and variables for kill ring access.
6772 * Internals of Kill Ring:: Variables that hold kill-ring data.
6775 File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
6777 43.8.1 Kill Ring Concepts
6778 -------------------------
6780 The kill ring records killed text as strings in a list, most recent
6781 first. A short kill ring, for example, might look like this:
6783 ("some text" "a different piece of text" "even older text")
6785 When the list reaches `kill-ring-max' entries in length, adding a new
6786 entry automatically deletes the last entry.
6788 When kill commands are interwoven with other commands, each kill
6789 command makes a new entry in the kill ring. Multiple kill commands in
6790 succession build up a single entry in the kill ring, which would be
6791 yanked as a unit; the second and subsequent consecutive kill commands
6792 add text to the entry made by the first one.
6794 For yanking, one entry in the kill ring is designated the "front" of
6795 the ring. Some yank commands "rotate" the ring by designating a
6796 different element as the "front." But this virtual rotation doesn't
6797 change the list itself--the most recent entry always comes first in the
6801 File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
6803 43.8.2 Functions for Killing
6804 ----------------------------
6806 `kill-region' is the usual subroutine for killing text. Any command
6807 that calls this function is a "kill command" (and should probably have
6808 `kill' in its name). `kill-region' puts the newly killed text in a new
6809 element at the beginning of the kill ring or adds it to the most recent
6810 element. It uses the `last-command' variable to determine whether the
6811 previous command was a kill command, and if so appends the killed text
6812 to the most recent entry.
6814 -- Command: kill-region start end &optional verbose
6815 This function kills the text in the region defined by START and
6816 END. The text is deleted but saved in the kill ring, along with
6817 its text properties. The value is always `nil'.
6819 In an interactive call, START and END are point and the mark.
6821 If the buffer is read-only, `kill-region' modifies the kill ring
6822 just the same, then signals an error without modifying the buffer.
6823 This is convenient because it lets the user use all the kill
6824 commands to copy text into the kill ring from a read-only buffer.
6826 -- Command: copy-region-as-kill start end
6827 This command saves the region defined by START and END on the kill
6828 ring (including text properties), but does not delete the text
6829 from the buffer. It returns `nil'. It also indicates the extent
6830 of the text copied by moving the cursor momentarily, or by
6831 displaying a message in the echo area.
6833 The command does not set `this-command' to `kill-region', so a
6834 subsequent kill command does not append to the same kill ring
6837 Don't call `copy-region-as-kill' in Lisp programs unless you aim to
6838 support Emacs 18. For Emacs 19, it is better to use `kill-new' or
6839 `kill-append' instead. *Note Low-Level Kill Ring::.
6842 File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
6844 43.8.3 Functions for Yanking
6845 ----------------------------
6847 "Yanking" means reinserting an entry of previously killed text from the
6848 kill ring. The text properties are copied too.
6850 -- Command: yank &optional arg
6851 This command inserts before point the text in the first entry in
6852 the kill ring. It positions the mark at the beginning of that
6853 text, and point at the end.
6855 If ARG is a list (which occurs interactively when the user types
6856 `C-u' with no digits), then `yank' inserts the text as described
6857 above, but puts point before the yanked text and puts the mark
6860 If ARG is a number, then `yank' inserts the ARGth most recently
6861 killed text--the ARGth element of the kill ring list.
6863 `yank' does not alter the contents of the kill ring or rotate it.
6866 -- Command: yank-pop arg
6867 This command replaces the just-yanked entry from the kill ring
6868 with a different entry from the kill ring.
6870 This is allowed only immediately after a `yank' or another
6871 `yank-pop'. At such a time, the region contains text that was just
6872 inserted by yanking. `yank-pop' deletes that text and inserts in
6873 its place a different piece of killed text. It does not add the
6874 deleted text to the kill ring, since it is already in the kill
6877 If ARG is `nil', then the replacement text is the previous element
6878 of the kill ring. If ARG is numeric, the replacement is the ARGth
6879 previous kill. If ARG is negative, a more recent kill is the
6882 The sequence of kills in the kill ring wraps around, so that after
6883 the oldest one comes the newest one, and before the newest one
6886 The value is always `nil'.
6889 File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
6891 43.8.4 Low-Level Kill Ring
6892 --------------------------
6894 These functions and variables provide access to the kill ring at a lower
6895 level, but still convenient for use in Lisp programs. They take care of
6896 interaction with X Window selections. They do not exist in Emacs
6899 -- Function: current-kill count &optional do-not-move
6900 The function `current-kill' rotates the yanking pointer which
6901 designates the "front" of the kill ring by COUNT places (from newer
6902 kills to older ones), and returns the text at that place in the
6905 If the optional second argument DO-NOT-MOVE is non-`nil', then
6906 `current-kill' doesn't alter the yanking pointer; it just returns
6907 the COUNTth kill, counting from the current yanking pointer.
6909 If COUNT is zero, indicating a request for the latest kill,
6910 `current-kill' calls the value of `interprogram-paste-function'
6911 (documented below) before consulting the kill ring.
6913 -- Function: kill-new string &optional replace
6914 This function makes the text STRING the latest entry in the kill
6915 ring, and sets `kill-ring-yank-pointer' to point to it.
6917 Normally, STRING is added to the front of the kill ring as a new
6918 entry. However, if optional argument REPLACE is non-`nil', the
6919 entry previously at the front of the kill ring is discarded, and
6922 This function runs the functions on `kill-hooks', and also invokes
6923 the value of `interprogram-cut-function' (see below).
6925 -- Function: kill-append string before-p
6926 This function appends the text STRING to the first entry in the
6927 kill ring. Normally STRING goes at the end of the entry, but if
6928 BEFORE-P is non-`nil', it goes at the beginning. This function
6929 also invokes the value of `interprogram-cut-function' (see below).
6931 -- Variable: interprogram-paste-function
6932 This variable provides a way of transferring killed text from other
6933 programs, when you are using a window system. Its value should be
6934 `nil' or a function of no arguments.
6936 If the value is a function, `current-kill' calls it to get the
6937 "most recent kill". If the function returns a non-`nil' value,
6938 then that value is used as the "most recent kill". If it returns
6939 `nil', then the first element of `kill-ring' is used.
6941 The normal use of this hook is to get the X server's primary
6942 selection as the most recent kill, even if the selection belongs
6943 to another X client. *Note X Selections::.
6945 -- Variable: interprogram-cut-function
6946 This variable provides a way of communicating killed text to other
6947 programs, when you are using a window system. Its value should be
6948 `nil' or a function of one argument.
6950 If the value is a function, `kill-new' and `kill-append' call it
6951 with the new first element of the kill ring as an argument.
6953 The normal use of this hook is to set the X server's primary
6954 selection to the newly killed text.
projects / chise / xemacs-chise.git.1 / blob