bug#18637: 24.4.50; doc of frame parameter DISPLAY vs actual value on MS Windows

[Andy Moreton <andrewjmoreton@gmail.com>]

On Mon 06 Oct 2014, Drew Adams wrote:

>> frame-monitor-attributes, if I understand what you want.
>
> I see that that function returns some information about (attributes
> of) the monitor that is most associated with the argument frame.  And
> I see that one of the attributes is `name'.   Presumably, monitors
> would be distinguished by this parameter.
>
> However, it is an optional parameter, so I can't imagine that one can
> count on it to distinguish monitors.  (Just why is it optional?)
> If one cannot count on `name', how is the identity of monitors
> determined?  Do you just go by the particular cons of attributes
> that is returned by `frame-monitor-attributes'?
>
> Also, FWIW, I don't see, in the doc, where the meanings of those
> attributes are specified.  The doc for `display-monitor-attributes'
> supposedly does that, but it says nothing about what the "Position",
> for `geometry' and `workarea', is relative to.  And it says nothing
> about what those attributes mean.
>
> I can guess the meaning for `geometry' here, being somewhat familiar
> with X window `geometry' specs, but there should be some mention or
> xref to the meaning/use of `geometry' outside Emacs, or else this
> parameter is unspecified in terms of its meaning or effect.
>
> And I cannot guess at all for `workarea'.  What is it?  How does/can
> it differ from `geometry'?

Perhaps an example will help. here is the output for a Windows machine
with two monitors (of different sizes), arranged side by side:

(display-monitor-attributes-list)
;; ==>
(((geometry 0 0 1920 1080)   ;; Left hand monitor
  (workarea 0 0 1920 1050)   ;; Bottom edge of screen not available
  task bar
  (mm-size 677 381)
  (name . "\\\\.\\DISPLAY1")
  (frames #<frame emacs@ajm-desktop *Ibuffer* 0000000005BBDC48>
          #<frame emacs@ajm-desktop *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)))

The X,Y origin is at top left of the display, which spans both monitors.
The Windows task bar is displayed across the bottom of the left hand
monitor, so that space is reserved for Windows and is not available for
display of emacs frames.

For an emacs frame on the right-hand monitor:

(frame-monitor-attributes)
;; ==>
((geometry 1920 0 1680 1050)
 (workarea 1920 0 1680 1050)
 (mm-size 593 370)
 (name . "\\\\.\\DISPLAY2")
 (frames #<frame emacs@ajm-desktop *scratch* 0000000005C5CC48>))

Does that help ?

    AndyM