Commit e68d43eb authored by Martin Rudalics's avatar Martin Rudalics
Browse files

Describe frame geometry and related functions in Elisp manual

* doc/lispref/display.texi (Size of Displayed Text, Line Height)
(Showing Images): Update references.
* doc/lispref/elisp.texi (Top): Update node listing.
* doc/lispref/frames.texi (Frame Geometry): New node.  Move
`Size and Position' section here.
(Size Parameters): Update references.
(Mouse Position): Update references and nomenclature.  Describe
new functions `x-mouse-absolute-pixel-position' and
`x-set-mouse-absolute-pixel-position'.
* doc/lispref/windows.texi (Window Sizes): Update references.
(Resizing Windows): Update references.  Move description of
`fit-frame-to-buffer' here.
(Coordinates and Windows): Update nomenclature and references.
Describe new arguments of `window-edges'.  Comment out
descriptions of `window-left-column', `window-top-line',
`window-pixel-left' and `window-pixel-top'.  Describe
`window-absolute-pixel-position'.
parent d13dc271
......@@ -1897,9 +1897,9 @@ to or less than the display width of @var{ellipsis}. If
The following function returns the size in pixels of text as if it were
displayed in a given window. This function is used by
@code{fit-window-to-buffer} (@pxref{Resizing Windows}) and
@code{fit-frame-to-buffer} (@pxref{Size and Position}) to make a window
exactly as large as the text it contains.
@code{fit-window-to-buffer} and @code{fit-frame-to-buffer}
(@pxref{Resizing Windows}) to make a window exactly as large as the text
it contains.
@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line
This function returns the size of the text of @var{window}'s buffer in
......@@ -1952,12 +1952,12 @@ height of both, if present, in the return value.
contents of the line, plus optional additional vertical line spacing
above or below the display line.
The height of the line contents is the maximum height of any
character or image on that display line, including the final newline
if there is one. (A display line that is continued doesn't include a
final newline.) That is the default line height, if you do nothing to
specify a greater height. (In the most common case, this equals the
height of the default frame font.)
The height of the line contents is the maximum height of any character
or image on that display line, including the final newline if there is
one. (A display line that is continued doesn't include a final
newline.) That is the default line height, if you do nothing to specify
a greater height. (In the most common case, this equals the height of
the corresponding frame's default font, see @ref{Frame Font}.)
There are several ways to explicitly specify a larger line height,
either by specifying an absolute height for the display line, or by
......@@ -5406,12 +5406,11 @@ This removes only images that were put into @var{buffer} the way
@cindex size of image
This function returns the size of an image as a pair
@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
specification. @var{pixels} non-@code{nil} means return sizes
measured in pixels, otherwise return sizes measured in canonical
character units (fractions of the width/height of the frame's default
font). @var{frame} is the frame on which the image will be displayed.
@var{frame} null or omitted means use the selected frame (@pxref{Input
Focus}).
specification. @var{pixels} non-@code{nil} means return sizes measured
in pixels, otherwise return sizes measured in the default character size
of @var{frame} (@pxref{Frame Font}). @var{frame} is the frame on which
the image will be displayed. @var{frame} null or omitted means use the
selected frame (@pxref{Input Focus}).
@end defun
@defvar max-image-size
......
......@@ -1041,6 +1041,7 @@ Frames
* Creating Frames:: Creating additional frames.
* Multiple Terminals:: Displaying on several different devices.
* Frame Geometry:: Geometric properties of frames.
* Frame Parameters:: Controlling frame size, position, font, etc.
* Terminal Parameters:: Parameters common for all frames on terminal.
* Frame Titles:: Automatic updating of frame titles.
......@@ -1064,12 +1065,18 @@ Frames
* Resources:: Getting resource values from the server.
* Display Feature Testing:: Determining the features of a terminal.
Frame Geometry
* 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.
Frame Parameters
* Parameter Access:: How to change a frame's parameters.
* Initial Parameters:: Specifying frame parameters when you make a frame.
* Window Frame Parameters:: List of frame parameters for window systems.
* Size and Position:: Changing the size and position of a frame.
* Geometry:: Parsing geometry specifications.
Window Frame Parameters
......
This diff is collapsed.
......@@ -432,8 +432,8 @@ specified either in units of pixels or in units of lines and columns.
On a graphical display, the latter actually correspond to the height and
width of a ``default'' character specified by the frame's default font
as returned by @code{frame-char-height} and @code{frame-char-width}
(@pxref{Size and Position}). Thus, if a window is displaying text with
a different font or size, the reported line height and column width for
(@pxref{Frame Font}). Thus, if a window is displaying text with a
different font or size, the reported line height and column width for
that window may differ from the actual number of text lines or columns
displayed within it.
......@@ -791,8 +791,8 @@ If the value of this option is non-@code{nil}, Emacs resizes windows in
units of pixels. This currently affects functions like
@code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
@code{minimize-window}, @code{fit-window-to-buffer},
@code{shrink-window-if-larger-than-buffer} (all listed below) and
@code{fit-frame-to-buffer} (@pxref{Size and Position}).
@code{fit-frame-to-buffer} and
@code{shrink-window-if-larger-than-buffer} (all listed below).
Note that when a frame's pixel size is not a multiple of its character
size, at least one window may get resized pixelwise even if this
......@@ -836,8 +836,7 @@ resize operations (@pxref{Preserving Window Sizes}).
If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil},
this function will try to resize the frame of @var{window} to fit its
contents by calling @code{fit-frame-to-buffer} (@pxref{Size and
Position}).
contents by calling @code{fit-frame-to-buffer} (see below).
@end deffn
@defopt fit-window-to-buffer-horizontally
......@@ -858,6 +857,47 @@ live window and this option is non-@code{nil}. If this is
non-@code{nil} value means frames can be resized in both dimensions.
@end defopt
If you have a frame that displays only one window, you can fit that
frame to its buffer using the command @code{fit-frame-to-buffer}.
@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
This command adjusts the size of @var{frame} to display the contents of
its buffer exactly. @var{frame} can be any live frame and defaults to
the selected one. Fitting is done only if @var{frame}'s root window is
live. The arguments @var{max-height}, @var{min-height}, @var{max-width}
and @var{min-width} specify bounds on the new total size of
@var{frame}'s root window. @var{min-height} and @var{min-width} default
to the values of @code{window-min-height} and @code{window-min-width}
respectively.
If the optional argument @var{only} is @code{vertically}, this function
may resize the frame vertically only. If @var{only} is
@code{horizontally}, it may resize the frame horizontally only.
@end deffn
The behavior of @code{fit-frame-to-buffer} can be controlled with the
help of the two options listed next.
@defopt fit-frame-to-buffer-margins
This option can be used to specify margins around frames to be fit by
@code{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
@code{nil} for each which means to use no margins. The value specified
here can be overridden for a specific frame by that frame's
@code{fit-frame-to-buffer-margins} parameter, if present.
@end defopt
@defopt fit-frame-to-buffer-sizes
This option specifies size boundaries for @code{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-@code{nil}, it overrides the corresponding
argument of @code{fit-frame-to-buffer}.
@end defopt
@deffn Command shrink-window-if-larger-than-buffer &optional window
This command attempts to reduce @var{window}'s height as much as
possible while still showing its full buffer, but no less than
......@@ -3622,33 +3662,28 @@ is off the screen due to horizontal scrolling:
@end group
@end example
@node Coordinates and Windows
@section Coordinates and Windows
@cindex frame-relative coordinate
@cindex coordinate, relative to frame
@cindex window position
This section describes functions that report the position of a
window. Most of these functions report positions relative to the
window's frame. In this case, the coordinate origin @samp{(0,0)} lies
near the upper left corner of the frame. For technical reasons, on
graphical displays the origin is not located at the exact corner of
the graphical window as it appears on the screen. If Emacs is built
with the GTK+ toolkit, the origin is at the upper left corner of the
frame area used for displaying Emacs windows, below the title-bar,
GTK+ menu bar, and tool bar (since these are drawn by the window
manager and/or GTK+, not by Emacs). But if Emacs is not built with
GTK+, the origin is at the upper left corner of the tool bar (since in
this case Emacs itself draws the tool bar). In both cases, the X and
Y coordinates increase rightward and downward respectively.
Except where noted, X and Y coordinates are reported in integer
character units, i.e., numbers of lines and columns respectively. On a
graphical display, each ``line'' and ``column'' corresponds to the
height and width of a default character specified by the frame's
default font.
@defun window-edges &optional window
This section describes functions that report the position of a window.
Most of these functions report positions relative to an origin at the
native position of the window's frame (@pxref{Frame Geometry}). Some
functions report positions relative to the origin of the display of the
window's frame. In any case, the origin has the coordinates (0, 0) and
X and Y coordinates increase ``rightward'' and ``downward''
respectively.
For the following functions, X and Y coordinates are reported in
integer character units, i.e., numbers of lines and columns
respectively. On a graphical display, each ``line'' and ``column''
corresponds to the height and width of a default character specified by
the frame's default font (@pxref{Frame Font}).
@defun window-edges &optional window body absolute pixelwise
This function returns a list of the edge coordinates of @var{window}.
If @var{window} is omitted or @code{nil}, it defaults to the selected
window.
......@@ -3665,44 +3700,73 @@ header line, mode line, scroll bar, fringes, window divider and display
margins. On a text terminal, if the window has a neighbor on its right,
its right edge includes the separator line between the window and its
neighbor.
@end defun
@defun window-inside-edges &optional window
This function is similar to @code{window-edges}, but the returned edge
values are for the text area of the window. They exclude any header
line, mode line, scroll bar, fringes, window divider, display margins,
and vertical separator.
If the optional argument @var{body} is @code{nil}, this means to
return the edges corresponding to the total size of @var{window}.
@var{body} non-@code{nil} means to return the edges of @var{window}'s
body (aka text area). If @var{body} is non-@code{nil}, @var{window}
must specify a live window.
If the optional argument @var{absolute} is @code{nil}, this means to
return edges relative to the native position of @var{window}'s frame.
@var{absolute} non-@code{nil} means to return coordinates relative to
the origin (0, 0) of @var{window}'s display. On non-graphical systems
this argument has no effect.
If the optional argument @var{pixelwise} is @code{nil}, this means to
return the coordinates in terms of the default character width and
height of @var{window}'s frame (@pxref{Frame Font}), rounded if
necessary. @var{pixelwise} non-@code{nil} means to return the
coordinates in pixels. Note that the pixel specified by @var{right} and
@var{bottom} is immediately outside of these edges. If @var{absolute}
is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too.
@end defun
@defun window-top-line &optional window
This function returns the Y coordinate of the topmost row of
@var{window}, equivalent to the @var{top} entry in the list returned
by @code{window-edges}.
@defun window-body-edges &optional window
This function returns the edges of @var{window}'s body (@pxref{Window
Sizes}). Calling @code{(window-body-edges window)} is equivalent to
calling @code{(window-edges window t)}, see above.
@end defun
@comment The following two functions are confusing and hardly used.
@ignore
@defun window-left-column &optional window
This function returns the X coordinate of the leftmost column of
@var{window}, equivalent to the @var{left} entry in the list returned
by @code{window-edges}.
This function returns the leftmost column of @var{window}. This value
equals the @var{left} entry in the list returned by @code{(window-edges
window)} minus the number of columns occupied by the internal border of
@var{window}'s frame.
@end defun
@defun window-top-line &optional window
This function returns the topmost row of @var{window}. This value is
equal to the @var{top} entry in the list returned by @code{(window-edges
window)} minus the number of lines occupied by the internal border of
@var{window}'s frame.
@end defun
@end ignore
The following functions can be used to relate a set of
frame-relative coordinates to a window:
@defun window-at x y &optional frame
This function returns the live window at the frame-relative
coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no
window at that position, the return value is @code{nil}. If
@var{frame} is omitted or @code{nil}, it defaults to the selected
This function returns the live window at the coordinates @var{x} and
@var{y} given in default character sizes (@pxref{Frame Font}) relative
to the native position of @var{frame} (@pxref{Frame Geometry}).
If there is no window at that position, the return value is @code{nil}.
If @var{frame} is omitted or @code{nil}, it defaults to the selected
frame.
@end defun
@defun coordinates-in-window-p coordinates window
This function checks whether a window @var{window} occupies the
frame-relative coordinates @var{coordinates}, and if so, which part of
the window that is. @var{window} should be a live window.
This function checks whether a window @var{window} occupies the frame
relative coordinates @var{coordinates}, and if so, which part of the
window that is. @var{window} should be a live window.
@var{coordinates} should be a cons cell of the form @code{(@var{x}
. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
. @var{y})}, where @var{x} and @var{y} are given in default character
sizes (@pxref{Frame Font}) relative to the native position of
@var{window}'s frame (@pxref{Frame Geometry}).
If there is no window at the specified position, the return value is
@code{nil} . Otherwise, the return value is one of the following:
......@@ -3757,46 +3821,96 @@ each text character is taken to be ``one pixel''.
@defun window-pixel-edges &optional window
This function returns a list of pixel coordinates for the edges of
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
to the selected window.
@var{window}. Calling @code{(window-pixel-edges window)} is equivalent
to calling @code{(window-edges window nil nil t)}, see above.
@end defun
The return value has the form @code{(@var{left} @var{top} @var{right}
@var{bottom})}. The list elements are, respectively, the X pixel
coordinate of the left window edge, the Y pixel coordinate of the top
edge, one more than the X pixel coordinate of the right edge, and one
more than the Y pixel coordinate of the bottom edge.
@comment The following two functions are confusing and hardly used.
@ignore
@defun window-pixel-left &optional window
This function returns the left pixel edge of window @var{window}. This
value equals the @var{left} entry in the list returned by
@code{(window-pixel-edges window)} minus the number of pixels occupied
by the internal border of @var{window}'s frame. @var{window} must be a
valid window and defaults to the selected one.
@end defun
@defun window-inside-pixel-edges &optional window
This function is like @code{window-pixel-edges}, except that it
returns the pixel coordinates for the edges of the window's text area,
rather than the pixel coordinates for the edges of the window itself.
@var{window} must specify a live window.
@defun window-pixel-top &optional window
This function returns the top pixel edge of window @var{window}. This
value is equal to the @var{top} entry in the list returned by
@code{(window-pixel-edges window)} minus the number of pixels occupied
by the internal border of @var{window}'s frame. @var{window} must be a
valid window and defaults to the selected one.
@end defun
@end ignore
@defun window-body-pixel-edges &optional window
This function returns the pixel edges of @var{window}'s body. Calling
@code{(window-body-pixel-edges window)} is equivalent to calling
@code{(window-edges window t nil t)}, see above.
@end defun
The following functions return window positions in pixels, relative
to the display screen rather than the frame:
The following functions return window positions in pixels, relative to
the origin of the display screen rather than that of the frame:
@defun window-absolute-pixel-edges &optional window
This function is like @code{window-pixel-edges}, except that it
returns the edge pixel coordinates relative to the top left corner of
the display screen.
This function returns the pixel coordinates of @var{WINDOW} relative to
an origin at (0, 0) of the display of @var{window}'s frame. Calling
@code{(window-absolute-pixel-edges)} is equivalent to calling
@code{(window-edges window nil t t)}, see above.
@end defun
@defun window-inside-absolute-pixel-edges &optional window
This function is like @code{window-inside-pixel-edges}, except that it
returns the edge pixel coordinates relative to the top left corner of
the display screen. @var{window} must specify a live window.
@end defun
@defun window-absolute-body-pixel-edges &optional window
This function returns the pixel coordinates of @var{WINDOW}'s body
relative to an origin at (0, 0) of the display of @var{window}'s frame.
Calling @code{(window-absolute-body-pixel-edges window)} is equivalent
to calling @code{(window-edges window t t t)}, see above.
@defun window-pixel-left &optional window
This function returns the left pixel edge of window @var{window}.
@var{window} must be a valid window and defaults to the selected one.
Combined with @code{x-set-mouse-absolute-pixel-position}, this function
can be used to move the mouse pointer to an arbitrary buffer position
visible in some window:
@example
@group
(let ((edges (window-absolute-body-pixel-edges))
(position (pos-visible-in-window-p nil nil t)))
(x-set-mouse-absolute-pixel-position
(+ (nth 0 edges) (nth 0 position))
(+ (nth 1 edges) (nth 1 position))))
@end group
@end example
On a graphical terminal this form ``warps'' the mouse cursor to the
upper left corner of the glyph at the selected window's point. A
position calculated this way can be also used to show a tooltip window
there.
@end defun
@defun window-pixel-top &optional window
This function returns the top pixel edge of window @var{window}.
@var{window} must be a valid window and defaults to the selected one.
The following function returns the screen coordinates of a buffer
position visible in a window:
@defun window-absolute-pixel-position &optional position window
If the buffer position @var{position} is visible in window @var{window},
this function returns the display coordinates of the upper/left corner
of the glyph at @var{position}. The return value is a cons of the X-
and Y-coordinates of that corner, relative to an origin at (0, 0) of
@var{window}'s display. It returns @code{nil} if @var{position} is not
visible in @var{window}.
@var{window} must be a live window and defaults to the selected
window. @var{position} defaults to the value of @code{window-point}
of @var{window}.
This means that in order to move the mouse pointer to the position of
point in the selected window, it's sufficient to write:
@example
@group
(let ((position (window-absolute-pixel-position)))
(x-set-mouse-absolute-pixel-position
(car position) (cdr position)))
@end group
@end example
@end defun
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment