lisp/window.el

   1 ;;; window.el --- GNU Emacs window commands aside from those written in C
   2
   3 ;; Copyright (C) 1985, 1989, 1992, 1993, 1994, 2000, 2001, 2002,
   4 ;;   2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
   5
   6 ;; Maintainer: FSF
   7 ;; Keywords: internal
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software: you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation, either version 3 of the License, or
  14 ;; (at your option) any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  23
  24 ;;; Commentary:
  25
  26 ;; Window tree functions.
  27
  28 ;;; Code:
  29
  30 (eval-when-compile (require 'cl))
  31
  32 (defvar window-size-fixed nil
  33  "*Non-nil in a buffer means windows displaying the buffer are fixed-size.
  34 If the value is `height', then only the window's height is fixed.
  35 If the value is `width', then only the window's width is fixed.
  36 Any other non-nil value fixes both the width and the height.
  37 Emacs won't change the size of any window displaying that buffer,
  38 unless you explicitly change the size, or Emacs has no other choice.")
  39 (make-variable-buffer-local 'window-size-fixed)
  40
  41 (defmacro save-selected-window (&rest body)
  42   "Execute BODY, then select the previously selected window.
  43 The value returned is the value of the last form in BODY.
  44
  45 This macro saves and restores the selected window, as well as the
  46 selected window in each frame.  If the previously selected window
  47 is no longer live, then whatever window is selected at the end of
  48 BODY remains selected.  If the previously selected window of some
  49 frame is no longer live at the end of BODY, that frame's selected
  50 window is left alone.
  51
  52 This macro saves and restores the current buffer, since otherwise
  53 its normal operation could make a different buffer current.  The
  54 order of recently selected windows and the buffer list ordering
  55 are not altered by this macro (unless they are altered in BODY)."
  56   `(let ((save-selected-window-window (selected-window))
  57          ;; It is necessary to save all of these, because calling
  58          ;; select-window changes frame-selected-window for whatever
  59          ;; frame that window is in.
  60          (save-selected-window-alist
  61           (mapcar (lambda (frame) (cons frame (frame-selected-window frame)))
  62                   (frame-list))))
  63      (save-current-buffer
  64        (unwind-protect
  65            (progn ,@body)
  66          (dolist (elt save-selected-window-alist)
  67            (and (frame-live-p (car elt))
  68                 (window-live-p (cdr elt))
  69                 (set-frame-selected-window (car elt) (cdr elt) 'norecord)))
  70          (when (window-live-p save-selected-window-window)
  71            (select-window save-selected-window-window 'norecord))))))
  72
  73 (defun window-body-height (&optional window)
  74   "Return number of lines in WINDOW available for actual buffer text.
  75 WINDOW defaults to the selected window.
  76
  77 The return value does not include the mode line or the header
  78 line, if any.  If a line at the bottom of the window is only
  79 partially visible, that line is included in the return value.  If
  80 you do not want to include a partially visible bottom line in the
  81 return value, use `window-text-height' instead."
  82   (or window (setq window (selected-window)))
  83   (if (window-minibuffer-p window)
  84       (window-height window)
  85     (with-current-buffer (window-buffer window)
  86       (max 1 (- (window-height window)
  87                 (if mode-line-format 1 0)
  88                 (if header-line-format 1 0))))))
  89
  90 (defun one-window-p (&optional nomini all-frames)
  91   "Return non-nil if the selected window is the only window.
  92 Optional arg NOMINI non-nil means don't count the minibuffer
  93 even if it is active.  Otherwise, the minibuffer is counted
  94 when it is active.
  95
  96 The optional arg ALL-FRAMES t means count windows on all frames.
  97 If it is `visible', count windows on all visible frames.
  98 ALL-FRAMES nil or omitted means count only the selected frame,
  99 plus the minibuffer it uses (which may be on another frame).
 100 ALL-FRAMES 0 means count all windows in all visible or iconified frames.
 101 If ALL-FRAMES is anything else, count only the selected frame."
 102   (let ((base-window (selected-window)))
 103     (if (and nomini (eq base-window (minibuffer-window)))
 104         (setq base-window (next-window base-window)))
 105     (eq base-window
 106         (next-window base-window (if nomini 'arg) all-frames))))
 107
 108 (defun window-current-scroll-bars (&optional window)
 109   "Return the current scroll bar settings for WINDOW.
 110 WINDOW defaults to the selected window.
 111
 112 The return value is a cons cell (VERTICAL . HORIZONTAL) where
 113 VERTICAL specifies the current location of the vertical scroll
 114 bars (`left', `right', or nil), and HORIZONTAL specifies the
 115 current location of the horizontal scroll bars (`top', `bottom',
 116 or nil).
 117
 118 Unlike `window-scroll-bars', this function reports the scroll bar
 119 type actually used, once frame defaults and `scroll-bar-mode' are
 120 taken into account."
 121   (let ((vert (nth 2 (window-scroll-bars window)))
 122         (hor nil))
 123     (when (or (eq vert t) (eq hor t))
 124       (let ((fcsb (frame-current-scroll-bars
 125                    (window-frame (or window (selected-window))))))
 126         (if (eq vert t)
 127             (setq vert (car fcsb)))
 128         (if (eq hor t)
 129             (setq hor (cdr fcsb)))))
 130     (cons vert hor)))
 131
 132 (defun walk-windows (proc &optional minibuf all-frames)
 133   "Cycle through all windows, calling PROC for each one.
 134 PROC must specify a function with a window as its sole argument.
 135 The optional arguments MINIBUF and ALL-FRAMES specify the set of
 136 windows to include in the walk, see also `next-window'.
 137
 138 MINIBUF t means include the minibuffer window even if the
 139 minibuffer is not active.  MINIBUF nil or omitted means include
 140 the minibuffer window only if the minibuffer is active.  Any
 141 other value means do not include the minibuffer window even if
 142 the minibuffer is active.
 143
 144 Several frames may share a single minibuffer; if the minibuffer
 145 is active, all windows on all frames that share that minibuffer
 146 are included too.  Therefore, if you are using a separate
 147 minibuffer frame and the minibuffer is active and MINIBUF says it
 148 counts, `walk-windows' includes the windows in the frame from
 149 which you entered the minibuffer, as well as the minibuffer
 150 window.
 151
 152 ALL-FRAMES nil or omitted means cycle through all windows on
 153  WINDOW's frame, plus the minibuffer window if specified by the
 154  MINIBUF argument, see above.  If the minibuffer counts, cycle
 155  through all windows on all frames that share that minibuffer
 156  too.
 157 ALL-FRAMES t means cycle through all windows on all existing
 158  frames.
 159 ALL-FRAMES `visible' means cycle through all windows on all
 160  visible frames.
 161 ALL-FRAMES 0 means cycle through all windows on all visible and
 162  iconified frames.
 163 ALL-FRAMES a frame means cycle through all windows on that frame
 164  only.
 165 Anything else means cycle through all windows on WINDOW's frame
 166  and no others.
 167
 168 This function changes neither the order of recently selected
 169 windows nor the buffer list."
 170   ;; If we start from the minibuffer window, don't fail to come
 171   ;; back to it.
 172   (when (window-minibuffer-p (selected-window))
 173     (setq minibuf t))
 174   ;; Make sure to not mess up the order of recently selected
 175   ;; windows.  Use `save-selected-window' and `select-window'
 176   ;; with second argument non-nil for this purpose.
 177   (save-selected-window
 178     (when (framep all-frames)
 179       (select-window (frame-first-window all-frames) 'norecord))
 180     (let* (walk-windows-already-seen
 181            (walk-windows-current (selected-window)))
 182       (while (progn
 183                (setq walk-windows-current
 184                      (next-window walk-windows-current minibuf all-frames))
 185                (not (memq walk-windows-current walk-windows-already-seen)))
 186         (setq walk-windows-already-seen
 187               (cons walk-windows-current walk-windows-already-seen))
 188         (funcall proc walk-windows-current)))))
 189
 190 (defun get-window-with-predicate (predicate &optional minibuf
 191                                             all-frames default)
 192   "Return a window satisfying PREDICATE.
 193 More precisely, cycle through all windows using `walk-windows',
 194 calling the function PREDICATE on each one of them with the
 195 window as its sole argument.  Return the first window for which
 196 PREDICATE returns non-nil.  If no window satisfies PREDICATE,
 197 return DEFAULT.
 198
 199 The optional arguments MINIBUF and ALL-FRAMES specify the set of
 200 windows to include.  See `walk-windows' for the meaning of these
 201 arguments."
 202   (catch 'found
 203     (walk-windows #'(lambda (window)
 204                       (when (funcall predicate window)
 205                         (throw 'found window)))
 206                   minibuf all-frames)
 207     default))
 208
 209 (defalias 'some-window 'get-window-with-predicate)
 210
 211 ;; This should probably be written in C (i.e., without using `walk-windows').
 212 (defun get-buffer-window-list (&optional buffer-or-name minibuf all-frames)
 213   "Return list of all windows displaying BUFFER-OR-NAME, or nil if none.
 214 BUFFER-OR-NAME may be a buffer or the name of an existing buffer
 215 and defaults to the current buffer.
 216
 217 The optional arguments MINIBUF and ALL-FRAMES specify the set of
 218 windows to consider.  See `walk-windows' for the precise meaning
 219 of these arguments."
 220   (let ((buffer (cond
 221                  ((not buffer-or-name) (current-buffer))
 222                  ((bufferp buffer-or-name) buffer-or-name)
 223                  (t (get-buffer buffer-or-name))))
 224         windows)
 225     (walk-windows (function (lambda (window)
 226                               (if (eq (window-buffer window) buffer)
 227                                   (setq windows (cons window windows)))))
 228                   minibuf all-frames)
 229     windows))
 230
 231 (defun minibuffer-window-active-p (window)
 232   "Return t if WINDOW is the currently active minibuffer window."
 233   (eq window (active-minibuffer-window)))
 234 \f
 235 (defun count-windows (&optional minibuf)
 236    "Return the number of visible windows.
 237 The optional argument MINIBUF specifies whether the minibuffer
 238 window shall be counted.  See `walk-windows' for the precise
 239 meaning of this argument."
 240    (let ((count 0))
 241      (walk-windows (lambda (w) (setq count (+ count 1)))
 242                    minibuf)
 243      count))
 244
 245 (defun window-safely-shrinkable-p (&optional window)
 246   "Return t if WINDOW can be shrunk without shrinking other windows.
 247 WINDOW defaults to the selected window."
 248   (with-selected-window (or window (selected-window))
 249     (let ((edges (window-edges)))
 250       (or (= (nth 2 edges) (nth 2 (window-edges (previous-window))))
 251           (= (nth 0 edges) (nth 0 (window-edges (next-window))))))))
 252
 253 \f
 254 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 255 ;;; `balance-windows' subroutines using `window-tree'
 256
 257 ;;; Translate from internal window tree format
 258
 259 (defun bw-get-tree (&optional window-or-frame)
 260   "Get a window split tree in our format.
 261
 262 WINDOW-OR-FRAME must be nil, a frame, or a window.  If it is nil,
 263 then the whole window split tree for `selected-frame' is returned.
 264 If it is a frame, then this is used instead.  If it is a window,
 265 then the smallest tree containing that window is returned."
 266   (when window-or-frame
 267     (unless (or (framep window-or-frame)
 268                 (windowp window-or-frame))
 269       (error "Not a frame or window: %s" window-or-frame)))
 270   (let ((subtree (bw-find-tree-sub window-or-frame)))
 271     (when subtree
 272       (if (integerp subtree)
 273           nil
 274         (bw-get-tree-1 subtree)))))
 275
 276 (defun bw-get-tree-1 (split)
 277   (if (windowp split)
 278       split
 279     (let ((dir (car split))
 280           (edges (car (cdr split)))
 281           (childs (cdr (cdr split))))
 282       (list
 283        (cons 'dir (if dir 'ver 'hor))
 284        (cons 'b (nth 3 edges))
 285        (cons 'r (nth 2 edges))
 286        (cons 't (nth 1 edges))
 287        (cons 'l (nth 0 edges))
 288        (cons 'childs (mapcar #'bw-get-tree-1 childs))))))
 289
 290 (defun bw-find-tree-sub (window-or-frame &optional get-parent)
 291   (let* ((window (when (windowp window-or-frame) window-or-frame))
 292          (frame (when (windowp window) (window-frame window)))
 293          (wt (car (window-tree frame))))
 294     (when (< 1 (length (window-list frame 0)))
 295       (if window
 296           (bw-find-tree-sub-1 wt window get-parent)
 297         wt))))
 298
 299 (defun bw-find-tree-sub-1 (tree win &optional get-parent)
 300   (unless (windowp win) (error "Not a window: %s" win))
 301   (if (memq win tree)
 302       (if get-parent
 303           get-parent
 304         tree)
 305     (let ((childs (cdr (cdr tree)))
 306           child
 307           subtree)
 308       (while (and childs (not subtree))
 309         (setq child (car childs))
 310         (setq childs (cdr childs))
 311         (when (and child (listp child))
 312           (setq subtree (bw-find-tree-sub-1 child win get-parent))))
 313       (if (integerp subtree)
 314           (progn
 315             (if (= 1 subtree)
 316                 tree
 317               (1- subtree)))
 318         subtree
 319         ))))
 320
 321 ;;; Window or object edges
 322
 323 (defun bw-l (obj)
 324   "Left edge of OBJ."
 325   (if (windowp obj) (nth 0 (window-edges obj)) (cdr (assq 'l obj))))
 326 (defun bw-t (obj)
 327   "Top edge of OBJ."
 328   (if (windowp obj) (nth 1 (window-edges obj)) (cdr (assq 't obj))))
 329 (defun bw-r (obj)
 330   "Right edge of OBJ."
 331   (if (windowp obj) (nth 2 (window-edges obj)) (cdr (assq 'r obj))))
 332 (defun bw-b (obj)
 333   "Bottom edge of OBJ."
 334   (if (windowp obj) (nth 3 (window-edges obj)) (cdr (assq 'b obj))))
 335
 336 ;;; Split directions
 337
 338 (defun bw-dir (obj)
 339   "Return window split tree direction if OBJ.
 340 If OBJ is a window return 'both.  If it is a window split tree
 341 then return its direction."
 342   (if (symbolp obj)
 343       obj
 344     (if (windowp obj)
 345         'both
 346       (let ((dir (cdr (assq 'dir obj))))
 347         (unless (memq dir '(hor ver both))
 348           (error "Can't find dir in %s" obj))
 349         dir))))
 350
 351 (defun bw-eqdir (obj1 obj2)
 352   "Return t if window split tree directions are equal.
 353 OBJ1 and OBJ2 should be either windows or window split trees in
 354 our format.  The directions returned by `bw-dir' are compared and
 355 t is returned if they are `eq' or one of them is 'both."
 356   (let ((dir1 (bw-dir obj1))
 357         (dir2 (bw-dir obj2)))
 358     (or (eq dir1 dir2)
 359         (eq dir1 'both)
 360         (eq dir2 'both))))
 361
 362 ;;; Building split tree
 363
 364 (defun bw-refresh-edges (obj)
 365   "Refresh the edge information of OBJ and return OBJ."
 366   (unless (windowp obj)
 367     (let ((childs (cdr (assq 'childs obj)))
 368           (ol 1000)
 369           (ot 1000)
 370           (or -1)
 371           (ob -1))
 372       (dolist (o childs)
 373         (when (> ol (bw-l o)) (setq ol (bw-l o)))
 374         (when (> ot (bw-t o)) (setq ot (bw-t o)))
 375         (when (< or (bw-r o)) (setq or (bw-r o)))
 376         (when (< ob (bw-b o)) (setq ob (bw-b o))))
 377       (setq obj (delq 'l obj))
 378       (setq obj (delq 't obj))
 379       (setq obj (delq 'r obj))
 380       (setq obj (delq 'b obj))
 381       (add-to-list 'obj (cons 'l ol))
 382       (add-to-list 'obj (cons 't ot))
 383       (add-to-list 'obj (cons 'r or))
 384       (add-to-list 'obj (cons 'b ob))
 385       ))
 386   obj)
 387
 388 ;;; Balance windows
 389
 390 (defun balance-windows (&optional window-or-frame)
 391   "Make windows the same heights or widths in window split subtrees.
 392
 393 When called non-interactively WINDOW-OR-FRAME may be either a
 394 window or a frame.  It then balances the windows on the implied
 395 frame.  If the parameter is a window only the corresponding window
 396 subtree is balanced."
 397   (interactive)
 398   (let (
 399         (wt (bw-get-tree window-or-frame))
 400         (w)
 401         (h)
 402         (tried-sizes)
 403         (last-sizes)
 404         (windows (window-list nil 0)))
 405     (when wt
 406       (while (not (member last-sizes tried-sizes))
 407         (when last-sizes (setq tried-sizes (cons last-sizes tried-sizes)))
 408         (setq last-sizes (mapcar (lambda (w)
 409                                    (window-edges w))
 410                                  windows))
 411         (when (eq 'hor (bw-dir wt))
 412           (setq w (- (bw-r wt) (bw-l wt))))
 413         (when (eq 'ver (bw-dir wt))
 414           (setq h (- (bw-b wt) (bw-t wt))))
 415         (bw-balance-sub wt w h)))))
 416
 417 (defun bw-adjust-window (window delta horizontal)
 418   "Wrapper around `adjust-window-trailing-edge' with error checking.
 419 Arguments WINDOW, DELTA and HORIZONTAL are passed on to that function."
 420   ;; `adjust-window-trailing-edge' may fail if delta is too large.
 421   (while (>= (abs delta) 1)
 422     (condition-case err
 423         (progn
 424           (adjust-window-trailing-edge window delta horizontal)
 425           (setq delta 0))
 426       (error
 427        ;;(message "adjust: %s" (error-message-string err))
 428        (setq delta (/ delta 2))))))
 429
 430 (defun bw-balance-sub (wt w h)
 431   (setq wt (bw-refresh-edges wt))
 432   (unless w (setq w (- (bw-r wt) (bw-l wt))))
 433   (unless h (setq h (- (bw-b wt) (bw-t wt))))
 434   (if (windowp wt)
 435       (progn
 436         (when w
 437           (let ((dw (- w (- (bw-r wt) (bw-l wt)))))
 438             (when (/= 0 dw)
 439               (bw-adjust-window wt dw t))))
 440         (when h
 441           (let ((dh (- h (- (bw-b wt) (bw-t wt)))))
 442             (when (/= 0 dh)
 443               (bw-adjust-window wt dh nil)))))
 444     (let* ((childs (cdr (assq 'childs wt)))
 445            (cw (when w (/ w (if (bw-eqdir 'hor wt) (length childs) 1))))
 446            (ch (when h (/ h (if (bw-eqdir 'ver wt) (length childs) 1)))))
 447       (dolist (c childs)
 448         (bw-balance-sub c cw ch)))))
 449
 450 (defun window-fixed-size-p (&optional window direction)
 451   "Return t if WINDOW cannot be resized in DIRECTION.
 452 WINDOW defaults to the selected window.  DIRECTION can be
 453 nil (i.e. any), `height' or `width'."
 454   (with-current-buffer (window-buffer window)
 455     (when (and (boundp 'window-size-fixed) window-size-fixed)
 456       (not (and direction
 457                 (member (cons direction window-size-fixed)
 458                         '((height . width) (width . height))))))))
 459
 460 ;;; A different solution to balance-windows.
 461
 462 (defvar window-area-factor 1
 463   "Factor by which the window area should be over-estimated.
 464 This is used by `balance-windows-area'.
 465 Changing this globally has no effect.")
 466 (make-variable-buffer-local 'window-area-factor)
 467
 468 (defun balance-windows-area ()
 469   "Make all visible windows the same area (approximately).
 470 See also `window-area-factor' to change the relative size of
 471 specific buffers."
 472   (interactive)
 473   (let* ((unchanged 0) (carry 0) (round 0)
 474          ;; Remove fixed-size windows.
 475          (wins (delq nil (mapcar (lambda (win)
 476                                    (if (not (window-fixed-size-p win)) win))
 477                                  (window-list nil 'nomini))))
 478          (changelog nil)
 479          next)
 480     ;; Resizing a window changes the size of surrounding windows in complex
 481     ;; ways, so it's difficult to balance them all.  The introduction of
 482     ;; `adjust-window-trailing-edge' made it a bit easier, but it is still
 483     ;; very difficult to do.  `balance-window' above takes an off-line
 484     ;; approach: get the whole window tree, then balance it, then try to
 485     ;; adjust the windows so they fit the result.
 486     ;; Here, instead, we take a "local optimization" approach, where we just
 487     ;; go through all the windows several times until nothing needs to be
 488     ;; changed.  The main problem with this approach is that it's difficult
 489     ;; to make sure it terminates, so we use some heuristic to try and break
 490     ;; off infinite loops.
 491     ;; After a round without any change, we allow a second, to give a chance
 492     ;; to the carry to propagate a minor imbalance from the end back to
 493     ;; the beginning.
 494     (while (< unchanged 2)
 495       ;; (message "New round")
 496       (setq unchanged (1+ unchanged) round (1+ round))
 497       (dolist (win wins)
 498         (setq next win)
 499         (while (progn (setq next (next-window next))
 500                       (window-fixed-size-p next)))
 501         ;; (assert (eq next (or (cadr (member win wins)) (car wins))))
 502         (let* ((horiz
 503                 (< (car (window-edges win)) (car (window-edges next))))
 504                (areadiff (/ (- (* (window-height next) (window-width next)
 505                                   (buffer-local-value 'window-area-factor
 506                                                       (window-buffer next)))
 507                                (* (window-height win) (window-width win)
 508                                   (buffer-local-value 'window-area-factor
 509                                                       (window-buffer win))))
 510                             (max (buffer-local-value 'window-area-factor
 511                                                      (window-buffer win))
 512                                  (buffer-local-value 'window-area-factor
 513                                                      (window-buffer next)))))
 514                (edgesize (if horiz
 515                              (+ (window-height win) (window-height next))
 516                            (+ (window-width win) (window-width next))))
 517                (diff (/ areadiff edgesize)))
 518           (when (zerop diff)
 519             ;; Maybe diff is actually closer to 1 than to 0.
 520             (setq diff (/ (* 3 areadiff) (* 2 edgesize))))
 521           (when (and (zerop diff) (not (zerop areadiff)))
 522             (setq diff (/ (+ areadiff carry) edgesize))
 523             ;; Change things smoothly.
 524             (if (or (> diff 1) (< diff -1)) (setq diff (/ diff 2))))
 525           (if (zerop diff)
 526               ;; Make sure negligible differences don't accumulate to
 527               ;; become significant.
 528               (setq carry (+ carry areadiff))
 529             (bw-adjust-window win diff horiz)
 530             ;; (sit-for 0.5)
 531             (let ((change (cons win (window-edges win))))
 532               ;; If the same change has been seen already for this window,
 533               ;; we're most likely in an endless loop, so don't count it as
 534               ;; a change.
 535               (unless (member change changelog)
 536                 (push change changelog)
 537                 (setq unchanged 0 carry 0)))))))
 538     ;; We've now basically balanced all the windows.
 539     ;; But there may be some minor off-by-one imbalance left over,
 540     ;; so let's do some fine tuning.
 541     ;; (bw-finetune wins)
 542     ;; (message "Done in %d rounds" round)
 543     ))
 544
 545 \f
 546 (defcustom display-buffer-function nil
 547   "If non-nil, function to call to handle `display-buffer'.
 548 It will receive two args, the buffer and a flag which if non-nil
 549 means that the currently selected window is not acceptable.  It
 550 should choose or create a window, display the specified buffer in
 551 it, and return the window.
 552
 553 Commands such as `switch-to-buffer-other-window' and
 554 `find-file-other-window' work using this function."
 555   :type '(choice
 556           (const nil)
 557           (function :tag "function"))
 558   :group 'windows)
 559
 560 (defun special-display-p (buffer-name)
 561   "Return non-nil if a buffer named BUFFER-NAME gets a special frame.
 562 If the value is t, `display-buffer' or `pop-to-buffer' would
 563 create a special frame for that buffer using the default frame
 564 parameters.
 565
 566 If the value is a list, it is a list of frame parameters that
 567 would be used to make a frame for that buffer.  The variables
 568 `special-display-buffer-names' and `special-display-regexps'
 569 control this."
 570   (let (tmp)
 571   (cond
 572    ((not (stringp buffer-name)))
 573    ;; Make sure to return t in the following two cases.
 574    ((member buffer-name special-display-buffer-names) t)
 575      ((setq tmp (assoc buffer-name special-display-buffer-names)) (cdr tmp))
 576    ((catch 'found
 577       (dolist (regexp special-display-regexps)
 578         (cond
 579          ((stringp regexp)
 580           (when (string-match-p regexp buffer-name)
 581             (throw 'found t)))
 582          ((and (consp regexp) (stringp (car regexp))
 583                (string-match-p (car regexp) buffer-name))
 584             (throw 'found (cdr regexp))))))))))
 585
 586 (defcustom special-display-buffer-names nil
 587   "List of buffer names that should have their own special frames.
 588 Displaying a buffer with `display-buffer' or `pop-to-buffer', if
 589 its name is in this list, makes a special frame for it using
 590 `special-display-function'.  See also `special-display-regexps'.
 591
 592 An element of the list can be a list instead of just a string.
 593 There are two ways to use a list as an element:
 594   (BUFFER FRAME-PARAMETERS...)  (BUFFER FUNCTION OTHER-ARGS...)
 595 In the first case, the FRAME-PARAMETERS are pairs of the form
 596 \(PARAMETER . VALUE); these parameter values are used to create
 597 the frame.  In the second case, FUNCTION is called with BUFFER as
 598 the first argument, followed by the OTHER-ARGS--it can display
 599 BUFFER in any way it likes.  All this is done by the function
 600 found in `special-display-function'.
 601
 602 If the specified frame parameters include (same-buffer . t), the
 603 buffer is displayed in the currently selected window.  Otherwise, if
 604 they include (same-frame . t), the buffer is displayed in a new window
 605 in the currently selected frame.
 606
 607 If this variable appears \"not to work\", because you add a name to it
 608 but that buffer still appears in the selected window, look at the
 609 values of `same-window-buffer-names' and `same-window-regexps'.
 610 Those variables take precedence over this one."
 611   :type '(repeat (choice :tag "Buffer"
 612                          :value ""
 613                          (string :format "%v")
 614                          (cons :tag "With attributes"
 615                                :format "%v"
 616                                :value ("" . nil)
 617                                (string :format "%v")
 618                                (repeat :tag "Attributes"
 619                                        (cons :format "%v"
 620                                              (symbol :tag "Parameter")
 621                                              (sexp :tag "Value"))))))
 622   :group 'frames)
 623
 624 (defcustom special-display-regexps nil
 625   "List of regexps saying which buffers should have their own special frames.
 626 When displaying a buffer with `display-buffer' or
 627 `pop-to-buffer', if any regexp in this list matches the buffer
 628 name, it makes a special frame for the buffer by calling
 629 `special-display-function'.
 630
 631 An element of the list can be a list instead of just a string.
 632 There are two ways to use a list as an element:
 633   (REGEXP FRAME-PARAMETERS...)  (REGEXP FUNCTION OTHER-ARGS...)
 634 In the first case, the FRAME-PARAMETERS are pairs of the form
 635 \(PARAMETER . VALUE); these parameter values are used to create
 636 the frame.  In the second case, FUNCTION is called with BUFFER as
 637 the first argument, followed by the OTHER-ARGS--it can display
 638 the buffer in any way it likes.  All this is done by the function
 639 found in `special-display-function'.
 640
 641 If the specified frame parameters include (same-buffer . t), the
 642 buffer is displayed in the currently selected window.  Otherwise,
 643 if they include (same-frame . t), the buffer is displayed in a
 644 new window in the currently selected frame.
 645
 646 If this variable appears \"not to work\", because you add a
 647 regexp to it but the matching buffers still appear in the
 648 selected window, look at the values of `same-window-buffer-names'
 649 and `same-window-regexps'.  Those variables take precedence over
 650 this one."
 651   :type '(repeat (choice :tag "Buffer"
 652                          :value ""
 653                          (regexp :format "%v")
 654                          (cons :tag "With attributes"
 655                                :format "%v"
 656                                :value ("" . nil)
 657                                (regexp :format "%v")
 658                                (repeat :tag "Attributes"
 659                                        (cons :format "%v"
 660                                              (symbol :tag "Parameter")
 661                                              (sexp :tag "Value"))))))
 662   :group 'frames)
 663
 664 (defcustom special-display-function 'special-display-popup-frame
 665   "Function to call to make a new frame for a special buffer.
 666 It is called with two arguments, the buffer and optional buffer
 667 specific data, and should return a window displaying that buffer.
 668 The default value normally makes a separate frame for the buffer,
 669 using `special-display-frame-alist' to specify the frame
 670 parameters.
 671
 672 But if the buffer specific data includes (same-buffer . t) then
 673 the buffer is displayed in the current selected window.
 674 Otherwise if it includes (same-frame . t) then the buffer is
 675 displayed in a new window in the currently selected frame.
 676
 677 A buffer is special if it is listed in
 678 `special-display-buffer-names' or matches a regexp in
 679 `special-display-regexps'."
 680   :type 'function
 681   :group 'frames)
 682
 683 (defun same-window-p (buffer-name)
 684   "Return non-nil if a buffer named BUFFER-NAME would be shown in the \"same\" window.
 685 This function returns non-nil if `display-buffer' or
 686 `pop-to-buffer' would show a buffer named BUFFER-NAME in the
 687 selected rather than \(as usual\) some other window.  See
 688 `same-window-buffer-names' and `same-window-regexps'."
 689   (cond
 690    ((not (stringp buffer-name)))
 691    ;; The elements of `same-window-buffer-names' can be buffer
 692    ;; names or cons cells whose cars are buffer names.
 693    ((member buffer-name same-window-buffer-names))
 694    ((assoc buffer-name same-window-buffer-names))
 695    ((catch 'found
 696       (dolist (regexp same-window-regexps)
 697         ;; The elements of `same-window-regexps' can be regexps
 698         ;; or cons cells whose cars are regexps.
 699         (when (or (and (stringp regexp)
 700                        (string-match regexp buffer-name))
 701                   (and (consp regexp) (stringp (car regexp))
 702                        (string-match-p (car regexp) buffer-name)))
 703           (throw 'found t)))))))
 704
 705 (defcustom same-window-buffer-names nil
 706   "List of names of buffers that should appear in the \"same\" window.
 707 `display-buffer' and `pop-to-buffer' show a buffer whose name is
 708 on this list in the selected rather than some other window.
 709
 710 An element of this list can be a cons cell instead of just a
 711 string.  In that case the car must be a string specifying the
 712 buffer name.  This is for compatibility with
 713 `special-display-buffer-names'; the cdr of the cons cell is
 714 ignored.
 715
 716 See also `same-window-regexps'."
 717  :type '(repeat (string :format "%v"))
 718  :group 'windows)
 719
 720 (defcustom same-window-regexps nil
 721   "List of regexps saying which buffers should appear in the \"same\" window.
 722 `display-buffer' and `pop-to-buffer' show a buffer whose name
 723 matches a regexp on this list in the selected rather than some
 724 other window.
 725
 726 An element of this list can be a cons cell instead of just a
 727 string.  In that case the car must be a string, which specifies
 728 the buffer name.  This is for compatibility with
 729 `special-display-buffer-names'; the cdr of the cons cell is
 730 ignored.
 731
 732 See also `same-window-buffer-names'."
 733   :type '(repeat (regexp :format "%v"))
 734   :group 'windows)
 735
 736 (defcustom pop-up-frames nil
 737   "Whether `display-buffer' should make a separate frame.
 738 If nil, never make a seperate frame.
 739 If the value is `graphic-only', make a separate frame
 740 on graphic displays only.
 741 Any other non-nil value means always make a separate frame."
 742   :type '(choice
 743           (const :tag "Never" nil)
 744           (const :tag "On graphic displays only" graphic-only)
 745           (const :tag "Always" t))
 746   :group 'windows)
 747
 748 (defcustom display-buffer-reuse-frames nil
 749   "Non-nil means `display-buffer' should reuse frames.
 750 If the buffer in question is already displayed in a frame, raise
 751 that frame."
 752   :type 'boolean
 753   :version "21.1"
 754   :group 'windows)
 755
 756 (defcustom pop-up-windows t
 757   "Non-nil means `display-buffer' should make a new window."
 758   :type 'boolean
 759   :group 'windows)
 760
 761 (defcustom split-height-threshold 80
 762   "Minimum height of window to be split vertically.
 763 If the value is a number, `display-buffer' can split a window
 764 only if it has at least as many lines.  If the value is nil,
 765 `display-buffer' cannot split a window vertically.
 766
 767 If the window is the only window on its frame, `display-buffer'
 768 can split it regardless of this value."
 769   :type '(choice (const nil) (number :tag "lines"))
 770   :version "23.1"
 771   :group 'windows)
 772
 773 (defcustom split-width-threshold 160
 774   "Minimum width of window to be split horizontally.
 775 If the value is a number, `display-buffer' can split a window
 776 only if it has at least as many columns.  If the value is nil,
 777 `display-buffer' cannot split a window horizontally."
 778   :type '(choice (const nil) (number :tag "columns"))
 779   :version "23.1"
 780   :group 'windows)
 781
 782 (defcustom split-window-preferred-function nil
 783   "Function used by `display-buffer' to split windows.
 784 If non-nil, a function called with a window as single argument
 785 supposed to split that window and return the new window.  If the
 786 function returns nil the window is not split.
 787
 788 If nil, `display-buffer' will split the window respecting the
 789 values of `split-height-threshold' and `split-width-threshold'."
 790   :type '(choice (const nil) (function :tag "Function"))
 791   :version "23.1"
 792   :group 'windows)
 793
 794 (defun window--splittable-p (window &optional horizontal)
 795   "Return non-nil if WINDOW can be split evenly.
 796 Optional argument HORIZONTAL non-nil means check whether WINDOW
 797 can be split horizontally.
 798
 799 WINDOW can be split vertically when the following conditions
 800 hold:
 801
 802 - `window-size-fixed' is either nil or equals `width' for the
 803   buffer of WINDOW.
 804
 805 - `split-height-threshold' is a number and WINDOW is at least as
 806   high as `split-height-threshold'.
 807
 808 - When WINDOW is split evenly, the emanating windows are at least
 809   `window-min-height' lines tall and can accommodate at least one
 810   line plus - if WINDOW has one - a mode line.
 811
 812 WINDOW can be split horizontally when the following conditions
 813 hold:
 814
 815 - `window-size-fixed' is either nil or equals `height' for the
 816   buffer of WINDOW.
 817
 818 - `split-width-threshold' is a number and WINDOW is at least as
 819   wide as `split-width-threshold'.
 820
 821 - When WINDOW is split evenly, the emanating windows are at least
 822   `window-min-width' or two (whichever is larger) columns wide."
 823   (when (window-live-p window)
 824     (with-current-buffer (window-buffer window)
 825       (if horizontal
 826           ;; A window can be split horizontally when its width is not
 827           ;; fixed, it is at least `split-width-threshold' columns wide
 828           ;; and at least twice as wide as `window-min-width' and 2 (the
 829           ;; latter value is hardcoded).
 830           (and (memq window-size-fixed '(nil height))
 831                ;; Testing `window-full-width-p' here hardly makes any
 832                ;; sense nowadays.  This can be done more intuitively by
 833                ;; setting up `split-width-threshold' appropriately.
 834                (numberp split-width-threshold)
 835                (>= (window-width window)
 836                    (max split-width-threshold
 837                         (* 2 (max window-min-width 2)))))
 838         ;; A window can be split vertically when its height is not
 839         ;; fixed, it is at least `split-height-threshold' lines high,
 840         ;; and it is at least twice as high as `window-min-height' and 2
 841         ;; if it has a modeline or 1.
 842         (and (memq window-size-fixed '(nil width))
 843              (numberp split-height-threshold)
 844              (>= (window-height window)
 845                  (max split-height-threshold
 846                       (* 2 (max window-min-height
 847                                 (if mode-line-format 2 1))))))))))
 848
 849 (defun window--try-to-split-window (window)
 850   "Split WINDOW if it is splittable.
 851 See `window--splittable-p' for how to determine whether a window
 852 is splittable.  If WINDOW can be split, return the value returned
 853 by `split-window' (or `split-window-preferred-function')."
 854   (when (and (window-live-p window)
 855              (not (frame-parameter (window-frame window) 'unsplittable)))
 856     (if (functionp split-window-preferred-function)
 857         ;; `split-window-preferred-function' is specified, so use it.
 858         (funcall split-window-preferred-function window)
 859       (or (and (window--splittable-p window)
 860                ;; Split window vertically.
 861                (split-window window))
 862           (and (window--splittable-p window t)
 863                ;; Split window horizontally.
 864                (split-window window nil t))
 865           (and (eq window (frame-root-window (window-frame window)))
 866                (not (window-minibuffer-p window))
 867                ;; If WINDOW is the only window on its frame and not the
 868                ;; minibuffer window, attempt to split it vertically
 869                ;; disregarding the value of `split-height-threshold'.
 870                (let ((split-height-threshold 0))
 871                  (and (window--splittable-p window)
 872                       (split-window window))))))))
 873
 874 (defun window--frame-usable-p (frame)
 875   "Return FRAME if it can be used to display a buffer."
 876   (when (frame-live-p frame)
 877     (let ((window (frame-root-window frame)))
 878       ;; `frame-root-window' may be an internal window which is considered
 879       ;; "dead" by `window-live-p'.  Hence if `window' is not live we
 880       ;; implicitly know that `frame' has a visible window we can use.
 881       (when (or (not (window-live-p window))
 882                 (and (not (window-minibuffer-p window))
 883                      (not (window-dedicated-p window))))
 884         frame))))
 885
 886 (defcustom even-window-heights t
 887   "If non-nil `display-buffer' will try to even window heights.
 888 Otherwise `display-buffer' will leave the window configuration
 889 alone.  Heights are evened only when `display-buffer' chooses a
 890 window that appears above or below the selected window."
 891   :type 'boolean
 892   :group 'windows)
 893
 894 (defun window--even-window-heights (window)
 895   "Even heights of WINDOW and selected window.
 896 Do this only if these windows are vertically adjacent to each
 897 other, `even-window-heights' is non-nil, and the selected window
 898 is higher than WINDOW."
 899   (when (and even-window-heights
 900              (not (eq window (selected-window)))
 901              ;; Don't resize minibuffer windows.
 902              (not (window-minibuffer-p (selected-window)))
 903              (> (window-height (selected-window)) (window-height window))
 904              (eq (window-frame window) (window-frame (selected-window)))
 905              (let ((sel-edges (window-edges (selected-window)))
 906                    (win-edges (window-edges window)))
 907                (and (= (nth 0 sel-edges) (nth 0 win-edges))
 908                     (= (nth 2 sel-edges) (nth 2 win-edges))
 909                     (or (= (nth 1 sel-edges) (nth 3 win-edges))
 910                         (= (nth 3 sel-edges) (nth 1 win-edges))))))
 911     (let ((window-min-height 1))
 912       ;; Don't throw an error if we can't even window heights for
 913       ;; whatever reason.
 914       (condition-case nil
 915           (enlarge-window (/ (- (window-height window) (window-height)) 2))
 916         (error nil)))))
 917
 918 (defun window--display-buffer-1 (window)
 919   "Raise the frame containing WINDOW.
 920 Do not raise the selected frame.  Return WINDOW."
 921   (let* ((frame (window-frame window))
 922          (visible (frame-visible-p frame)))
 923     (unless (or (not visible)
 924                 ;; Assume the selected frame is already visible enough.
 925                 (eq frame (selected-frame))
 926                 ;; Assume the frame from which we invoked the minibuffer
 927                 ;; is visible.
 928                 (and (minibuffer-window-active-p (selected-window))
 929                      (eq frame (window-frame (minibuffer-selected-window)))))
 930       (raise-frame frame))
 931     window))
 932
 933 (defun window--display-buffer-2 (buffer window)
 934   "Display BUFFER in WINDOW and make its frame visible.
 935 Return WINDOW."
 936   (when (and (buffer-live-p buffer) (window-live-p window))
 937     (set-window-buffer window buffer)
 938     (window--display-buffer-1 window)))
 939
 940 (defun display-buffer (buffer-or-name &optional not-this-window frame)
 941   "Make buffer BUFFER-OR-NAME appear in some window but don't select it.
 942 BUFFER-OR-NAME must be a buffer or the name of an existing
 943 buffer.  Return the window chosen to display BUFFER-OR-NAME or
 944 nil if no such window is found.
 945
 946 Optional argument NOT-THIS-WINDOW non-nil means display the
 947 buffer in a window other than the selected one, even if it is
 948 already displayed in the selected window.
 949
 950 Optional argument FRAME specifies which frames to investigate
 951 when the specified buffer is already displayed.  If the buffer is
 952 already displayed in some window on one of these frames simply
 953 return that window.  Possible values of FRAME are:
 954
 955 `visible' - consider windows on all visible frames.
 956
 957 0 - consider windows on all visible or iconified frames.
 958
 959 t - consider windows on all frames.
 960
 961 A specific frame - consider windows on that frame only.
 962
 963 nil - consider windows on the selected frame \(actually the
 964 last non-minibuffer frame\) only.  If, however, either
 965 `display-buffer-reuse-frames' or `pop-up-frames' is non-nil
 966 \(non-nil and not graphic-only on a text-only terminal),
 967 consider all visible or iconified frames."
 968   (interactive "BDisplay buffer:\nP")
 969   (let* ((can-use-selected-window
 970           ;; The selected window is usable unless either NOT-THIS-WINDOW
 971           ;; is non-nil, it is dedicated to its buffer, or it is the
 972           ;; `minibuffer-window'.
 973           (not (or not-this-window
 974                    (window-dedicated-p (selected-window))
 975                    (window-minibuffer-p))))
 976          (buffer (if (bufferp buffer-or-name)
 977                      buffer-or-name
 978                    (get-buffer buffer-or-name)))
 979          (name-of-buffer (buffer-name buffer))
 980          ;; On text-only terminals do not pop up a new frame when
 981          ;; `pop-up-frames' equals graphic-only.
 982          (use-pop-up-frames (if (eq pop-up-frames 'graphic-only)
 983                                 (display-graphic-p)
 984                               pop-up-frames))
 985          ;; `frame-to-use' is the frame where to show `buffer' - either
 986          ;; the selected frame or the last nonminibuffer frame.
 987          (frame-to-use
 988           (or (window--frame-usable-p (selected-frame))
 989               (window--frame-usable-p (last-nonminibuffer-frame))))
 990          ;; `window-to-use' is the window we use for showing `buffer'.
 991          window-to-use)
 992     (cond
 993      ((not (buffer-live-p buffer))
 994       (error "No such buffer %s" buffer))
 995      (display-buffer-function
 996       ;; Let `display-buffer-function' do the job.
 997       (funcall display-buffer-function buffer not-this-window))
 998      ((and (not not-this-window)
 999            (eq (window-buffer (selected-window)) buffer))
1000       ;; The selected window already displays BUFFER and
1001       ;; `not-this-window' is nil, so use it.
1002       (window--display-buffer-1 (selected-window)))
1003      ((and can-use-selected-window (same-window-p name-of-buffer))
1004       ;; If the buffer's name tells us to use the selected window do so.
1005       (window--display-buffer-2 buffer (selected-window)))
1006      ((let ((frames (or frame
1007                         (and (or use-pop-up-frames
1008                                  display-buffer-reuse-frames
1009                                  (not (last-nonminibuffer-frame)))
1010                              0)
1011                         (last-nonminibuffer-frame))))
1012         (and (setq window-to-use (get-buffer-window buffer frames))
1013              (or can-use-selected-window
1014                  (not (eq (selected-window) window-to-use)))))
1015       ;; If the buffer is already displayed in some window use that.
1016       (window--display-buffer-1 window-to-use))
1017      ((and special-display-function
1018            ;; `special-display-p' returns either t or a list of frame
1019            ;; parameters to pass to `special-display-function'.
1020            (let ((pars (special-display-p name-of-buffer)))
1021              (when pars
1022                (funcall special-display-function
1023                         buffer (if (listp pars) pars))))))
1024      ((or use-pop-up-frames (not frame-to-use))
1025       ;; We want or need a new frame.
1026       (window--display-buffer-2
1027        buffer (frame-selected-window (funcall pop-up-frame-function))))
1028      ((and pop-up-windows
1029            ;; Make a new window.
1030            (or (not (frame-parameter frame-to-use 'unsplittable))
1031                ;; If the selected frame cannot be split look at
1032                ;; `last-nonminibuffer-frame'.
1033                (and (eq frame-to-use (selected-frame))
1034                     (setq frame-to-use (last-nonminibuffer-frame))
1035                     (window--frame-usable-p frame-to-use)
1036                     (not (frame-parameter frame-to-use 'unsplittable))))
1037            ;; Attempt to split largest or least recently used window.
1038            (setq window-to-use
1039                  (or (window--try-to-split-window
1040                       (get-largest-window frame-to-use t))
1041                      (window--try-to-split-window
1042                       (get-lru-window frame-to-use t))))
1043            (window--display-buffer-2 buffer window-to-use)))
1044      ((setq window-to-use
1045             ;; Reuse an existing window.
1046             (or (get-lru-window frame-to-use)
1047                 (get-buffer-window buffer 'visible)
1048                 (get-largest-window 'visible nil)
1049                 (get-buffer-window buffer 0)
1050                 (get-largest-window 0 nil)
1051                 (frame-selected-window (funcall pop-up-frame-function))))
1052       (window--even-window-heights window-to-use)
1053       (window--display-buffer-2 buffer window-to-use)))))
1054
1055 (defun pop-to-buffer (buffer-or-name &optional other-window norecord)
1056   "Select buffer BUFFER-OR-NAME in some window, preferably a different one.
1057 BUFFER-OR-NAME may be a buffer, a string \(a buffer name), or
1058 nil.  If BUFFER-OR-NAME is a string not naming an existent
1059 buffer, create a buffer with that name.  If BUFFER-OR-NAME is
1060 nil, choose some other buffer.
1061
1062 If `pop-up-windows' is non-nil, windows can be split to display
1063 the buffer.  If optional second arg OTHER-WINDOW is non-nil,
1064 insist on finding another window even if the specified buffer is
1065 already visible in the selected window, and ignore
1066 `same-window-regexps' and `same-window-buffer-names'.
1067
1068 If the window to show BUFFER-OR-NAME is not on the selected
1069 frame, raise that window's frame and give it input focus.
1070
1071 This function returns the buffer it switched to.  This uses the
1072 function `display-buffer' as a subroutine; see the documentation
1073 of `display-buffer' for additional customization information.
1074
1075 Optional third arg NORECORD non-nil means do not put this buffer
1076 at the front of the list of recently selected ones."
1077   (let ((buffer
1078          ;; FIXME: This behavior is carried over from the previous C version
1079          ;; of pop-to-buffer, but really we should use just
1080          ;; `get-buffer' here.
1081          (if (null buffer-or-name) (other-buffer (current-buffer))
1082            (or (get-buffer buffer-or-name)
1083                (let ((buf (get-buffer-create buffer-or-name)))
1084                  (set-buffer-major-mode buf)
1085                  buf))))
1086         (old-window (selected-window))
1087         (old-frame (selected-frame))
1088         new-window new-frame)
1089     (set-buffer buffer)
1090     (setq new-window (display-buffer buffer other-window))
1091     (unless (eq new-window old-window)
1092       ;; `display-buffer' has chosen another window, select it.
1093       (select-window new-window norecord)
1094       (setq new-frame (window-frame new-window))
1095       (unless (eq new-frame old-frame)
1096         ;; `display-buffer' has chosen another frame, make sure it gets
1097         ;; input focus and is risen.
1098         (select-frame-set-input-focus new-frame)))
1099     buffer))
1100
1101 ;; I think this should be the default; I think people will prefer it--rms.
1102 (defcustom split-window-keep-point t
1103   "If non-nil, \\[split-window-vertically] keeps the original point \
1104 in both children.
1105 This is often more convenient for editing.
1106 If nil, adjust point in each of the two windows to minimize redisplay.
1107 This is convenient on slow terminals, but point can move strangely.
1108
1109 This option applies only to `split-window-vertically' and
1110 functions that call it.  `split-window' always keeps the original
1111 point in both children."
1112   :type 'boolean
1113   :group 'windows)
1114
1115 (defun split-window-vertically (&optional size)
1116   "Split selected window into two windows, one above the other.
1117 The upper window gets SIZE lines and the lower one gets the rest.
1118 SIZE negative means the lower window gets -SIZE lines and the
1119 upper one the rest.  With no argument, split windows equally or
1120 close to it.  Both windows display the same buffer, now current.
1121
1122 If the variable `split-window-keep-point' is non-nil, both new
1123 windows will get the same value of point as the selected window.
1124 This is often more convenient for editing.  The upper window is
1125 the selected window.
1126
1127 Otherwise, we choose window starts so as to minimize the amount of
1128 redisplay; this is convenient on slow terminals.  The new selected
1129 window is the one that the current value of point appears in.  The
1130 value of point can change if the text around point is hidden by the
1131 new mode line.
1132
1133 Regardless of the value of `split-window-keep-point', the upper
1134 window is the original one and the return value is the new, lower
1135 window."
1136   (interactive "P")
1137   (let ((old-window (selected-window))
1138         (old-point (point))
1139         (size (and size (prefix-numeric-value size)))
1140         moved-by-window-height moved new-window bottom)
1141     (and size (< size 0)
1142          ;; Handle negative SIZE value.
1143          (setq size (+ (window-height) size)))
1144     (setq new-window (split-window nil size))
1145     (unless split-window-keep-point
1146       (save-excursion
1147         (set-buffer (window-buffer))
1148         (goto-char (window-start))
1149         (setq moved (vertical-motion (window-height)))
1150         (set-window-start new-window (point))
1151         (when (> (point) (window-point new-window))
1152           (set-window-point new-window (point)))
1153         (when (= moved (window-height))
1154           (setq moved-by-window-height t)
1155           (vertical-motion -1))
1156         (setq bottom (point)))
1157       (and moved-by-window-height
1158            (<= bottom (point))
1159            (set-window-point old-window (1- bottom)))
1160       (and moved-by-window-height
1161            (<= (window-start new-window) old-point)
1162            (set-window-point new-window old-point)
1163            (select-window new-window)))
1164     (split-window-save-restore-data new-window old-window)))
1165
1166 ;; This is to avoid compiler warnings.
1167 (defvar view-return-to-alist)
1168
1169 (defun split-window-save-restore-data (new-window old-window)
1170   (with-current-buffer (window-buffer)
1171     (when view-mode
1172       (let ((old-info (assq old-window view-return-to-alist)))
1173         (when old-info
1174           (push (cons new-window (cons (car (cdr old-info)) t))
1175                 view-return-to-alist))))
1176     new-window))
1177
1178 (defun split-window-horizontally (&optional size)
1179   "Split selected window into two windows side by side.
1180 The selected window becomes the left one and gets SIZE columns.
1181 SIZE negative means the right window gets -SIZE lines.
1182
1183 SIZE includes the width of the window's scroll bar; if there are
1184 no scroll bars, it includes the width of the divider column to
1185 the window's right, if any.  SIZE omitted or nil means split
1186 window equally.
1187
1188 The selected window remains selected.  Return the new window."
1189   (interactive "P")
1190   (let ((old-window (selected-window))
1191         (size (and size (prefix-numeric-value size))))
1192     (and size (< size 0)
1193          ;; Handle negative SIZE value.
1194          (setq size (+ (window-width) size)))
1195     (split-window-save-restore-data (split-window nil size t) old-window)))
1196
1197 \f
1198 (defun set-window-text-height (window height)
1199   "Sets the height in lines of the text display area of WINDOW to HEIGHT.
1200 HEIGHT doesn't include the mode line or header line, if any, or
1201 any partial-height lines in the text display area.
1202
1203 Note that the current implementation of this function cannot
1204 always set the height exactly, but attempts to be conservative,
1205 by allocating more lines than are actually needed in the case
1206 where some error may be present."
1207   (let ((delta (- height (window-text-height window))))
1208     (unless (zerop delta)
1209       ;; Setting window-min-height to a value like 1 can lead to very
1210       ;; bizarre displays because it also allows Emacs to make *other*
1211       ;; windows 1-line tall, which means that there's no more space for
1212       ;; the modeline.
1213       (let ((window-min-height (min 2 height))) ; One text line plus a modeline.
1214         (if (and window (not (eq window (selected-window))))
1215             (save-selected-window
1216               (select-window window 'norecord)
1217               (enlarge-window delta))
1218           (enlarge-window delta))))))
1219
1220 \f
1221 (defun enlarge-window-horizontally (columns)
1222   "Make selected window COLUMNS wider.
1223 Interactively, if no argument is given, make selected window one
1224 column wider."
1225   (interactive "p")
1226   (enlarge-window columns t))
1227
1228 (defun shrink-window-horizontally (columns)
1229   "Make selected window COLUMNS narrower.
1230 Interactively, if no argument is given, make selected window one
1231 column narrower."
1232   (interactive "p")
1233   (shrink-window columns t))
1234
1235 (defun window-buffer-height (window)
1236   "Return the height (in screen lines) of the buffer that WINDOW is displaying."
1237   (with-current-buffer (window-buffer window)
1238     (max 1
1239          (count-screen-lines (point-min) (point-max)
1240                              ;; If buffer ends with a newline, ignore it when
1241                              ;; counting height unless point is after it.
1242                              (eobp)
1243                              window))))
1244
1245 (defun count-screen-lines (&optional beg end count-final-newline window)
1246   "Return the number of screen lines in the region.
1247 The number of screen lines may be different from the number of actual lines,
1248 due to line breaking, display table, etc.
1249
1250 Optional arguments BEG and END default to `point-min' and `point-max'
1251 respectively.
1252
1253 If region ends with a newline, ignore it unless optional third argument
1254 COUNT-FINAL-NEWLINE is non-nil.
1255
1256 The optional fourth argument WINDOW specifies the window used for obtaining
1257 parameters such as width, horizontal scrolling, and so on.  The default is
1258 to use the selected window's parameters.
1259
1260 Like `vertical-motion', `count-screen-lines' always uses the current buffer,
1261 regardless of which buffer is displayed in WINDOW.  This makes possible to use
1262 `count-screen-lines' in any buffer, whether or not it is currently displayed
1263 in some window."
1264   (unless beg
1265     (setq beg (point-min)))
1266   (unless end
1267     (setq end (point-max)))
1268   (if (= beg end)
1269       0
1270     (save-excursion
1271       (save-restriction
1272         (widen)
1273         (narrow-to-region (min beg end)
1274                           (if (and (not count-final-newline)
1275                                    (= ?\n (char-before (max beg end))))
1276                               (1- (max beg end))
1277                             (max beg end)))
1278         (goto-char (point-min))
1279         (1+ (vertical-motion (buffer-size) window))))))
1280
1281 (defun fit-window-to-buffer (&optional window max-height min-height)
1282   "Adjust height of WINDOW to display its buffer's contents exactly.
1283 WINDOW defaults to the selected window.
1284 Optional argument MAX-HEIGHT specifies the maximum height of the
1285 window and defaults to the height of WINDOW's frame.
1286 Optional argument MIN-HEIGHT specifies the minimum height of the
1287 window and defaults to `window-min-height'.
1288 Both, MAX-HEIGHT and MIN-HEIGHT are specified in lines and
1289 include the mode line and header line, if any.
1290 Always return nil."
1291   (interactive)
1292
1293   (when (null window)
1294     (setq window (selected-window)))
1295   (when (null max-height)
1296     (setq max-height (frame-height (window-frame window))))
1297
1298   (let* ((buf
1299           ;; Buffer that is displayed in WINDOW
1300           (window-buffer window))
1301          (window-height
1302           ;; The current height of WINDOW
1303           (window-height window))
1304          (desired-height
1305           ;; The height necessary to show the buffer displayed by WINDOW
1306           ;; (`count-screen-lines' always works on the current buffer).
1307           (with-current-buffer buf
1308             (+ (count-screen-lines)
1309                ;; If the buffer is empty, (count-screen-lines) is
1310                ;; zero.  But, even in that case, we need one text line
1311                ;; for cursor.
1312                (if (= (point-min) (point-max))
1313                    1 0)
1314                ;; For non-minibuffers, count the mode-line, if any
1315                (if (and (not (window-minibuffer-p window))
1316                         mode-line-format)
1317                    1 0)
1318                ;; Count the header-line, if any
1319                (if header-line-format 1 0))))
1320          (delta
1321           ;; Calculate how much the window height has to change to show
1322           ;; desired-height lines, constrained by MIN-HEIGHT and MAX-HEIGHT.
1323           (- (max (min desired-height max-height)
1324                   (or min-height window-min-height))
1325              window-height)))
1326
1327     ;; Don't try to redisplay with the cursor at the end
1328     ;; on its own line--that would force a scroll and spoil things.
1329     (when (with-current-buffer buf
1330             (and (eobp) (bolp) (not (bobp))))
1331       (set-window-point window (1- (window-point window))))
1332
1333     (save-selected-window
1334       (select-window window 'norecord)
1335
1336       ;; Adjust WINDOW to the nominally correct size (which may actually
1337       ;; be slightly off because of variable height text, etc).
1338       (unless (zerop delta)
1339         (enlarge-window delta))
1340
1341       ;; Check if the last line is surely fully visible.  If not,
1342       ;; enlarge the window.
1343       (let ((end (with-current-buffer buf
1344                    (save-excursion
1345                      (goto-char (point-max))
1346                      (when (and (bolp) (not (bobp)))
1347                        ;; Don't include final newline
1348                        (backward-char 1))
1349                      (when truncate-lines
1350                        ;; If line-wrapping is turned off, test the
1351                        ;; beginning of the last line for visibility
1352                        ;; instead of the end, as the end of the line
1353                        ;; could be invisible by virtue of extending past
1354                        ;; the edge of the window.
1355                        (forward-line 0))
1356                      (point)))))
1357         (set-window-vscroll window 0)
1358         (while (and (< desired-height max-height)
1359                     (= desired-height (window-height window))
1360                     (not (pos-visible-in-window-p end window)))
1361           (enlarge-window 1)
1362           (setq desired-height (1+ desired-height)))))))
1363
1364 (defun shrink-window-if-larger-than-buffer (&optional window)
1365   "Shrink height of WINDOW if its buffer doesn't need so many lines.
1366 More precisely, shrink WINDOW vertically to be as small as
1367 possible, while still showing the full contents of its buffer.
1368 WINDOW defaults to the selected window.
1369
1370 Do not shrink to less than `window-min-height' lines.  Do nothing
1371 if the buffer contains more lines than the present window height,
1372 or if some of the window's contents are scrolled out of view, or
1373 if shrinking this window would also shrink another window, or if
1374 the window is the only window of its frame.
1375
1376 Return non-nil if the window was shrunk, nil otherwise."
1377   (interactive)
1378   (when (null window)
1379     (setq window (selected-window)))
1380   (let* ((frame (window-frame window))
1381          (mini (frame-parameter frame 'minibuffer))
1382          (edges (window-edges window)))
1383     (if (and (not (eq window (frame-root-window frame)))
1384              (window-safely-shrinkable-p window)
1385              (pos-visible-in-window-p (point-min) window)
1386              (not (eq mini 'only))
1387              (or (not mini)
1388                  (let ((mini-window (minibuffer-window frame)))
1389                    (or (null mini-window)
1390                        (not (eq frame (window-frame mini-window)))
1391                        (< (nth 3 edges)
1392                           (nth 1 (window-edges mini-window)))
1393                        (> (nth 1 edges)
1394                           (frame-parameter frame 'menu-bar-lines))))))
1395         (fit-window-to-buffer window (window-height window)))))
1396
1397 (defun kill-buffer-and-window ()
1398   "Kill the current buffer and delete the selected window."
1399   (interactive)
1400   (let ((window-to-delete (selected-window))
1401         (buffer-to-kill (current-buffer))
1402         (delete-window-hook (lambda ()
1403                               (condition-case nil
1404                                   (delete-window)
1405                                 (error nil)))))
1406     (unwind-protect
1407         (progn
1408           (add-hook 'kill-buffer-hook delete-window-hook t t)
1409           (if (kill-buffer (current-buffer))
1410               ;; If `delete-window' failed before, we rerun it to regenerate
1411               ;; the error so it can be seen in the echo area.
1412               (when (eq (selected-window) window-to-delete)
1413                 (delete-window))))
1414       ;; If the buffer is not dead for some reason (probably because
1415       ;; of a `quit' signal), remove the hook again.
1416       (condition-case nil
1417           (with-current-buffer buffer-to-kill
1418             (remove-hook 'kill-buffer-hook delete-window-hook t))
1419         (error nil)))))
1420
1421 (defun quit-window (&optional kill window)
1422   "Bury or kill (with KILL non-nil) the buffer displayed in WINDOW.
1423 With a prefix argument, kill the buffer instead.
1424
1425 KILL defaults to nil, WINDOW to the selected window.  If WINDOW
1426 is dedicated or a minibuffer window, delete it and, if it's the
1427 only window on its frame, delete its frame as well provided there
1428 are other frames left.  Otherwise, display some other buffer in
1429 the window."
1430   (interactive "P")
1431   (let* ((window (or window (selected-window)))
1432          (buffer (window-buffer window)))
1433     (if (or (window-minibuffer-p window) (window-dedicated-p window))
1434         (if (eq window (frame-root-window (window-frame window)))
1435             ;; If this is the only window on its frame, try to delete the
1436             ;; frame (`delete-windows-on' knows how to do that).
1437             (delete-windows-on buffer (selected-frame))
1438           ;; Other windows are left, delete this window.  But don't
1439           ;; throw an error if that fails for some reason.
1440           (condition-case nil
1441               (delete-window window)
1442             (error nil)))
1443       ;; The window is neither dedicated nor a minibuffer window,
1444       ;; display another buffer in it.
1445       (with-selected-window window
1446         (switch-to-buffer (other-buffer))))
1447     ;; Deal with the buffer.
1448     (if kill
1449         (kill-buffer buffer)
1450       (bury-buffer buffer))))
1451
1452 (defvar recenter-last-op nil
1453   "Indicates the last recenter operation performed.
1454 Possible values: `top', `middle', `bottom'.")
1455
1456 (defun recenter-top-bottom (&optional arg)
1457   "Move current line to window center, top, and bottom, successively.
1458 With no prefix argument, the first call redraws the frame and
1459  centers point vertically within the window.  Successive calls
1460  scroll the window, placing point on the top, bottom, and middle
1461  consecutively.  The cycling order is middle -> top -> bottom.
1462
1463 A prefix argument is handled like `recenter':
1464  With numeric prefix ARG, move current line to window-line ARG.
1465  With plain `C-u', move current line to window center.
1466
1467 Top and bottom destinations are actually `scroll-margin' lines
1468  the from true window top and bottom."
1469   (interactive "P")
1470   (cond
1471    (arg (recenter arg))                 ; Always respect ARG.
1472    ((or (not (eq this-command last-command))
1473         (eq recenter-last-op 'bottom))
1474     (setq recenter-last-op 'middle)
1475     (recenter))
1476    (t
1477     (let ((this-scroll-margin
1478            (min (max 0 scroll-margin)
1479                 (truncate (/ (window-body-height) 4.0)))))
1480       (cond ((eq recenter-last-op 'middle)
1481              (setq recenter-last-op 'top)
1482              (recenter this-scroll-margin))
1483             ((eq recenter-last-op 'top)
1484              (setq recenter-last-op 'bottom)
1485              (recenter (- -1 this-scroll-margin))))))))
1486
1487 (define-key global-map [?\C-l] 'recenter-top-bottom)
1488 \f
1489 (defvar mouse-autoselect-window-timer nil
1490   "Timer used by delayed window autoselection.")
1491
1492 (defvar mouse-autoselect-window-position nil
1493   "Last mouse position recorded by delayed window autoselection.")
1494
1495 (defvar mouse-autoselect-window-window nil
1496   "Last window recorded by delayed window autoselection.")
1497
1498 (defvar mouse-autoselect-window-state nil
1499   "When non-nil, special state of delayed window autoselection.
1500 Possible values are `suspend' \(suspend autoselection after a menu or
1501 scrollbar interaction\) and `select' \(the next invocation of
1502 'handle-select-window' shall select the window immediately\).")
1503
1504 (defun mouse-autoselect-window-cancel (&optional force)
1505   "Cancel delayed window autoselection.
1506 Optional argument FORCE means cancel unconditionally."
1507   (unless (and (not force)
1508                ;; Don't cancel for select-window or select-frame events
1509                ;; or when the user drags a scroll bar.
1510                (or (memq this-command
1511                          '(handle-select-window handle-switch-frame))
1512                    (and (eq this-command 'scroll-bar-toolkit-scroll)
1513                         (memq (nth 4 (event-end last-input-event))
1514                               '(handle end-scroll)))))
1515     (setq mouse-autoselect-window-state nil)
1516     (when (timerp mouse-autoselect-window-timer)
1517       (cancel-timer mouse-autoselect-window-timer))
1518     (remove-hook 'pre-command-hook 'mouse-autoselect-window-cancel)))
1519
1520 (defun mouse-autoselect-window-start (mouse-position &optional window suspend)
1521   "Start delayed window autoselection.
1522 MOUSE-POSITION is the last position where the mouse was seen as returned
1523 by `mouse-position'.  Optional argument WINDOW non-nil denotes the
1524 window where the mouse was seen.  Optional argument SUSPEND non-nil
1525 means suspend autoselection."
1526   ;; Record values for MOUSE-POSITION, WINDOW, and SUSPEND.
1527   (setq mouse-autoselect-window-position mouse-position)
1528   (when window (setq mouse-autoselect-window-window window))
1529   (setq mouse-autoselect-window-state (when suspend 'suspend))
1530   ;; Install timer which runs `mouse-autoselect-window-select' after
1531   ;; `mouse-autoselect-window' seconds.
1532   (setq mouse-autoselect-window-timer
1533         (run-at-time
1534          (abs mouse-autoselect-window) nil 'mouse-autoselect-window-select)))
1535
1536 (defun mouse-autoselect-window-select ()
1537   "Select window with delayed window autoselection.
1538 If the mouse position has stabilized in a non-selected window, select
1539 that window.  The minibuffer window is selected only if the minibuffer is
1540 active.  This function is run by `mouse-autoselect-window-timer'."
1541   (condition-case nil
1542       (let* ((mouse-position (mouse-position))
1543              (window
1544               (condition-case nil
1545                   (window-at (cadr mouse-position) (cddr mouse-position)
1546                              (car mouse-position))
1547                 (error nil))))
1548         (cond
1549          ((or (menu-or-popup-active-p)
1550               (and window
1551                    (not (coordinates-in-window-p (cdr mouse-position) window))))
1552           ;; A menu / popup dialog is active or the mouse is on the scroll-bar
1553           ;; of WINDOW, temporarily suspend delayed autoselection.
1554           (mouse-autoselect-window-start mouse-position nil t))
1555          ((eq mouse-autoselect-window-state 'suspend)
1556           ;; Delayed autoselection was temporarily suspended, reenable it.
1557           (mouse-autoselect-window-start mouse-position))
1558          ((and window (not (eq window (selected-window)))
1559                (or (not (numberp mouse-autoselect-window))
1560                    (and (> mouse-autoselect-window 0)
1561                         ;; If `mouse-autoselect-window' is positive, select
1562                         ;; window if the window is the same as before.
1563                         (eq window mouse-autoselect-window-window))
1564                    ;; Otherwise select window if the mouse is at the same
1565                    ;; position as before.  Observe that the first test after
1566                    ;; starting autoselection usually fails since the value of
1567                    ;; `mouse-autoselect-window-position' recorded there is the
1568                    ;; position where the mouse has entered the new window and
1569                    ;; not necessarily where the mouse has stopped moving.
1570                    (equal mouse-position mouse-autoselect-window-position))
1571                ;; The minibuffer is a candidate window if it's active.
1572                (or (not (window-minibuffer-p window))
1573                    (eq window (active-minibuffer-window))))
1574           ;; Mouse position has stabilized in non-selected window: Cancel
1575           ;; delayed autoselection and try to select that window.
1576           (mouse-autoselect-window-cancel t)
1577           ;; Select window where mouse appears unless the selected window is the
1578           ;; minibuffer.  Use `unread-command-events' in order to execute pre-
1579           ;; and post-command hooks and trigger idle timers.  To avoid delaying
1580           ;; autoselection again, set `mouse-autoselect-window-state'."
1581           (unless (window-minibuffer-p (selected-window))
1582             (setq mouse-autoselect-window-state 'select)
1583             (setq unread-command-events
1584                   (cons (list 'select-window (list window))
1585                         unread-command-events))))
1586          ((or (and window (eq window (selected-window)))
1587               (not (numberp mouse-autoselect-window))
1588               (equal mouse-position mouse-autoselect-window-position))
1589           ;; Mouse position has either stabilized in the selected window or at
1590           ;; `mouse-autoselect-window-position': Cancel delayed autoselection.
1591           (mouse-autoselect-window-cancel t))
1592          (t
1593           ;; Mouse position has not stabilized yet, resume delayed
1594           ;; autoselection.
1595           (mouse-autoselect-window-start mouse-position window))))
1596     (error nil)))
1597
1598 (defun handle-select-window (event)
1599   "Handle select-window events."
1600   (interactive "e")
1601   (let ((window (posn-window (event-start event))))
1602     (unless (or (not (window-live-p window))
1603                 ;; Don't switch if we're currently in the minibuffer.
1604                 ;; This tries to work around problems where the
1605                 ;; minibuffer gets unselected unexpectedly, and where
1606                 ;; you then have to move your mouse all the way down to
1607                 ;; the minibuffer to select it.
1608                 (window-minibuffer-p (selected-window))
1609                 ;; Don't switch to minibuffer window unless it's active.
1610                 (and (window-minibuffer-p window)
1611                      (not (minibuffer-window-active-p window)))
1612                 ;; Don't switch when autoselection shall be delayed.
1613                 (and (numberp mouse-autoselect-window)
1614                      (not (zerop mouse-autoselect-window))
1615                      (not (eq mouse-autoselect-window-state 'select))
1616                      (progn
1617                        ;; Cancel any delayed autoselection.
1618                        (mouse-autoselect-window-cancel t)
1619                        ;; Start delayed autoselection from current mouse
1620                        ;; position and window.
1621                        (mouse-autoselect-window-start (mouse-position) window)
1622                        ;; Executing a command cancels delayed autoselection.
1623                        (add-hook
1624                         'pre-command-hook 'mouse-autoselect-window-cancel))))
1625       (when mouse-autoselect-window
1626         ;; Reset state of delayed autoselection.
1627         (setq mouse-autoselect-window-state nil)
1628         ;; Run `mouse-leave-buffer-hook' when autoselecting window.
1629         (run-hooks 'mouse-leave-buffer-hook))
1630       (select-window window))))
1631
1632 (defun delete-other-windows-vertically (&optional window)
1633   "Delete the windows in the same column with WINDOW, but not WINDOW itself.
1634 This may be a useful alternative binding for \\[delete-other-windows]
1635  if you often split windows horizontally."
1636   (interactive)
1637   (let* ((window (or window (selected-window)))
1638          (edges (window-edges window))
1639          (w window) delenda)
1640     (while (not (eq (setq w (next-window w 1)) window))
1641       (let ((e (window-edges w)))
1642         (when (and (= (car e) (car edges))
1643                    (= (caddr e) (caddr edges)))
1644           (push w delenda))))
1645     (mapc 'delete-window delenda)))
1646
1647 (defun truncated-partial-width-window-p (&optional window)
1648   "Return non-nil if lines in WINDOW are specifically truncated due to its width.
1649 WINDOW defaults to the selected window.
1650 Return nil if WINDOW is not a partial-width window
1651  (regardless of the value of `truncate-lines').
1652 Otherwise, consult the value of `truncate-partial-width-windows'
1653  for the buffer shown in WINDOW."
1654   (unless window
1655     (setq window (selected-window)))
1656   (unless (window-full-width-p window)
1657     (let ((t-p-w-w (buffer-local-value 'truncate-partial-width-windows
1658                                        (window-buffer window))))
1659       (if (integerp t-p-w-w)
1660           (< (window-width window) t-p-w-w)
1661         t-p-w-w))))
1662
1663 (define-key ctl-x-map "2" 'split-window-vertically)
1664 (define-key ctl-x-map "3" 'split-window-horizontally)
1665 (define-key ctl-x-map "}" 'enlarge-window-horizontally)
1666 (define-key ctl-x-map "{" 'shrink-window-horizontally)
1667 (define-key ctl-x-map "-" 'shrink-window-if-larger-than-buffer)
1668 (define-key ctl-x-map "+" 'balance-windows)
1669 (define-key ctl-x-4-map "0" 'kill-buffer-and-window)
1670
1671 ;; arch-tag: b508dfcc-c353-4c37-89fa-e773fe10cea9
1672 ;;; window.el ends here