Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 465 bytes --]

The doc string for select-window does not discuss the sometime need to also
set input focus to the selected window's frame when one wants future input
events to go there.  I would suggest adding this along with a reference to
select-frame-set-input-focus.

Even better might be to add select-frame-window which would combine
select-window and select-frame-set-input-focus for those times where you
want to both select the frame and change its selected window.

Bob

[-- Attachment #2: Type: text/html, Size: 1058 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 867 bytes --]

On Tue, Dec 12, 2017 at 10:39 AM, Robert Weiner <rsw@gnu.org> wrote:

> The doc string for select-window does not discuss the sometime need to
> also set input focus to the selected window's frame when one wants future
> input events to go there.  I would suggest adding this along with a
> reference to select-frame-set-input-focus.
>
> Even better might be to add select-frame-window which would combine
> select-window and select-frame-set-input-focus for those times where you
> want to both select the frame and change its selected window.
>

​The same issue exists with save-selected-window except that it applies to
the start selected window rather than a new one.  Another macro,
save-selected-frame-window, would keep input from switching to another
frame within its scope since this is not part of save-selected-window's
behavior.

Bob

[-- Attachment #2: Type: text/html, Size: 1903 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 308 bytes --]

On Tue, Dec 12, 2017 at 1:13 PM, Robert Weiner <rsw@gnu.org> wrote:

> Another macro, save-selected-frame-window, would keep input from switching
> to another frame within its scope since this is not part of
> save-selected-window's behavior.
>

​save-selected-frame would be a better name.

Bob

[-- Attachment #2: Type: text/html, Size: 1269 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Stefan Monnier]

> Even better might be to add select-frame-window which would combine
> select-window and select-frame-set-input-focus for those times where you
> want to both select the frame and change its selected window.

"selected" and "has focus" are fundamentally technically independent,
even though in practice they are strongly correlated.  So it's natural
for users to get confused about these issues, and we should be extra
careful in our terminology to try and not make this confusion worse.

So if you want a function which modifies focus, it should not be called
select-frame-window: it needs to have "focus" in its name.


        Stefan

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Stefan Monnier]

> ​The same issue exists with save-selected-window except that it applies to
> the start selected window rather than a new one.  Another macro,
> save-selected-frame-window, would keep input from switching to another
> frame within its scope since this is not part of save-selected-window's
> behavior.

You mean some kind of `save-frame-focus` macro (tho that name itself
can be confusing since it seems to refer to `frame-focus` which is yet
another kettle of fish)?

"Manually" changing focus should be something done very rarely in Elisp,
so why/when would you need to use something like `save-frame-focus`?


        Stefan

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 546 bytes --]

On Tue, Dec 12, 2017 at 3:37 PM, Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

>
> So if you want a function which modifies focus, it should not be called
> select-frame-window: it needs to have "focus" in its name.
>

​Similarly, the doc for select-frame should include something
on how to change input focus. It mentions input focus but
doesn't say how to affect it.

Sounds like we would need to call this new function:

   select-window-set-input-focus

which would parallel select-frame-set-input-focus nicely.

Bob

[-- Attachment #2: Type: text/html, Size: 1949 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 1275 bytes --]

On Tue, Dec 12, 2017 at 3:40 PM, Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > ​The same issue exists with save-selected-window except that it applies
> to
> > the start selected window rather than a new one.  Another macro,
> > save-selected-frame-window, would keep input from switching to another
> > frame within its scope since this is not part of save-selected-window's
> > behavior.
>
> You mean some kind of `save-frame-focus` macro (tho that name itself
> can be confusing since it seems to refer to `frame-focus` which is yet
> another kettle of fish)?
>

​Yes, save-input-focus or save-frame-input-focus for consistency with other
naming.​

​​
>
> ​​
> "Manually" changing focus should be something done very rarely in Elisp,
> ​​
> so why/when would you need to use something like `save-frame-focus`?
>

​Hyperbole has a feature that lets you either drag a dired item (or other
item type)
to another frame (input switches to that frame) or throw the dired item to
another
frame (input stays in the same frame).  The throw command calls the drag
command
to reuse its logic, since it is fairly involved and doesn't make sense to
duplicate,
but then needs to restore the focus to original frame.

Bob

[-- Attachment #2: Type: text/html, Size: 2972 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Stefan Monnier]

> ​Hyperbole has a feature that lets you either drag a dired item (or
> other item type) to another frame (input switches to that frame) or
> throw the dired item to another frame (input stays in the same frame).
> The throw command calls the drag command to reuse its logic, since it
> is fairly involved and doesn't make sense to duplicate, but then needs
> to restore the focus to original frame.

Wouldn't it make sense to solve this by doing it the other around:
implement drag on top of throw?

The kind of "undo" we get from save-excursion and friends is very handy
and powerful, but in many cases "undoing" is either very difficult or
even impossible (e.g. save-window-excursion can undo changes to the
current frame, but there is simply no way to implement the equivalent
for frames, because once a frame is created the user has seen it (and
in my case, had to position it with his mouse) and once a frame has been
deleted you've lost some of the information attached to it which Emacs
can't recreate because it's specific to your particular window-manager).

When you request to change the focus, the window-manager may immediately
execute some user-visible action, so you can't fully "undo" it.


        Stefan

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[martin rudalics]

 > The doc string for select-window does not discuss the sometime need to also
 > set input focus to the selected window's frame when one wants future input
 > events to go there.  I would suggest adding this along with a reference to
 > select-frame-set-input-focus.

`select-window' is a function with immediate effect so we can give it a
self-contained doc-string and description.

`select-frame-set-input-focus' OTOH lumps together three things: It
selects a frame and thus implicitly its selected window and tells the
window manager to raise that frame and to give it input focus.  The
latter two do not have immediate effect, they induce a delay and require
a cooperating window manager.  (Raising the frame is a bad idea IMHO but
admittedly a compromise to accommodate the standard behavior of most
existing window managers.)

So the reference you suggest would have to be accompanied by an
explanation of delays and a reference to the window manager.  Such
explanation would make the doc-string quite complex (and we're not even
talking about redirected frame focus yet).

So I think that people who need information about how to raise a frame
or giving it input focus should look into the Elisp manual.

 > Even better might be to add select-frame-window which would combine
 > select-window and select-frame-set-input-focus for those times where you
 > want to both select the frame and change its selected window.

But `select-window' does select the window's frame.

martin

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Stefan Monnier]

> `select-window' is a function with immediate effect so we can give it a
> self-contained doc-string and description.
[...]
> So I think that people who need information about how to raise a frame
> or giving it input focus should look into the Elisp manual.

I don't think select-window should explain what
select-frame-set-input-focus does, indeed.  But I think it'd be OK for
it to make it clear that it doesn't directly affect focus, with a link
to another function that does.


        Stefan

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 1220 bytes --]

On Wed, Dec 13, 2017 at 8:37 AM, Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > `select-window' is a function with immediate effect so we can give it a
> > self-contained doc-string and description.
> [...]
> > So I think that people who need information about how to raise a frame
> > or giving it input focus should look into the Elisp manual.
>
> I don't think select-window should explain what
> select-frame-set-input-focus does, indeed.  But I think it'd be OK for
> it to make it clear that it doesn't directly affect focus, with a link
> to another function that does.
>

​Agreed.  It is natural for people to start programming things in Emacs
with a single frame and multiple windows.  As they expand their knowledge
to multiple frames and selecting a window in another frame, they'll want to
know the extent of what select-window handles and what it doesn't.  Their
could be simple explanations and references on input focus like:

Although this selects the window's frame, it does not alter the frame's
position in the window stack (see `raise-frame') nor does it direct input
focus to that frame.
To do both of those at once, see `select-frame-set-input-focus'.

Bob
​

[-- Attachment #2: Type: text/html, Size: 2348 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 2181 bytes --]

On Wed, Dec 13, 2017 at 3:49 AM, martin rudalics <rudalics@gmx.at> wrote:

> > The doc string for select-window does not discuss the sometime need to
> also
> > set input focus to the selected window's frame when one wants future
> input
> > events to go there.  I would suggest adding this along with a reference
> to
> > select-frame-set-input-focus.
>
> `select-window' is a function with immediate effect so we can give it a
> self-contained doc-string and description.
>
> `select-frame-set-input-focus' OTOH lumps together three things: It
> selects a frame and thus implicitly its selected window and tells the
> window manager to raise that frame and to give it input focus.  The
> latter two do not have immediate effect, they induce a delay and require
> a cooperating window manager.  (Raising the frame is a bad idea IMHO but
> admittedly a compromise to accommodate the standard behavior of most
> existing window managers.)
>
> So the reference you suggest would have to be accompanied by an
> explanation of delays and a reference to the window manager.
>

Delays and interaction with the window manager are lower-level
implementation details that could be covered in the Elisp manual
as you say, rather than the doc string.

The overriding issue is that the general concept of selecting an
editable window in most systems would include input focus going
to that window.  In Emacs, this is true in a single frame session
where selecting a window makes any following input characters go
to the window's buffer.  So new and even experienced Elisp
programmers could easily assume that selecting a window in another
frame would behave similarly.  It does not because as you note,
the situation is more complex.

So this needs to be pointed out to people when they first look at
the doc string for select-window.  Yet there is no need in the doc
string to talk about delays (any modern system will respond pretty
responsively to such requests) nor to get into window system details
other than to mention raising windows and directing input focus along
with the associated functions, as I noted in my prior message.

Bob
​

[-- Attachment #2: Type: text/html, Size: 4344 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[martin rudalics]

 > Although this selects the window's frame, it does not alter the frame's
 > position in the window stack (see `raise-frame') nor does it direct input
 > focus to that frame.
 > To do both of those at once, see `select-frame-set-input-focus'.

We can add that but I'll rather let Eli decide whether it's useful.

martin

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii]

> Date: Wed, 13 Dec 2017 20:29:46 +0100
> From: martin rudalics <rudalics@gmx.at>
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
>  > Although this selects the window's frame, it does not alter the frame's
>  > position in the window stack (see `raise-frame') nor does it direct input
>  > focus to that frame.
>  > To do both of those at once, see `select-frame-set-input-focus'.
> 
> We can add that but I'll rather let Eli decide whether it's useful.

I generally consider this to be a futile waste of energy, as it can
never work reliably with all the window managers out there.  It is
much easier either to install the WM which behaves as you want, or
make an Emacs key binding to do that.

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Stefan Monnier]

>> > Although this selects the window's frame, it does not alter the frame's
>> > position in the window stack (see `raise-frame') nor does it direct input
>> > focus to that frame.
>> > To do both of those at once, see `select-frame-set-input-focus'.
>> We can add that but I'll rather let Eli decide whether it's useful.
> I generally consider this to be a futile waste of energy, as it can
> never work reliably with all the window managers out there.  It is
> much easier either to install the WM which behaves as you want, or
> make an Emacs key binding to do that.

Not sure what "that" refers to in this last sentence.
The proposal is just to add the above paragraph (or something similar)
to the docstring of select-window to clarify that select-window doesn't
affect frame focus.


        Stefan

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Wed, 13 Dec 2017 17:10:32 -0500
> Cc: martin rudalics <rudalics@gmx.at>, rswgnu@gmail.com, emacs-devel@gnu.org
> 
> >> > Although this selects the window's frame, it does not alter the frame's
> >> > position in the window stack (see `raise-frame') nor does it direct input
> >> > focus to that frame.
> >> > To do both of those at once, see `select-frame-set-input-focus'.
> >> We can add that but I'll rather let Eli decide whether it's useful.
> > I generally consider this to be a futile waste of energy, as it can
> > never work reliably with all the window managers out there.  It is
> > much easier either to install the WM which behaves as you want, or
> > make an Emacs key binding to do that.
> 
> Not sure what "that" refers to in this last sentence.
> The proposal is just to add the above paragraph (or something similar)
> to the docstring of select-window to clarify that select-window doesn't
> affect frame focus.

My misunderstanding, sorry.

But if the issue is documentation, why not show a proposed patch?
That'd make clear what is being proposed, because discussing
documentation changes without a concrete proposal is not an efficient
way of making such decisions.

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 509 bytes --]

On Wed, Dec 13, 2017 at 10:33 PM, Eli Zaretskii <eliz@gnu.org> wrote:

>
> My misunderstanding, sorry.
>
> But if the issue is documentation, why not show a proposed patch?
>

​I did with this suggested addition to select-window's doc string:

"Although this selects the window's frame, it does not alter the
frame's position in the window stack (see `raise-frame') nor does
it direct input focus to that frame.  To do both of those at once,
see `select-frame-set-input-focus'.

Bob​
​

[-- Attachment #2: Type: text/html, Size: 2155 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii]

> From: Robert Weiner <rsw@gnu.org>
> Date: Thu, 14 Dec 2017 10:01:03 -0500
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, martin rudalics <rudalics@gmx.at>, 
> 	emacs-devel <emacs-devel@gnu.org>
> 
> ​I did with this suggested addition to select-window's doc string:
> 
> "Although this selects the window's frame, it does not alter the
> frame's position in the window stack (see `raise-frame') nor does
> it direct input focus to that frame.  To do both of those at once,
> see `select-frame-set-input-focus'.

Sorry, I don't see how input focus or frame position in z-order are
related to selecting a window.  Input focus is per-frame, not
per-window.  Someone who looks for information about focus or z-order
will look for frame-related stuff, not window-related stuff.

I could perhaps agree to a note in the manual where select-window is
described, but even there this information looks too far-fetched and
out of its natural place.

Maybe you could explain how you arrived at considering input focus and
z-order while using select-window.  Perhaps that would help me
understand the connection, because right now I see none.

Thanks.

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 1029 bytes --]

What I really want and think is needed is a simpler programming model when
multiple frames are involved.

I want something window-related with the simplicity of select-window and
with-selected-window but that
handles the complexities of multiple frames and asynchronous window
managers internally dealing with:
  window selection
  frame selection (already built-in to select-window)
  input focus
  and redisplay.

So if we had mega-select-window (whatever it is called), it would select
the desired window and its frame,
switch input focus there and force a redisplay for that window.
mega-with-selected-window would be similar
but in macro form, handling arbitrary bodies.

Does anyone else see a need for something like this or am I the only one
that finds there are too many gotchas
and complexities in dealing with combinations of these issues right now?

Bob

​(I will get back to expanding the doc for select-window later but I wanted
to give you the broader view of what
triggered this).​

[-- Attachment #2: Type: text/html, Size: 2526 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Stefan Monnier]

> Does anyone else see a need for something like this or am I the only one
> that finds there are too many gotchas
> and complexities in dealing with combinations of these issues right now?

I think we're generally better off embracing the idea that it's not
Emacs's job to decide how to handle focus and window stacking.

Because the problems with focus and such don't all have to do with
technicalities of how the APIs work, but also with interaction about the
specific focus policy that the user may have chosen in his
window-manager (as well as with the frame/window management policies he
has setup in his display-buffer-alist).


        Stefan

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 2987 bytes --]

On Thu, Dec 14, 2017 at 8:42 PM, Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > Does anyone else see a need for something like this or am I the only one
> > that finds there are too many gotchas
> > and complexities in dealing with combinations of these issues right now?
>
> I think we're generally better off embracing the idea that it's not
> Emacs's job to decide how to handle focus and window stacking.
>

It would be nice, but my experience has been that doing so just
leads to window-based commands that don't work well or properly
in a multi-frame environment.

​​
> Because the problems with focus and such don't all have to do with
> ​​
> technicalities of how the APIs work, but also with interaction about the
> ​​
> specific focus policy that the user may have chosen in his
> ​​
> window-manager (as well as with the frame/window management policies he
> ​​
> has setup in his display-buffer-alist).
> ​
>

Good point.  But I still think the idea of selected-window could
be better defined in a multi-frame environment as well as the
concept of "where editing takes place".

​From the Basic Concepts of Emacs Windows section of the Elisp Manual:

'In each frame, at any time, exactly one Emacs window is designated as
“selected within the frame”.  For the selected frame, that window is
called the “selected window”—the one in which most editing takes place,
and in which the cursor for selected windows appears (*note Cursor
Parameters::).  The selected window’s buffer is usually also the current
buffer, except when ‘set-buffer’ has been used (*note Current Buffer::).
As for non-selected frames, the window selected within the frame becomes
the selected window if the frame is ever selected.  *Note Selecting
Windows::.'

So if I programmatically select-window in a frame that does not have or gain
input focus, will most editing take place there?  Programmatic editing
commands
generally will and user editing commands will not.  So it depends what you
consider
"most editing" which I think remains undefined, right?  Maybe there is
another
as yet undefined idea in there of interactive window selection where input
focus
does shift.

At the very least, the basic sequence of calls to select an arbitrary window
for user editing should be explained both here and in the select-window
function,
since someone thinking about windows and buffers isn't likely to reference
frame-related documentation even though input focus is a frame-related
concept.
Just as someone concerned with whether it will rain today listens to a
weather
report and doesn't look up the technicalities of local cloud accumulation.
Yes,
there are complexities here but I believe it is possible to abstract a bit
more and
handle basic cases better so that multi-frame window handling can be
programmed more
like single frame window handling for the vast majority of cases.

Bob

[-- Attachment #2: Type: text/html, Size: 6169 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 895 bytes --]

On Thu, Dec 14, 2017 at 10:01 AM, Robert Weiner <rsw@gnu.org> wrote:

> On Wed, Dec 13, 2017 at 10:33 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>
>>
>> My misunderstanding, sorry.
>>
>> But if the issue is documentation, why not show a proposed patch?
>>
>
> ​I did with this suggested addition to select-window's doc string:
>
> "Although this selects the window's frame, it does not alter the
> frame's position in the window stack (see `raise-frame') nor does
> it direct input focus to that frame.  To do both of those at once,
> see `select-frame-set-input-focus'.
>

​I still think this is a clear and modest proposal.  select-window already
mentions frames so I don't see an issue with cross-referencing more
frame-related
behavior to make the needs clear with one additional sentence.  Are you guys
still against this given the further explanations?

Bob
​

[-- Attachment #2: Type: text/html, Size: 3160 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 1368 bytes --]

On Thu, Dec 14, 2017 at 8:42 PM, Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > Does anyone else see a need for something like this or am I the only one
> > that finds there are too many gotchas
> > and complexities in dealing with combinations of these issues right now?
>
> I think we're generally better off embracing the idea that it's not
> Emacs's job to decide how to handle focus and window stacking.
> ​​
>

​​
>
> ​​
> Because the problems with focus and such don't all have to do with
> ​​
> technicalities of how the APIs work, but also with interaction about the
> ​​
> specific focus policy that the user may have chosen in his
> ​​
> window-manager (as well as with the frame/window management policies he
> ​​
> has setup in his display-buffer-alist).
>

​It is good that advanced users like yourself can customize handling of
frame positioning, stacking and input focus but most users will simply
use the policy of their native window manager, so that is the first
scenario that we should seek to improve, if any.

Given that Emacs offers raise-frame, lower-frame and
select-frame-set-input-focus
to programmers, we have to acknowledge that these will be used in specific
scenarios to provide a best effort result in affecting frame stacking and
input focus redirection.

Bob

[-- Attachment #2: Type: text/html, Size: 3512 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii]

> From: Robert Weiner <rsw@gnu.org>
> Date: Sat, 16 Dec 2017 11:21:56 -0500
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, martin rudalics <rudalics@gmx.at>, 
> 	emacs-devel <emacs-devel@gnu.org>
> 
>  "Although this selects the window's frame, it does not alter the
>  frame's position in the window stack (see `raise-frame') nor does
>  it direct input focus to that frame.  To do both of those at once,
>  see `select-frame-set-input-focus'.
> 
> ​I still think this is a clear and modest proposal.  select-window already
> mentions frames so I don't see an issue with cross-referencing more frame-related
> behavior to make the needs clear with one additional sentence.  Are you guys
> still against this given the further explanations?

Yes.  You are proposing to add text about a completely unrelated
aspect of Emacs.  Selecting a window has nothing to do with focus, but
it's absurd to ask Emacs to mention in doc strings aspects that are
NOT related to the aspects the doc string describes: there are too
many of those.

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii]

> From: Robert Weiner <rsw@gnu.org>
> Date: Sat, 16 Dec 2017 11:11:43 -0500
> Cc: Eli Zaretskii <eliz@gnu.org>, martin rudalics <rudalics@gmx.at>, emacs-devel <emacs-devel@gnu.org>
> 
> So if I programmatically select-window in a frame that does not have or gain
> input focus, will most editing take place there?

That's a meaningless question, IMO, because "editing takes place"
means interactive editing, and that only happens _after_ your command
finishes its job, and Emacs returns to the main command loop.  And the
manual says "_most_ editing" for a reason.

> Maybe there is another as yet undefined idea in there of interactive
> window selection where input focus does shift.

I think you are interpreting the ELisp manual too literally.  It is
not meant to describe how the Emacs internals work, certainly not in
all cases.  The text which describes what it means for the window to
be "selected" is intended to make the _notion_ of the selected window
clear enough to continue describing the features which manipulate the
selected window, nothing more, nothing less.  You should not interpret
that text as an exhaustive and mathematically rigorous _definition_ of
what a selected window is, and even less when Emacs decides on its own
to select a different window.  The simplest example is the minibuffer
window.

> At the very least, the basic sequence of calls to select an arbitrary window
> for user editing should be explained both here and in the select-window function,
> since someone thinking about windows and buffers isn't likely to reference
> frame-related documentation even though input focus is a frame-related concept.

And they don't need to look up frame- and focus-related documentation,
as long as they only need to select a window.  What you needed is to
select another frame, select another window on that frame, and make
sure that frame is at the top of the z-order.  That has very little to
do with selecting a window, and much more to do with frames and input
focus -- and those topics are described in the docs under their proper
subjects.

I could support some gentle notes in the ELisp manual's node
"Selecting Windows", where it already mentions frames.  But doc
strings are inappropriate for references to almost unrelated subjects,
nor for general descriptions of complex topics.

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 1947 bytes --]

On Sat, Dec 16, 2017 at 11:29 AM, Eli Zaretskii <eliz@gnu.org> wrote:

>
> > ​I still think this is a clear and modest proposal.  select-window
> already
> > mentions frames so I don't see an issue with cross-referencing more
> frame-related
> > behavior to make the needs clear with one additional sentence.  Are you
> guys
> > still against this given the further explanations?
>
> Yes.  You are proposing to add text about a completely unrelated
> aspect of Emacs.  Selecting a window has nothing to do with focus


​The main question I am trying to address is how to tell an Elisp programmer
how to redirect user input to an arbitrary window.  Whether or not we have
a specific name for this redirection, where user input goes changes when
select-window is called within the selected frame.  So there is input focus
which is frame-related but there is also window-related input redirection.
My argument is that there needs to be one place to look to understand
that.

Maybe select-window is not the place, it just seems that programmers
focused on
handling windows would naturally look there.

How and where would you explain this?  Can you explain how to do it in a few
sentences?  If yes, then let's add it somewhere and make it easy to find.
If not, then maybe a simplifying function would be justified.

I read through parts of the Elisp manual.  The section on Windows does not
explain
how to redirect user input ot an arbitrary window.  The top-level on Frames
does
not either.  It is not until I get to the section on Input Focus that I get
any
helpful information on this and that section refers only to frames, not
selected
windows.

So my thought is that where interactive user input goes is broader than
input focus,
is connected to what window is selected, and should be explained in one
place in
a succinct manner that is easily findable when looking up windows or frames.

Bob

[-- Attachment #2: Type: text/html, Size: 4758 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 1141 bytes --]

On Sat, Dec 16, 2017 at 12:04 PM, Robert Weiner <rsw@gnu.org> wrote:

>
> So my thought is that where interactive user input goes is broader than
> input focus,
> is connected to what window is selected, and should be explained in one
> place in
> a succinct manner that is easily findable when looking up windows or
> frames.
>

​I would also argue that although I agree that selecting windows, selecting
frames and
setting user input to a frame are all different concepts, they are
lower-level concepts
from which higher-level user-centered behaviors are built.  The user model
is much closer
to "I select a thing that I see and any further inputs go there".  In fact,
with many
window managers this is true, as a click in a window will select the frame,
the window
and set input focus there.  So there is no reason to avoid offering the
Elisp programmer
a similar model that documents these concepts in combination and brings the
programming
model closer to the user model.  For those times where finer-grained
control is necessary,
the individual behavior primitives are always available.

Bob



​

[-- Attachment #2: Type: text/html, Size: 3026 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 1164 bytes --]

On Sat, Dec 16, 2017 at 11:42 AM, Eli Zaretskii <eliz@gnu.org> wrote:

>
> And they don't need to look up frame- and focus-related documentation,
> as long as they only need to select a window.  What you needed is to
> select another frame, select another window on that frame, and make
> sure that frame is at the top of the z-order.  That has very little to
> do with selecting a window, and much more to do with frames and input
> focus -- and those topics are described in the docs under their proper
> subjects.
>

​I largely agree with the above now and spoke to this in
one of my last messages​ where I talked about combining
lower-level concepts into one area of documentation so
user input can be directed to a specific window and that
window's frame can be seen on screen in its entirety.

​​
>
> ​​
> I could support some gentle notes in the ELisp manual's node
> ​​
> "Selecting Windows", where it already mentions frames.  But doc
> ​​
> strings are inappropriate for references to almost unrelated subjects,
> ​​
> nor for general descriptions of complex topics.
>

​Okay, thanks.

Bob
​

[-- Attachment #2: Type: text/html, Size: 3005 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii]

> From: Robert Weiner <rsw@gnu.org>
> Date: Sat, 16 Dec 2017 12:04:03 -0500
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, martin rudalics <rudalics@gmx.at>, 
> 	emacs-devel <emacs-devel@gnu.org>
> 
> ​The main question I am trying to address is how to tell an Elisp programmer
> how to redirect user input to an arbitrary window.  Whether or not we have
> a specific name for this redirection, where user input goes changes when
> select-window is called within the selected frame.  So there is input focus
> which is frame-related but there is also window-related input redirection.
> My argument is that there needs to be one place to look to understand
> that.
> 
> Maybe select-window is not the place, it just seems that programmers focused on
> handling windows would naturally look there.
> 
> How and where would you explain this?

There's a node "Input Focus" in the ELisp manual.  What is missing
from it to cover what you want?

In my scheme of Emacs-ware, there's no such thing as "redirecting
input to a window".  Input is redirected to a frame, and then the
selected window on that frame is usually the one that reacts to user
input (I say "usually' because some input, like mouse gestures, can
operate on n on-selected windows).

> I read through parts of the Elisp manual.  The section on Windows does not explain
> how to redirect user input ot an arbitrary window.  The top-level on Frames does
> not either.  It is not until I get to the section on Input Focus that I get any
> helpful information on this and that section refers only to frames, not selected
> windows.

Then perhaps the only stuff that's missing is some appropriately
worded index entries that lead to "Input Focus", and maybe also short
notes with cross-references elsewhere in the manual.

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 2401 bytes --]

On Sat, Dec 16, 2017 at 12:26 PM, Eli Zaretskii <eliz@gnu.org> wrote:

>
> There's a node "Input Focus" in the ELisp manual.  What is missing
> from it to cover what you want?
>
> In my scheme of Emacs-ware, there's no such thing as "redirecting
> input to a window".


​When the user selects another window within the selected frame
or a select-window is done on the selected frame, user input
(typing) and programmatic input (insert) shifts from the prior
window to the new window.  No frame change has occurred yet
where user input like self-inserting characters goes is different.
How can this not be part of your Emacs model?

​​
>   Input is redirected to a frame, and then t
> ​​
> ​​
> he
> ​​
>
> ​​
> selected window on that frame is usually
> ​​
> the one that reacts to user
> ​​
> input (I say "usually' because some input
> ​​
> , like mouse gestures, can
> ​​
> operate on n on-selected windows).
>
​​
​
​Some concept other than input focus is sending those inputs to the
selected window (maybe we limit discussion to keyboard inputs for now).
Maybe it could have a name and be described.
​

> ​​
>
> ​​
> > I read through parts of the Elisp manual.  The section on Windows does
> not explain
> ​​
> > how to redirect user input ot an arbitrary window.  The top-level on
> Frames does
> ​​
> > not either.  It is not until I get to the section on Input Focus that I
> get any
> ​​
> > helpful information on this and that section refers only to frames, not
> selected
> ​​
> > windows.
> ​​
>
> ​​
> Then perhaps the only stuff that's missing is some appropriately
> ​​
> worded index entries that lead to "Input Focus", and maybe also short
> ​​
> notes with cross-references elsewhere in the manual.

​​
Frame-level input focus is insufficient to describe the window to which
keyboard input goes in all cases.  It requires a combination of set input
focus and select-window, right?  Plus, if we want to see any changes in
buffer-to-window mappings during the course of a function, we must invoke
redisplay.  It is the description of the interrelations of these things that
is not described in a single place anywhere, especially with code samples,
making it difficult for programmers to see what must be done.

Bob

[-- Attachment #2: Type: text/html, Size: 6591 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii]

> From: Robert Weiner <rsw@gnu.org>
> Date: Sat, 16 Dec 2017 13:16:48 -0500
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, martin rudalics <rudalics@gmx.at>, 
> 	emacs-devel <emacs-devel@gnu.org>
> 
> ​When the user selects another window within the selected frame
> or a select-window is done on the selected frame, user input
> (typing) and programmatic input (insert) shifts from the prior
> window to the new window.

Correct for user input (but note the important exception of the
mini-window).  Not necessarily correct for 'insert' etc. -- many of
these APIs can work on a specified window, which is different from the
selected one.

> No frame change has occurred yet
> where user input like self-inserting characters goes is different.
> How can this not be part of your Emacs model?

As long as the selected frame is unchanged, the model holds: you need
only select the window.

> ​​Frame-level input focus is insufficient to describe the window to which
> keyboard input goes in all cases.

Keyboard input goes to the selected window of the selected frame.
Why isn't that description sufficient?

> Plus, if we want to see any changes in buffer-to-window mappings
> during the course of a function, we must invoke redisplay.

Not normally, no.  Normally, you select the frame and the window, and
then redisplay will do the rest automatically after your command
completes.  To need some change displayed in the middle of a command
is unusual.

> It is the description of the interrelations of these things that
> is not described in a single place anywhere, especially with code samples,
> making it difficult for programmers to see what must be done.

I don't understand why a complex task involving several steps must
necessarily be described in a single place.

Once again, I suggest to add a few notes with cross-references to the
existing nodes; I think this should be enough for those rare cases
where the reader might not realize that the complete job requires
doing several things together.

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 2606 bytes --]

On Sat, Dec 16, 2017 at 1:41 PM, Eli Zaretskii <eliz@gnu.org> wrote:

>
> > No frame change has occurred yet
> > where user input like self-inserting characters goes is different.
> > How can this not be part of your Emacs model?
>
> As long as the selected frame is unchanged, the model holds: you need
> only select the window.
>
> > ​​Frame-level input focus is insufficient to describe the window to which
> > keyboard input goes in all cases.
>

​We were talking about how input focus was an insufficient
concept to describe which window user input is directed to.
Similarly, select-window is insufficient by itself as well.
​

> ​​
>
> ​​
> Keyboard input goes to the selected window of the selected frame.
> ​​
> Why isn't that description sufficient?
>

​Where is that explained?  How does one find it?
​

> ​​
>
> ​​
> > Plus, if we want to see any changes in buffer-to-window mappings
> ​​
> > during the course of a function, we must invoke redisplay.
>
> Not normally, no.  Normally, you select the frame and the window, and
> then redisplay will do the rest automatically after your command
> completes.  To need some change displayed in the middle of a command
> is unusual.
>

I think temporarily displaying a frame from the stack is
a useful visual technique that would see more use were it
simpler to implement.

​​
>
> ​​
> > It is the description of the interrelations of these things that
> ​​
> > is not described in a single place anywhere, especially with code
> samples,
> ​​
> > making it difficult for programmers to see what must be done.
> ​​
>
> ​​
> I don't understand why a complex task involving several steps must
> ​​
> necessarily be described in a single place.
>

​The implementation may be complex now but the user-level concept
is not.  It can be thought of as one thing: display the current
contents of a window now (regardless of the window's frame or
other frame's obscuring it or what buffer was attached at creation)
I think this seems complex to you because you know many of the
intricacies of what it takes​, but from a user perspective, it is
one thing.

​​
>
> ​​
> Once again, I suggest to add a few notes with cross-references to the
> ​​
> existing nodes; I think this should be enough for those rare cases
> ​​
> where the reader might not realize that the complete job requires
> ​​
> doing several things together.
>

​Any idea what to say?

Bob
​
​​
​​
​​

[-- Attachment #2: Type: text/html, Size: 7140 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii]

> From: Robert Weiner <rsw@gnu.org>
> Date: Sat, 16 Dec 2017 14:18:09 -0500
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, martin rudalics <rudalics@gmx.at>, 
> 	emacs-devel <emacs-devel@gnu.org>
> 
>  > ​​Frame-level input focus is insufficient to describe the window to which
>  > keyboard input goes in all cases.
> 
> ​We were talking about how input focus was an insufficient
> concept to describe which window user input is directed to.
> Similarly, select-window is insufficient by itself as well.

And I disagree with that.  I think it _is_ sufficient.

>  ​​Keyboard input goes to the selected window of the selected frame.
>  ​​Why isn't that description sufficient?
> 
> ​Where is that explained?  How does one find it?

It's in the text you cited about what the "selected window" means.  If
you are saying that "most editing" does not necessarily cover keyboard
input, I'm okay with adding that as an example.  (Once again, such
text must not be interpreted too literally, because, e.g., commands
like "C-x 5 0" are definitely "keyboard input", but affect something
other than the selected window.)

>  ​​> Plus, if we want to see any changes in buffer-to-window mappings
>  ​​> during the course of a function, we must invoke redisplay.
> 
>  Not normally, no.  Normally, you select the frame and the window, and
>  then redisplay will do the rest automatically after your command
>  completes.  To need some change displayed in the middle of a command
>  is unusual.
> 
> I think temporarily displaying a frame from the stack is
> a useful visual technique that would see more use were it
> simpler to implement.

"Useful" does not contradict "unusual".  Because it's unusual, finding
the details about achieving these goals could legitimately be somewhat
harder than for the more popular use cases.

>  ​​> It is the description of the interrelations of these things that
>  ​​> is not described in a single place anywhere, especially with code samples,
>  ​​> making it difficult for programmers to see what must be done.
>  ​​
>  ​​I don't understand why a complex task involving several steps must
>  ​​necessarily be described in a single place.
> 
> ​The implementation may be complex now but the user-level concept
> is not.

I wasn't talking about the implementation.  I was talking about the
task of a Lisp programmer who needs to select a window on another
frame and make sure the frame is raised and input focus is redirected
to it.  This task is more complex than just selecting a window on the
currently selected frame.

> I think this seems complex to you because you know many of the
> intricacies of what it takes​, but from a user perspective, it is
> one thing.

I disagree, and not because of my developer experience, but because of
my user experience.

But at this point in the dispute, let's agree to disagree, because
we've reiterated the same arguments at least thrice.

>  ​​Once again, I suggest to add a few notes with cross-references to the
>  ​​existing nodes; I think this should be enough for those rare cases
>  ​​where the reader might not realize that the complete job requires
>  ​​doing several things together.
> 
> ​Any idea what to say?

I thought you might have an idea, but if not, I will do it.

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 596 bytes --]

On Sat, Dec 16, 2017 at 2:56 PM, Eli Zaretskii <eliz@gnu.org> wrote:

>
> >  ​​Once again, I suggest to add a few notes with cross-references to the
> >  ​​existing nodes; I think this should be enough for those rare cases
> >  ​​where the reader might not realize that the complete job requires
> >  ​​doing several things together.
> >
> > ​Any idea what to say?
>
> I thought you might have an idea, but if not, I will do it.
>

​Better you do it so we know it will go in.

And I'll probably work on a temp-display-frame idea and see what you think.

Bob

[-- Attachment #2: Type: text/html, Size: 1590 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 3866 bytes --]

On Sat, Dec 16, 2017 at 2:56 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Robert Weiner <rsw@gnu.org>
> > Date: Sat, 16 Dec 2017 14:18:09 -0500
> > Cc: Stefan Monnier <monnier@iro.umontreal.ca>, martin rudalics <
> rudalics@gmx.at>,
> >       emacs-devel <emacs-devel@gnu.org>
> >
> >  > ​​Frame-level input focus is insufficient to describe the window to
> which
> >  > keyboard input goes in all cases.
> >
> > ​We were talking about how input focus was an insufficient
> > concept to describe which window user input is directed to.
> > Similarly, select-window is insufficient by itself as well.
>
> And I disagree with that.  I think it _is_ sufficient.
>

As you said, we have covered this enough.

​
> ​​
> > ​Where is that explained?  How does one find it?
> ​​
>
> ​​
>
> ​​
> It's in the text you cited about what the "selected w
> ​​
> indow" means.  If
> ​​
> you are saying that "most editing" does not necess
> ​​
> arily cover keyboard
> ​​
> input, I'm okay with adding that as an example.
> ​​
>
​​
That would be good if it had a reference to where to find
the rest of the information covering keyboard input.

Bob
​​​​

>   (Once again, such
> text must not be interpreted too literally, because, e.g., commands
> like "C-x 5 0" are definitely "keyboard input", but affect something
> other than the selected window.)
>

​Yes.
​

> ​​
>
> ​​
> >  ​​> Plus, if we want to see any changes in buffer-to-window mappings
> ​​
> >  ​​> during the course of a function, we must invoke redisplay.
> ​​
> >
> ​​
> >  Not normally, no.  Normally, you select the frame and the window, and
> ​​
> >  then redisplay will do the rest automatically after your command
> ​​
> >  completes.  To need some change displayed in the middle of a command
> ​​
> >  is unusual.
>
​​

​Okay.​

​​


> ​​
> > I think temporarily displaying a frame from the stack is
> ​​
> > a useful visual technique that would see more use were it
> ​​
> > simpler to implement.
> ​​
>
> ​​
> "Useful" does not contradict "unusual".  Because it's unusual, finding
> ​​
> the details about achieving these goals could legitimately be somewhat
> ​​
> harder than for the more popular use cases.
>

​So you are saying it may be hard yet potentially worthwhile
to do?

​​
>
> ​​
> >  ​​> It is the description of the interrelations of these things that
> ​​
> >  ​​> is not described in a single place anywhere, especially with code
> samples,
> ​​
> >  ​​> making it difficult for programmers to see what must be done.
> ​​
> >  ​​
> ​​
> >  ​​I don't understand why a complex task involving several steps must
> ​​
> >  ​​necessarily be described in a single place.
> ​​
> >
> ​​
> > ​The implementation may be complex now but the user-level concept
> ​​
> > is not.
> ​​
>
> ​​
> I wasn't talking about the implementation.  I was talking about the
> ​​
> task of a Lisp programmer who needs to select a window on another
> ​​
> frame and make sure the frame is raised and input focus is redirected
> ​​
> to it.  This task is more complex than just selecting a window on the
> ​​
> currently selected frame.
> ​​
>
> ​​
> > I think this seems complex to you because you know many of the
> ​​
> > intricacies of what it takes​, but from a user perspective, it is
> ​​
> > one thing.
> ​​
>
> ​​
> I disagree, and not because of my developer experience, but because of
> ​​
> my user experience.
>

​So we see this differently.  Thanks for the time discussing it.

Bob

[-- Attachment #2: Type: text/html, Size: 11378 bytes --]

Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii]

> From: Robert Weiner <rsw@gnu.org>
> Date: Sat, 16 Dec 2017 15:52:22 -0500
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, martin rudalics <rudalics@gmx.at>, 
> 	emacs-devel <emacs-devel@gnu.org>
> 
>  >  ​​Once again, I suggest to add a few notes with cross-references to the
>  >  ​​existing nodes; I think this should be enough for those rare cases
>  >  ​​where the reader might not realize that the complete job requires
>  >  ​​doing several things together.
>  >
>  > ​Any idea what to say?
> 
>  I thought you might have an idea, but if not, I will do it.
> 
> ​Better you do it so we know it will go in.

Done.