Function: display-monitor-attributes-list

display-monitor-attributes-list is a byte-compiled function defined in frame.el.gz.

Signature

(display-monitor-attributes-list &optional DISPLAY)

Documentation

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.

The attributes for a physical monitor are represented as an alist 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)
 mm-size -- Width and height in millimeters in the form of
             (WIDTH HEIGHT)
 frames -- List of frames dominated by the physical monitor
 scale-factor (*) -- Scale factor (float)
 name (*) -- Name of the physical monitor as a string
 source (*) -- Source of multi-monitor information as a string

where X, Y, WIDTH, and HEIGHT are integers. X and Y are coordinates of the top-left corner, and might be negative for monitors other than the primary one. Keys labeled with (*) are optional.

The "work area" is a measure of the "usable" display space. It may be less than the total screen size, owing to space taken up by window manager features (docks, taskbars, etc.). The precise details depend on the platform and environment.

The source attribute describes the source from which the information was obtained. On X, this may be one of: "Gdk",
"XRandR 1.5", "XRandr", "Xinerama", or "fallback".
If it is "fallback", it means Emacs was built without GTK and without XrandR or Xinerama extensions, in which case the information about multiple physical monitors will be provided as if they all as a whole formed a single monitor.

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-tooltip) frame (including invisible ones) in a graphical display is dominated by exactly one physical monitor at a time, though it can span multiple (or no) physical monitors.

View in manual

Probably introduced at or before Emacs version 24.4.

Source Code

;; Defined in /usr/src/emacs/lisp/frame.el.gz
(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.

The attributes for a physical monitor are represented as an alist
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)
 mm-size  -- Width and height in millimeters in the form of
             (WIDTH HEIGHT)
 frames   -- List of frames dominated by the physical monitor
 scale-factor (*) -- Scale factor (float)
 name (*) -- Name of the physical monitor as a string
 source (*) -- Source of multi-monitor information as a string

where X, Y, WIDTH, and HEIGHT are integers.  X and Y are coordinates
of the top-left corner, and might be negative for monitors other than
the primary one.  Keys labeled with (*) are optional.

The \"work area\" is a measure of the \"usable\" display space.
It may be less than the total screen size, owing to space taken up
by window manager features (docks, taskbars, etc.).  The precise
details depend on the platform and environment.

The `source' attribute describes the source from which the
information was obtained.  On X, this may be one of: \"Gdk\",
\"XRandR 1.5\", \"XRandr\", \"Xinerama\", or \"fallback\".
If it is \"fallback\", it means Emacs was built without GTK
and without XrandR or Xinerama extensions, in which case the
information about multiple physical monitors will be provided
as if they all as a whole formed a single monitor.

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-tooltip) frame (including invisible ones)
in a graphical display is dominated by exactly one physical
monitor at a time, though it can span multiple (or no) physical
monitors."
  (let ((frame-type (framep-on-display display)))
    (cond
     ((eq frame-type 'x)
      (x-display-monitor-attributes-list display))
     ((eq frame-type 'w32)
      (w32-display-monitor-attributes-list display))
     ((eq frame-type 'ns)
      (ns-display-monitor-attributes-list display))
     ((eq frame-type 'pgtk)
      (pgtk-display-monitor-attributes-list display))
     ((eq frame-type 'haiku)
      (haiku-display-monitor-attributes-list display))
     ((eq frame-type 'android)
      (android-display-monitor-attributes-list display))
     (t
      (let ((geometry (list 0 0 (display-pixel-width display)
			    (display-pixel-height display))))
	`(((geometry . ,geometry)
	   (workarea . ,geometry)
	   (mm-size . (,(display-mm-width display)
		       ,(display-mm-height display)))
	   (frames . ,(frames-on-display-list display)))))))))