@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.
emacs, The GNU Emacs Manual}). Emacs can connect to other X displays
via the command @code{make-frame-on-display}. Each X display has its
own selected frame and its own minibuffer windows; however, only one
-of those frames is ``@emph{the} selected frame'' at any given moment
+of those frames is @emph{the} selected frame at any given moment
(@pxref{Input Focus}). Emacs can even connect to other text
terminals, by interacting with the @command{emacsclient} program.
@xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
the other frame parameters from the alist @var{parameters}.
@var{display} should be the name of an X display (a string).
-Before creating the frame, this function ensures that Emacs is ``set
-up'' to display graphics. For instance, if Emacs has not processed X
+Before creating the frame, this function ensures that Emacs is set
+up to display graphics. For instance, if Emacs has not processed X
resources (e.g., if it was started on a text terminal), it does so at
this time. In all other respects, this function behaves like
@code{make-frame} (@pxref{Creating Frames}).
@end defun
@cindex multi-monitor
- On some ``multi-monitor'' setups, a single X display outputs to more
+ On some multi-monitor setups, a single X display outputs to more
than one physical monitor. You can use the functions
@code{display-monitor-attributes-list} and @code{frame-monitor-attributes}
to obtain information about such setups.
coordinates might be negative.
@item workarea
-Position of the top-left corner and size of the work area (``usable''
+Position of the top-left corner and size of the work area (usable
space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}.
This may be different from @samp{geometry} in that space occupied by
-various window manager features (docks, taskbars, etc.) may be
+various window manager features (docks, taskbars, etc.)@: may be
excluded from the work area. Whether or not such features actually
subtract from the work area depends on the platform and environment.
Again, if the monitor is not the primary monitor, some of the
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 @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
+
+
@node Frame Parameters
@section Frame Parameters
@cindex 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.
@end menu
@end defun
@defun modify-frame-parameters frame alist
-This function alters the parameters of frame @var{frame} based on the
-elements of @var{alist}. Each element of @var{alist} has the form
-@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
-parameter. If you don't mention a parameter in @var{alist}, its value
-doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
-frame.
+This function alters the frame @var{frame} based on the elements of
+@var{alist}. Each element of @var{alist} has the form
+@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming
+a parameter. If you don't mention a parameter in @var{alist}, its
+value doesn't change. If @var{frame} is @code{nil}, it defaults to
+the selected frame.
+
+Some parameters are only meaningful for frames on certain kinds of
+display (@pxref{Frames}). If @var{alist} includes parameters that are
+not meaningful for the @var{frame}'s display, this function will
+change its value in the frame's parameter list, but will otherwise
+ignore it.
+
+When @var{alist} specifies more than one parameter whose value can
+affect the new size of @var{frame}, the final size of the frame may
+differ according to the toolkit used. For example, specifying that a
+frame should from now on have a menu and/or tool bar instead of none and
+simultaneously specifying the new height of the frame will inevitably
+lead to a recalculation of the frame's height. Conceptually, in such
+case, this function will try to have the explicit height specification
+prevail. It cannot be excluded, however, that the addition (or removal)
+of the menu or tool bar, when eventually performed by the toolkit, will
+defeat this intention.
+
+Sometimes, binding @code{frame-inhibit-implied-resize} (@pxref{Implied
+Frame Resizing}) to a non-@code{nil} value around calls to this function
+may fix the problem sketched here. Sometimes, however, exactly such
+binding may be hit by the problem.
@end defun
@defun set-frame-parameter frame parm value
This function sets the frame parameter @var{parm} to the specified
-@var{value}. If @var{frame} is @code{nil}, it defaults to the
-selected frame.
+@var{value}. If @var{frame} is @code{nil}, it defaults to the selected
+frame.
@end defun
@defun modify-all-frames-parameters alist
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.
+If the window manager refuses to align a frame at the left or top screen
+edge, combining position notation and @code{user-position} as in
+
+@example
+(modify-frame-parameters
+ nil '((user-position . t) (left . (+ -4))))
+@end example
+
+may help to override that.
+
@vindex top, a frame parameter
@item top
The screen position of the top (or bottom) edge, in pixels, with respect
@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
user-position}) does for the position parameters @code{top} and
@code{left}.
-@cindex full-screen frames
+@cindex fullboth frames
+@cindex fullheight frames
+@cindex fullwidth frames
+@cindex maximized frames
@vindex fullscreen, a frame parameter
@item fullscreen
-Specify that width, height or both shall be maximized. The value
-@code{fullwidth} specifies that width shall be as wide as possible. The
-value @code{fullheight} specifies that height shall be as tall as
-possible. The value @code{fullboth} specifies that both the width and
-the height shall be set to the size of the screen. The value
-@code{maximized} specifies that the frame shall be maximized.
-
-The difference between @code{maximized} and @code{fullboth} is that a
-maximized frame usually keeps its title bar and the buttons for resizing
+This parameter specifies whether to maximize the frame's width, height
+or both. Its value can be @code{fullwidth}, @code{fullheight},
+@code{fullboth}, or @code{maximized}. A @dfn{fullwidth} frame is as
+wide as possible, a @dfn{fullheight} frame is as tall as possible, and
+a @dfn{fullboth} frame is both as wide and as tall as possible. A
+@dfn{maximized} frame is like a ``fullboth'' frame, except that it usually
+keeps its title bar and the buttons for resizing
and closing the frame. Also, maximized frames typically avoid hiding
-any task bar or panels displayed on the desktop. ``Fullboth'' frames,
-on the other hand, usually omit the title bar and occupy the entire
+any task bar or panels displayed on the desktop. A ``fullboth'' frame,
+on the other hand, usually omits the title bar and occupies the entire
available screen space.
-``Fullheight'' and ``fullwidth'' frames are more similar to maximized
+Full-height and full-width frames are more similar to maximized
frames in this regard. However, these typically display an external
border which might be absent with maximized frames. Hence the heights
-of maximized and fullheight frames and the widths of maximized and
-fullwidth frames often differ by a few pixels.
+of maximized and full-height frames and the widths of maximized and
+full-width frames often differ by a few pixels.
With some window managers you may have to customize the variable
@code{frame-resize-pixelwise} (@pxref{Size and Position}) in order to
-make a frame truly appear ``maximized'' or ``fullscreen''. Moreover,
+make a frame truly appear maximized or full-screen. Moreover,
some window managers might not support smooth transition between the
-various fullscreen or maximization states. Customizing the variable
+various full-screen or maximization states. Customizing the variable
@code{x-frame-normalize-before-maximize} can help to overcome that.
@vindex fullscreen-restore, a frame parameter
@item fullscreen-restore
-This parameter specifies the desired ``fullscreen'' state of the frame
+This parameter specifies the desired fullscreen state of the frame
after invoking the @code{toggle-frame-fullscreen} command (@pxref{Frame
Commands,,, emacs, The GNU Emacs Manual}) in the ``fullboth'' state.
Normally this parameter is installed automatically by that command when
toggling the state to fullboth. If, however, you start Emacs in the
-fullboth state, you have to specify the desired behavior in your initial
+``fullboth'' state, you have to specify the desired behavior in your initial
file as, for example
@example
becomes hollow box, and bar becomes a narrower bar).
@end defopt
+@defopt x-stretch-cursor
+This variable controls the width of the block cursor displayed on
+extra-wide glyphs such as a tab or a stretch of white space. By
+default, the block cursor is only as wide as the font's default
+character, and will not cover all of the width of the glyph under it
+if that glyph is extra-wide. A non-@code{nil} value of this variable
+means draw the block cursor as wide as the glyph under it. The
+default value is @code{nil}.
+
+This variable has no effect on text-mode frames, since the text-mode
+cursor is drawn by the terminal out of Emacs's control.
+@end defopt
+
@defopt blink-cursor-alist
This variable specifies how to blink the cursor. Each element has the
form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
type equals @var{on-state} (comparing using @code{equal}), the
corresponding @var{off-state} specifies what the cursor looks like
-when it blinks ``off''. Both @var{on-state} and @var{off-state}
+when it blinks off. Both @var{on-state} and @var{off-state}
should be suitable values for the @code{cursor-type} frame parameter.
There are various defaults for how to blink each type of cursor, if
@vindex screen-gamma, a frame parameter
@item screen-gamma
@cindex gamma correction
-If this is a number, Emacs performs ``gamma correction'' which adjusts
+If this is a number, Emacs performs gamma correction which adjusts
the brightness of all colors. The value should be the screen gamma of
your display.
@code{frame-alpha-lower-limit} is 20.
The @code{alpha} frame parameter can also be a cons cell
-@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
-opacity of the frame when it is selected, and @samp{inactive} is the
+@code{(@var{active} . @var{inactive})}, where @var{active} is the
+opacity of the frame when it is selected, and @var{inactive} is the
opacity when it is not selected.
@end table
@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
@end defun
@defun set-terminal-parameter terminal parameter value
-This function sets the parameter @var{parm} of @var{terminal} to the
+This function sets the parameter @var{parameter} of @var{terminal} to the
specified @var{value}, and returns the previous value of that
parameter.
@end defun
function gets one argument, @var{frame}). By default, @var{frame} is
the selected frame.
-A frame cannot be deleted if its minibuffer is used by other frames.
+A frame cannot be deleted as long as its minibuffer serves as surrogate
+minibuffer for another frame (@pxref{Minibuffers and Frames}).
Normally, you cannot delete a frame if all other frames are invisible,
but if @var{force} is non-@code{nil}, then you are allowed to do so.
@end deffn
@defun visible-frame-list
This function returns a list of just the currently visible frames.
@xref{Visibility of Frames}. Frames on text terminals always count as
-``visible'', even though only the selected one is actually displayed.
+visible, even though only the selected one is actually displayed.
@end defun
@defun next-frame &optional frame minibuf
This function lets you cycle conveniently through all the frames on
the current display from an arbitrary starting point. It returns the
-``next'' frame after @var{frame} in the cycle. If @var{frame} is
+next frame after @var{frame} in the cycle. If @var{frame} is
omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
Focus}).
minibuffer-window}).
@cindex frame without a minibuffer
-However, you can also create a frame with no minibuffer. Such a frame
-must use the minibuffer window of some other frame. When you create the
-frame, you can explicitly specify the minibuffer window to use (in some
-other frame). If you don't, then the minibuffer is found in the frame
-which is the value of the variable @code{default-minibuffer-frame}. Its
-value should be a frame that does have a minibuffer.
+@cindex surrogate minibuffer frame
+However, you can also create a frame without a minibuffer. Such a frame
+must use the minibuffer window of some other frame. That other frame
+will serve as @dfn{surrogate minibuffer frame} for this frame and cannot
+be deleted via @code{delete-frame} (@pxref{Deleting Frames}) as long as
+this frame is live.
+
+When you create the frame, you can explicitly specify the minibuffer
+window to use (in some other frame). If you don't, then the minibuffer
+is found in the frame which is the value of the variable
+@code{default-minibuffer-frame}. Its value should be a frame that does
+have a minibuffer.
If you use a minibuffer-only frame, you might want that frame to raise
when you enter the minibuffer. If so, set the variable
When Emacs displays its frames on several terminals (@pxref{Multiple
Terminals}), each terminal has its own selected frame. But only one
-of these is ``@emph{the} selected frame'': it's the frame that belongs
+of these is @emph{the} selected frame: it's the frame that belongs
to the terminal from which the most recent input came. That is, when
Emacs runs a command that came from a certain terminal, the selected
frame is the one of that terminal. Since Emacs runs only a single
explicitly switch to a different frame from a Lisp function, call
@code{select-frame-set-input-focus}.
-Lisp programs can also switch frames ``temporarily'' by calling the
+Lisp programs can also switch frames temporarily by calling the
function @code{select-frame}. This does not alter the window system's
concept of focus; rather, it escapes from the window manager's control
until that control is somehow reasserted.
value is @code{t} if @var{frame} is visible, @code{nil} if it is
invisible, and @code{icon} if it is iconified.
-On a text terminal, all frames are considered ``visible'' for the
+On a text terminal, all frames are considered visible for the
purposes of this function, even though only one frame is displayed.
@xref{Raising and Lowering}.
@end defun
You should design @var{body} to return when it sees the up-event that
indicates the release of the button, or whatever kind of event means
it is time to stop tracking.
+
+The @code{track-mouse} form causes Emacs to generate mouse motion
+events by binding the variable @code{track-mouse} to a
+non-@code{nil} value. If that variable has the special value
+@code{dragging}, it additionally instructs the display engine to
+refrain from changing the shape of the mouse pointer. This is
+desirable in Lisp programs that require mouse dragging across large
+portions of Emacs display, which might otherwise cause the mouse
+pointer to change its shape according to the display portion it hovers
+on (@pxref{Pointer Shape}). Therefore, Lisp programs that need the
+mouse pointer to retain its original shape during dragging should bind
+@code{track-mouse} to the value @code{dragging} at the beginning of
+their @var{body}.
@end defspec
The usual purpose of tracking mouse motion is to indicate on the screen
@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
@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
@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 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 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}.
@defvar x-resource-class
This variable specifies the application name that @code{x-get-resource}
should look up. The default value is @code{"Emacs"}. You can examine X
-resources for application names other than ``Emacs'' by binding this
+resources for other application names by binding this
variable to some other string, around a call to @code{x-get-resource}.
@end defvar
This function returns non-@code{nil} if all the face attributes in
@var{attributes} are supported (@pxref{Face Attributes}).
-The definition of `supported' is somewhat heuristic, but basically
+The definition of ``supported'' is somewhat heuristic, but basically
means that a face containing all the attributes in @var{attributes},
when merged with the default face for display, can be represented in a
way that's
different in appearance than the default face, and
@item
-`close in spirit' to what the attributes specify, if not exact.
+close in spirit to what the attributes specify, if not exact.
@end enumerate
Point (2) implies that a @code{:weight black} attribute will be
satisfied by any display that can display bold, as will
@code{:foreground "yellow"} as long as some yellowish color can be
displayed, but @code{:slant italic} will @emph{not} be satisfied by
-the tty display code's automatic substitution of a `dim' face for
+the tty display code's automatic substitution of a dim face for
italic.
@end defun
This function returns the height of the screen in pixels.
On a character terminal, it gives the height in characters.
-For graphical terminals, note that on ``multi-monitor'' setups this
+For graphical terminals, note that on multi-monitor setups this
refers to the pixel height for all physical monitors associated with
@var{display}. @xref{Multiple Terminals}.
@end defun
This function returns the width of the screen in pixels.
On a character terminal, it gives the width in characters.
-For graphical terminals, note that on ``multi-monitor'' setups this
+For graphical terminals, note that on multi-monitor setups this
refers to the pixel width for all physical monitors associated with
@var{display}. @xref{Multiple Terminals}.
@end defun
This function returns the height of the screen in millimeters,
or @code{nil} if Emacs cannot get that information.
-For graphical terminals, note that on ``multi-monitor'' setups this
+For graphical terminals, note that on multi-monitor setups this
refers to the height for all physical monitors associated with
@var{display}. @xref{Multiple Terminals}.
@end defun
This function returns the width of the screen in millimeters,
or @code{nil} if Emacs cannot get that information.
-For graphical terminals, note that on ``multi-monitor'' setups this
+For graphical terminals, note that on multi-monitor setups this
refers to the width for all physical monitors associated with
@var{display}. @xref{Multiple Terminals}.
@end defun
@end defun
@defun x-server-vendor &optional display
-This function returns the ``vendor'' that provided the window system
+This function returns the vendor that provided the window system
software (as a string). On GNU and Unix systems this really means
whoever distributes the X server. On MS-Windows this is the vendor ID
string of the Windows OS (Microsoft).