@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Frames
server, Emacs knows by the similarity in their names that they share a
single keyboard.
- On some ``multi-monitor'' setups, a single X display outputs to more
-than one physical monitor. Currently, there is no way for Emacs to
-distinguish between the different physical monitors.
-
@deffn Command make-frame-on-display display &optional parameters
This function creates and returns a new frame on @var{display}, taking
the other frame parameters from the alist @var{parameters}.
on that display (@pxref{Deleting Frames}).
@end defun
+@cindex multi-monitor
+ On some ``multi-monitor'' setups, a single X display outputs to more
+than one physical monitor. @code{display-monitor-attributes-list} and
+@code{frame-monitor-attributes} can be used to obtain information
+about each physical monitor on multi-monitor setups.
+
+@defun display-monitor-attributes-list &optional display
+This function returns a list of physical monitor attributes on
+@var{display}. Each element of the list is an association list,
+representing the attributes of each physical monitor. The first
+element corresponds to the primary monitor.
+
+Attributes for a physical monitor are:
+
+@table @samp
+@item geometry
+Position and size in pixels in the form of @samp{(X Y WIDTH HEIGHT)}
+
+@item workarea
+Position and size of the workarea in pixels in the form of @samp{(X Y
+WIDTH HEIGHT)}
+
+@item mm-size
+Width and height in millimeters in the form of @samp{(WIDTH HEIGHT)}
+
+@item frames
+List of frames dominated by the physical monitor
+
+@item name
+Name of the physical monitor as a string
+@end table
+
+where X, Y, WIDTH, and HEIGHT are integers. @samp{name} is optional.
+
+A frame is dominated by a physical monitor when either the
+largest area of the frame resides in the monitor, or the monitor
+is the closest to the frame if the frame does not intersect any
+physical monitors. Every non-tip frame (including invisible one)
+in a graphical display is dominated by exactly one physical
+monitor at a time, though it can span multiple (or no) physical
+monitors.
+
+@var{display} defaults to the selected frame's display.
+@end defun
+
+@defun frame-monitor-attributes &optional frame
+This function returns the attributes of the physical monitor
+dominating @var{frame}, which defaults to the selected frame.
+
+A frame is dominated by a physical monitor when either the
+largest area of the frame resides in the monitor, or the monitor
+is the closest to the frame if the frame does not intersect any
+physical monitors.
+@end defun
+
@node Frame Parameters
@section Frame Parameters
@cindex frame parameters
precise width by specifying that width as a negative integer. If both
widths are negative, only the left fringe gets the specified width.
+@vindex right-divider-width, a frame parameter
+@item right-divider-width
+The width (thickness) reserved for the right divider (@pxref{Window
+Dividers}) of any window on the frame, in pixels. A value of zero means
+to not draw right dividers.
+
+@vindex bottom-divider-width, a frame parameter
+@item bottom-divider-width
+The width (thickness) reserved for the bottom divider (@pxref{Window
+Dividers}) of any window on the frame, in pixels. A value of zero means
+to not draw bottom dividers.
+
@vindex menu-bar-lines frame parameter
@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu
@cindex gamma correction
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, a floating point number.
+your display.
Usual PC monitors have a screen gamma of 2.2, so color values in
Emacs, and in X windows generally, are calibrated to display properly
frame.
@end defun
-@defun set-frame-size frame cols rows
+@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 semantics of a value of @code{nil} for this option depends
+on the toolkit used: Dragging the frame border with the mouse is usually
+always 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 may be, however, either ignored or cause a
+rounding (GTK+, Windows) or get accepted (Lucid, Motif).
+@end defopt
+
+@defun set-frame-size frame width height pixelwise
This function sets the size of @var{frame}, measured in characters;
-@var{cols} and @var{rows} specify the new width and height.
+@var{width} and @var{height} specify the new width in columns and the
+new height in lines.
-To set the size based on values measured in pixels, use
-@code{frame-char-height} and @code{frame-char-width} to convert
-them to units of characters.
+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 lines &optional pretend
-This function resizes @var{frame} to a height of @var{lines} lines. The
+@defun set-frame-height frame height &optional pretend pixelwise
+This function resizes @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{lines}
+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
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
+@defun set-frame-width frame width &optional pretend pixelwise
This function sets the width 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
@c FIXME? Belongs more in Emacs manual than here?
@c But, e.g., fit-window-to-buffer is in this manual.
-@deffn Command fit-frame-to-buffer &optional frame max-height min-height
-This command adjusts the height of @var{frame} (the default is the
-selected frame) to fit its contents. The optional arguments
-@var{max-height} and @var{min-height} specify the maximum and minimum
-new frame heights, respectively.
-
-@vindex fit-frame-to-buffer-bottom-margin
-The default minimum height corresponds to @code{window-min-height}.
-The default maximum height is the screen height below the current top
-position of the frame, minus any margin specified by the option
-@code{fit-frame-to-buffer-bottom-margin}.
+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
change it.
@end defun
+@defvar focus-in-hook
+This is a normal hook run when an Emacs frame gains input focus.
+@end defvar
+
+@defvar focus-out-hook
+This is a normal hook run when an Emacs frame loses input focus.
+@end defvar
+
@defopt focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers
focus when the user moves the mouse. Non-@code{nil} says that it does.
On a character terminal, it gives the height in characters.
For graphical terminals, note that on ``multi-monitor'' setups this
-refers to the pixel width for all physical monitors associated with
+refers to the pixel height for all physical monitors associated with
@var{display}. @xref{Multiple Terminals}.
@end defun
@defun display-mm-height &optional display
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
+refers to the height for all physical monitors associated with
+@var{display}. @xref{Multiple Terminals}.
@end defun
@defun display-mm-width &optional display
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
+refers to the width for all physical monitors associated with
+@var{display}. @xref{Multiple Terminals}.
@end defun
@defopt display-mm-dimensions-alist