1 This is ../info/lispref.info, produced by makeinfo version 4.0 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: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows
58 When a window is selected, the buffer in the window becomes the
59 current buffer, and the cursor will appear in it.
61 - Function: selected-window &optional device
62 This function returns the selected window. This is the window in
63 which the cursor appears and to which many commands apply. Each
64 separate device can have its own selected window, which is
65 remembered as focus changes from device to device. Optional
66 argument DEVICE specifies which device to return the selected
67 window for, and defaults to the selected device.
69 - Function: select-window window &optional norecord
70 This function makes WINDOW the selected window. The cursor then
71 appears in WINDOW (on redisplay). The buffer being displayed in
72 WINDOW is immediately designated the current buffer.
74 If optional argument NORECORD is non-`nil' then the global and
75 per-frame buffer orderings are not modified, as by the function
78 The return value is WINDOW.
80 (setq w (next-window))
82 => #<window 65 on windows.texi>
84 - Macro: save-selected-window forms...
85 This macro records the selected window, executes FORMS in
86 sequence, then restores the earlier selected window. It does not
87 save or restore anything about the sizes, arrangement or contents
88 of windows; therefore, if the FORMS change them, the changes are
91 The following functions choose one of the windows on the screen,
92 offering various criteria for the choice.
94 - Function: get-lru-window &optional frame
95 This function returns the window least recently "used" (that is,
96 selected). The selected window is always the most recently used
99 The selected window can be the least recently used window if it is
100 the only window. A newly created window becomes the least
101 recently used window until it is selected. A minibuffer window is
104 The argument FRAME controls which windows are considered.
106 * If it is `nil', consider windows on the selected frame.
108 * If it is `t', consider windows on all frames.
110 * If it is `visible', consider windows on all visible frames.
112 * If it is 0, consider windows on all visible or iconified
115 * If it is a frame, consider windows on that frame.
117 - Function: get-largest-window &optional frame
118 This function returns the window with the largest area (height
119 times width). If there are no side-by-side windows, then this is
120 the window with the most lines. A minibuffer window is never a
123 If there are two windows of the same size, then the function
124 returns the window that is first in the cyclic ordering of windows
125 (see following section), starting from the selected window.
127 The argument FRAME controls which set of windows are considered.
128 See `get-lru-window', above.
131 File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows
133 Cyclic Ordering of Windows
134 ==========================
136 When you use the command `C-x o' (`other-window') to select the next
137 window, it moves through all the windows on the screen in a specific
138 cyclic order. For any given configuration of windows, this order never
139 varies. It is called the "cyclic ordering of windows".
141 This ordering generally goes from top to bottom, and from left to
142 right. But it may go down first or go right first, depending on the
143 order in which the windows were split.
145 If the first split was vertical (into windows one above each other),
146 and then the subwindows were split horizontally, then the ordering is
147 left to right in the top of the frame, and then left to right in the
148 next lower part of the frame, and so on. If the first split was
149 horizontal, the ordering is top to bottom in the left part, and so on.
150 In general, within each set of siblings at any level in the window tree,
151 the order is left to right, or top to bottom.
153 - Function: next-window &optional window minibuf all-frames
154 This function returns the window following WINDOW in the cyclic
155 ordering of windows. This is the window that `C-x o' would select
156 if typed when WINDOW is selected. If WINDOW is the only window
157 visible, then this function returns WINDOW. If omitted, WINDOW
158 defaults to the selected window.
160 The value of the argument MINIBUF determines whether the
161 minibuffer is included in the window order. Normally, when
162 MINIBUF is `nil', the minibuffer is included if it is currently
163 active; this is the behavior of `C-x o'. (The minibuffer window
164 is active while the minibuffer is in use. *Note Minibuffers::.)
166 If MINIBUF is `t', then the cyclic ordering includes the
167 minibuffer window even if it is not active.
169 If MINIBUF is neither `t' nor `nil', then the minibuffer window is
170 not included even if it is active.
172 The argument ALL-FRAMES specifies which frames to consider. Here
173 are the possible values and their meanings:
176 Consider all the windows in WINDOW's frame, plus the
177 minibuffer used by that frame even if it lies in some other
181 Consider all windows in all existing frames.
184 Consider all windows in all visible frames. (To get useful
185 results, you must ensure WINDOW is in a visible frame.)
188 Consider all windows in all visible or iconified frames.
191 Consider precisely the windows in WINDOW's frame, and no
194 This example assumes there are two windows, both displaying the
195 buffer `windows.texi':
198 => #<window 56 on windows.texi>
199 (next-window (selected-window))
200 => #<window 52 on windows.texi>
201 (next-window (next-window (selected-window)))
202 => #<window 56 on windows.texi>
204 - Function: previous-window &optional window minibuf all-frames
205 This function returns the window preceding WINDOW in the cyclic
206 ordering of windows. The other arguments specify which windows to
207 include in the cycle, as in `next-window'.
209 - Command: other-window count &optional frame
210 This function selects the COUNTth following window in the cyclic
211 order. If count is negative, then it selects the -COUNTth
212 preceding window. It returns `nil'.
214 In an interactive call, COUNT is the numeric prefix argument.
216 The argument FRAME controls which set of windows are considered.
217 * If it is `nil' or omitted, then windows on the selected frame
220 * If it is a frame, then windows on that frame are considered.
222 * If it is `t', then windows on all frames that currently exist
223 (including invisible and iconified frames) are considered.
225 * If it is the symbol `visible', then windows on all visible
226 frames are considered.
228 * If it is the number 0, then windows on all visible and
229 iconified frames are considered.
231 * If it is any other value, then the behavior is undefined.
233 - Function: walk-windows proc &optional minibuf all-frames
234 This function cycles through all windows, calling `proc' once for
235 each window with the window as its sole argument.
237 The optional arguments MINIBUF and ALL-FRAMES specify the set of
238 windows to include in the scan. See `next-window', above, for
242 File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
247 This section describes low-level functions to examine windows or to
248 display buffers in windows in a precisely controlled fashion. *Note
249 Displaying Buffers::, for related functions that find a window to use
250 and specify a buffer for it. The functions described there are easier
251 to use than these, but they employ heuristics in choosing or creating a
252 window; use these functions when you need complete control.
254 - Function: set-window-buffer window buffer-or-name
255 This function makes WINDOW display BUFFER-OR-NAME as its contents.
258 (set-window-buffer (selected-window) "foo")
261 - Function: window-buffer &optional window
262 This function returns the buffer that WINDOW is displaying. If
263 WINDOW is omitted, this function returns the buffer for the
267 => #<buffer windows.texi>
269 - Function: get-buffer-window buffer-or-name &optional frame
270 This function returns a window currently displaying
271 BUFFER-OR-NAME, or `nil' if there is none. If there are several
272 such windows, then the function returns the first one in the
273 cyclic ordering of windows, starting from the selected window.
274 *Note Cyclic Window Ordering::.
276 The argument ALL-FRAMES controls which windows to consider.
278 * If it is `nil', consider windows on the selected frame.
280 * If it is `t', consider windows on all frames.
282 * If it is `visible', consider windows on all visible frames.
284 * If it is 0, consider windows on all visible or iconified
287 * If it is a frame, consider windows on that frame.
290 File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
292 Displaying Buffers in Windows
293 =============================
295 In this section we describe convenient functions that choose a window
296 automatically and use it to display a specified buffer. These functions
297 can also split an existing window in certain circumstances. We also
298 describe variables that parameterize the heuristics used for choosing a
299 window. *Note Buffers and Windows::, for low-level functions that give
300 you more precise control.
302 Do not use the functions in this section in order to make a buffer
303 current so that a Lisp program can access or modify it; they are too
304 drastic for that purpose, since they change the display of buffers in
305 windows, which is gratuitous and will surprise the user. Instead, use
306 `set-buffer' (*note Current Buffer::) and `save-excursion' (*note
307 Excursions::), which designate buffers as current for programmed access
308 without affecting the display of buffers in windows.
310 - Command: switch-to-buffer buffer-or-name &optional norecord
311 This function makes BUFFER-OR-NAME the current buffer, and also
312 displays the buffer in the selected window. This means that a
313 human can see the buffer and subsequent keyboard commands will
314 apply to it. Contrast this with `set-buffer', which makes
315 BUFFER-OR-NAME the current buffer but does not display it in the
316 selected window. *Note Current Buffer::.
318 If BUFFER-OR-NAME does not identify an existing buffer, then a new
319 buffer by that name is created. The major mode for the new buffer
320 is set according to the variable `default-major-mode'. *Note Auto
323 Normally the specified buffer is put at the front of the buffer
324 list. This affects the operation of `other-buffer'. However, if
325 NORECORD is non-`nil', this is not done. *Note The Buffer List::.
327 The `switch-to-buffer' function is often used interactively, as
328 the binding of `C-x b'. It is also used frequently in programs.
329 It always returns `nil'.
331 - Command: switch-to-buffer-other-window buffer-or-name
332 This function makes BUFFER-OR-NAME the current buffer and displays
333 it in a window not currently selected. It then selects that
334 window. The handling of the buffer is the same as in
337 The currently selected window is absolutely never used to do the
338 job. If it is the only window, then it is split to make a
339 distinct window for this purpose. If the selected window is
340 already displaying the buffer, then it continues to do so, but
341 another window is nonetheless found to display it in as well.
343 - Function: pop-to-buffer buffer-or-name &optional other-window
345 This function makes BUFFER-OR-NAME the current buffer and switches
346 to it in some window, preferably not the window previously
347 selected. The "popped-to" window becomes the selected window
350 If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
351 looks for a window in any visible frame already displaying the
352 buffer; if there is one, it returns that window and makes it be
353 selected within its frame. If there is none, it creates a new
354 frame and displays the buffer in it.
356 If `pop-up-frames' is `nil', then `pop-to-buffer' operates
357 entirely within the selected frame. (If the selected frame has
358 just a minibuffer, `pop-to-buffer' operates within the most
359 recently selected frame that was not just a minibuffer.)
361 If the variable `pop-up-windows' is non-`nil', windows may be
362 split to create a new window that is different from the original
363 window. For details, see *Note Choosing Window::.
365 If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
366 another window even if BUFFER-OR-NAME is already visible in the
367 selected window. Thus BUFFER-OR-NAME could end up displayed in
368 two windows. On the other hand, if BUFFER-OR-NAME is already
369 displayed in the selected window and OTHER-WINDOW is `nil', then
370 the selected window is considered sufficient display for
371 BUFFER-OR-NAME, so that nothing needs to be done.
373 All the variables that affect `display-buffer' affect
374 `pop-to-buffer' as well. *Note Choosing Window::.
376 If BUFFER-OR-NAME is a string that does not name an existing
377 buffer, a buffer by that name is created. The major mode for the
378 new buffer is set according to the variable `default-major-mode'.
379 *Note Auto Major Mode::.
381 If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
383 An example use of this function is found at the end of *Note
386 - Command: replace-buffer-in-windows buffer
387 This function replaces BUFFER with some other buffer in all
388 windows displaying it. The other buffer used is chosen with
389 `other-buffer'. In the usual applications of this function, you
390 don't care which other buffer is used; you just want to make sure
391 that BUFFER is no longer displayed.
393 This function returns `nil'.
396 File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
398 Choosing a Window for Display
399 =============================
401 This section describes the basic facility that chooses a window to
402 display a buffer in--`display-buffer'. All the higher-level functions
403 and commands use this subroutine. Here we describe how to use
404 `display-buffer' and how to customize it.
406 - Command: display-buffer buffer-or-name &optional not-this-window
407 This command makes BUFFER-OR-NAME appear in some window, like
408 `pop-to-buffer', but it does not select that window and does not
409 make the buffer current. The identity of the selected window is
410 unaltered by this function.
412 If NOT-THIS-WINDOW is non-`nil', it means to display the specified
413 buffer in a window other than the selected one, even if it is
414 already on display in the selected window. This can cause the
415 buffer to appear in two windows at once. Otherwise, if
416 BUFFER-OR-NAME is already being displayed in any window, that is
417 good enough, so this function does nothing.
419 `display-buffer' returns the window chosen to display
422 Precisely how `display-buffer' finds or creates a window depends on
423 the variables described below.
425 A window can be marked as "dedicated" to a particular buffer. Then
426 XEmacs will not automatically change which buffer appears in the
427 window, such as `display-buffer' might normally do.
429 - Function: window-dedicated-p window
430 This function returns WINDOW's dedicated object, usually `t' or
433 - Function: set-window-buffer-dedicated window buffer
434 This function makes WINDOW display BUFFER and be dedicated to that
435 buffer. Then XEmacs will not automatically change which buffer
436 appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
437 not be dedicated (but doesn't change which buffer appears in it
440 - User Option: pop-up-windows
441 This variable controls whether `display-buffer' makes new windows.
442 If it is non-`nil' and there is only one window, then that window
443 is split. If it is `nil', then `display-buffer' does not split
444 the single window, but uses it whole.
446 - User Option: split-height-threshold
447 This variable determines when `display-buffer' may split a window,
448 if there are multiple windows. `display-buffer' always splits the
449 largest window if it has at least this many lines. If the largest
450 window is not this tall, it is split only if it is the sole window
451 and `pop-up-windows' is non-`nil'.
453 - User Option: pop-up-frames
454 This variable controls whether `display-buffer' makes new frames.
455 If it is non-`nil', `display-buffer' looks for an existing window
456 already displaying the desired buffer, on any visible frame. If
457 it finds one, it returns that window. Otherwise it makes a new
458 frame. The variables `pop-up-windows' and
459 `split-height-threshold' do not matter if `pop-up-frames' is
462 If `pop-up-frames' is `nil', then `display-buffer' either splits a
463 window or reuses one.
465 *Note Frames::, for more information.
467 - Variable: pop-up-frame-function
468 This variable specifies how to make a new frame if `pop-up-frames'
471 Its value should be a function of no arguments. When
472 `display-buffer' makes a new frame, it does so by calling that
473 function, which should return a frame. The default value of the
474 variable is a function that creates a frame using properties from
475 `pop-up-frame-plist'.
477 - Variable: pop-up-frame-plist
478 This variable holds a plist specifying frame properties used when
479 `display-buffer' makes a new frame. *Note Frame Properties::, for
480 more information about frame properties.
482 - Variable: special-display-buffer-names
483 A list of buffer names for buffers that should be displayed
484 specially. If the buffer's name is in this list, `display-buffer'
485 handles the buffer specially.
487 By default, special display means to give the buffer a dedicated
490 If an element is a list, instead of a string, then the CAR of the
491 list is the buffer name, and the rest of the list says how to
492 create the frame. There are two possibilities for the rest of the
493 list. It can be a plist, specifying frame properties, or it can
494 contain a function and arguments to give to it. (The function's
495 first argument is always the buffer to be displayed; the arguments
496 from the list come after that.)
498 - Variable: special-display-regexps
499 A list of regular expressions that specify buffers that should be
500 displayed specially. If the buffer's name matches any of the
501 regular expressions in this list, `display-buffer' handles the
504 By default, special display means to give the buffer a dedicated
507 If an element is a list, instead of a string, then the CAR of the
508 list is the regular expression, and the rest of the list says how
509 to create the frame. See above, under
510 `special-display-buffer-names'.
512 - Variable: special-display-function
513 This variable holds the function to call to display a buffer
514 specially. It receives the buffer as an argument, and should
515 return the window in which it is displayed.
517 The default value of this variable is
518 `special-display-popup-frame'.
520 - Function: special-display-popup-frame buffer
521 This function makes BUFFER visible in a frame of its own. If
522 BUFFER is already displayed in a window in some frame, it makes
523 the frame visible and raises it, to use that window. Otherwise, it
524 creates a frame that will be dedicated to BUFFER.
526 This function uses an existing window displaying BUFFER whether or
527 not it is in a frame of its own; but if you set up the above
528 variables in your init file, before BUFFER was created, then
529 presumably the window was previously made by this function.
531 - User Option: special-display-frame-plist
532 This variable holds frame properties for
533 `special-display-popup-frame' to use when it creates a frame.
535 - Variable: same-window-buffer-names
536 A list of buffer names for buffers that should be displayed in the
537 selected window. If the buffer's name is in this list,
538 `display-buffer' handles the buffer by switching to it in the
541 - Variable: same-window-regexps
542 A list of regular expressions that specify buffers that should be
543 displayed in the selected window. If the buffer's name matches
544 any of the regular expressions in this list, `display-buffer'
545 handles the buffer by switching to it in the selected window.
547 - Variable: display-buffer-function
548 This variable is the most flexible way to customize the behavior of
549 `display-buffer'. If it is non-`nil', it should be a function
550 that `display-buffer' calls to do the work. The function should
551 accept two arguments, the same two arguments that `display-buffer'
552 received. It should choose or create a window, display the
553 specified buffer, and then return the window.
555 This hook takes precedence over all the other options and hooks
558 A window can be marked as "dedicated" to its buffer. Then
559 `display-buffer' does not try to use that window.
561 - Function: window-dedicated-p window
562 This function returns `t' if WINDOW is marked as dedicated;
565 - Function: set-window-dedicated-p window flag
566 This function marks WINDOW as dedicated if FLAG is non-`nil', and
567 nondedicated otherwise.
570 File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows
575 Each window has its own value of point, independent of the value of
576 point in other windows displaying the same buffer. This makes it useful
577 to have multiple windows showing one buffer.
579 * The window point is established when a window is first created; it
580 is initialized from the buffer's point, or from the window point
581 of another window opened on the buffer if such a window exists.
583 * Selecting a window sets the value of point in its buffer to the
584 window's value of point. Conversely, deselecting a window sets
585 the window's value of point from that of the buffer. Thus, when
586 you switch between windows that display a given buffer, the point
587 value for the selected window is in effect in the buffer, while
588 the point values for the other windows are stored in those windows.
590 * As long as the selected window displays the current buffer, the
591 window's point and the buffer's point always move together; they
594 * *Note Positions::, for more details on buffer positions.
596 As far as the user is concerned, point is where the cursor is, and
597 when the user switches to another buffer, the cursor jumps to the
598 position of point in that buffer.
600 - Function: window-point window
601 This function returns the current position of point in WINDOW.
602 For a non-selected window, this is the value point would have (in
603 that window's buffer) if that window were selected.
605 When WINDOW is the selected window and its buffer is also the
606 current buffer, the value returned is the same as point in that
609 Strictly speaking, it would be more correct to return the
610 "top-level" value of point, outside of any `save-excursion' forms.
611 But that value is hard to find.
613 - Function: set-window-point window position
614 This function positions point in WINDOW at position POSITION in
618 File: lispref.info, Node: Window Start, Next: Vertical Scrolling, Prev: Window Point, Up: Windows
620 The Window Start Position
621 =========================
623 Each window contains a marker used to keep track of a buffer position
624 that specifies where in the buffer display should start. This position
625 is called the "display-start" position of the window (or just the
626 "start"). The character after this position is the one that appears at
627 the upper left corner of the window. It is usually, but not
628 inevitably, at the beginning of a text line.
630 - Function: window-start &optional window
631 This function returns the display-start position of window WINDOW.
632 If WINDOW is `nil', the selected window is used. For example,
637 When you create a window, or display a different buffer in it, the
638 display-start position is set to a display-start position recently
639 used for the same buffer, or 1 if the buffer doesn't have any.
641 For a realistic example, see the description of `count-lines' in
644 - Function: window-end &optional window
645 This function returns the position of the end of the display in
646 window WINDOW. If WINDOW is `nil', the selected window is used.
648 Simply changing the buffer text or moving point does not update the
649 value that `window-end' returns. The value is updated only when
650 Emacs redisplays and redisplay actually finishes.
652 If the last redisplay of WINDOW was preempted, and did not finish,
653 Emacs does not know the position of the end of display in that
654 window. In that case, this function returns a value that is not
655 correct. In a future version, `window-end' will return `nil' in
658 - Function: set-window-start window position &optional noforce
659 This function sets the display-start position of WINDOW to
660 POSITION in WINDOW's buffer. It returns POSITION.
662 The display routines insist that the position of point be visible
663 when a buffer is displayed. Normally, they change the
664 display-start position (that is, scroll the window) whenever
665 necessary to make point visible. However, if you specify the
666 start position with this function using `nil' for NOFORCE, it
667 means you want display to start at POSITION even if that would put
668 the location of point off the screen. If this does place point
669 off screen, the display routines move point to the left margin on
670 the middle line in the window.
672 For example, if point is 1 and you set the start of the window
673 to 2, then point would be "above" the top of the window. The
674 display routines will automatically move point if it is still 1
675 when redisplay occurs. Here is an example:
677 ;; Here is what `foo' looks like before executing
678 ;; the `set-window-start' expression.
680 ---------- Buffer: foo ----------
681 -!-This is the contents of buffer foo.
687 ---------- Buffer: foo ----------
694 ;; Here is what `foo' looks like after executing
695 ;; the `set-window-start' expression.
696 ---------- Buffer: foo ----------
697 his is the contents of buffer foo.
703 ---------- Buffer: foo ----------
705 If NOFORCE is non-`nil', and POSITION would place point off screen
706 at the next redisplay, then redisplay computes a new window-start
707 position that works well with point, and thus POSITION is not used.
709 - Function: pos-visible-in-window-p &optional position window
710 This function returns `t' if POSITION is within the range of text
711 currently visible on the screen in WINDOW. It returns `nil' if
712 POSITION is scrolled vertically out of view. The argument
713 POSITION defaults to the current position of point; WINDOW, to the
714 selected window. Here is an example:
716 (or (pos-visible-in-window-p
717 (point) (selected-window))
720 The `pos-visible-in-window-p' function considers only vertical
721 scrolling. If POSITION is out of view only because WINDOW has
722 been scrolled horizontally, `pos-visible-in-window-p' returns `t'.
723 *Note Horizontal Scrolling::.
726 File: lispref.info, Node: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Window Start, Up: Windows
731 Vertical scrolling means moving the text up or down in a window. It
732 works by changing the value of the window's display-start location. It
733 may also change the value of `window-point' to keep it on the screen.
735 In the commands `scroll-up' and `scroll-down', the directions "up"
736 and "down" refer to the motion of the text in the buffer at which you
737 are looking through the window. Imagine that the text is written on a
738 long roll of paper and that the scrolling commands move the paper up
739 and down. Thus, if you are looking at text in the middle of a buffer
740 and repeatedly call `scroll-down', you will eventually see the
741 beginning of the buffer.
743 Some people have urged that the opposite convention be used: they
744 imagine that the window moves over text that remains in place. Then
745 "down" commands would take you to the end of the buffer. This view is
746 more consistent with the actual relationship between windows and the
747 text in the buffer, but it is less like what the user sees. The
748 position of a window on the terminal does not move, and short scrolling
749 commands clearly move the text up or down on the screen. We have chosen
750 names that fit the user's point of view.
752 The scrolling functions (aside from `scroll-other-window') have
753 unpredictable results if the current buffer is different from the buffer
754 that is displayed in the selected window. *Note Current Buffer::.
756 - Command: scroll-up &optional count
757 This function scrolls the text in the selected window upward COUNT
758 lines. If COUNT is negative, scrolling is actually downward.
760 If COUNT is `nil' (or omitted), then the length of scroll is
761 `next-screen-context-lines' lines less than the usable height of
762 the window (not counting its modeline).
764 `scroll-up' returns `nil'.
766 - Command: scroll-down &optional count
767 This function scrolls the text in the selected window downward
768 COUNT lines. If COUNT is negative, scrolling is actually upward.
770 If COUNT is omitted or `nil', then the length of the scroll is
771 `next-screen-context-lines' lines less than the usable height of
772 the window (not counting its mode line).
774 `scroll-down' returns `nil'.
776 - Command: scroll-other-window &optional count
777 This function scrolls the text in another window upward COUNT
778 lines. Negative values of COUNT, or `nil', are handled as in
781 You can specify a buffer to scroll with the variable
782 `other-window-scroll-buffer'. When the selected window is the
783 minibuffer, the next window is normally the one at the top left
784 corner. You can specify a different window to scroll with the
785 variable `minibuffer-scroll-window'. This variable has no effect
786 when any other window is selected. *Note Minibuffer Misc::.
788 When the minibuffer is active, it is the next window if the
789 selected window is the one at the bottom right corner. In this
790 case, `scroll-other-window' attempts to scroll the minibuffer. If
791 the minibuffer contains just one line, it has nowhere to scroll
792 to, so the line reappears after the echo area momentarily displays
793 the message "Beginning of buffer".
795 - Variable: other-window-scroll-buffer
796 If this variable is non-`nil', it tells `scroll-other-window'
797 which buffer to scroll.
799 - User Option: scroll-step
800 This variable controls how scrolling is done automatically when
801 point moves off the screen. If the value is zero, then redisplay
802 scrolls the text to center point vertically in the window. If the
803 value is a positive integer N, then redisplay brings point back on
804 screen by scrolling N lines in either direction, if possible;
805 otherwise, it centers point. The default value is zero.
807 - User Option: scroll-conservatively
808 This variable controls how many lines Emacs tries to scroll before
809 recentering. If you set it to a small number, then when you move
810 point a short distance off the screen, XEmacs will scroll the
811 screen just far enough to bring point back on screen, provided
812 that does not exceed `scroll-conservatively' lines. This variable
813 overrides the redisplay preemption.
815 - User Option: next-screen-context-lines
816 The value of this variable is the number of lines of continuity to
817 retain when scrolling by full screens. For example, `scroll-up'
818 with an argument of `nil' scrolls so that this many lines at the
819 bottom of the window appear instead at the top. The default value
822 - Command: recenter &optional count
823 This function scrolls the selected window to put the text where
824 point is located at a specified vertical position within the
827 If COUNT is a nonnegative number, it puts the line containing
828 point COUNT lines down from the top of the window. If COUNT is a
829 negative number, then it counts upward from the bottom of the
830 window, so that -1 stands for the last usable line in the window.
831 If COUNT is a non-`nil' list, then it stands for the line in the
832 middle of the window.
834 If COUNT is `nil', `recenter' puts the line containing point in
835 the middle of the window, then clears and redisplays the entire
838 When `recenter' is called interactively, COUNT is the raw prefix
839 argument. Thus, typing `C-u' as the prefix sets the COUNT to a
840 non-`nil' list, while typing `C-u 4' sets COUNT to 4, which
841 positions the current line four lines from the top.
843 With an argument of zero, `recenter' positions the current line at
844 the top of the window. This action is so handy that some people
845 make a separate key binding to do this. For example,
847 (defun line-to-top-of-window ()
848 "Scroll current line to top of window.
849 Replaces three keystroke sequence C-u 0 C-l."
853 (global-set-key [kp-multiply] 'line-to-top-of-window)
856 File: lispref.info, Node: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows
861 Because we read English first from top to bottom and second from left
862 to right, horizontal scrolling is not like vertical scrolling. Vertical
863 scrolling involves selection of a contiguous portion of text to display.
864 Horizontal scrolling causes part of each line to go off screen. The
865 amount of horizontal scrolling is therefore specified as a number of
866 columns rather than as a position in the buffer. It has nothing to do
867 with the display-start position returned by `window-start'.
869 Usually, no horizontal scrolling is in effect; then the leftmost
870 column is at the left edge of the window. In this state, scrolling to
871 the right is meaningless, since there is no data to the left of the
872 screen to be revealed by it; so this is not allowed. Scrolling to the
873 left is allowed; it scrolls the first columns of text off the edge of
874 the window and can reveal additional columns on the right that were
875 truncated before. Once a window has a nonzero amount of leftward
876 horizontal scrolling, you can scroll it back to the right, but only so
877 far as to reduce the net horizontal scroll to zero. There is no limit
878 to how far left you can scroll, but eventually all the text will
879 disappear off the left edge.
881 - Command: scroll-left count
882 This function scrolls the selected window COUNT columns to the
883 left (or to the right if COUNT is negative). The return value is
884 the total amount of leftward horizontal scrolling in effect after
885 the change--just like the value returned by `window-hscroll'
888 - Command: scroll-right count
889 This function scrolls the selected window COUNT columns to the
890 right (or to the left if COUNT is negative). The return value is
891 the total amount of leftward horizontal scrolling in effect after
892 the change--just like the value returned by `window-hscroll'
895 Once you scroll a window as far right as it can go, back to its
896 normal position where the total leftward scrolling is zero,
897 attempts to scroll any farther right have no effect.
899 - Function: window-hscroll &optional window
900 This function returns the total leftward horizontal scrolling of
901 WINDOW--the number of columns by which the text in WINDOW is
902 scrolled left past the left margin.
904 The value is never negative. It is zero when no horizontal
905 scrolling has been done in WINDOW (which is usually the case).
907 If WINDOW is `nil', the selected window is used.
916 - Function: set-window-hscroll window columns
917 This function sets the number of columns from the left margin that
918 WINDOW is scrolled to the value of COLUMNS. The argument COLUMNS
919 should be zero or positive; if not, it is taken as zero.
921 The value returned is COLUMNS.
923 (set-window-hscroll (selected-window) 10)
926 Here is how you can determine whether a given position POSITION is
927 off the screen due to horizontal scrolling:
929 (defun hscroll-on-screen (window position)
933 (>= (- (current-column) (window-hscroll window)) 0)
934 (< (- (current-column) (window-hscroll window))
935 (window-width window)))))
938 File: lispref.info, Node: Size of Window, Next: Position of Window, Prev: Horizontal Scrolling, Up: Windows
943 An Emacs window is rectangular, and its size information consists of
944 the height (in lines or pixels) and the width (in character positions
945 or pixels). The modeline is included in the height. The pixel width
946 and height values include scrollbars and margins, while the
947 line/character-position values do not.
949 Note that the height in lines, and the width in characters, are
950 determined by dividing the corresponding pixel value by the height or
951 width of the default font in that window (if this is a variable-width
952 font, the average width is used). The resulting values may or may not
953 represent the actual number of lines in the window, or the actual number
954 of character positions in any particular line, esp. if there are pixmaps
955 or various different fonts in the window.
957 The following functions return size information about a window:
959 - Function: window-height &optional window
960 This function returns the number of lines in WINDOW, including its
961 modeline but not including the horizontal scrollbar, if any (this
962 is different from `window-pixel-height'). If WINDOW is `nil', the
963 function uses the selected window.
967 (split-window-vertically)
968 => #<window on "windows.texi" 0x679b>
972 - Function: window-width &optional window
973 This function returns the number of columns in WINDOW, not
974 including any left margin, right margin, or vertical scrollbar
975 (this is different from `window-pixel-width'). If WINDOW is
976 `nil', the function uses the selected window.
982 (split-window-horizontally)
983 => #<window on "windows.texi" 0x7538>
987 Note that after splitting the window into two side-by-side windows,
988 the width of each window is less the half the width of the original
989 window because a vertical scrollbar appeared between the windows,
990 occupying two columns worth of space. Also, the height shrunk by one
991 because horizontal scrollbars appeared that weren't there before.
992 (Horizontal scrollbars appear only when lines are truncated, not when
993 they wrap. This is usually the case for horizontally split windows but
994 not for full-frame windows. You can change this using the variables
995 `truncate-lines' and `truncate-partial-width-windows'.)
997 - Function: window-pixel-height &optional window
998 This function returns the height of WINDOW in pixels, including
999 its modeline and horizontal scrollbar, if any. If WINDOW is
1000 `nil', the function uses the selected window.
1002 (window-pixel-height)
1004 (split-window-vertically)
1005 => #<window on "windows.texi" 0x68a6>
1006 (window-pixel-height)
1009 - Function: window-pixel-width &optional window
1010 This function returns the width of WINDOW in pixels, including any
1011 left margin, right margin, or vertical scrollbar that may be
1012 displayed alongside it. If WINDOW is `nil', the function uses the
1015 (window-pixel-width)
1017 (window-pixel-height)
1019 (split-window-horizontally)
1020 => #<window on "windows.texi" 0x7538>
1021 (window-pixel-width)
1023 (window-pixel-height)
1026 - Function: window-text-area-pixel-height &optional window
1027 This function returns the height in pixels of the text displaying
1028 portion of WINDOW, which defaults to the selected window. Unlike
1029 `window-pixel-height', the space occupied by the modeline and
1030 horizontal scrollbar, if any, is not counted.
1032 - Function: window-text-area-pixel-width &optional window
1033 This function returns the width in pixels of the text displaying
1034 portion of WINDOW, which defaults to the selected window. Unlike
1035 `window-pixel-width', the space occupied by the vertical scrollbar
1036 and divider, if any, is not counted.
1038 - Function: window-displayed-text-pixel-height &optional window
1040 This function returns the height in pixels of the text displayed in
1041 WINDOW, which defaults to the selected window. Unlike
1042 `window-text-area-pixel-height', any blank space below the end of
1043 the buffer is not included. If optional argument NOCLIPPED is
1044 non-`nil', any space occupied by clipped lines will not be
1048 File: lispref.info, Node: Position of Window, Next: Resizing Windows, Prev: Size of Window, Up: Windows
1050 The Position of a Window
1051 ========================
1053 XEmacs provides functions to determine the absolute location of
1054 windows within a frame, and the relative location of a window in
1055 comparison to other windows in the same frame.
1057 - Function: window-pixel-edges &optional window
1058 This function returns a list of the pixel edge coordinates of
1059 WINDOW. If WINDOW is `nil', the selected window is used.
1061 The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements
1062 relative to 0, 0 at the top left corner of the frame. The element
1063 RIGHT of the value is one more than the rightmost pixel used by
1064 WINDOW (including any left margin, right margin, or vertical
1065 scrollbar displayed alongside it), and BOTTOM is one more than the
1066 bottommost pixel used by WINDOW (including any modeline or
1067 horizontal scrollbar displayed above or below it). The frame area
1068 does not include any frame menubars or toolbars that may be
1069 displayed; thus, for example, if there is only one window on the
1070 frame, the values for LEFT and TOP will always be 0.
1072 If WINDOW is at the upper left corner of its frame, RIGHT and
1073 BOTTOM are the same as the values returned by
1074 `(window-pixel-width)' and `(window-pixel-height)' respectively,
1075 and TOP and BOTTOM are zero.
1077 There is no longer a function `window-edges' because it does not
1078 make sense in a world with variable-width and variable-height lines, as
1079 are allowed in XEmacs.
1081 - Function: window-highest-p window
1082 This function returns non-`nil' if WINDOW is along the top of its
1085 - Function: window-lowest-p window
1086 This function returns non-`nil' if WINDOW is along the bottom of
1089 - Function: window-text-area-pixel-edges &optional window
1090 This function allows one to determine the location of the
1091 text-displaying portion of WINDOW, which defaults to the selected
1092 window, with respect to the top left corner of the window. It
1093 returns a list of integer pixel positions `(left top right
1094 bottom)', all relative to `(0,0)' at the top left corner of the
projects / chise / xemacs-chise.git- / blob