1 This is ../info/lispref.info, produced by makeinfo version 4.0b 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: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers
58 This section describes the two primitives for creating buffers.
59 `get-buffer-create' creates a buffer if it finds no existing buffer
60 with the specified name; `generate-new-buffer' always creates a new
61 buffer and gives it a unique name.
63 Other functions you can use to create buffers include
64 `with-output-to-temp-buffer' (*note Temporary Displays::) and
65 `create-file-buffer' (*note Visiting Files::). Starting a subprocess
66 can also create a buffer (*note Processes::).
68 - Function: get-buffer-create name
69 This function returns a buffer named NAME. It returns an existing
70 buffer with that name, if one exists; otherwise, it creates a new
71 buffer. The buffer does not become the current buffer--this
72 function does not change which buffer is current.
74 An error is signaled if NAME is not a string.
76 (get-buffer-create "foo")
79 The major mode for the new buffer is set to Fundamental mode. The
80 variable `default-major-mode' is handled at a higher level. *Note
83 - Function: generate-new-buffer name
84 This function returns a newly created, empty buffer, but does not
85 make it current. If there is no buffer named NAME, then that is
86 the name of the new buffer. If that name is in use, this function
87 adds suffixes of the form `<N>' to NAME, where N is an integer.
88 It tries successive integers starting with 2 until it finds an
91 An error is signaled if NAME is not a string.
93 (generate-new-buffer "bar")
95 (generate-new-buffer "bar")
97 (generate-new-buffer "bar")
100 The major mode for the new buffer is set to Fundamental mode. The
101 variable `default-major-mode' is handled at a higher level. *Note
104 See the related function `generate-new-buffer-name' in *Note
108 File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers
113 "Killing a buffer" makes its name unknown to XEmacs and makes its
114 text space available for other use.
116 The buffer object for the buffer that has been killed remains in
117 existence as long as anything refers to it, but it is specially marked
118 so that you cannot make it current or display it. Killed buffers retain
119 their identity, however; two distinct buffers, when killed, remain
120 distinct according to `eq'.
122 If you kill a buffer that is current or displayed in a window, XEmacs
123 automatically selects or displays some other buffer instead. This means
124 that killing a buffer can in general change the current buffer.
125 Therefore, when you kill a buffer, you should also take the precautions
126 associated with changing the current buffer (unless you happen to know
127 that the buffer being killed isn't current). *Note Current Buffer::.
129 If you kill a buffer that is the base buffer of one or more indirect
130 buffers, the indirect buffers are automatically killed as well.
132 The `buffer-name' of a killed buffer is `nil'. To test whether a
133 buffer has been killed, you can either use this feature or the function
136 - Function: buffer-live-p object
137 This function returns `t' if OBJECT is an editor buffer that has
138 not been deleted, `nil' otherwise.
140 - Command: kill-buffer buffer-or-name
141 This function kills the buffer BUFFER-OR-NAME, freeing all its
142 memory for use as space for other buffers. (Emacs version 18 and
143 older was unable to return the memory to the operating system.)
144 It returns `nil'. The argument BUFFER-OR-NAME may be a buffer or
147 Any processes that have this buffer as the `process-buffer' are
148 sent the `SIGHUP' signal, which normally causes them to terminate.
149 (The basic meaning of `SIGHUP' is that a dialup line has been
150 disconnected.) *Note Deleting Processes::.
152 If the buffer is visiting a file and contains unsaved changes,
153 `kill-buffer' asks the user to confirm before the buffer is killed.
154 It does this even if not called interactively. To prevent the
155 request for confirmation, clear the modified flag before calling
156 `kill-buffer'. *Note Buffer Modification::.
158 Killing a buffer that is already dead has no effect.
160 (kill-buffer "foo.unchanged")
162 (kill-buffer "foo.changed")
164 ---------- Buffer: Minibuffer ----------
165 Buffer foo.changed modified; kill anyway? (yes or no) yes
166 ---------- Buffer: Minibuffer ----------
170 - Variable: kill-buffer-query-functions
171 After confirming unsaved changes, `kill-buffer' calls the functions
172 in the list `kill-buffer-query-functions', in order of appearance,
173 with no arguments. The buffer being killed is the current buffer
174 when they are called. The idea is that these functions ask for
175 confirmation from the user for various nonstandard reasons. If
176 any of them returns `nil', `kill-buffer' spares the buffer's life.
178 - Variable: kill-buffer-hook
179 This is a normal hook run by `kill-buffer' after asking all the
180 questions it is going to ask, just before actually killing the
181 buffer. The buffer to be killed is current when the hook
182 functions run. *Note Hooks::.
184 - Variable: buffer-offer-save
185 This variable, if non-`nil' in a particular buffer, tells
186 `save-buffers-kill-emacs' and `save-some-buffers' to offer to save
187 that buffer, just as they offer to save file-visiting buffers. The
188 variable `buffer-offer-save' automatically becomes buffer-local
189 when set for any reason. *Note Buffer-Local Variables::.
192 File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers
197 An "indirect buffer" shares the text of some other buffer, which is
198 called the "base buffer" of the indirect buffer. In some ways it is
199 the analogue, for buffers, of a symbolic link among files. The base
200 buffer may not itself be an indirect buffer. One base buffer may have
201 several "indirect children".
203 The text of the indirect buffer is always identical to the text of
204 its base buffer; changes made by editing either one are visible
205 immediately in the other.
207 But in all other respects, the indirect buffer and its base buffer
208 are completely separate. They have different names, different values of
209 point and mark, different narrowing, different markers and extents
210 (though inserting or deleting text in either buffer relocates the
211 markers and extents for both), different major modes, and different
212 local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not
213 automatically share text properties among themselves and their base
216 An indirect buffer cannot visit a file, but its base buffer can. If
217 you try to save the indirect buffer, that actually works by saving the
220 Killing an indirect buffer has no effect on its base buffer. Killing
221 the base buffer kills all its indirect children.
223 - Command: make-indirect-buffer base-buffer name
224 This creates an indirect buffer named NAME whose base buffer is
225 BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string.
227 If BASE-BUFFER is an indirect buffer, its base buffer is used as
228 the base for the new buffer.
230 (make-indirect-buffer "*scratch*" "indirect")
231 => #<buffer "indirect">
233 - Function: buffer-base-buffer &optional buffer
234 This function returns the base buffer of BUFFER. If BUFFER is not
235 indirect, the value is `nil'. Otherwise, the value is another
236 buffer, which is never an indirect buffer. If BUFFER is not
237 supplied, it defaults to the current buffer.
239 (buffer-base-buffer (get-buffer "indirect"))
240 => #<buffer "*scratch*">
242 - Function: buffer-indirect-children &optional buffer
243 This function returns a list of all indirect buffers whose base
244 buffer is BUFFER. If BUFFER is indirect, the return value will
245 always be `nil'; see `make-indirect-buffer'. If BUFFER is not
246 supplied, it defaults to the current buffer.
248 (buffer-indirect-children (get-buffer "*scratch*"))
249 => (#<buffer "indirect">)
252 File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top
257 This chapter describes most of the functions and variables related to
258 Emacs windows. See *Note Display::, for information on how text is
259 displayed in windows.
263 * Basic Windows:: Basic information on using windows.
264 * Splitting Windows:: Splitting one window into two windows.
265 * Deleting Windows:: Deleting a window gives its space to other windows.
266 * Selecting Windows:: The selected window is the one that you edit in.
267 * Cyclic Window Ordering:: Moving around the existing windows.
268 * Buffers and Windows:: Each window displays the contents of a buffer.
269 * Displaying Buffers:: Higher-lever functions for displaying a buffer
270 and choosing a window for it.
271 * Choosing Window:: How to choose a window for displaying a buffer.
272 * Window Point:: Each window has its own location of point.
273 * Window Start:: The display-start position controls which text
274 is on-screen in the window.
275 * Vertical Scrolling:: Moving text up and down in the window.
276 * Horizontal Scrolling:: Moving text sideways on the window.
277 * Size of Window:: Accessing the size of a window.
278 * Position of Window:: Accessing the position of a window.
279 * Resizing Windows:: Changing the size of a window.
280 * Window Configurations:: Saving and restoring the state of the screen.
283 File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows
285 Basic Concepts of Emacs Windows
286 ===============================
288 A "window" in XEmacs is the physical area of the screen in which a
289 buffer is displayed. The term is also used to refer to a Lisp object
290 that represents that screen area in XEmacs Lisp. It should be clear
291 from the context which is meant.
293 XEmacs groups windows into frames. A frame represents an area of
294 screen available for XEmacs to use. Each frame always contains at least
295 one window, but you can subdivide it vertically or horizontally into
296 multiple nonoverlapping Emacs windows.
298 In each frame, at any time, one and only one window is designated as
299 "selected within the frame". The frame's cursor appears in that
300 window. At ant time, one frame is the selected frame; and the window
301 selected within that frame is "the selected window". The selected
302 window's buffer is usually the current buffer (except when `set-buffer'
303 has been used). *Note Current Buffer::.
305 For practical purposes, a window exists only while it is displayed in
306 a frame. Once removed from the frame, the window is effectively deleted
307 and should not be used, _even though there may still be references to
308 it_ from other Lisp objects. Restoring a saved window configuration is
309 the only way for a window no longer on the screen to come back to life.
310 (*Note Deleting Windows::.)
312 Each window has the following attributes:
320 * window edges with respect to the frame or screen
322 * the buffer it displays
324 * position within the buffer at the upper left of the window
326 * amount of horizontal scrolling, in columns
332 * how recently the window was selected
334 Users create multiple windows so they can look at several buffers at
335 once. Lisp libraries use multiple windows for a variety of reasons, but
336 most often to display related information. In Rmail, for example, you
337 can move through a summary buffer in one window while the other window
338 shows messages one at a time as they are reached.
340 The meaning of "window" in XEmacs is similar to what it means in the
341 context of general-purpose window systems such as X, but not identical.
342 The X Window System places X windows on the screen; XEmacs uses one or
343 more X windows as frames, and subdivides them into Emacs windows. When
344 you use XEmacs on a character-only terminal, XEmacs treats the whole
345 terminal screen as one frame.
347 Most window systems support arbitrarily located overlapping windows.
348 In contrast, Emacs windows are "tiled"; they never overlap, and
349 together they fill the whole screen or frame. Because of the way in
350 which XEmacs creates new windows and resizes them, you can't create
351 every conceivable tiling of windows on an Emacs frame. *Note Splitting
352 Windows::, and *Note Size of Window::.
354 *Note Display::, for information on how the contents of the window's
355 buffer are displayed in the window.
357 - Function: windowp object
358 This function returns `t' if OBJECT is a window.
361 File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows
366 The functions described here are the primitives used to split a
367 window into two windows. Two higher level functions sometimes split a
368 window, but not always: `pop-to-buffer' and `display-buffer' (*note
369 Displaying Buffers::).
371 The functions described here do not accept a buffer as an argument.
372 The two "halves" of the split window initially display the same buffer
373 previously visible in the window that was split.
375 - Function: one-window-p &optional nomini which-frames which-devices
376 This function returns non-`nil' if there is only one window. The
377 argument NOMINI, if non-`nil', means don't count the minibuffer
378 even if it is active; otherwise, the minibuffer window is
379 included, if active, in the total number of windows which is
380 compared against one.
382 The remaining arguments controls which set of windows are counted,
383 as with `next-window'.
385 - Command: split-window &optional window size horizontal
386 This function splits WINDOW into two windows. The original window
387 WINDOW remains the selected window, but occupies only part of its
388 former screen area. The rest is occupied by a newly created
389 window which is returned as the value of this function.
391 If HORIZONTAL is non-`nil', then WINDOW splits into two side by
392 side windows. The original window WINDOW keeps the leftmost SIZE
393 columns, and gives the rest of the columns to the new window.
394 Otherwise, it splits into windows one above the other, and WINDOW
395 keeps the upper SIZE lines and gives the rest of the lines to the
396 new window. The original window is therefore the left-hand or
397 upper of the two, and the new window is the right-hand or lower.
399 If WINDOW is omitted or `nil', then the selected window is split.
400 If SIZE is omitted or `nil', then WINDOW is divided evenly into
401 two parts. (If there is an odd line, it is allocated to the new
402 window.) When `split-window' is called interactively, all its
405 The following example starts with one window on a frame that is 50
406 lines high by 80 columns wide; then the window is split.
408 (setq w (selected-window))
409 => #<window 8 on windows.texi>
410 (window-edges) ; Edges in order:
411 => (0 0 80 50) ; left-top-right-bottom
413 ;; Returns window created
414 (setq w2 (split-window w 15))
415 => #<window 28 on windows.texi>
417 => (0 15 80 50) ; Bottom window;
420 => (0 0 80 15) ; Top window
422 The frame looks like this:
434 Next, the top window is split horizontally:
436 (setq w3 (split-window w 35 t))
437 => #<window 32 on windows.texi>
439 => (35 0 80 15) ; Left edge at column 35
441 => (0 0 35 15) ; Right edge at column 35
443 => (0 15 80 50) ; Bottom window unchanged
445 Now, the screen looks like this:
458 Normally, Emacs indicates the border between two side-by-side
459 windows with a scroll bar (*note Scroll Bars: X Frame Properties.)
460 or `|' characters. The display table can specify alternative
461 border characters; see *Note Display Tables::.
463 - Command: split-window-vertically &optional size
464 This function splits the selected window into two windows, one
465 above the other, leaving the selected window with SIZE lines.
467 This function is simply an interface to `split-window'. Here is
468 the complete function definition for it:
470 (defun split-window-vertically (&optional arg)
471 "Split current window into two windows, one above the other."
473 (split-window nil (and arg (prefix-numeric-value arg))))
475 - Command: split-window-horizontally &optional size
476 This function splits the selected window into two windows
477 side-by-side, leaving the selected window with SIZE columns.
479 This function is simply an interface to `split-window'. Here is
480 the complete definition for `split-window-horizontally' (except for
481 part of the documentation string):
483 (defun split-window-horizontally (&optional arg)
484 "Split selected window into two windows, side by side..."
486 (split-window nil (and arg (prefix-numeric-value arg)) t))
489 File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows
494 A window remains visible on its frame unless you "delete" it by
495 calling certain functions that delete windows. A deleted window cannot
496 appear on the screen, but continues to exist as a Lisp object until
497 there are no references to it. There is no way to cancel the deletion
498 of a window aside from restoring a saved window configuration (*note
499 Window Configurations::). Restoring a window configuration also
500 deletes any windows that aren't part of that configuration.
502 When you delete a window, the space it took up is given to one
503 adjacent sibling. (In Emacs version 18, the space was divided evenly
504 among all the siblings.)
506 - Function: window-live-p window
507 This function returns `nil' if WINDOW is deleted, and `t'
510 *Warning:* Erroneous information or fatal errors may result from
511 using a deleted window as if it were live.
513 - Command: delete-window &optional window force
514 This function removes WINDOW from the display. If WINDOW is
515 omitted, then the selected window is deleted. If window is the
516 only one on its frame, the frame is deleted as well.
518 Normally, you cannot delete the last non-minibuffer-only frame
519 (you must use `save-buffers-kill-emacs' or `kill-emacs'); an error
520 is signaled instead. However, if optional second argument FORCE is
521 non-`nil', you can delete the last frame. (This will automatically
522 call `save-buffers-kill-emacs'.)
524 This function returns `nil'.
526 When `delete-window' is called interactively, the selected window
529 - Command: delete-other-windows &optional window
530 This function makes WINDOW the only window on its frame, by
531 deleting the other windows in that frame. If WINDOW is omitted or
532 `nil', then the selected window is used by default.
536 - Command: delete-windows-on buffer &optional which-frames
538 This function deletes all windows showing BUFFER. If there are no
539 windows showing BUFFER, it does nothing.
541 `delete-windows-on' operates frame by frame. If a frame has
542 several windows showing different buffers, then those showing
543 BUFFER are removed, and the others expand to fill the space. If
544 all windows in some frame are showing BUFFER (including the case
545 where there is only one window), then the frame reverts to having a
546 single window showing another buffer chosen with `other-buffer'.
547 *Note The Buffer List::.
549 The argument WHICH-FRAMES controls which frames to operate on:
552 Delete all windows showing BUFFER in any frame.
555 Delete only windows showing BUFFER in the selected frame.
558 Delete all windows showing BUFFER in any visible frame.
561 Delete all windows showing BUFFER in any visible frame.
564 If it is a frame, delete all windows showing BUFFER in that
567 *Warning:* This is similar to, but not identical to, the meaning
568 of the WHICH-FRAMES argument to `next-window'; the meanings of
569 `nil' and `t' are reversed.
571 The optional argument WHICH-DEVICES further clarifies on which
572 devices to search for frames as specified by WHICH-FRAMES. This
573 value is only meaningful if WHICH-FRAMES is not `t'.
576 Consider all devices on the selected console.
579 Consider only the one device DEVICE.
582 Consider all devices on CONSOLE.
585 Consider all devices with device type DEVICE-TYPE.
588 Consider all devices on window system consoles.
591 Consider all devices without restriction.
593 This function always returns `nil'.
596 File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows
601 When a window is selected, the buffer in the window becomes the
602 current buffer, and the cursor will appear in it.
604 - Function: selected-window &optional device
605 This function returns the selected window. This is the window in
606 which the cursor appears and to which many commands apply. Each
607 separate device can have its own selected window, which is
608 remembered as focus changes from device to device. Optional
609 argument DEVICE specifies which device to return the selected
610 window for, and defaults to the selected device.
612 - Function: select-window window &optional norecord
613 This function makes WINDOW the selected window. The cursor then
614 appears in WINDOW (on redisplay). The buffer being displayed in
615 WINDOW is immediately designated the current buffer.
617 If optional argument NORECORD is non-`nil' then the global and
618 per-frame buffer orderings are not modified, as by the function
621 The return value is WINDOW.
623 (setq w (next-window))
625 => #<window 65 on windows.texi>
627 - Special Form: save-selected-window forms...
628 This special form records the selected window, executes FORMS in
629 sequence, then restores the earlier selected window. It does not
630 save or restore anything about the sizes, arrangement or contents
631 of windows; therefore, if the FORMS change them, the changes are
634 The following functions choose one of the windows on the screen,
635 offering various criteria for the choice.
637 - Function: get-lru-window &optional which-frames which-devices
638 This function returns the window least recently "used" (that is,
639 selected). The selected window is always the most recently used
642 The selected window can be the least recently used window if it is
643 the only window. A newly created window becomes the least
644 recently used window until it is selected. A minibuffer window is
647 By default, only the windows in the selected frame are considered.
648 The optional argument WHICH-FRAMES changes this behavior. Here
649 are the possible values and their meanings:
652 Consider all the windows in the selected windows's frame,
653 plus the minibuffer used by that frame even if it lies in
657 Consider all windows in all existing frames.
660 Consider all windows in all visible frames. (To get useful
661 results, you must ensure WINDOW is in a visible frame.)
664 Consider all windows in all visible or iconified frames.
667 Consider all windows on frame FRAME.
670 Consider precisely the windows in the selected window's
671 frame, and no others.
673 The optional argument WHICH-DEVICES further clarifies on which
674 devices to search for frames as specified by WHICH-FRAMES. This
675 value is only meaningful if WHICH-FRAMES is non-`nil'.
678 Consider all devices on the selected console.
681 Consider only the one device DEVICE.
684 Consider all devices on CONSOLE.
687 Consider all devices with device type DEVICE-TYPE.
690 Consider all devices on window system consoles.
693 Consider all devices without restriction.
696 - Function: get-largest-window &optional which-frames which-devices
697 This function returns the window with the largest area (height
698 times width). If there are no side-by-side windows, then this is
699 the window with the most lines. A minibuffer window is never a
702 If there are two windows of the same size, then the function
703 returns the window that is first in the cyclic ordering of windows
704 (see following section), starting from the selected window.
706 The remaining arguments control which set of windows are
707 considered. See `next-window', above.
710 File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows
712 Cyclic Ordering of Windows
713 ==========================
715 When you use the command `C-x o' (`other-window') to select the next
716 window, it moves through all the windows on the screen in a specific
717 cyclic order. For any given configuration of windows, this order never
718 varies. It is called the "cyclic ordering of windows".
720 This ordering generally goes from top to bottom, and from left to
721 right. But it may go down first or go right first, depending on the
722 order in which the windows were split.
724 If the first split was vertical (into windows one above each other),
725 and then the subwindows were split horizontally, then the ordering is
726 left to right in the top of the frame, and then left to right in the
727 next lower part of the frame, and so on. If the first split was
728 horizontal, the ordering is top to bottom in the left part, and so on.
729 In general, within each set of siblings at any level in the window tree,
730 the order is left to right, or top to bottom.
732 - Function: next-window &optional window minibuf which-frames
734 This function returns the window following WINDOW in the cyclic
735 ordering of windows. This is the window that `C-x o' would select
736 if typed when WINDOW is selected. If WINDOW is the only window
737 visible, then this function returns WINDOW. If omitted, WINDOW
738 defaults to the selected window.
740 The value of the argument MINIBUF determines whether the
741 minibuffer is included in the window order. Normally, when
742 MINIBUF is `nil', the minibuffer is included if it is currently
743 active; this is the behavior of `C-x o'. (The minibuffer window
744 is active while the minibuffer is in use. *Note Minibuffers::.)
746 If MINIBUF is `t', then the cyclic ordering includes the
747 minibuffer window even if it is not active.
749 If MINIBUF is neither `t' nor `nil', then the minibuffer window is
750 not included even if it is active.
752 By default, only the windows in the selected frame are considered.
753 The optional argument WHICH-FRAMES changes this behavior. Here
754 are the possible values and their meanings:
757 Consider all the windows in WINDOW's frame, plus the
758 minibuffer used by that frame even if it lies in some other
762 Consider all windows in all existing frames.
765 Consider all windows in all visible frames. (To get useful
766 results, you must ensure WINDOW is in a visible frame.)
769 Consider all windows in all visible or iconified frames.
772 Consider all windows on frame FRAME.
775 Consider precisely the windows in WINDOW's frame, and no
778 The optional argument WHICH-DEVICES further clarifies on which
779 devices to search for frames as specified by WHICH-FRAMES. This
780 value is only meaningful if WHICH-FRAMES is non-`nil'.
783 Consider all devices on the selected console.
786 Consider only the one device DEVICE.
789 Consider all devices on CONSOLE.
792 Consider all devices with device type DEVICE-TYPE.
795 Consider all devices on window system consoles.
798 Consider all devices without restriction.
800 If you use consistent values for MINIBUF, WHICH-FRAMES, and
801 WHICH-DEVICES, you can use `next-window' to iterate through the
802 entire cycle of acceptable windows, eventually ending up back at
803 the window you started with. `previous-window' traverses the same
804 cycle, in the reverse order.
806 This example assumes there are two windows, both displaying the
807 buffer `windows.texi':
810 => #<window 56 on windows.texi>
811 (next-window (selected-window))
812 => #<window 52 on windows.texi>
813 (next-window (next-window (selected-window)))
814 => #<window 56 on windows.texi>
816 - Function: previous-window &optional window minibuf which-frames
818 This function returns the window preceding WINDOW in the cyclic
819 ordering of windows. The other arguments specify which windows to
820 include in the cycle, as in `next-window'.
822 - Command: other-window count &optional which-frames which-devices
823 This function selects the COUNTth following window in the cyclic
824 order. If COUNT is negative, then it selects the -COUNTth
825 preceding window. It returns `nil'.
827 In an interactive call, COUNT is the numeric prefix argument.
829 The other arguments specify which windows to include in the cycle,
832 - Function: walk-windows function &optional minibuf which-frames
834 This function cycles through all windows, calling `function' once
835 for each window with the window as its sole argument.
837 The other arguments specify which windows to cycle through, as in
841 File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
846 This section describes low-level functions to examine windows or to
847 display buffers in windows in a precisely controlled fashion. *Note
848 Displaying Buffers::, for related functions that find a window to use
849 and specify a buffer for it. The functions described there are easier
850 to use than these, but they employ heuristics in choosing or creating a
851 window; use these functions when you need complete control.
853 - Function: set-window-buffer window buffer-or-name &optional norecord
854 This function makes WINDOW display BUFFER-OR-NAME as its contents.
855 BUFFER-OR-NAME can be a buffer or a buffer name.
857 With non-`nil' optional argument NORECORD, do not modify the
858 global or per-frame buffer ordering.
860 This function returns `nil'.
862 (set-window-buffer (selected-window) "foo")
865 - Function: window-buffer &optional window
866 This function returns the buffer that WINDOW is displaying. If
867 WINDOW is omitted, this function returns the buffer for the
871 => #<buffer windows.texi>
873 - Function: get-buffer-window buffer-or-name &optional which-frames
875 This function returns a window currently displaying
876 BUFFER-OR-NAME, or `nil' if there is none. If there are several
877 such windows, then the function returns the first one in the
878 cyclic ordering of windows, starting from the selected window.
879 *Note Cyclic Window Ordering::.
881 The remaining arguments control which windows to consider. They
882 have the same meaning as for `next-window'.
885 File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
887 Displaying Buffers in Windows
888 =============================
890 In this section we describe convenient functions that choose a window
891 automatically and use it to display a specified buffer. These functions
892 can also split an existing window in certain circumstances. We also
893 describe variables that parameterize the heuristics used for choosing a
894 window. *Note Buffers and Windows::, for low-level functions that give
895 you more precise control.
897 Do not use the functions in this section in order to make a buffer
898 current so that a Lisp program can access or modify it; they are too
899 drastic for that purpose, since they change the display of buffers in
900 windows, which is gratuitous and will surprise the user. Instead, use
901 `set-buffer' (*note Current Buffer::) and `save-excursion' (*note
902 Excursions::), which designate buffers as current for programmed access
903 without affecting the display of buffers in windows.
905 - Command: switch-to-buffer buffer-or-name &optional norecord
906 This function makes BUFFER-OR-NAME the current buffer, and also
907 displays the buffer in the selected window. This means that a
908 human can see the buffer and subsequent keyboard commands will
909 apply to it. Contrast this with `set-buffer', which makes
910 BUFFER-OR-NAME the current buffer but does not display it in the
911 selected window. *Note Current Buffer::.
913 If BUFFER-OR-NAME does not identify an existing buffer, then a new
914 buffer by that name is created. The major mode for the new buffer
915 is set according to the variable `default-major-mode'. *Note Auto
918 Normally the specified buffer is put at the front of the buffer
919 list. This affects the operation of `other-buffer'. However, if
920 NORECORD is non-`nil', this is not done. *Note The Buffer List::.
922 The `switch-to-buffer' function is often used interactively, as
923 the binding of `C-x b'. It is also used frequently in programs.
924 It always returns `nil'.
926 - Command: switch-to-buffer-other-window buffer-or-name
927 This function makes BUFFER-OR-NAME the current buffer and displays
928 it in a window not currently selected. It then selects that
929 window. The handling of the buffer is the same as in
932 The currently selected window is absolutely never used to do the
933 job. If it is the only window, then it is split to make a
934 distinct window for this purpose. If the selected window is
935 already displaying the buffer, then it continues to do so, but
936 another window is nonetheless found to display it in as well.
938 - Function: pop-to-buffer buffer-or-name &optional other-window
940 This function makes BUFFER-OR-NAME the current buffer and switches
941 to it in some window, preferably not the window previously
942 selected. The "popped-to" window becomes the selected window
945 If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
946 looks for a window in any visible frame already displaying the
947 buffer; if there is one, it returns that window and makes it be
948 selected within its frame. If there is none, it creates a new
949 frame and displays the buffer in it.
951 If `pop-up-frames' is `nil', then `pop-to-buffer' operates
952 entirely within the selected frame. (If the selected frame has
953 just a minibuffer, `pop-to-buffer' operates within the most
954 recently selected frame that was not just a minibuffer.)
956 If the variable `pop-up-windows' is non-`nil', windows may be
957 split to create a new window that is different from the original
958 window. For details, see *Note Choosing Window::.
960 If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
961 another window even if BUFFER-OR-NAME is already visible in the
962 selected window. Thus BUFFER-OR-NAME could end up displayed in
963 two windows. On the other hand, if BUFFER-OR-NAME is already
964 displayed in the selected window and OTHER-WINDOW is `nil', then
965 the selected window is considered sufficient display for
966 BUFFER-OR-NAME, so that nothing needs to be done.
968 All the variables that affect `display-buffer' affect
969 `pop-to-buffer' as well. *Note Choosing Window::.
971 If BUFFER-OR-NAME is a string that does not name an existing
972 buffer, a buffer by that name is created. The major mode for the
973 new buffer is set according to the variable `default-major-mode'.
974 *Note Auto Major Mode::.
976 If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
978 An example use of this function is found at the end of *Note
981 - Command: replace-buffer-in-windows buffer &optional which-frames
983 This function replaces BUFFER with some other buffer in all
984 windows displaying it. The other buffer used is chosen with
985 `other-buffer'. In the usual applications of this function, you
986 don't care which other buffer is used; you just want to make sure
987 that BUFFER is no longer displayed.
989 The optional arguments WHICH-FRAMES and WHICH-DEVICES have the
990 same meaning as with `delete-windows-on'.
992 This function returns `nil'.
995 File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
997 Choosing a Window for Display
998 =============================
1000 This section describes the basic facility that chooses a window to
1001 display a buffer in--`display-buffer'. All the higher-level functions
1002 and commands use this subroutine. Here we describe how to use
1003 `display-buffer' and how to customize it.
1005 - Command: display-buffer buffer-or-name &optional not-this-window
1007 This command makes BUFFER-OR-NAME appear in some window, like
1008 `pop-to-buffer', but it does not select that window and does not
1009 make the buffer current. The identity of the selected window is
1010 unaltered by this function.
1012 BUFFER-OR-NAME can be a buffer or the name of one.
1014 If NOT-THIS-WINDOW is non-`nil', it means to display the specified
1015 buffer in a window other than the selected one, even if it is
1016 already on display in the selected window. This can cause the
1017 buffer to appear in two windows at once. Otherwise, if
1018 BUFFER-OR-NAME is already being displayed in any window, that is
1019 good enough, so this function does nothing.
1021 If OVERRIDE-FRAME is non-`nil', display on that frame instead of
1022 the current frame (or the dedicated frame).
1024 `display-buffer' returns the window chosen to display
1027 Precisely how `display-buffer' finds or creates a window depends on
1028 the variables described below.
1030 A window can be marked as "dedicated" to a particular buffer. Then
1031 XEmacs will not automatically change which buffer appears in the
1032 window, such as `display-buffer' might normally do.
1034 - Function: window-dedicated-p window
1035 This function returns WINDOW's dedicated object, usually `t' or
1038 - Function: set-window-buffer-dedicated window buffer
1039 This function makes WINDOW display BUFFER and be dedicated to that
1040 buffer. Then XEmacs will not automatically change which buffer
1041 appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
1042 not be dedicated (but doesn't change which buffer appears in it
1045 - User Option: pop-up-windows
1046 This variable controls whether `display-buffer' makes new windows.
1047 If it is non-`nil' and there is only one window, then that window
1048 is split. If it is `nil', then `display-buffer' does not split
1049 the single window, but uses it whole.
1051 - User Option: split-height-threshold
1052 This variable determines when `display-buffer' may split a window,
1053 if there are multiple windows. `display-buffer' always splits the
1054 largest window if it has at least this many lines. If the largest
1055 window is not this tall, it is split only if it is the sole window
1056 and `pop-up-windows' is non-`nil'.
1058 - User Option: pop-up-frames
1059 This variable controls whether `display-buffer' makes new frames.
1060 If it is non-`nil', `display-buffer' looks for an existing window
1061 already displaying the desired buffer, on any visible frame. If
1062 it finds one, it returns that window. Otherwise it makes a new
1063 frame. The variables `pop-up-windows' and
1064 `split-height-threshold' do not matter if `pop-up-frames' is
1067 If `pop-up-frames' is `nil', then `display-buffer' either splits a
1068 window or reuses one.
1070 *Note Frames::, for more information.
1072 - Variable: pop-up-frame-function
1073 This variable specifies how to make a new frame if `pop-up-frames'
1076 Its value should be a function of no arguments. When
1077 `display-buffer' makes a new frame, it does so by calling that
1078 function, which should return a frame. The default value of the
1079 variable is a function that creates a frame using properties from
1080 `pop-up-frame-plist'.
1082 - Variable: pop-up-frame-plist
1083 This variable holds a plist specifying frame properties used when
1084 `display-buffer' makes a new frame. *Note Frame Properties::, for
1085 more information about frame properties.
1087 - Variable: special-display-buffer-names
1088 A list of buffer names for buffers that should be displayed
1089 specially. If the buffer's name is in this list, `display-buffer'
1090 handles the buffer specially.
1092 By default, special display means to give the buffer a dedicated
1095 If an element is a list, instead of a string, then the CAR of the
1096 list is the buffer name, and the rest of the list says how to
1097 create the frame. There are two possibilities for the rest of the
1098 list. It can be a plist, specifying frame properties, or it can
1099 contain a function and arguments to give to it. (The function's
1100 first argument is always the buffer to be displayed; the arguments
1101 from the list come after that.)
1103 - Variable: special-display-regexps
1104 A list of regular expressions that specify buffers that should be
1105 displayed specially. If the buffer's name matches any of the
1106 regular expressions in this list, `display-buffer' handles the
1109 By default, special display means to give the buffer a dedicated
1112 If an element is a list, instead of a string, then the CAR of the
1113 list is the regular expression, and the rest of the list says how
1114 to create the frame. See above, under
1115 `special-display-buffer-names'.
1117 - Variable: special-display-function
1118 This variable holds the function to call to display a buffer
1119 specially. It receives the buffer as an argument, and should
1120 return the window in which it is displayed.
1122 The default value of this variable is
1123 `special-display-popup-frame'.
1125 - Function: special-display-popup-frame buffer
1126 This function makes BUFFER visible in a frame of its own. If
1127 BUFFER is already displayed in a window in some frame, it makes
1128 the frame visible and raises it, to use that window. Otherwise, it
1129 creates a frame that will be dedicated to BUFFER.
1131 This function uses an existing window displaying BUFFER whether or
1132 not it is in a frame of its own; but if you set up the above
1133 variables in your init file, before BUFFER was created, then
1134 presumably the window was previously made by this function.
1136 - User Option: special-display-frame-plist
1137 This variable holds frame properties for
1138 `special-display-popup-frame' to use when it creates a frame.
1140 - Variable: same-window-buffer-names
1141 A list of buffer names for buffers that should be displayed in the
1142 selected window. If the buffer's name is in this list,
1143 `display-buffer' handles the buffer by switching to it in the
1146 - Variable: same-window-regexps
1147 A list of regular expressions that specify buffers that should be
1148 displayed in the selected window. If the buffer's name matches
1149 any of the regular expressions in this list, `display-buffer'
1150 handles the buffer by switching to it in the selected window.
1152 - Variable: display-buffer-function
1153 This variable is the most flexible way to customize the behavior of
1154 `display-buffer'. If it is non-`nil', it should be a function
1155 that `display-buffer' calls to do the work. The function should
1156 accept two arguments, the same two arguments that `display-buffer'
1157 received. It should choose or create a window, display the
1158 specified buffer, and then return the window.
1160 This hook takes precedence over all the other options and hooks
1163 A window can be marked as "dedicated" to its buffer. Then
1164 `display-buffer' does not try to use that window.
1166 - Function: window-dedicated-p window
1167 This function returns `t' if WINDOW is marked as dedicated;
1170 - Function: set-window-dedicated-p window flag
1171 This function marks WINDOW as dedicated if FLAG is non-`nil', and
1172 nondedicated otherwise.
1175 File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows
1180 Each window has its own value of point, independent of the value of
1181 point in other windows displaying the same buffer. This makes it useful
1182 to have multiple windows showing one buffer.
1184 * The window point is established when a window is first created; it
1185 is initialized from the buffer's point, or from the window point
1186 of another window opened on the buffer if such a window exists.
1188 * Selecting a window sets the value of point in its buffer to the
1189 window's value of point. Conversely, deselecting a window sets
1190 the window's value of point from that of the buffer. Thus, when
1191 you switch between windows that display a given buffer, the point
1192 value for the selected window is in effect in the buffer, while
1193 the point values for the other windows are stored in those windows.
1195 * As long as the selected window displays the current buffer, the
1196 window's point and the buffer's point always move together; they
1199 * *Note Positions::, for more details on buffer positions.
1201 As far as the user is concerned, point is where the cursor is, and
1202 when the user switches to another buffer, the cursor jumps to the
1203 position of point in that buffer.
1205 - Function: window-point &optional window
1206 This function returns the current position of point in WINDOW.
1207 For a non-selected window, this is the value point would have (in
1208 that window's buffer) if that window were selected.
1210 When WINDOW is the selected window and its buffer is also the
1211 current buffer, the value returned is the same as the value of
1212 point in that buffer.
1214 Strictly speaking, it would be more correct to return the
1215 "top-level" value of point, outside of any `save-excursion' forms.
1216 But that value is hard to find.
1218 - Function: set-window-point window position
1219 This function positions point in WINDOW at position POSITION in
projects / chise / xemacs-chise.git- / blob