28.3.4 Frame Size And Position

You can read or change the size and position of a frame using the frame parameters left, top, height, and width. Whatever geometry parameters you don’t specify are chosen by the window manager in its usual fashion.

Here are some special features for working with sizes and positions. (For the precise meaning of “selected frame” used by these functions, see Input Focus.)

Function: set-frame-position frame left top

This function sets the position of the top left corner of frame to left and top. These arguments are measured in pixels, and normally count from the top left corner of the screen.

Negative parameter values position the bottom edge of the window up from the bottom edge of the screen, or the right window edge to the left of the right edge of the screen. It would probably be better if the values were always counted from the left and top, so that negative arguments would position the frame partly off the top or left edge of the screen, but it seems inadvisable to change that now.

Function: frame-height &optional frame

Function: frame-width &optional frame

These functions return the height and width of frame, measured in lines and columns. If you don’t supply frame, they use the selected frame.

Function: frame-pixel-height &optional frame

Function: frame-pixel-width &optional frame

These functions return the height and width of the main display area of frame, measured in pixels. If you don’t supply frame, they use the selected frame. For a text terminal, the results are in characters rather than pixels.

These values include the internal borders, and windows’ scroll bars and fringes (which belong to individual windows, not to the frame itself). The exact value of the heights depends on the window-system and toolkit in use. With GTK+, the height does not include any tool bar or menu bar. With the Motif or Lucid toolkits, it includes the tool bar but not the menu bar. In a graphical version with no toolkit, it includes both the tool bar and menu bar. For a text terminal, the result includes the menu bar.

Function: frame-char-height &optional frame

Function: frame-char-width &optional frame

These functions return the height and width of a character in frame, measured in pixels. The values depend on the choice of font. If you don’t supply frame, these functions use the selected frame.

User Option: frame-resize-pixelwise

If this option is nil, a frame’s size is usually rounded to a multiple of the current values of that frame’s frame-char-height and frame-char-width. If this is non-nil, no rounding occurs, hence frame sizes can increase/decrease by one pixel.

Setting this causes the next resize operation to pass the corresponding size hints to the window manager. This means that this variable should be set only in a user’s initial file; applications should never bind it temporarily.

The precise meaning of a value of nil for this option depends on the toolkit used. Dragging the frame border with the mouse is usually done character-wise. Calling set-frame-size (see below) with arguments that do not specify the frame size as an integer multiple of its character size, however, may: be ignored, cause a rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows).

With some window managers you may have to set this to non-nil in order to make a frame appear truly “maximized” or “fullscreen”.

Function: set-frame-size frame width height pixelwise

This function sets the size of frame, measured in characters; width and height specify the new width in columns and the new height in lines.

The optional argument pixelwise non-nil means to measure the new width and height in units of pixels instead. Note that if frame-resize-pixelwise is nil, some toolkits may refuse to fully honor the request if it does not increase/decrease the frame size to a multiple of its character size.

Function: set-frame-height frame height &optional pretend pixelwise

This function resizes frame to a height of height lines. The sizes of existing windows in frame are altered proportionally to fit.

If pretend is non-nil, then Emacs displays height lines of output in frame, but does not change its value for the actual height of the frame. This is only useful on text terminals. Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. Setting the frame height “for real” does not always work, because knowing the correct actual size may be necessary for correct cursor positioning on text terminals.

The optional fourth argument pixelwise non-nil means that frame should be height pixels high. Note that if frame-resize-pixelwise is nil, some toolkits may refuse to fully honor the request if it does not increase/decrease the frame height to a multiple of its character height.

Function: set-frame-width frame width &optional pretend pixelwise

This function sets the width of frame, measured in characters. The argument pretend has the same meaning as in set-frame-height.

The optional fourth argument pixelwise non-nil means that frame should be width pixels wide. Note that if frame-resize-pixelwise is nil, some toolkits may refuse to fully honor the request if it does not increase/decrease the frame width to a multiple of its character width.

If you have a frame that displays only one window, you can fit that frame to its buffer using the command fit-frame-to-buffer.

Command: fit-frame-to-buffer &optional frame max-height min-height max-width min-width only

This command adjusts the size of frame to display the contents of its buffer exactly. frame can be any live frame and defaults to the selected one. Fitting is done only if frame’s root window is live. The arguments max-height, min-height, max-width and min-width specify bounds on the new total size of frame’s root window. min-height and min-width default to the values of window-min-height and window-min-width respectively.

If the optional argument only is vertically, this function may resize the frame vertically only. If only is horizontally, it may resize the frame horizontally only.

The behavior of fit-frame-to-buffer can be controlled with the help of the two options listed next.

User Option: fit-frame-to-buffer-margins

This option can be used to specify margins around frames to be fit by fit-frame-to-buffer. Such margins can be useful to avoid, for example, that such frames overlap the taskbar.

It specifies the numbers of pixels to be left free on the left, above, the right, and below a frame that shall be fit. The default specifies nil for each which means to use no margins. The value specified here can be overridden for a specific frame by that frame’s fit-frame-to-buffer-margins parameter, if present.

User Option: fit-frame-to-buffer-sizes

This option specifies size boundaries for fit-frame-to-buffer. It specifies the total maximum and minimum lines and maximum and minimum columns of the root window of any frame that shall be fit to its buffer. If any of these values is non-nil, it overrides the corresponding argument of fit-frame-to-buffer.