From 8603bdb3b7ab4c4faa10ddadcdc2708228717220 Mon Sep 17 00:00:00 2001 From: Xue Fuqiao Date: Thu, 27 Feb 2014 18:15:52 +0800 Subject: [PATCH] * doc/lispref/frames.texi (Multiple Terminals): Document `display-monitor-attributes-list' and `display-monitor-attributes'. (Display Feature Testing): Add some notes about multi-monitor. * etc/NEWS: Related edit. --- doc/lispref/ChangeLog | 6 ++++ doc/lispref/frames.texi | 71 ++++++++++++++++++++++++++++++++++++++--- 2 files changed, 72 insertions(+), 5 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 6eb45dc3f4f..8d473033bd2 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,9 @@ +2014-02-27 Xue Fuqiao + + * frames.texi (Multiple Terminals): Document + `display-monitor-attributes-list' and `display-monitor-attributes'. + (Display Feature Testing): Add some notes about multi-monitor. + 2014-02-27 Glenn Morris * minibuf.texi (Programmed Completion): diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index d281c6652a0..403d9f6884e 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -266,10 +266,6 @@ that X server. When you use two or more screens belonging to one 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}. @@ -316,6 +312,61 @@ you can do this, you must first delete all the frames that were open 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 @@ -2370,12 +2421,13 @@ images, Emacs cannot display a tool bar. This function returns the number of screens associated with the display. @end defun +@c FIXME: Document `x-display-pixel-{width, height}'? @defun display-pixel-height &optional display 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 -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 @@ -2388,14 +2440,23 @@ refers to the pixel width for all physical monitors associated with @var{display}. @xref{Multiple Terminals}. @end defun +@c FIXME: Document `x-display-mm-{width, height}'? @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 -- 2.39.2