mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-30 04:10:54 -08:00
Code Issues Projects Releases Wiki Activity

Fix bug #18636 with documentation of multi-monitor displays.

Browse source 
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.
This commit is contained in:
Eli Zaretskii 2014-10-08 13:16:45 +03:00
parent a7044030f3
commit 28ec0a87ca
5 changed files with 116 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

13
doc/lispref/ChangeLog
View file

@ -1,3 +1,16 @@
2014-10-08 Eli Zaretskii <eliz@gnu.org>
* 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 <rgm@gnu.org>
* commands.texi (Generic Commands): Copyedits.

89
doc/lispref/frames.texi
View file

@ -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 #<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)))
@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

13
lisp/ChangeLog
View file

@ -1,3 +1,16 @@
2014-10-08 Eli Zaretskii <eliz@gnu.org>
* 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 <rudalics@gmx.at>
* term.el (term-window-width): Subtract 1 from the width when

4
lisp/faces.el
View file

@ -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))

19
lisp/frame.el
View file

@ -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