elisp: Size and Position
28.3.3 Size and Position
------------------------
You can read or change the position of a frame using the frame
parameters ‘left’ and ‘top’ (
Position Parameters) and its size
using the ‘height’ and ‘width’ parameters (Size Parameters).
Here are some special features for working with sizes and positions.
For all of these functions the argument FRAME must denote a live frame
and defaults to the selected frame.
-- Function: frame-position &optional frame
This function returns the outer position (Frame Layout) of
FRAME in pixels. The value is a cons giving the coordinates of the
top left corner of the outer frame of FRAME relative to an origin
at the position (0, 0) of the frame’s display. On a text terminal
frame both values are zero.
-- Function: set-frame-position frame x y
This function sets the outer frame position of FRAME to X and Y.
The latter arguments specify pixels and normally count from an
origin at the position (0, 0) of FRAME’s display.
A negative parameter value positions the right edge of the outer
frame by -X pixels left from the right edge of the screen or the
bottom edge by -Y pixels up from the bottom edge of the screen.
This function has no effect on text terminal frames.
-- Function: frame-pixel-height &optional frame
-- Function: frame-pixel-width &optional frame
These functions return the inner height and width (the height and
width of the display area, see Frame Layout) of FRAME in
pixels. For a text terminal, the results are in characters rather
than pixels.
-- Function: frame-text-height &optional frame
-- Function: frame-text-width &optional frame
These functions return the height and width of the text area of
FRAME (Frame Layout), measured in pixels. For a text
terminal, the results are in characters rather than pixels.
The value returned by ‘frame-text-height’ differs from that
returned by ‘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 ‘frame-text-width’ differs from that returned
by ‘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.
-- Function: frame-height &optional frame
-- Function: frame-width &optional frame
These functions return the height and width of the text area of
FRAME, measured in units of the default font height and width of
FRAME (Frame Font). These functions are plain shorthands
for writing ‘(frame-parameter frame 'height)’ and ‘(frame-parameter
frame 'width)’.
If the text area of 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.
-- 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’ whenever the frame is resized. If this is
non-‘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 ‘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 ‘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 full-screen.
-- Function: set-frame-size frame width height &optional pixelwise
This function sets the size of the text area of FRAME, measured in
terms of the canonical height and width of a character on FRAME
(Frame Font).
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 the text area of 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
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 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 the text area 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.
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.
Info Catalog
elisp: Frame Font
elisp: Frame Geometry
elisp: Implied Frame Resizing