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

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

[Drew Adams]

> > Is there no support for multiple monitors on MS Windows?
> 
> There is, but by and large, Emacs will see them as a single large
> desktop.  See here:
> http://msdn.microsoft.com/en-us/library/dd145071%28v=vs.85%29.aspx
> (We don't support the "independent monitors" mode mentioned there.)
> 
> In any case, "multiple monitors" and "multiple displays" are 2
> different issues.  Each display can have multiple monitors.

OK.  Where can one find doc about using multiple monitors with Emacs?

> > I was not able to find out how to obtain info about which monitor
> > is being used to show a particular frame
> 
> The functions you mentioned provide that info, or maybe I don't
> understand what info are you looking for.q

Which function tells you what monitor is showing a given frame (on
MS Windows)?

I should maybe point out that the OP reporting this problem is not on
MS Windows, AFAIK.  My question about Windows was for me, to see if I
could understand the problem even though I am on Windows (and even
though I do not have multiple monitors).

> > how to specify which monitor to use to display a particular frame.
> 
> You can't.
> 
> > The symptom reported was that by modifying a frame's parameters
> > to restore its previous values of `top', `left', `width' and
> > `height', the frame got moved to another monitor, for some
> > reason.
> 
> Probably because the pixel coordinates mapped to that other monitor,
> the URL above explains that, among other things.

I appreciate your replies and your trying to help, but I don't quite
understand you here.  The URL you cite introduces a long chapter.

My Lisp code in question simply does this:

1. If not "maximized" then "maximize", after recording the original
   frame location and size, by setting frame parameters `restore-left',...
   `restore-height' to the original values of parameters `left',...`height'.

2. If "maximized" then use `modify-frame-parameters' to restore
   parameters `left',...`height' to the values saved in parameters
   `restore-left',...`restore-height'.

I put "maximized" in quotes here because the code maximizes not wrt
the screen but the screen possibly minus the space used by a standalone
minibuffer frame.  But that should be an irrelevant detail.

No doubt the problematic code is somewhere in my function
`maximize-frame', which calculates the position and size for maximizing.
It uses either function `mac-display-available-pixel-bounds', if
available, or functions `x-display-pixel-width' and
`x-display-pixel-height'.

I'm guessing that that is the problem (?) - I do not pass the frame as
an argument to `x-display-pixel-*'.  But the doc for those functions
says (since Emacs 20, and still now) that if arg DISPLAY is omitted
then the display of the selected frame is used.  So I would think
that it would not be necessary to pass the selected frame as arg.

You say that a monitor is not a display - OK.  But I do not see
anything that speaks to which monitor gets used.  I am only using
the available display space, as returned by `x-display-pixel-*'.

Dunno what else the problem could be here - i.e., why the newly
repositioned and resized frame would show up on the other monitor.
All the other functions I call here pass the frame explicitly.

In sum, all the code does is either (b) "maximize", by repositioning
and resizing to fit (essentially) what `x-display-pixel-width' and
`x-display-pixel-height' say is the available space or (b) reposition
and resize back to previous `left' etc. settings.  Why the frame ends
up being moved to another monitor is a mystery to me.

This is the full function definition:

(defun frcmds-available-screen-pixel-bounds ()
  "Returns a value of the same form as option `available-screen-pixel-bounds'.
This represents the currently available screen area."
  (or available-screen-pixel-bounds     ; Use the option, if available.
      (if (fboundp 'mac-display-available-pixel-bounds) ; Mac-OS.
          (mac-display-available-pixel-bounds)
        (list 0
              0
              (x-display-pixel-width)
              (x-display-pixel-height)))))

You say "Probably because the pixel coordinates mapped to that other
monitor", and that the URL explains this.  Could you elaborate, or point
me to the section of that chapter that you have in mind?  Do you think
there is something I am not doing that I should be doing, to try to keep
the calculation of the display size to the current monitor?

I understand that on MS Windows the surface of the available monitors
is summed to give the display size.  But (a) I don't think the OP is on
Windows and (b) I don't see how that would be a problem anyway.  It seems
to be (I'm guessing) that the `left' setting is somehow giving a
coordinate that corresponds to, or is being interpreted as, a coordinate
on the other monitor.

Yes, this is verbose, and no, I don't expect that you have the answer to
my coding problem.  If you do have some light to shine on this, however,
then that is appreciated.

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

[Eli Zaretskii]

> Date: Mon, 6 Oct 2014 09:31:00 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 18637@debbugs.gnu.org
> 
> > > Is there no support for multiple monitors on MS Windows?
> > 
> > There is, but by and large, Emacs will see them as a single large
> > desktop.  See here:
> > http://msdn.microsoft.com/en-us/library/dd145071%28v=vs.85%29.aspx
> > (We don't support the "independent monitors" mode mentioned there.)
> > 
> > In any case, "multiple monitors" and "multiple displays" are 2
> > different issues.  Each display can have multiple monitors.
> 
> OK.  Where can one find doc about using multiple monitors with Emacs?

There's nothing to document: they are treated as just one large
monitor.  The only functions we have are in that node you mentioned.

> > > I was not able to find out how to obtain info about which monitor
> > > is being used to show a particular frame
> > 
> > The functions you mentioned provide that info, or maybe I don't
> > understand what info are you looking for.q
> 
> Which function tells you what monitor is showing a given frame (on
> MS Windows)?

frame-monitor-attributes, if I understand what you want.

> > > The symptom reported was that by modifying a frame's parameters
> > > to restore its previous values of `top', `left', `width' and
> > > `height', the frame got moved to another monitor, for some
> > > reason.
> > 
> > Probably because the pixel coordinates mapped to that other monitor,
> > the URL above explains that, among other things.
> 
> I appreciate your replies and your trying to help, but I don't quite
> understand you here.  The URL you cite introduces a long chapter.

Read it and its sections.  You will find the information you want
there.  Skip whatever sounds not relevant or too low-level, and keep
reading.

> Yes, this is verbose, and no, I don't expect that you have the answer to
> my coding problem.  If you do have some light to shine on this, however,
> then that is appreciated.

Read the MSDN documentation I pointed to, the answers are there.

If, after that, you still don't understand what could go wrong with
your code, come back and ask more specific questions with specific
code snippets.  Right now, what you write and ask just shows how much
of the background you are missing to start reasoning about this.

The issues are not complicated once you understand how Windows treats
multiple monitors.

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

[Drew Adams]

> That's my understanding as well, but someone who has access to such
> a system should actually try that and report back.
> 
> > I guess that would mean that frame-position coordinates (`left',
> > `top') are then interpreted relative to that other monitor (?).
> > Is that right?
> 
> No, I think they are "ignored".  That is, the coordinates are
> interpreted in the virtual coordinate system, but then Windows
> decides on its own how to position the frame, using the criterion
> described above.

By "criterion described above, do you mean just based on which monitor
is showing more of the frame?

(Note too that I am using MS Windows, but the OP who reported the
problem is, I think, not on Windows.)

> > Here is what I guess I still do not understand.  Are the values of
> > `left' etc. frame parameters relative to just the virtual display
> > (which is the envelope of all of the monitors, at least on
> > Windows)?
> 
> Yes, according to my reading of the code and the MSDN documentation.
> But again, actually trying that will bring a much more reliable
> information.
> 
> > But if that were the case then I would think that restoring a
> > recorded `left' etc. parameter later would put the frame back
> > where it was, which is apparently not what is happening.
> 
> Except that Windows has its own rules, see above, at least when you
> create a frame that didn't exist (i.e. restore it from information
> recorded in some file).

This code does not create any new frames.  It just calls
`modify-frame-parameters' on an existing frame, setting its `left',
`top', `width', and `height' parameters.

> > The Windows doc you pointed to also says that the primary monitor
> > is not necessarily at the left.  So if `left' etc were not
> > absolute but relative to the monitor origin then maybe this is what
> > happened:
> >
> > 1. The OP had a frame in the left monitor, but the right monitor
> >    was primary.  Since the primary monitor has the virtual screen's
> >    origin at its top left, positions in the left monitor would have
> >    negative horizontal positions.
> >
> >    Dunno whether that means they should also have negative `left'
> >    positions, for Emacs.  If `left' etc. are relative to the
> >    virtual screen then yes, they would.  If `left' etc. is relative
> >    to the current monitor then no, they would not.
> 
> Again, my understanding is that they are relative to the visrtual
> coordinate system.
> 
> > The relevant code snippet is what I sent earlier
> > (`frcmds-available-screen-pixel-bounds'), plus functions
> > `maximize-frame' and `restore-frame', here:
> > http://www.emacswiki.org/emacs-en/download/frame-cmds.el
> >
> > In those two commands I do the following.
> >
> > For `maximize-frame':
> >
> > 1. Save the current `left' etc. as parameters `restore-left' etc.
> > 2. Calculate the available screen size, using
> >    `frcmds-available-screen-pixel-bounds'.
> > 3. Set `left' and `top' both to 0 and `width' and `height' to the
> >    calculated screen size.
> >
> > For `restore-frame':
> >
> > Restore `left' etc. from the saved values `restore-left' etc.
> 
> That's a lot of code, and I have no way of trying it.

If you are interested, you can try it easily, by downloading these
two files:
http://www.emacswiki.org/emacs-en/download/frame-cmds.el
http://www.emacswiki.org/emacs-en/download/frame-fns.el

> I think at this stage it is best for the user in question to try
> some simple code that reports frame coordinates and creates a frame
> given specific coordinates, and then see what that means for us.

I've sent him a mail, but I don't know whether he will have the time
or interest to follow up on this.

> Oh, and I think this is no longer about the docs, so probably a new
> bug report is in order, specifically about restoring frames on
> multi-monitor displays.

Agreed.  And thanks for your input.

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

[Eli Zaretskii]

> Date: Tue, 7 Oct 2014 11:12:56 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 18637@debbugs.gnu.org
> 
> > That's my understanding as well, but someone who has access to such
> > a system should actually try that and report back.
> > 
> > > I guess that would mean that frame-position coordinates (`left',
> > > `top') are then interpreted relative to that other monitor (?).
> > > Is that right?
> > 
> > No, I think they are "ignored".  That is, the coordinates are
> > interpreted in the virtual coordinate system, but then Windows
> > decides on its own how to position the frame, using the criterion
> > described above.
> 
> By "criterion described above, do you mean just based on which monitor
> is showing more of the frame?

Yes.

> (Note too that I am using MS Windows, but the OP who reported the
> problem is, I think, not on Windows.)

Then the problem might be even more complicated than I thought ;-)

> > > But if that were the case then I would think that restoring a
> > > recorded `left' etc. parameter later would put the frame back
> > > where it was, which is apparently not what is happening.
> > 
> > Except that Windows has its own rules, see above, at least when you
> > create a frame that didn't exist (i.e. restore it from information
> > recorded in some file).
> 
> This code does not create any new frames.  It just calls
> `modify-frame-parameters' on an existing frame, setting its `left',
> `top', `width', and `height' parameters.

Then I'd expect it to "just work".  Of course, it doesn't, so there's
some factor or factors at work that we don't understand.

> > That's a lot of code, and I have no way of trying it.
> 
> If you are interested, you can try it easily, by downloading these
> two files:
> http://www.emacswiki.org/emacs-en/download/frame-cmds.el
> http://www.emacswiki.org/emacs-en/download/frame-fns.el

No, I meant I have no access to a system with more than one monitor.

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

[Drew Adams]

> Then I'd expect it to "just work".  Of course, it doesn't, so
> there's some factor or factors at work that we don't understand.

Yeah, me too, on both accounts.

> > > That's a lot of code, and I have no way of trying it.
> >
> > If you are interested, you can try it easily, by downloading these
> > two files:
> > http://www.emacswiki.org/emacs-en/download/frame-cmds.el
> > http://www.emacswiki.org/emacs-en/download/frame-fns.el
> 
> No, I meant I have no access to a system with more than one monitor.

Me neither.

I filed bug #18657 for this issue.

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

[Drew Adams]

> > > In any case, "multiple monitors" and "multiple displays" are 2
> > > different issues.  Each display can have multiple monitors.
> >
> > OK.  Where can one find doc about using multiple monitors with
> > Emacs?
> 
> There's nothing to document: they are treated as just one large
> monitor.  The only functions we have are in that node you mentioned.
>
> > > > I was not able to find out how to obtain info about which
> > > > monitor is being used to show a particular frame
> > >
> > > The functions you mentioned provide that info, or maybe I don't
> > > understand what info are you looking for.q
> >
> > Which function tells you what monitor is showing a given frame (on
> > MS Windows)?
> 
> 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'?

> > > > The symptom reported was that by modifying a frame's
> > > > parameters to restore its previous values of `top', `left',
> > > > `width' and `height', the frame got moved to another monitor,
> > > > for some reason.
> > >
> > > Probably because the pixel coordinates mapped to that other
> > > monitor, the URL above explains that, among other things.
> >
> > I appreciate your replies and your trying to help, but I don't
> > quite understand you here.  The URL you cite introduces a long
> > chapter.
> 
> Read it and its sections.  You will find the information you want
> there.  Skip whatever sounds not relevant or too low-level, and keep
> reading. Read the MSDN documentation I pointed to, the answers are there.
> 
> If, after that, you still don't understand what could go wrong with
> your code, come back and ask more specific questions with specific
> code snippets.  Right now, what you write and ask just shows how
> much of the background you are missing to start reasoning about this.
> 
> The issues are not complicated once you understand how Windows
> treats multiple monitors.

OK.

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

[Drew Adams]

In (elisp) `Basic Parameters' I see this description of frame parameter
`display':

  The display on which to open this frame.  It should be a string of
  the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
  variable.

But if I evaluate `(frame-parameters)' on MS Windows I see this value
for parameter `display': "w32".

"w32" does not seem to fit the form `"HOST:DPY.SCREEN"'.  What gives?

And why is that string surrounded by `...'?  And why aren't the
components of that "form" described: What are acceptable values for
HOST, DPY, and SCREEN?

(I assume that the `:' and `.' are to be taken literally here, and that
HOST, DPY, and SCREEN are placeholders, although there is zero
explanation of this.)

Also, I searched the manual case-sensitively for DISPLAY, and found no description/specification/explanation of "the `DISPLAY' environment variable.  So referring users to that env var to find a specification
of the form `"HOST:DPY.SCREEN"' is unhelpful and misleading.

Please clear up this doc - make it properly specify what form the value
of parameter `display' takes.


In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-09-15 on LEG570
Bzr revision: 117884 dancol@dancol.org-20140915050944-sqsajysnwef51f9m
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking 'CFLAGS=-O0 -g3' CPPFLAGS=-DGLYPH_DEBUG=1'

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

[Eli Zaretskii]

> Date: Sun, 5 Oct 2014 12:23:34 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> In (elisp) `Basic Parameters' I see this description of frame parameter
> `display':
> 
>   The display on which to open this frame.  It should be a string of
>   the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
>   variable.
> 
> But if I evaluate `(frame-parameters)' on MS Windows I see this value
> for parameter `display': "w32".
> 
> "w32" does not seem to fit the form `"HOST:DPY.SCREEN"'.  What gives?

Emacs on MS-Windows doesn't support the notion of 'display', so all
frames return the same value of that parameter.

> And why is that string surrounded by `...'?

An artifact of Texinfo markup.

> And why aren't the components of that "form" described: What are
> acceptable values for HOST, DPY, and SCREEN?

Users on X already know what they are; users on other systems don't
need to know, because this is not supported.  Either way, this notion
is not an Emacs invention, it is a feature of the X window system.

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

[Eli Zaretskii]

> Date: Sun, 05 Oct 2014 22:30:22 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 18637@debbugs.gnu.org
> 
> > Date: Sun, 5 Oct 2014 12:23:34 -0700 (PDT)
> > From: Drew Adams <drew.adams@oracle.com>
> > 
> > In (elisp) `Basic Parameters' I see this description of frame parameter
> > `display':
> > 
> >   The display on which to open this frame.  It should be a string of
> >   the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
> >   variable.

Btw, this is not the best place in the manual to read about this.  A
better one is "Multiple Terminals", where it says explicitly that this
is only relevant on X.  The index entry "displays, multiple" leads to
that node.

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

[Andy Moreton]

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

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

[Drew Adams]

> Does that help ?

Yes, the example helps me understand.  Thanks.

My comment, however, was that none of this is documented.
It should be.  What `geometry' and `workarea' mean should
be specified.

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

[Andy Moreton]

On Tue 07 Oct 2014, Eli Zaretskii wrote:

>> The relevant code snippet is what I sent earlier
>> (`frcmds-available-screen-pixel-bounds'), plus functions
>> `maximize-frame' and `restore-frame', here:
>> http://www.emacswiki.org/emacs-en/download/frame-cmds.el> 
>> In those two commands I do the following.
>> 
>> For `maximize-frame':
>> 
>> 1. Save the current `left' etc. as parameters `restore-left' etc.
>> 2. Calculate the available screen size, using
>>    `frcmds-available-screen-pixel-bounds'.
>> 3. Set `left' and `top' both to 0 and `width' and `height' to the
>>    calculated screen size.
>> 
>> For `restore-frame':
>> 
>> Restore `left' etc. from the saved values `restore-left' etc.
>
> That's a lot of code, and I have no way of trying it.

I have a multi-monitor system, but I'm not going to perform experiments
without a clearer recipe. I did try rearranging the physical monitor
layout as follows (which makes it quite easy to lose the position of the
cursor). Things may get more confusing with three or more monitors...

;; Two monitors arranged physically as:
;;  +---------+
;;  |         |
;;  |    2    |+---------+
;;  |         ||         |
;;  +---------+|    1    |
;;             |         |
;;             +---------+
(display-monitor-attributes-list)
;; ==>
(((geometry 0 0 1920 1080)
  (workarea 0 0 1920 1050)
  (mm-size 677 381)
  (name . "\\\\.\\DISPLAY1")
  (frames))
 ((geometry -1680 -646 1680 1050)
  (workarea -1680 -646 1680 1050)
  (mm-size 593 370)
  (name . "\\\\.\\DISPLAY2")
  (frames)))

(display-pixel-height)  ;; ==> 1726
(display-pixel-width)   ;; ==> 3600

(display-mm-height)     ;; ==>  609
(display-mm-width)      ;; ==> 1269

> I think at this stage it is best for the user in question to try some
> simple code that reports frame coordinates and creates a frame given
> specific coordinates, and then see what that means for us.
>
> Oh, and I think this is no longer about the docs, so probably a new
> bug report is in order, specifically about restoring frames on
> multi-monitor displays.

True, as long as the meaning of geometry/workarea and the coordinate
system are given a little more detail in the docs.

    AdnyM

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

[Drew Adams]

> I have a multi-monitor system, but I'm not going to perform
> experiments without a clearer recipe. I did try rearranging the physical
> monitor layout as follows (which makes it quite easy to lose the position
> of the cursor). Things may get more confusing with three or more monitors...
> 
> ;; Two monitors arranged physically as:
> ;;  +---------+
> ;;  |         |
> ;;  |    2    |+---------+
> ;;  |         ||         |
> ;;  +---------+|    1    |
> ;;             |         |
> ;;             +---------+
> (display-monitor-attributes-list)
> ;; ==>
> (((geometry 0 0 1920 1080)
>   (workarea 0 0 1920 1050)
>   (mm-size 677 381)
>   (name . "\\\\.\\DISPLAY1")
>   (frames))
>  ((geometry -1680 -646 1680 1050)
>   (workarea -1680 -646 1680 1050)
>   (mm-size 593 370)
>   (name . "\\\\.\\DISPLAY2")
>   (frames)))
> 
> (display-pixel-height)  ;; ==> 1726
> (display-pixel-width)   ;; ==> 3600
> 
> (display-mm-height)     ;; ==>  609
> (display-mm-width)      ;; ==> 1269

Thanks for the offer, Andy.  I don't have a better recipe to give,
unfortunately.  I've mentioned in this thread all of the info I have.

I think it might be enough if you tried the `maximize-frame' and
`restore-frame' commands in frame-cmds.el, especially if (I'm
guessing, based on the conversation with Eli) you have one monitor
that is smaller than the other.

It sounds like perhaps you will see a frame that you maximize or
restore this way jump from one frame to another.  Perhaps that will
happen more if most of the frame before the operation is in fact
shown on the other frame.

But the OP did not mention that.  His report seemed to suggest that
the frame was shown completely in one frame and then jumped to
another frame when it was maximized (or restored?).

The frame-cmds.el code just changes frame parameters `left', `top',
`width', and `height'.  In principle, restoring just resets the
original values for these, and maximizing sets them to values that
fill the screen (which is not necessarily the same thing as the
monitor).

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

[Eli Zaretskii]

> Date: Mon, 6 Oct 2014 10:25:31 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 18637@debbugs.gnu.org
> 
> > > Which function tells you what monitor is showing a given frame (on
> > > MS Windows)?
> > 
> > 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.

If you need to distinguish them, which should be very rarely.

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

I guess it's optional because not all windowing systems support it.
It is always present on MS-Windows, AFAIK.

> 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'?

Depends on what you need this for.

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

[Drew Adams]

> > Read it and its sections.  You will find the information you want
> > there.  Skip whatever sounds not relevant or too low-level, and
> > keep reading. Read the MSDN documentation I pointed to, the answers
> > are there.

I read it all.

The closest thing I noticed as relevant to my question was the 2 bits
below, in Multiple Display Monitors > About Multiple Display Monitors
> Positioning Objects on Multiple Display Monitors:

1.

 CreateWindow(Ex) displays a window on the monitor that contains the
 largest part of the window.  Maximizes on the monitor that contains the
 largest part of the window before it was minimized.

I gather from that that perhaps the problem is that a larger portion
of the displayed frame might be on the other monitor, in which case
the frame gets displayed (only?) on the other monitor.  I guess that
would mean that frame-position coordinates (`left', `top') are then
interpreted relative to that other monitor (?).  Is that right?

2.

 To position an object on a multiple monitor system

   1. Determine the appropriate monitor.
   2. Get the coordinates to the monitor.
   3. Position the object using the coordinates.

This suggests that the position of the desired (target) monitor
needs to be added to the frame position, to get it to be on the
intended monitor.

Was that your point?

Here is what I guess I still do not understand.  Are the values of
`left' etc. frame parameters relative to just the virtual display
(which is the envelope of all of the monitors, at least on Windows)?
In that case they would be essentially absolute and not depend on
which monitor the frame is shown in.

That is what I would expect, from the fact that Emacs just "sees a
single large desktop", as Stefan put it.

But if that were the case then I would think that restoring a
recorded `left' etc. parameter later would put the frame back where
it was, which is apparently not what is happening.

On the other hand, if `left' etc. are relative to the monitor in
which the frame is shown then I guess my code would need to add the
monitor position and size, to give coordinates that are absolute
(i.e., relative to the virtual display, aka "desktop").

The Windows doc you pointed to also says that the primary monitor
is not necessarily at the left.  So if `left' etc were not absolute
but relative to the monitor origin then maybe this is what happened:

1. The OP had a frame in the left monitor, but the right monitor was
   primary.  Since the primary monitor has the virtual screen's origin
   at its top left, positions in the left monitor would have negative
   horizontal positions.

   Dunno whether that means they should also have negative `left'
   positions, for Emacs.  If `left' etc. are relative to the virtual 
   screen then yes, they would.  If `left' etc. is relative to the
   current monitor then no, they would not.

2. My maximize/restore code stored the values of `left' etc. for
   later restore/maximize, but if these values are relative to the
   current monitor, when restored they might be interpreted as
   relative to the primary monitor (since no monitor is specified).
   So the frame would jump to the monitor on the right.

Is that possible?  If so, why wouldn't the monitor for the frame
remain the same?  What determines which monitor gets used?

> > If, after that, you still don't understand what could go wrong
> > with your code, come back and ask more specific questions with specific
> > code snippets.  Right now, what you write and ask just shows how
> > much of the background you are missing to start reasoning about
> > this.
> >
> > The issues are not complicated once you understand how Windows
> > treats multiple monitors.

Hopefully you can see from the above a little more clearly what I
still misunderstand.  And hopefully you will be able to help me
understand a bit better.

The relevant code snippet is what I sent earlier
(`frcmds-available-screen-pixel-bounds'), plus functions
`maximize-frame' and `restore-frame', here:
http://www.emacswiki.org/emacs-en/download/frame-cmds.el

In those two commands I do the following.

For `maximize-frame':

1. Save the current `left' etc. as parameters `restore-left' etc.
2. Calculate the available screen size, using
   `frcmds-available-screen-pixel-bounds'.
3. Set `left' and `top' both to 0 and `width' and `height' to the
   calculated screen size.

For `restore-frame':

Restore `left' etc. from the saved values `restore-left' etc.

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

[Eli Zaretskii]

> Date: Mon, 6 Oct 2014 13:52:17 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 18637@debbugs.gnu.org
> 
> The closest thing I noticed as relevant to my question was the 2 bits
> below, in Multiple Display Monitors > About Multiple Display Monitors
> > Positioning Objects on Multiple Display Monitors:
> 
> 1.
> 
>  CreateWindow(Ex) displays a window on the monitor that contains the
>  largest part of the window.  Maximizes on the monitor that contains the
>  largest part of the window before it was minimized.
> 
> I gather from that that perhaps the problem is that a larger portion
> of the displayed frame might be on the other monitor, in which case
> the frame gets displayed (only?) on the other monitor.

That's my understanding as well, but someone who has access to such a
system should actually try that and report back.

> I guess that would mean that frame-position coordinates (`left',
> `top') are then interpreted relative to that other monitor (?).  Is
> that right?

No, I think they are "ignored".  That is, the coordinates are
interpreted in the virtual coordinate system, but then Windows decides
on its own how to position the frame, using the criterion described
above.

> 2.
> 
>  To position an object on a multiple monitor system
> 
>    1. Determine the appropriate monitor.
>    2. Get the coordinates to the monitor.
>    3. Position the object using the coordinates.
> 
> This suggests that the position of the desired (target) monitor
> needs to be added to the frame position, to get it to be on the
> intended monitor.

But I think this is not enough: you need also make sure the size of
the frame is such as to cause Windows decide to actually place the
frame on that monitor.  Because if the size is such that the largest
portion of the window is on another monitor, you won't get what you
want.

Again, something to play with and report.

> Here is what I guess I still do not understand.  Are the values of
> `left' etc. frame parameters relative to just the virtual display
> (which is the envelope of all of the monitors, at least on Windows)?

Yes, according to my reading of the code and the MSDN documentation.
But again, actually trying that will bring a much more reliable
information.

> But if that were the case then I would think that restoring a
> recorded `left' etc. parameter later would put the frame back where
> it was, which is apparently not what is happening.

Except that Windows has its own rules, see above, at least when you
create a frame that didn't exist (i.e. restore it from information
recorded in some file).

> The Windows doc you pointed to also says that the primary monitor
> is not necessarily at the left.  So if `left' etc were not absolute
> but relative to the monitor origin then maybe this is what happened:
> 
> 1. The OP had a frame in the left monitor, but the right monitor was
>    primary.  Since the primary monitor has the virtual screen's origin
>    at its top left, positions in the left monitor would have negative
>    horizontal positions.
> 
>    Dunno whether that means they should also have negative `left'
>    positions, for Emacs.  If `left' etc. are relative to the virtual 
>    screen then yes, they would.  If `left' etc. is relative to the
>    current monitor then no, they would not.

Again, my understanding is that they are relative to the visrtual
coordinate system.

> The relevant code snippet is what I sent earlier
> (`frcmds-available-screen-pixel-bounds'), plus functions
> `maximize-frame' and `restore-frame', here:
> http://www.emacswiki.org/emacs-en/download/frame-cmds.el
> 
> In those two commands I do the following.
> 
> For `maximize-frame':
> 
> 1. Save the current `left' etc. as parameters `restore-left' etc.
> 2. Calculate the available screen size, using
>    `frcmds-available-screen-pixel-bounds'.
> 3. Set `left' and `top' both to 0 and `width' and `height' to the
>    calculated screen size.
> 
> For `restore-frame':
> 
> Restore `left' etc. from the saved values `restore-left' etc.

That's a lot of code, and I have no way of trying it.

I think at this stage it is best for the user in question to try some
simple code that reports frame coordinates and creates a frame given
specific coordinates, and then see what that means for us.

Oh, and I think this is no longer about the docs, so probably a new
bug report is in order, specifically about restoring frames on
multi-monitor displays.

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

[Drew Adams]

> > > In (elisp) `Basic Parameters' I see this description of frame
> > > parameter `display':
> > >
> > >   The display on which to open this frame.  It should be a
> > >   string of the form `"HOST:DPY.SCREEN"', just like the
> > >   `DISPLAY' environment variable.
> 
> Btw, this is not the best place in the manual to read about this.
> A better one is "Multiple Terminals", where it says explicitly
> that this is only relevant on X.  The index entry "displays,
> multiple" leads to that node.

As a matter of fact, that is the node I started with, when trying
to find out about such things.  Please see this help-gnu-emacs
thread, where I mention that node and provide some context.
http://lists.gnu.org/archive/html/help-gnu-emacs/2014-10/msg00099.html

Is there no support for multiple monitors on MS Windows?  That's
really what I was looking for info about, along with general info
about Emacs display on multiple monitors.  When looking, I came
across the doc for `display-monitor-attributes-list' and
`frame-monitor-attributes'.

I was not able to find out how to obtain info about which monitor
is being used to show a particular frame, or how to specify
which monitor to use to display a particular frame.

The symptom reported was that by modifying a frame's parameters
to restore its previous values of `top', `left', `width' and
`height', the frame got moved to another monitor, for some
reason.

I don't have multiple monitors, to try things out, but I was
looking for some info in the manual that might explain what the
OP reports.

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

[Eli Zaretskii]

> Date: Sun, 5 Oct 2014 19:55:48 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 18637@debbugs.gnu.org
> 
> Is there no support for multiple monitors on MS Windows?

There is, but by and large, Emacs will see them as a single large
desktop.  See here:

  http://msdn.microsoft.com/en-us/library/dd145071%28v=vs.85%29.aspx

(We don't support the "independent monitors" mode mentioned there.)

In any case, "multiple monitors" and "multiple displays" are 2
different issues.  Each display can have multiple monitors.

> I was not able to find out how to obtain info about which monitor
> is being used to show a particular frame

The functions you mentioned provide that info, or maybe I don't
understand what info are you looking for.q

> how to specify which monitor to use to display a particular frame.

You can't.

> The symptom reported was that by modifying a frame's parameters
> to restore its previous values of `top', `left', `width' and
> `height', the frame got moved to another monitor, for some
> reason.

Probably because the pixel coordinates mapped to that other monitor,
the URL above explains that, among other things.

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

[Stefan Monnier]

> Each display can have multiple monitors.

Indeed, and for that reason, Emacs sees a single large desktop under X11
as well.


        Stefan

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

[Drew Adams]

> > In (elisp) `Basic Parameters' I see this description of frame
> > parameter `display':
> >
> >   The display on which to open this frame.  It should be a string
> >   of the form `"HOST:DPY.SCREEN"', just like the `DISPLAY'
> >   environment variable.
> >
> > But if I evaluate `(frame-parameters)' on MS Windows I see this
> > value for parameter `display': "w32".
> >
> > "w32" does not seem to fit the form `"HOST:DPY.SCREEN"'.  What
> > gives?
> 
> Emacs on MS-Windows doesn't support the notion of 'display', so all
> frames return the same value of that parameter.

OK, then the doc should mention this, or at least say that the
string might not take the form "HOST:DPY.SCREEN" on some platforms,
and preferably say something about what to expect on the
exceptional platforms (and perhaps give some idea of what use the
exceptional value is - what it can be used for, or what info it
conveys).

> > And why is that string surrounded by `...'?
> 
> An artifact of Texinfo markup.

I see.  Is that then correct, or should the `...' be absent?
There are strings in the manual that are not surrounded by `...'.

> > And why aren't the components of that "form" described: What are
> > acceptable values for HOST, DPY, and SCREEN?
> 
> Users on X already know what they are; users on other systems don't
> need to know, because this is not supported.  Either way, this
> notion is not an Emacs invention, it is a feature of the X
> window system.

Then please say that.  E.g., say that the value is useful only for
X Window, or only relevant for it.  If the function itself has no
use beyond X Window, then please make that clear.