[Emacs-diffs] emacs-24 r117559: Fix bug #18636 with documentation of multi-monitor displays.

[Eli Zaretskii]

------------------------------------------------------------
revno: 117559
revision-id: address@hidden
parent: address@hidden
fixes bug: http://debbugs.gnu.org/18636
committer: Eli Zaretskii <address@hidden>
branch nick: emacs-24
timestamp: Wed 2014-10-08 13:16:45 +0300
message:
  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.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/frames.texi        
frames.texi-20091113204419-o5vbwnq5f7feedwu-6180
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/faces.el                  faces.el-20091113204419-o5vbwnq5f7feedwu-562
  lisp/frame.el                  frame.el-20091113204419-o5vbwnq5f7feedwu-275

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-10-04 06:59:30 +0000
+++ b/doc/lispref/ChangeLog     2014-10-08 10:16:45 +0000
@@ -1,3 +1,16 @@
+2014-10-08  Eli Zaretskii  <address@hidden>
+
+       * 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  <address@hidden>
 
        * commands.texi (Generic Commands): Copyedits.

=== modified file 'doc/lispref/frames.texi'
--- a/doc/lispref/frames.texi   2014-10-04 03:03:52 +0000
+++ b/doc/lispref/frames.texi   2014-10-08 10:16:45 +0000
@@ -131,6 +131,13 @@
 (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 @@
 terminals, by interacting with the @command{emacsclient} program.
 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
 
address@hidden X display names
address@hidden display name on X
   A single X server can handle more than one display.  Each X display
-has a three-part name, @address@hidden:@address@hidden
-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,
address@hidden@var{hostname}:@address@hidden  The
+first part, @var{hostname}, specifies the name of the machine to which
+the display is physically connected.  The second part,
address@hidden, 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,
address@hidden, 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 @@
 
 @defun display-monitor-attributes-list &optional display
 This function returns a list of physical monitor attributes on
address@hidden, 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:
address@hidden, 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}
address@hidden @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
address@hidden(@var{x} @var{y} @var{width} @var{height})}.
+Position of the top-left corner and size of the work area in pixels as
address@hidden(@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 @@
 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:
+
address@hidden
+  (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 #<frame emacs@@host *foo* 0000000005BBDC48>
+            #<frame emacs@@host *scratch* 000000008179D370>))
+   ((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)))
address@hidden smalllisp
+
 @end defun
 
 @defun frame-monitor-attributes &optional frame
@@ -529,8 +579,9 @@
 @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}:@address@hidden"}, just like the
address@hidden environment variable.
+form @address@hidden:@address@hidden, just like the
address@hidden environment variable.  @xref{Multiple Terminals}, for
+more details about display names.
 
 @vindex display-type, a frame parameter
 @item display-type
@@ -586,12 +637,14 @@
 @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

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-10-06 06:45:10 +0000
+++ b/lisp/ChangeLog    2014-10-08 10:16:45 +0000
@@ -1,3 +1,16 @@
+2014-10-08  Eli Zaretskii  <address@hidden>
+
+       * 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  <address@hidden>
 
        * term.el (term-window-width): Subtract 1 from the width when

=== modified file 'lisp/faces.el'
--- a/lisp/faces.el     2014-07-09 18:46:33 +0000
+++ b/lisp/faces.el     2014-10-08 10:16:45 +0000
@@ -1814,7 +1814,9 @@
 (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))

=== modified file 'lisp/frame.el'
--- a/lisp/frame.el     2014-10-04 03:03:52 +0000
+++ b/lisp/frame.el     2014-10-08 10:16:45 +0000
@@ -1381,6 +1381,7 @@
 
 (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 @@
 
 (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 @@
 
 (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 @@
 (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 @@
 (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 @@
   "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 @@
 
 (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 @@
 
 (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 @@
 
 (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 @@
   "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 @@
 
 (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 @@
 
  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