ErgoEmacsEmacsLispBlogEmacsLispBuy Tutorial

28.16 Changing the Size of a Window

The window size functions fall into two classes: high-level commands that change the size of windows and low-level functions that access window size. Emacs does not permit overlapping windows or gaps between windows, so resizing a window always affects at least one other window.

— Command: enlarge-window size &optional horizontal

This function makes the selected window size lines taller by stealing lines from windows above or below. In a first round, it takes lines from one window at a time until that window is window-min-height lines tall, then takes from another. If, at the end of the first round, the selected window is still not tall enough, enlarge-window starts a second round, where it deletes windows above or below the selected one.

If horizontal is non-nil, this function makes the window size columns wider, stealing columns instead of lines. If a window from which columns are stolen shrinks below window-min-width columns, that window disappears.

If the requested size would exceed that of the window's frame, then the function makes the window occupy the entire height (or width) of the frame.

If there are various other windows from which lines or columns can be stolen, and some of them specify fixed size (using window-size-fixed, see below), they are left untouched while other windows are “robbed.” If it would be necessary to alter the size of a fixed-size window, enlarge-window gets an error instead.

If size is negative, this function shrinks the selected window by −size lines or columns. If that makes the window smaller than the minimum size (window-min-height and window-min-width), then enlarge-window deletes the window.

enlarge-window returns nil.

— Command: enlarge-window-horizontally columns

This function makes the selected window columns wider. It could be defined as follows:

          (defun enlarge-window-horizontally (columns)
            (interactive "p")
            (enlarge-window columns t))
— Command: shrink-window size &optional horizontal

This function is like enlarge-window but negates the argument size, making the selected window smaller by giving lines (or columns) to the other windows. If the window shrinks below window-min-height or window-min-width, then it disappears.

If size is negative, the window is enlarged by −size lines or columns.

— Command: shrink-window-horizontally columns

This function makes the selected window columns narrower. It could be defined as follows:

          (defun shrink-window-horizontally (columns)
            (interactive "p")
            (shrink-window columns t))
— Function: adjust-window-trailing-edge window delta horizontal

This function makes the selected window delta lines taller or delta columns wider, by moving the bottom or right edge. This function does not delete other windows; if it cannot make the requested size adjustment, it signals an error. On success, this function returns nil.

— Command: fit-window-to-buffer &optional window max-height min-height

This command makes window the right height to display its contents exactly. The default for window is the selected window.

The optional argument max-height specifies the maximum height the window is allowed to be; nil means use the maximum permissible height of a window on window's frame. The optional argument min-height specifies the minimum height for the window; nil means use window-min-height. All these height values include the mode line and/or header line.

This function can delete windows when their height shrinks below min-height. It returns non-nil if it orderly resized window, and nil otherwise.

— Command: shrink-window-if-larger-than-buffer &optional window

This command shrinks window vertically to be as small as possible while still showing the full contents of its buffer—but not less than window-min-height lines. The default for window is the selected window.

However, this command does nothing if the window is already too small to display the whole text of the buffer, or if part of the contents are currently scrolled off screen, or if the window is not the full width of its frame, or if the window is the only window in its frame.

This command returns non-nil if it actually shrank the window and nil otherwise.

— Variable: window-size-fixed

If this variable is non-nil, in a given buffer, then the size of any window displaying that buffer remains fixed unless you either explicitly change it or Emacs has no other choice.

If the value is height, then only the window's height is fixed; if the value is width, then only the window's width is fixed. Any other non-nil value fixes both the width and the height.

This variable automatically becomes buffer-local when set.

Explicit size-change functions such as enlarge-window get an error if they would have to change a window size which is fixed. Therefore, when you want to change the size of such a window, you should bind window-size-fixed to nil, like this:

          (let ((window-size-fixed nil))
             (enlarge-window 10))

Deleting an adjacent window or changing the frame size may change the size of a fixed-size window, if there is no other alternative.

The following two variables constrain the window-structure-changing functions to a minimum height and width.

— User Option: window-min-height

The value of this variable specifies how short a window may become before it is automatically deleted. Making a window smaller than window-min-height automatically deletes it, and no window may be created shorter than this. The value is measured in line units. When the window wants a mode line and/or a header line, they are counted as one line each. The default value is 4. A value less than 1 is ignored.

— User Option: window-min-width

The value of this variable specifies how narrow a window may become before it is automatically deleted. Making a window smaller than window-min-width automatically deletes it, and no window may be created narrower than this. The value is measured in characters and includes any fringes or the scroll bar. The default value is 10. A value less than 2 is ignored.

Emacs provides two functions to balance windows, that is, to even out the sizes of windows on the same frame. The minibuffer window and fixed-size windows are not resized by these functions.

— Command: balance-windows &optional window-or-frame

This function balances windows in a way that gives more space to full-width and/or full-height windows. If window-or-frame specifies a frame, it balances all windows on that frame. If window-or-frame specifies a window, it balances this window and its “siblings” only. Think of a sibling as the other (original or new) window with respect to the present one, involved in the process of splitting; see Splitting Windows. Since a sibling may have been split again, a window can have more than one sibling.

— Command: balance-windows-area

This function attempts to give all windows on the selected frame approximately the same share of the screen area. This means that full-width or full-height windows are not given more space than other windows.

blog comments powered by Disqus