From 28ec0a87ca43f6d62b1503bedfe25640269fd7ef Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Wed, 8 Oct 2014 13:16:45 +0300 Subject: [PATCH] Fix bug #18636 with documentation of multi-monitor displays. doc/lispref/frames.texi (Multiple Terminals): Improve the description of X display names. Add index entries. (Basic Parameters): Add a cross-reference to where X display names are described. (Position Parameters): Mention that positional parameters of the form (+ POS) can be negative if they are on a non-primary monitor of a multi-monitor display. (Creating Frames): Mention that on multi-monitor displays the frame might be positioned differently than specified by the frame parameters alist. lisp/faces.el (display-grayscale-p): Mention in the doc string that the argument can be either a display name or a frame. lisp/frame.el (display-pixel-height, display-pixel-width) (display-mm-height, display-mm-width, display-backing-store) (display-save-under, display-planes, display-color-cells) (display-visual-class, display-monitor-attributes-list) (display-screens): Mention in the doc string that the argument can be either a display name or a frame. Improve the docs of the monitor attributes. --- doc/lispref/ChangeLog | 13 ++++++ doc/lispref/frames.texi | 89 ++++++++++++++++++++++++++++++++--------- lisp/ChangeLog | 13 ++++++ lisp/faces.el | 4 +- lisp/frame.el | 19 +++++++-- 5 files changed, 116 insertions(+), 22 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index babcc22959e..36497470705 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,16 @@ +2014-10-08 Eli Zaretskii + + * frames.texi (Multiple Terminals): Improve the description of X + display names. Add index entries. + (Basic Parameters): Add a cross-reference to where X display names + are described. + (Position Parameters): Mention that positional parameters of the + form (+ POS) can be negative if they are on a non-primary monitor + of a multi-monitor display. (Bug#18636) + (Creating Frames): Mention that on multi-monitor displays the + frame might be positioned differently than specified by the frame + parameters alist. + 2014-10-04 Glenn Morris * commands.texi (Generic Commands): Copyedits. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index afbace34575..cb3fefd7115 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -131,6 +131,13 @@ applies any parameters listed in @code{frame-inherited-parameters} (see below) and not present in the argument, taking the values from the frame that was selected when @code{make-frame} was called. +Note that on multi-monitor displays (@pxref{Multiple Terminals}), the +window manager might position the frame differently than specified by +the positional parameters in @var{alist} (@pxref{Position +Parameters}). For example, some window managers have a policy of +displaying the frame on the monitor that contains the largest part of +the window (a.k.a.@: the @dfn{dominating} monitor). + This function itself does not make the new frame the selected frame. @xref{Input Focus}. The previously selected frame remains selected. On graphical terminals, however, the windowing system may select the @@ -258,13 +265,27 @@ of those frames is ``@emph{the} selected frame'' at any given moment terminals, by interacting with the @command{emacsclient} program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@cindex X display names +@cindex display name on X A single X server can handle more than one display. Each X display -has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}. -The first two parts, @var{host} and @var{server}, identify the X -server; the third part, @var{screen}, identifies a screen number on -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. +has a three-part name, +@samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}. The +first part, @var{hostname}, specifies the name of the machine to which +the display is physically connected. The second part, +@var{displaynumber}, is a zero-based number that identifies one or +more monitors connected to that machine that share a common keyboard +and pointing device (mouse, tablet, etc.). The third part, +@var{screennumber}, identifies a zero-based screen number (a separate +monitor) that is part of a single monitor collection on 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. + + Systems that don't use the X window system, such as MS-Windows, +don't support the notion of X displays, and have only one display on +each host. The display name on these systems doesn't follow the above +3-part format; for example, the display name on MS-Windows systems is +a constant string @samp{w32}, and exists for compatibility, so that +you could pass it to functions that expect a display name. @deffn Command make-frame-on-display display &optional parameters This function creates and returns a new frame on @var{display}, taking @@ -320,19 +341,27 @@ to obtain information about such setups. @defun display-monitor-attributes-list &optional display This function returns a list of physical monitor attributes on -@var{display}, which defaults to that of the selected frame. -Each element of the list is an association list, representing the -attributes of a physical monitor. The first element corresponds to -the primary monitor. The attribute keys and values are: +@var{display}, which can be a display name (a string), a terminal, or +a frame; if omitted or @code{nil}, it defaults to the selected frame's +display. Each element of the list is an association list, +representing the attributes of a physical monitor. The first element +corresponds to the primary monitor. The attribute keys and values +are: @table @samp @item geometry -Position and size in pixels as @samp{(@var{x} @var{y} -@var{width} @var{height})}. +Position of the top-left corner of the monitor's screen and its size, +in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}. Note +that, if the monitor is not the primary monitor, some of the +coordinates might be negative. @item workarea -Position and size of the work area in pixels as -@samp{(@var{x} @var{y} @var{width} @var{height})}. +Position of the top-left corner and size of the work area in pixels as +@samp{(@var{x} @var{y} @var{width} @var{height})}. This is different +from @samp{geometry} in that the various system windows, such as the +task bar and side bar, are excluded from the work area. Note that, if +the monitor is not the primary monitor, some of the coordinates might +be negative. @item mm-size Width and height in millimeters as @samp{(@var{width} @var{height})} @@ -353,6 +382,27 @@ does not intersect any physical monitors) that monitor is the closest to the frame. Every (non-tooltip) frame (whether visible or not) in a graphical display is dominated by exactly one physical monitor at a time, though the frame can span multiple (or no) physical monitors. + +Here's an example of the data produced by this function on a 2-monitor +display: + +@smalllisp + (display-monitor-attributes-list) + @result{} + (((geometry 0 0 1920 1080) ;; Left hand monitor + (workarea 0 0 1920 1050) ;; Bottom of screen used for task bar + task bar + (mm-size 677 381) + (name . "\\\\.\\DISPLAY1") + (frames # + #)) + ((geometry 1920 0 1680 1050) ;; Right hand monitor + (workarea 1920 0 1680 1050) ;; Whole screen can be used + (mm-size 593 370) + (name . "\\\\.\\DISPLAY2") + (frames))) +@end smalllisp + @end defun @defun frame-monitor-attributes &optional frame @@ -529,8 +579,9 @@ frame. @code{title} and @code{name} are meaningful on all terminals. @vindex display, a frame parameter @item display The display on which to open this frame. It should be a string of the -form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the -@env{DISPLAY} environment variable. +form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the +@env{DISPLAY} environment variable. @xref{Multiple Terminals}, for +more details about display names. @vindex display-type, a frame parameter @item display-type @@ -586,12 +637,14 @@ right screen edge. @item @code{(+ @var{pos})} This specifies the position of the left frame edge relative to the left screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. +negative value specifies a position outside the screen or on a monitor +other than the primary one (for multi-monitor displays). @item @code{(- @var{pos})} This specifies the position of the right frame edge relative to the right screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. +negative value specifies a position outside the screen or on a monitor +other than the primary one (for multi-monitor displays). @end table Some window managers ignore program-specified positions. If you want to diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 5045e5d1469..e8fd37925fa 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,16 @@ +2014-10-08 Eli Zaretskii + + * faces.el (display-grayscale-p): Mention in the doc string that + the argument can be either a display name or a frame. + + * frame.el (display-pixel-height, display-pixel-width) + (display-mm-height, display-mm-width, display-backing-store) + (display-save-under, display-planes, display-color-cells) + (display-visual-class, display-monitor-attributes-list) + (display-screens): Mention in the doc string that the argument can + be either a display name or a frame. Improve the docs of the + monitor attributes. (Bug#18636) + 2014-10-06 Martin Rudalics * term.el (term-window-width): Subtract 1 from the width when diff --git a/lisp/faces.el b/lisp/faces.el index f316245d165..20665286b4f 100644 --- a/lisp/faces.el +++ b/lisp/faces.el @@ -1814,7 +1814,9 @@ If omitted or nil, that stands for the selected frame's display." (declare-function x-display-grayscale-p "xfns.c" (&optional terminal)) (defun display-grayscale-p (&optional display) - "Return non-nil if frames on DISPLAY can display shades of gray." + "Return non-nil if frames on DISPLAY can display shades of gray. +DISPLAY should be either a frame or a display name (a string). +If omitted or nil, that stands for the selected frame's display." (let ((frame-type (framep-on-display display))) (cond ((memq frame-type '(x w32 ns)) diff --git a/lisp/frame.el b/lisp/frame.el index f4d7622e662..9ab24cefc0f 100644 --- a/lisp/frame.el +++ b/lisp/frame.el @@ -1381,6 +1381,7 @@ frame's display)." (defun display-screens (&optional display) "Return the number of screens associated with DISPLAY. +DISPLAY should be either a frame or a display name (a string). If DISPLAY is omitted or nil, it defaults to the selected frame's display." (let ((frame-type (framep-on-display display))) (cond @@ -1393,6 +1394,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display." (defun display-pixel-height (&optional display) "Return the height of DISPLAY's screen in pixels. +DISPLAY can be a display name or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display. For character terminals, each character counts as a single pixel. @@ -1412,6 +1414,7 @@ with DISPLAY. To get information for each physical monitor, use (defun display-pixel-width (&optional display) "Return the width of DISPLAY's screen in pixels. +DISPLAY can be a display name or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display. For character terminals, each character counts as a single pixel. @@ -1450,6 +1453,7 @@ not explicitly specified." (defun display-mm-height (&optional display) "Return the height of DISPLAY's screen in millimeters. If the information is unavailable, this function returns nil. +DISPLAY can be a display name or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display. You can override what the system thinks the result should be by @@ -1470,6 +1474,7 @@ monitor, use `display-monitor-attributes-list'." (defun display-mm-width (&optional display) "Return the width of DISPLAY's screen in millimeters. If the information is unavailable, this function returns nil. +DISPLAY can be a display name or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display. You can override what the system thinks the result should be by @@ -1493,6 +1498,7 @@ monitor, use `display-monitor-attributes-list'." "Return the backing store capability of DISPLAY's screen. The value may be `always', `when-mapped', `not-useful', or nil if the question is inapplicable to a certain kind of display. +DISPLAY can be a display name or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display." (let ((frame-type (framep-on-display display))) (cond @@ -1505,6 +1511,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display." (defun display-save-under (&optional display) "Return non-nil if DISPLAY's screen supports the SaveUnder feature. +DISPLAY can be a display name or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display." (let ((frame-type (framep-on-display display))) (cond @@ -1517,6 +1524,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display." (defun display-planes (&optional display) "Return the number of planes supported by DISPLAY. +DISPLAY can be a display name or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display." (let ((frame-type (framep-on-display display))) (cond @@ -1531,6 +1539,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display." (defun display-color-cells (&optional display) "Return the number of color cells supported by DISPLAY. +DISPLAY can be a display name or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display." (let ((frame-type (framep-on-display display))) (cond @@ -1547,6 +1556,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display." "Return the visual class of DISPLAY. The value is one of the symbols `static-gray', `gray-scale', `static-color', `pseudo-color', `true-color', or `direct-color'. +DISPLAY can be a display name or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display." (let ((frame-type (framep-on-display display))) (cond @@ -1567,6 +1577,7 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display." (defun display-monitor-attributes-list (&optional display) "Return a list of physical monitor attributes on DISPLAY. +DISPLAY can be a display name, a terminal name, or a frame. If DISPLAY is omitted or nil, it defaults to the selected frame's display. Each element of the list represents the attributes of a physical monitor. The first element corresponds to the primary monitor. @@ -1576,14 +1587,16 @@ of attribute keys and values as follows: geometry -- Position and size in pixels in the form of (X Y WIDTH HEIGHT) workarea -- Position and size of the work area in pixels in the - form of (X Y WIDTH HEIGHT) + form of (X Y WIDTH HEIGHT); this excludes task bar etc. mm-size -- Width and height in millimeters in the form of (WIDTH HEIGHT) frames -- List of frames dominated by the physical monitor name (*) -- Name of the physical monitor as a string -where X, Y, WIDTH, and HEIGHT are integers. Keys labeled -with (*) are optional. +where X, Y, WIDTH, and HEIGHT are integers, which might be negative +for monitors other than the primary one. X and Y are coordinates +of the top-left corner of the rectange. Keys labeled with (*) are +optional. A frame is dominated by a physical monitor when either the largest area of the frame resides in the monitor, or the monitor -- 2.39.2