diff options
Diffstat (limited to 'doc/lispref/frames.texi')
| -rw-r--r-- | doc/lispref/frames.texi | 96 |
1 files changed, 77 insertions, 19 deletions
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 464c5fccc4f..a14702a7ce1 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,29 @@ 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 (``usable'' +space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}. +This may be different from @samp{geometry} in that space occupied by +various window manager features (docks, taskbars, etc.) may be +excluded from the work area. Whether or not such features actually +subtract from the work area depends on the platform and environment. +Again, 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})} @@ -342,10 +373,14 @@ List of frames that this physical monitor dominates (see below). @item name Name of the physical monitor as @var{string}. + +@item source +Source of the multi-monitor information as @var{string}; +e.g., @samp{XRandr} or @samp{Xinerama}. @end table @var{x}, @var{y}, @var{width}, and @var{height} are integers. -@samp{name} may not be present. +@samp{name} and @samp{source} may be absent. A frame is @dfn{dominated} by a physical monitor when either the largest area of the frame resides in that monitor, or (if the frame @@ -353,6 +388,26 @@ 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: + +@lisp + (display-monitor-attributes-list) + @result{} + (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor} + (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height} + (mm-size 677 381) + (name . "DISPLAY1") + (frames #<frame emacs@@host *Messages* 0x11578c0> + #<frame emacs@@host *scratch* 0x114b838>)) + ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor} + (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used} + (mm-size 593 370) + (name . "DISPLAY2") + (frames))) +@end lisp + @end defun @defun frame-monitor-attributes &optional frame @@ -529,8 +584,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 +642,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 |