[RFC wayland-protocols] unstable: add protocol to give focus to a foreign surface

Markus Ongyerth wl at ongy.net
Thu Jul 5 17:40:21 UTC 2018

On 2018/7月/05 04:26, David Edmundson wrote:
> This protocol is to address the following use case.
> A user clicks on a URL link in an IRC chat and a web browser opens. We want
> an existing browser window to raise or if it's a newly spawned application
> to claim focus on startup.
> Naturally we also don't want any arbitrary client to be able to raise
> themselves arbitrarily.
Since this steals focus, I have to agree. But what we do want, is a way for 
clients to gain attention.
Probably via some kind of urgency flag on their toplevel.
I think raising a window (or for virtual-desktops, changing the desktop) is 
the extreme case of this, so I think it would fit a general urgency/attention 
grabbing protocol.
As I explain further down (I wrote this mail bottom up) I think we should be 
able to provide a way to allow the focus stealing, so we could have this in a 
protocl with a request family (or enum on one request?) for:
Attention: e.g. console bell, or some password query for a background task
Urgent: Something went wrong in e.g. gparted long-running process
Raise/Show: e.g. browser got opened a new tab for another application

> The protocol is a combination of xdg-foreign and some very simplified
> aspects of X's startup-notification.
> In the example above, the chat client gets a token from the compositor and
> passes it to the browser using:
>   - an environment variable for newly spawned apps
>   - platofrm-hints in the org.freedesktop.Application interface
>   - some hint in the relevant xdg-portal interface
>   - any custom mechanism
There was a discussion about this very recently in the suggestion for session 
recovery, it's not quite this easy.
And I think a quite common way to start applications (if we don't want to 
limit this to http[s]) is xdg-open, which I'm not sure if it provides for this 
use case.

As Drew pointed out in his answer already, the out  of band mechanism will not 
be the easiest thing to define. And when you read the previous discussion, 
you'll notice that the consense on which IPC to use isn't all that strong =.=

> The browser then requests a raise of a top-level using this token.
> (Exact common mechanisms should probably be defined, but maybe not in this
> document)
> The exporter is virtually identical to xdg-foreign's exporter, but we can't
> re-use directly it as it's important that clients know what the exported
> handle could be used for.
> Extending xdg-foreign would be a viable solution, but the lifespan of
> handles needs to be different..
> Honouring the activation request is entirely up to the compositor which can
> have whatever advanced focus rules it wants.
> Draft proposal below:
I feel like this is a bit too specific and complicated for what's supposed to 
be achieved here.

IMO we'd have a better solution (and more flexible to build on in the future) 
if this was split into two protocols, one for raising a window, and the other 
for passing serials.

The former protocol would simply have a request to be raised, that takes a 
valid serial. This could also be used for applications with multiple windows 
if they want to have another of their windows focused (e.g. fancy editor when 
you try to open a file again).

Then provide a secondary protocol that "hooks" into this one, by sharing 
This would be a simpler protocol without a direct use, but could be used as 
base to share (implicit) permissions gated on user interaction between clients 
that intend to outsource some task.
This protocol could largely look like xdg-foreign (maybe have the exporter one 
be destroyed implicit immediatly after the event) since serials have their own 
> -----------
> <?xml version="1.0" encoding="UTF-8"?>
> <protocol name="xdg_foreign_activator">
>   <copyright>
>   </copyright>
>   <description summary="Protocol for sharing focus between cross-process
> xdg surfaces">
>       This protocol allows a top level to give up focus and pass it to a
> specific other client.
>       An example use case would be a chat client opening a link in a
> browser, that should raise an existing window
>       or start the newly opened window with focus.
>       The application releasing focus (focus_exported) fetches a handle
> from the compositor and then passes it to another client using a third
> party mechanism.
>       The receiving application can use this handle to request focus from
> the compositor.
>   </description>
>   <interface name="zxdg_focus_exporter_v1" version="1">
>     <description summary="interface for exporting surfaces">
>       A global interface used for exporting surfaces that can later be
> imported
>       using xdg_importer.
I think you meant to:
>     </description>
>     <request name="destroy" type="destructor">
>       <description summary="destroy the xdg_focus_exporter object">
>         Notify the compositor that the xdg_exporter object will no longer be
>         used.
>       </description>
>     </request>
>     <request name="export_surface">
>       <description summary="export a toplevel surface">
>           It is an error to export a focus that is not mapped.
>       </description>
>       <arg name="id" type="new_id" interface="zxdg_focus_exported_v1"
>            summary="the new xdg_exported object"/>
>       <arg name="surface" type="object" interface="wl_surface"
>            summary="the surface to export"/>
>     </request>
>   </interface>
>   <interface name="zxdg_focus_exported_v1" version="1">
>     <description summary="an exported activation handle">
>     </description>
>     <request name="destroy" type="destructor">
>       <description summary="unexport the exported surface">
>           Inform the compositor that this focus_exported object is no
> longer used.
>           The handle remains valid and can still be used by the compositor.
> This is to allow windows to close themselves
>           after activating another application.
>       </description>
>     </request>
>     <event name="handle">
>       <description summary="the exported activation handle">
>         The handle event contains the unique handle of this exported surface
>         reference. It may be shared with any client, which then can use it
> to
>         import the surface by calling zxdg_activator_v1.activate_toplevel.
> A handle
>         may be used only once.
>       </description>
>       <arg name="handle" type="string" summary="the exported activation
> handle"/>
>     </event>
>   </interface>
>   <interface name="zxdg_focus_activator_v1" version="1">
>     <description summary="interface for importing surfaces">
>       A global interface used for importing surfaces exported by
> xdg_focus_exporter.
>       With this interface, a client can create a reference to a surface of
>       another client.
>     </description>
>     <request name="destroy" type="destructor">
>       <description summary="destroy the xdg_activator object">
>         Notify the compositor that the xdg_activator object will no longer
> be
>         used.
>       </description>
>     </request>
>     <request name="activate_toplevel">
>       <description summary="activate a toplevel surface">
>           Request to the compositor that this surface should claim focus
> from the exported handle.
>           This request can be sent at any time to raise an alread mapped
> window or before the window is
>           mapped to request focus when the window is first configured.
>           At this point the handle is invalidated and cannot be used again.
>           The compositor is free to ignore this request.
>       </description>
>       <arg name="toplevel" type="xdg_toplevel">
>       <arg name="handle" type="string"
>            summary="the exported activation handle"/>
>     </request>
>   </interface>
> </protocol>

> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20180705/91dbddc4/attachment.sig>

More information about the wayland-devel mailing list