martin/emacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Describe frame geometry and related functions in Elisp manual

Browse Source 
* 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'.
This commit is contained in:
Martin Rudalics
2015-08-20 18:09:24 +02:00
parent d13dc271e5
commit e68d43eb87
4 changed files with 792 additions and 411 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
doc/lispref/display.texi
View File

@@ -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

9
doc/lispref/elisp.texi
View File

@@ -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

889
doc/lispref/frames.texi
View File

@@ -80,6 +80,7 @@ for @code{framep} above.
@menu
* 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.
@@ -416,6 +417,545 @@ This function returns the attributes of the physical monitor
dominating (see above) @var{frame}, which defaults to the selected frame.
@end defun
@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 ``(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 non-minibuffer 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{non-minibuffer 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 x-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
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 ``fullscreen''.
@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 ``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 @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 fullscreen (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
@node Frame Parameters
@section Frame Parameters
@cindex frame parameters
@@ -438,7 +978,6 @@ frame transparency, the parameter @code{alpha} is also meaningful.
* 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.
@end menu
@@ -723,12 +1262,12 @@ pixel sizes of these character units (@pxref{Face Attributes}).
@table @code
@vindex height, a frame parameter
@item height
The height of the frame's text area (@pxref{Size and Position}), in
The height of the frame's text area (@pxref{Frame Geometry}), in
characters.
@vindex width, a frame parameter
@item width
The width of the frame's text area (@pxref{Size and Position}), in
The width of the frame's text area (@pxref{Frame Geometry}), in
characters.
@vindex user-size, a frame parameter
@@ -1183,309 +1722,6 @@ equivalent to the @code{:background} attribute of the
@end table
@node Size and Position
@subsection Frame Size and Position
@cindex size of frame
@cindex screen size
@cindex frame size
@cindex resize frame
You can read or change the size and position of a frame using the frame
parameters @code{left}, @code{top}, @code{height}, and @code{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.
Most of the functions described below use a @var{frame} argument which
has to specify a live frame. If omitted or @code{nil}, it specifies the
selected frame, see @ref{Input Focus}.
@defun set-frame-position frame left top
This function sets the position of the top left corner of @var{frame} to
@var{left} and @var{top}. These arguments are measured in pixels, and
normally count from the top left corner of the screen to the top left
corner of the rectangle allotted to the frame by the window manager.
Negative parameter values position the bottom edge of that rectangle up
from the bottom edge of the screen, or the right rectangle 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.
@end defun
@cindex frame default font
@cindex default font of a frame
Each frame has a @dfn{default font} which specifies the canonical height
and width of a character on that frame. The default font is used when
retrieving or changing the size of a frame in terms of columns or lines.
It is also used when resizing (@pxref{Window Sizes}) or splitting
(@pxref{Splitting Windows}) windows.
@defun frame-char-height &optional frame
@defunx frame-char-width &optional frame
These functions return the canonical 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 below 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
graphical frames.
@end deffn
@cindex frame display area
@cindex display area of a frame
The @dfn{display area} of a frame is a rectangular area within the area
allotted to the frame by the window manager. The display area neither
includes the title bar (@pxref{Frame Titles}) nor any other decorations
provided by the window manager (like an external border used for
resizing frames via mouse dragging).
The actual height of the display area depends on the window-system
and toolkit in use. With GTK+, the display area does not include any
tool bar or menu bar. With the Motif or Lucid toolkits and with
Windows, the display area 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. On a text terminal, the display area includes the menu
bar.
@defun frame-pixel-height &optional frame
@defunx frame-pixel-width &optional frame
These functions return the height and width of the display area of
@var{frame}, measured in pixels. For a text terminal, the results are
in characters rather than pixels.
@end defun
@cindex frame text area
@cindex text area of a frame
The @dfn{text area} of a frame is a concept implicitly used by all
functions that change a frame's height or width. It is a rectangle
located within the display area. Its size is obtained from that of the
display area by subtracting the sizes of any tool or menu bars that are
part of the display area, 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}.
@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}, 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 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}. 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 pixles is not a multiple of
its default font size, the values returned by this 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}. If this is non-@code{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 @code{nil} for this option depends
on the toolkit used. Dragging the frame border with the mouse is usually
done character-wise. 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 ``fullscreen''.
@end defopt
@defun set-frame-size frame width height pixelwise
This function sets the size of the text area of @var{frame}, measured in
characters; @var{width} and @var{height} specify the new width in
columns and the new height in lines.
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 ``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 @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.
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 a 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 display area of the frame in order to
accommodate the size change. Note that wrapping a menu or tool bar
usually does not resize the frame's display area, hence this will alter
the number of displayed lines.
Occasionally, such implied resizing of the display area may be
unwanted, for example, when the frame is maximized or made fullscreen
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 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 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 frame), and @code{t} otherwise (which
means the 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
@c FIXME? Belongs more in Emacs manual than here?
@c But, e.g., fit-window-to-buffer is in this manual.
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
@node Geometry
@subsection Geometry
@@ -2088,8 +2324,10 @@ give access to the current position of the mouse.
@defun mouse-position
This function returns a description of the position of the mouse. The
value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
and @var{y} are integers giving the position in characters relative to
the top left corner of the inside of @var{frame}.
and @var{y} are integers giving the (possibly rounded) position in
multiples of the default character size of @var{frame} (@pxref{Frame
Font}) relative to the native position of @var{frame} (@pxref{Frame
Geometry}).
@end defun
@defvar mouse-position-function
@@ -2105,9 +2343,13 @@ This abnormal hook exists for the benefit of packages like
@defun set-mouse-position frame x y
This function @dfn{warps the mouse} to position @var{x}, @var{y} in
frame @var{frame}. The arguments @var{x} and @var{y} are integers,
giving the position in characters relative to the top left corner of the
inside of @var{frame}. If @var{frame} is not visible, this function
does nothing. The return value is not significant.
giving the position in multiples of the default character size of
@var{frame} (@pxref{Frame Font}) relative to the native position of
@var{frame} (@pxref{Frame Geometry}).
The resulting mouse position is constrained to the native frame of
@var{frame}. If @var{frame} is not visible, this function does nothing.
The return value is not significant.
@end defun
@defun mouse-pixel-position
@@ -2118,12 +2360,31 @@ coordinates in units of pixels rather than units of characters.
@defun set-mouse-pixel-position frame x y
This function warps the mouse like @code{set-mouse-position} except that
@var{x} and @var{y} are in units of pixels rather than units of
characters. These coordinates are not required to be within the frame.
characters.
If @var{frame} is not visible, this function does nothing. The return
value is not significant.
The resulting mouse position is not constrained to the native frame of
@var{frame}. If @var{frame} is not visible, this function does nothing.
The return value is not significant.
@end defun
On a graphical terminal the following two functions allow to retrieve
and set the absolute position of the mouse cursor.
@defun x-mouse-absolute-pixel-position
This function returns a cons cell (@var{x} . @var{y}) of the coordinates
of the mouse cursor position in pixels, relative to a position (0, 0) of
the selected frame's display.
@end defun
@defun x-set-mouse-absolute-pixel-position x y
This function moves the mouse cursor to the position (@var{x}, @var{y}).
The coordinates @var{x} and @var{y} are interpreted in pixels relative
to a position (0, 0) of the selected frame's display.
@end defun
The following function can tell whether the mouse cursor is currently
visible on a frame:
@defun frame-pointer-visible-p &optional frame
This predicate function returns non-@code{nil} if the mouse pointer
displayed on @var{frame} is visible; otherwise it returns @code{nil}.

276
doc/lispref/windows.texi
View File

@@ -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.
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.
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.
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
@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.
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-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.
@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 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 Y coordinate of the topmost row of
@var{window}, equivalent to the @var{top} entry in the list returned
by @code{window-edges}.
@end defun
@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 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.
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.
@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.
@end defun
The following functions return window positions in pixels, relative
to the display screen rather than 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.
@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.
@var{window}. Calling @code{(window-pixel-edges window)} is equivalent
to calling @code{(window-edges window nil nil t)}, see above.
@end defun
@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}.
@var{window} must be a valid window and defaults to the selected one.
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-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.
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 origin of the display screen rather than that of the frame:
@defun window-absolute-pixel-edges &optional window
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-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.
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
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