From 7ebd57e9d6b6f26ff4c92dd4d93af163d1befc4e Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sun, 2 Mar 2014 17:00:27 -0800 Subject: [PATCH] Minor doc tweaks for display-*-width, height * lisp/frame.el (display-pixel-height, display-pixel-width) (display-mm-dimensions-alist, display-mm-height) (display-mm-width): Doc tweaks. * doc/lispref/frames.texi: Remove FIXME comments. The x- versions of these functions are internal details that do not need documenting. * etc/NEWS: Related markup. --- doc/lispref/frames.texi | 2 -- etc/NEWS | 3 ++- lisp/ChangeLog | 6 ++++++ lisp/frame.el | 46 +++++++++++++++++++++++++---------------- 4 files changed, 36 insertions(+), 21 deletions(-) diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 403d9f6884e..439f9686733 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -2421,7 +2421,6 @@ images, Emacs cannot display a tool bar. This function returns the number of screens associated with the display. @end defun -@c FIXME: Document `x-display-pixel-{width, height}'? @defun display-pixel-height &optional display This function returns the height of the screen in pixels. On a character terminal, it gives the height in characters. @@ -2440,7 +2439,6 @@ refers to the pixel width for all physical monitors associated with @var{display}. @xref{Multiple Terminals}. @end defun -@c FIXME: Document `x-display-mm-{width, height}'? @defun display-mm-height &optional display This function returns the height of the screen in millimeters, or @code{nil} if Emacs cannot get that information. diff --git a/etc/NEWS b/etc/NEWS index ce98be2dda2..a5919069000 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -142,10 +142,11 @@ entries of a file. `frame-monitor-attributes' can be used to obtain information about each physical monitor on multi-monitor setups. ++++ *** The functions `display-pixel-width' and `display-pixel-height' now behave consistently among the platforms: they return the pixel width or height for all physical monitors associated with the given display -as if they were on X11. To get information for each physical +as if they were on X. To get information for each physical monitor, use the new functions above. Similar notes also apply to `x-display-pixel-width', `x-display-pixel-height', `display-mm-width', `display-mm-height', `x-display-mm-width', and `x-display-mm-height'. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index a2a88f4b86b..9c3a7ac9945 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,9 @@ +2014-03-03 Glenn Morris + + * frame.el (display-pixel-height, display-pixel-width) + (display-mm-dimensions-alist, display-mm-height) + (display-mm-width): Doc tweaks. + 2014-03-02 Barry O'Reilly * simple.el (undo-elt-in-region): Fix buffer corruption for edge diff --git a/lisp/frame.el b/lisp/frame.el index 4f189a82289..b62c939d536 100644 --- a/lisp/frame.el +++ b/lisp/frame.el @@ -1393,12 +1393,14 @@ 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. +If DISPLAY is omitted or nil, it defaults to the selected frame's display. + For character terminals, each character counts as a single pixel. + For graphical terminals, note that on \"multi-monitor\" setups this refers to the pixel height for all physical monitors associated with DISPLAY. To get information for each physical monitor, use -`display-monitor-attributes-list'. -If DISPLAY is omitted or nil, it defaults to the selected frame's display." +`display-monitor-attributes-list'." (let ((frame-type (framep-on-display display))) (cond ((memq frame-type '(x w32 ns)) @@ -1410,12 +1412,14 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display." (defun display-pixel-width (&optional display) "Return the width of DISPLAY's screen in pixels. +If DISPLAY is omitted or nil, it defaults to the selected frame's display. + For character terminals, each character counts as a single pixel. + For graphical terminals, note that on \"multi-monitor\" setups this refers to the pixel width for all physical monitors associated with DISPLAY. To get information for each physical monitor, use -`display-monitor-attributes-list'. -If DISPLAY is omitted or nil, it defaults to the selected frame's display." +`display-monitor-attributes-list'." (let ((frame-type (framep-on-display display))) (cond ((memq frame-type '(x w32 ns)) @@ -1425,14 +1429,14 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display." (defcustom display-mm-dimensions-alist nil "Alist for specifying screen dimensions in millimeters. -The dimensions will be used for `display-mm-height' and -`display-mm-width' if defined for the respective display. +The functions `display-mm-height' and `display-mm-width' consult +this list before asking the system. -Each element of the alist has the form (display . (width . height)), -e.g. (\":0.0\" . (287 . 215)). +Each element has the form (DISPLAY . (WIDTH . HEIGHT)), e.g. +\(\":0.0\" . (287 . 215)). -If `display' equals t, it specifies dimensions for all graphical -displays not explicitly specified." +If `display' is t, it specifies dimensions for all graphical displays +not explicitly specified." :version "22.1" :type '(alist :key-type (choice (string :tag "Display name") (const :tag "Default" t)) @@ -1445,13 +1449,16 @@ displays not explicitly specified." (defun display-mm-height (&optional display) "Return the height of DISPLAY's screen in millimeters. -System values can be overridden by `display-mm-dimensions-alist'. -If the information is unavailable, value is nil. +If the information is unavailable, this function returns nil. +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 +adding an entry to `display-mm-dimensions-alist'. + For graphical terminals, note that on \"multi-monitor\" setups this refers to the height in millimeters for all physical monitors associated with DISPLAY. To get information for each physical -monitor, use `display-monitor-attributes-list'. -If DISPLAY is omitted or nil, it defaults to the selected frame's display." +monitor, use `display-monitor-attributes-list'." (and (memq (framep-on-display display) '(x w32 ns)) (or (cddr (assoc (or display (frame-parameter nil 'display)) display-mm-dimensions-alist)) @@ -1462,13 +1469,16 @@ If DISPLAY is omitted or nil, it defaults to the selected frame's display." (defun display-mm-width (&optional display) "Return the width of DISPLAY's screen in millimeters. -System values can be overridden by `display-mm-dimensions-alist'. -If the information is unavailable, value is nil. +If the information is unavailable, this function returns nil. +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 +adding an entry to `display-mm-dimensions-alist'. + For graphical terminals, note that on \"multi-monitor\" setups this refers to the width in millimeters for all physical monitors associated with DISPLAY. To get information for each physical -monitor, use `display-monitor-attributes-list'. -If DISPLAY is omitted or nil, it defaults to the selected frame's display." +monitor, use `display-monitor-attributes-list'." (and (memq (framep-on-display display) '(x w32 ns)) (or (cadr (assoc (or display (frame-parameter nil 'display)) display-mm-dimensions-alist)) -- 2.39.2