+
+@node Frame Geometry
+@section Frame Geometry
+@cindex frame geometry
+@cindex frame position
+@cindex position of frame
+@cindex frame size
+@cindex size of frame
+
+The geometry of a frame depends on the toolkit that was used to build
+this instance of Emacs and the terminal that displays the frame. This
+chapter describes these dependencies and some of the functions to deal
+with them. Note that the @var{frame} argument of all of these functions
+has to specify a live frame (@pxref{Deleting Frames}). If omitted or
+@code{nil}, it specifies the selected frame (@pxref{Input Focus}).
+
+@menu
+* Frame Layout:: Basic layout of frames.
+* Frame Font:: The default font of a frame and how to set it.
+* Size and Position:: Changing the size and position of a frame.
+* Implied Frame Resizing:: Implied resizing of frames and how to prevent it.
+@end menu
+
+
+@node Frame Layout
+@subsection Frame Layout
+@cindex frame layout
+@cindex layout of frame
+
+The drawing below sketches the layout of a frame on a graphical
+terminal:
+@smallexample
+@group
+
+ <------------ Outer Frame Width ----------->
+ ___________________________________________
+ ^(0) ___________ External Border __________ |
+ | | |_____________ Title Bar ______________| |
+ | | (1)_____________ Menu Bar ______________| | ^
+ | | (2)_____________ Tool Bar ______________| | ^
+ | | (3) _________ Internal Border ________ | | ^
+ | | | | ^ | | | |
+ | | | | | | | | |
+Outer | | | Inner | | | Native
+Frame | | | Frame | | | Frame
+Height | | | Height | | | Height
+ | | | | | | | | |
+ | | | |<--+--- Inner Frame Width ------->| | | |
+ | | | | | | | | |
+ | | | |___v______________________________| | | |
+ | | |___________ Internal Border __________| | v
+ v |______________ External Border _____________|
+ <-------- Native Frame Width -------->
+
+@end group
+@end smallexample
+
+In practice not all of the areas shown in the drawing will or may be
+present. The meaning of these areas is:
+
+@table @samp
+@item Outer Frame
+@cindex outer frame
+@cindex outer edges
+@cindex outer width
+@cindex outer height
+The @dfn{outer frame} is a rectangle comprising all areas shown in the
+drawing. The edges of that rectangle are called the @dfn{outer edges}
+of the frame. The @dfn{outer width} and @dfn{outer height} of the frame
+specify the size of that rectangle.
+
+@cindex outer position
+The upper left corner of the outer frame (indicated by @samp{(0)} in the
+drawing above) is the @dfn{outer position} or the frame. It is
+specified by and settable via the @code{left} and @code{top} frame
+parameters (@pxref{Position Parameters}) as well as the functions
+@code{frame-position} and @code{set-frame-position} (@pxref{Size and
+Position}).
+
+@item External Border
+@cindex external border
+The @dfn{external border} is part of the decorations supplied by the
+window manager. It's typically used for resizing the frame with the
+mouse. The external border is normally not shown on ``fullboth'' and
+maximized frames (@pxref{Size Parameters}) and doesn't exist for text
+terminal frames.
+
+ The external border should not be confused with the @dfn{outer
+border} specified by the @code{border-width} frame parameter
+(@pxref{Layout Parameters}). Since the outer border is usually ignored
+on most platforms it is not covered here.
+
+@item Title Bar
+@cindex title bar
+The @dfn{title bar} is also part of the window manager's decorations and
+typically displays the title of the frame (@pxref{Frame Titles}) as well
+as buttons for minimizing, maximizing and deleting the frame. The title
+bar is usually not displayed on fullboth (@pxref{Size Parameters})
+or tooltip frames. Title bars don't exist for text terminal frames.
+
+@item Menu Bar
+@cindex internal menu bar
+@cindex external menu bar
+The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs
+itself) or external (drawn by a toolkit). Most builds (GTK+, Lucid,
+Motif and Windows) rely on an external menu bar. NS also uses an
+external menu bar which, however, is not part of the outer frame.
+Non-toolkit builds can provide an internal menu bar. On text terminal
+frames, the menu bar is part of the frame's root window (@pxref{Windows
+and Frames}).
+
+@item Tool Bar
+@cindex internal tool bar
+@cindex external tool bar
+Like the menu bar, the tool bar (@pxref{Tool Bar}) can be either
+internal (drawn by Emacs itself) or external (drawn by a toolkit). The
+GTK+ and NS builds have the tool bar drawn by the toolkit. The
+remaining builds use internal tool bars. With GTK+ the tool bar can be
+located on either side of the frame, immediately outside the internal
+border, see below.
+
+@item Native Frame
+@cindex native frame
+@cindex native edges
+@cindex native width
+@cindex native height
+@cindex display area
+The @dfn{native frame} is a rectangle located entirely within the outer
+frame. It excludes the areas occupied by the external border, the title
+bar and any external menu or external tool bar. The area enclosed by
+the native frame is sometimes also referred to as the @dfn{display area}
+of the frame. The edges of the native frame are called the @dfn{native
+edges} of the frame. The @dfn{native width} and @dfn{native height} of
+the frame specify the size of the rectangle.
+
+@cindex native position
+The top left corner of the native frame specifies the @dfn{native
+position} of the frame. (1)--(3) in the drawing above indicate that
+position for the various builds:
+
+@itemize @w{}
+@item (1) non-toolkit and terminal frames
+
+@item (2) Lucid, Motif and Windows frames
+
+@item (3) GTK+ and NS frames
+@end itemize
+
+Accordingly, the native height of a frame includes the height of the
+tool bar but not that of the menu bar (Lucid, Motif, Windows) or those
+of the menu bar and the tool bar (non-toolkit and text terminal frames).
+
+The native position of a frame is the reference position of functions
+that set or return the current position of the mouse (@pxref{Mouse
+Position}) and for functions dealing with the position of windows like
+@code{window-edges}, @code{window-at} or @code{coordinates-in-window-p}
+(@pxref{Coordinates and Windows}).
+
+@item Internal Border
+The internal border (@pxref{Layout Parameters}) is a border drawn by
+Emacs around the inner frame (see below).
+
+@item Inner Frame
+@cindex inner frame
+@cindex inner edges
+@cindex inner width
+@cindex inner height
+The @dfn{inner frame} is the rectangle reserved for the frame's windows.
+It's enclosed by the internal border which, however, is not part of the
+inner frame. Its edges are called the @dfn{inner edges} of the frame.
+The @dfn{inner width} and @dfn{inner height} specify the size of the
+rectangle.
+
+@cindex minibuffer-less frame
+@cindex minibuffer-only frame
+As a rule, the inner frame is subdivided into the frame's root window
+(@pxref{Windows and Frames}) and the frame's minibuffer window
+(@pxref{Minibuffer Windows}). There are two notable exceptions to this
+rule: A @dfn{minibuffer-less frame} contains a root window only and does
+not contain a minibuffer window. A @dfn{minibuffer-only frame} contains
+only a minibuffer window which also serves as that frame's root window.
+See @ref{Initial Parameters} for how to create such frame
+configurations.
+
+@item Text Area
+@cindex text area
+The @dfn{text area} of a frame is a somewhat fictitious area located
+entirely within the native frame. It can be obtained by removing from
+the native frame any internal borders, one vertical and one horizontal
+scroll bar, and one left and one right fringe as specified for this
+frame, see @ref{Layout Parameters}.
+@end table
+
+@cindex absolute position
+The @dfn{absolute position} of a frame or its edges is usually given in
+terms of pixels counted from an origin at position (0, 0) of the frame's
+display. Note that with multiple monitors the origin does not
+necessarily coincide with the top left corner of the entire usable
+display area. Hence the absolute outer position of a frame or the
+absolute positions of the edges of the outer, native or inner frame can
+be negative in such an environment even when that frame is completely
+visible.
+
+ For a frame on a graphical terminal the following function returns the
+sizes of the areas described above:
+
+@defun frame-geometry &optional frame
+This function returns geometric attributes of @var{frame}. The return
+value is an association list of the attributes listed below. All
+coordinate, height and width values are integers counting pixels.
+
+@table @code
+@item outer-position
+A cons of the absolute X- and Y-coordinates of the outer position of
+@var{frame}, relative to the origin at position (0, 0) of @var{frame}'s
+display.
+
+@item outer-size
+A cons of the outer width and height of @var{frame}.
+
+@item external-border-size
+A cons of the horizontal and vertical width of @var{frame}'s external
+borders as supplied by the window manager. If the window manager
+doesn't supply these values, Emacs will try to guess them from the
+coordinates of the outer and inner frame.
+
+@item title-bar-size
+A cons of the width and height of the title bar of @var{frame} as
+supplied by the window manager or operating system. If both of them are
+zero, the frame has no title bar. If only the width is zero, Emacs was
+not able to retrieve the width information.
+
+@item menu-bar-external
+If non-@code{nil}, this means the menu bar is external (not part of the
+native frame of @var{frame}).
+
+@item menu-bar-size
+A cons of the width and height of the menu bar of @var{frame}.
+
+@item tool-bar-external
+If non-@code{nil}, this means the tool bar is external (not part of the
+native frame of @var{frame}).
+
+@item tool-bar-position
+This tells on which side the tool bar on @var{frame} is and can be one
+of @code{left}, @code{top}, @code{right} or @code{bottom}. The only
+toolkit that currently supports a value other than @code{top} is GTK+.
+
+@item tool-bar-size
+A cons of the width and height of the tool bar of @var{frame}.
+
+@item internal-border-width
+The width of the internal border of @var{frame}.
+@end table
+@end defun
+
+The following function can be used to retrieve the edges of the outer,
+native and inner frame.
+
+@defun frame-edges &optional frame type
+This function returns the edges of the outer, native or inner frame of
+@var{frame}. @var{frame} must be a live frame and defaults to the
+selected one. The list returned has the form (@var{left} @var{top}
+@var{right} @var{bottom}) where all values are in pixels relative to the
+position (0, 0) of @var{frame}'s display. For terminal frames
+@var{left} and @var{top} are both zero.
+
+Optional argument @var{type} specifies the type of the edges to return:
+@var{type} @code{outer-edges} means to return the outer edges of
+@var{frame}, @code{native-edges} (or @code{nil}) means to return its
+native edges and @code{inner-edges} means to return its inner edges.
+
+Notice that the pixels at the positions @var{bottom} and @var{right}
+lie immediately outside the corresponding frame. This means that if you
+have, for example, two side-by-side frames positioned such that the
+right outer edge of the frame on the left equals the left outer edge of
+the frame on the right, the pixels representing that edge are part
+of the frame on the right.
+@end defun
+
+
+@node Frame Font
+@subsection Frame Font
+@cindex default font
+@cindex default character size
+@cindex default character width
+@cindex default width of character
+@cindex default character height
+@cindex default height of character
+Each frame has a @dfn{default font} which specifies the default
+character size for that frame. This size is meant when retrieving or
+changing the size of a frame in terms of columns or lines
+(@pxref{Size Parameters}). It is also used when resizing (@pxref{Window
+Sizes}) or splitting (@pxref{Splitting Windows}) windows.
+
+@cindex line height
+@cindex column width
+The term @dfn{line height} is sometimes used instead of ``default
+character height''. Similarly, the term @dfn{column width} is used as
+shorthand for ``default character width''.
+
+@defun frame-char-height &optional frame
+@defunx frame-char-width &optional frame
+These functions return the default height and width of a character in
+@var{frame}, measured in pixels. Together, these values establish the
+size of the default font on @var{frame}. The values depend on the
+choice of font for @var{frame}, see @ref{Font and Color Parameters}.
+@end defun
+
+The default font can be also set directly with the following function:
+
+@deffn Command set-frame-font font &optional keep-size frames
+This sets the default font to @var{font}. When called interactively, it
+prompts for the name of a font, and uses that font on the selected
+frame. When called from Lisp, @var{font} should be a font name (a
+string), a font object, font entity, or a font spec.
+
+If the optional argument @var{keep-size} is @code{nil}, this keeps the
+number of frame lines and columns fixed. (If non-@code{nil}, the option
+@code{frame-inhibit-implied-resize} described in the next section will
+override this.) If @var{keep-size} is non-@code{nil} (or with a prefix
+argument), it tries to keep the size of the display area of the current
+frame fixed by adjusting the number of lines and columns.
+
+If the optional argument @var{frames} is @code{nil}, this applies the
+font to the selected frame only. If @var{frames} is non-@code{nil}, it
+should be a list of frames to act upon, or @code{t} meaning all existing
+and all future graphical frames.
+@end deffn
+
+
+@node Size and Position
+@subsection Size and Position
+@cindex frame size
+@cindex frame position
+@cindex position of frame
+
+You can read or change the position of a frame using the frame
+parameters @code{left} and @code{top} (@pxref{Position Parameters}) and
+its size using the @code{height} and @code{width} parameters
+(@pxref{Size Parameters}). Here are some special features for working
+with sizes and positions. For all of these functions the argument
+@var{frame} must denote a live frame and defaults to the selected frame.
+
+@defun frame-position &optional Lisp_Object &optional frame
+This function returns the outer position (@pxref{Frame Layout}) of
+@var{frame} in pixels. The value is a cons giving the coordinates of
+the top left corner of the outer frame of @var{frame} relative to an
+origin at the position (0, 0) of the frame's display. On a text
+terminal frame both values are zero.
+@end defun
+
+@defun set-frame-position frame X Y
+This function sets the outer frame position of @var{frame} to @var{X}
+and @var{Y}. The latter arguments specify pixels and normally count
+from an origin at the position (0, 0) of @var{frame}'s display.
+
+A negative parameter value positions the right edge of the outer frame
+by @var{-x} pixels left from the right edge of the screen or the bottom
+edge by @var{-y} pixels up from the bottom edge of the screen.
+
+This function has no effect on text terminal frames.
+@end defun
+
+@defun frame-pixel-height &optional frame
+@defunx frame-pixel-width &optional frame
+ These functions return the inner height and width (the height and
+width of the display area, see @ref{Frame Layout}) of @var{frame} in
+pixels. For a text terminal, the results are in characters rather than
+pixels.
+@end defun
+
+@defun frame-text-height &optional frame
+@defunx frame-text-width &optional frame
+These functions return the height and width of the text area of
+@var{frame} (@pxref{Frame Layout}), measured in pixels. For a text
+terminal, the results are in characters rather than pixels.
+
+The value returned by @code{frame-text-height} differs from that
+returned by @code{frame-pixel-height} by not including the heights of
+any internal tool bar or menu bar, the height of one horizontal scroll
+bar and the widths of the internal border.
+
+The value returned by @code{frame-text-width} differs from that returned
+by @code{frame-pixel-width} by not including the width of one vertical
+scroll bar, the widths of one left and one right fringe and the widths
+of the internal border.
+@end defun
+
+@defun frame-height &optional frame
+@defunx frame-width &optional frame
+These functions return the height and width of the text area of
+@var{frame}, measured in units of the default font height and width of
+@var{frame} (@pxref{Frame Font}). These functions are plain shorthands
+for writing @code{(frame-parameter frame 'height)} and
+@code{(frame-parameter frame 'width)}.
+
+If the text area of @var{frame} measured in pixels is not a multiple of
+its default font size, the values returned by these functions are
+rounded down to the number of characters of the default font that fully
+fit into the text area.
+@end defun
+
+@defopt frame-resize-pixelwise
+If this option is @code{nil}, a frame's size is usually rounded to a
+multiple of the current values of that frame's @code{frame-char-height}
+and @code{frame-char-width} whenever the frame is resized. If this is
+non-@code{nil}, no rounding occurs, hence frame sizes can
+increase/decrease by one pixel.
+
+Setting this variable usually 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 @code{nil} for this option depends on
+the toolkit used. Dragging the external border with the mouse is done
+character-wise provided the window manager is willing to process the
+corresponding size hints. Calling @code{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-@code{nil} in
+order to make a frame appear truly maximized or full-screen.
+@end defopt
+
+@defun set-frame-size frame width height pixelwise
+This function sets the size of the text area of @var{frame}, measured in
+terms of the canonical height and width of a character on @var{frame}
+(@pxref{Frame Font}).
+
+The optional argument @var{pixelwise} non-@code{nil} means to measure
+the new width and height in units of pixels instead. Note that if
+@code{frame-resize-pixelwise} is @code{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.
+@end defun
+
+@defun set-frame-height frame height &optional pretend pixelwise
+This function resizes the text area of @var{frame} to a height of
+@var{height} lines. The sizes of existing windows in @var{frame} are
+altered proportionally to fit.
+
+If @var{pretend} is non-@code{nil}, then Emacs displays @var{height}
+lines of output in @var{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 directly does not always work, because knowing the correct
+actual size may be necessary for correct cursor positioning on
+text terminals.
+
+The optional fourth argument @var{pixelwise} non-@code{nil} means that
+@var{frame} should be @var{height} pixels high. Note that if
+@code{frame-resize-pixelwise} is @code{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.
+@end defun
+
+@defun set-frame-width frame width &optional pretend pixelwise
+This function sets the width of the text area of @var{frame}, measured
+in characters. The argument @var{pretend} has the same meaning as in
+@code{set-frame-height}.
+
+The optional fourth argument @var{pixelwise} non-@code{nil} means that
+@var{frame} should be @var{width} pixels wide. Note that if
+@code{frame-resize-pixelwise} is @code{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.
+@end defun
+
+None of these three functions will make a frame smaller than needed to
+display all of its windows together with their scroll bars, fringes,
+margins, dividers, mode and header lines. This contrasts with requests
+by the window manager triggered, for example, by dragging the external
+border of a frame with the mouse. Such requests are always honored by
+clipping, if necessary, portions that cannot be displayed at the right,
+bottom corner of the frame.
+
+
+@node Implied Frame Resizing
+@subsection Implied Frame Resizing
+@cindex implied frame resizing
+@cindex implied resizing of frame
+
+By default, Emacs tries to keep the number of lines and columns of a
+frame's text area unaltered when, for example, adding or removing the
+menu bar, changing the default font or setting the width of the frame's
+scroll bars. This means, however, that in such case Emacs must ask the
+window manager to resize the outer frame in order to accommodate the
+size change. Note that wrapping a menu or tool bar usually does not
+resize the frame's outer size, hence this will alter the number of
+displayed lines.
+
+ Occasionally, such @dfn{implied frame resizing} may be unwanted, for
+example, when the frame is maximized or made full-screen (where it's
+turned off by default). In other cases you can disable implied resizing
+with the following option:
+
+@defopt frame-inhibit-implied-resize
+If this option is @code{nil}, changing font, menu bar, tool bar,
+internal borders, fringes or scroll bars of a specific frame may
+implicitly resize the frame's display area in order to preserve the
+number of columns or lines the frame displays. If this option is
+non-@code{nil}, no implied resizing is done.
+
+The value of this option can be also be a list of frame parameters. In
+that case, implied resizing is inhibited when changing a parameter that
+appears in this list. The frame parameters currently handled by this
+option are: @code{font}, @code{font-backend},
+@code{internal-border-width}, @code{menu-bar-lines} and
+@code{tool-bar-lines}.
+
+Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height},
+@code{vertical-scroll-bars}, @code{horizontal-scroll-bars},
+@code{left-fringe} and @code{right-fringe} frame parameters is handled
+as if the frame contained just one live window. This means, for
+example, that removing vertical scroll bars on a frame containing
+several side by side windows will shrink the outer frame width by the
+width of one scroll bar provided this option is @code{nil} and keep it
+unchanged if this option is either @code{t} or a list containing
+@code{vertical-scroll-bars}.
+
+The default value is @code{'(tool-bar-lines)} for Lucid, Motif and
+Windows (which means that adding/removing a tool bar there does not
+change the outer frame height), @code{nil} on all other window systems
+including GTK+ (which means that changing any of the parameters listed
+above may change the size of the outer frame), and @code{t} otherwise
+(which means the outer frame size never changes implicitly when there's
+no window system support).
+
+Note that when a frame is not large enough to accommodate a change of
+any of the parameters listed above, Emacs may try to enlarge the frame
+even if this option is non-@code{nil}.
+@end defopt
+
+