Hi Jonas, > On Jul 13, 2016, at 12:58 AM, Jonas Ådahl <[email protected]> wrote: > > xdg-foreign is a protocol meant to enable setting up inter surface > relationships across clients. Potential use cases are out-of-process > dialogs, such as file dialogs, meant to be used by sandboxed processes > that may not have the access it needs to implement such dialogs. > > It works by enabling a client to export a surface, creating a handle > for the exported surface. The handle, in form of a unique string, may > be shared in some way with other clients (for example the provider of > the file dialog) which can then import the exported surface. > > Signed-off-by: Jonas Ådahl <[email protected]>
Interesting protocol. Just a wild thought: would surface-exporting be something useful in the core Wayland protocol? (Not now, but...) I'll need to re-read and imagine the scenarios, but I feel like there is some inconsistency in either the descriptions or the protocol itself. Specifically, I thought that the exported surface from client A would be displayed by client B as an xdg_toplevel, but then I also see set_parent_of, meaning that client B can add subsurfaces to the imported surface? No need to explain that in length, I think I just need to re-read. Some notes inline below. > --- > > Hi, > > This protocol is intended to be used by flatpak's xdg desktop portals, in > order > to have a portal dialog (such as a file chooser) to be stacked above (and > maybe > as a modal) a parent surface. > > A compositor that want to be able to run sandboxed Wayland clients that need > to > use portals would need to implement this protocol. > > In short, a sandboxed client would "export" its surface and in the process > retrieve a server generated handle string, acting as a unique identifier for > the exported window. In the flatpak case the client will pass the identifier > string via D-Bus to a xdg desktop portal service provider, which will then > import it using xdg_importer and create a xdg_imported object that it can be > used to modify the stacking relationship. > > So far the only supported operation is setting an imported window to be the > parent of some surface. > > Note that the protocol documentation says "xdg_surface". In the future this > would be "xdg_toplevel". > > > Jonas > > Makefile.am | 1 + > unstable/xdg-foreign/README | 4 + > unstable/xdg-foreign/xdg-foreign-unstable-v1.xml | 177 +++++++++++++++++++++++ > 3 files changed, 182 insertions(+) > create mode 100644 unstable/xdg-foreign/README > create mode 100644 unstable/xdg-foreign/xdg-foreign-unstable-v1.xml > > diff --git a/Makefile.am b/Makefile.am > index 71d2632..06a1bb2 100644 > --- a/Makefile.am > +++ b/Makefile.am > @@ -8,6 +8,7 @@ unstable_protocols = > \ > unstable/relative-pointer/relative-pointer-unstable-v1.xml > \ > unstable/pointer-constraints/pointer-constraints-unstable-v1.xml > \ > unstable/tablet/tablet-unstable-v1.xml > \ > + unstable/xdg-foreign/xdg-foreign-unstable-v1.xml > \ > $(NULL) > > stable_protocols = > \ > diff --git a/unstable/xdg-foreign/README b/unstable/xdg-foreign/README > new file mode 100644 > index 0000000..f5bcb83 > --- /dev/null > +++ b/unstable/xdg-foreign/README > @@ -0,0 +1,4 @@ > +xdg foreign protocol > + > +Maintainers: > +Jonas Ådahl <[email protected]> > diff --git a/unstable/xdg-foreign/xdg-foreign-unstable-v1.xml > b/unstable/xdg-foreign/xdg-foreign-unstable-v1.xml > new file mode 100644 > index 0000000..d8a90c3 > --- /dev/null > +++ b/unstable/xdg-foreign/xdg-foreign-unstable-v1.xml > @@ -0,0 +1,177 @@ > +<?xml version="1.0" encoding="UTF-8"?> > +<protocol name="xdg_foreign_unstable_v1"> > + > + <copyright> > + Copyright © 2015-2016 Red Hat Inc. > + > + Permission is hereby granted, free of charge, to any person obtaining a > + copy of this software and associated documentation files (the > "Software"), > + to deal in the Software without restriction, including without limitation > + the rights to use, copy, modify, merge, publish, distribute, sublicense, > + and/or sell copies of the Software, and to permit persons to whom the > + Software is furnished to do so, subject to the following conditions: > + > + The above copyright notice and this permission notice (including the next > + paragraph) shall be included in all copies or substantial portions of the > + Software. > + > + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS > OR > + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, > + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL > + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR > OTHER > + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING > + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER > + DEALINGS IN THE SOFTWARE. > + </copyright> > + > + <description summary="Protocol for exporting xdg surface handles"> > + This protocol specifies a way for making it possible to reference a > surface > + of a different client. With such a reference, a client can, by using the > + interfaces provided by this protocol, manipulate the relatioship between > its relationship > + own surfaces and surface of some other client, for example stack some of > its > + own surface above the other clients surface. own surfaces and the surface of some other client. For example, a client may stack another client's surface above some of its own. How about something like the above wording, which fits the scenario of a client wanting to stack a flatpak portal dialog / file chooser above its own surface(s). > + > + In order for a client A to get a reference of a surface of client B, > client > + B must first export its surface using xdg_exporter.export. Upon doing > this, > + client B will receive a handle (a unique string) that it may share with > + client A in some way (for example D-Bus). After client A have received > the has received > + handle from client B, it may use xdg_importer.import to create a > reference > + to the surface client B just exported. See the corresponding requests for > + details. > + > + Warning! The protocol described in this file is experimental. Each > version > + of this protocol should be considered incompatible with any other > version, > + and a client binding to a version different to the one advertised will be > + terminated. Once the protocol is declared stable, backward compatibility > + is guaranteed, the '_' prefix will be removed from the name and the > + version will be reset to 1. > + </description> > + > + <interface name="zxdg_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. > + </description> > + > + <request name="destroy" type="destructor"> > + <description summary="destroy the xdg_exporter object"> > + Notify the compositor that the xdg_exporter object will no longer be > + used. > + </description> > + </request> > + > + <request name="export"> > + <description summary="export a surface"> > + The export request exports the passed surface so that it can later be > + imported via xdg_importer. When called, a new xdg_exported object will > + be created and xdg_exported.handle will be sent immediately. See the > + corresponding interface and event for details. > + > + A surface may be exported multiple times, and each exported handle may > + be used to create a xdg_imported multiple times. Only xdg_surface > + surfaces may be exported. > + </description> > + > + <arg name="id" type="new_id" interface="zxdg_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_importer_v1" version="1"> > + <description summary="interface for importing surfaces"> > + A global interface used for importing surfaces exported by > xdg_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_importer object"> > + Notify the compositor that the xdg_importer object will no longer be > + used. > + </description> > + </request> > + > + <request name="import"> > + <description summary="import a surface"> > + The import request imports a surface from any client given a handle > + retrieved by exporting said surface using xdg_exporter.export. When > + called, a new xdg_imported object will be created. This new object > + represents the imported surface, and the importing client can > + manipulate its relationship using it. See xdg_imported for details. > + </description> > + > + <arg name="id" type="new_id" interface="zxdg_imported_v1" > + summary="the new xdg_imported object"/> > + <arg name="handle" type="string" > + summary="the exported surface handle"/> > + </request> > + </interface> > + > + <interface name="zxdg_exported_v1" version="1"> How about xdg_export instead of 'exported'? > + <description summary="an exported surface handle"> > + A xdg_exported object represents an exported reference to a surface. > The > + exported surface may be referenced as long as the xdg_exported object > not > + destroyed. Destroying the xdg_exported invalidates any relationship the > + importer may have established using xdg_imported. > + </description> > + > + <request name="destroy" type="destructor"> > + <description summary="unexport the exported surface"> > + Unexport the previously exported surface. This invalidates any Perhaps 'revoke' instead of unexport. > + relationship the importer may have set up using the xdg_imported created > + given the handle sent via xdg_exported.handle. > + </description> > + </request> > + > + <event name="handle"> > + <description summary="the exported surface 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 xdg_importer.import. A handle may only be > + used to import the surface once. How would this be enforced? > + </description> > + > + <arg name="handle" type="string" summary="the exported surface > handle"/> > + </event> > + </interface> > + > + <interface name="zxdg_imported_v1" version="1"> How about xdg_import? > + <description summary="an imported surface handle"> > + A xdg_imported object represents a imported reference to surface > exported an imported > + by some client. A client can use this interface to manipulate > + relationships between its own surfaces and the imported surface. > + </description> > + > + <request name="destroy" type="destructor"> > + <description summary="destroy the xdg_imported object"> > + Notify the compositor that it will no longer use the xdg_imported > + object. Any relationship that may have been set up will at this point > + be invalidated. > + </description> > + </request> > + > + <request name="set_parent_of"> > + <description summary="set as the parent of some surface"> > + Set the imported surface as the parent of some surface of the client. > + The passed surface must be a toplevel xdg_surface. Calling this function > + sets up a surface to surface relation with the same stacking and > positioning > + semantics as xdg_surface.set_parent. > + </description> > + > + <arg name="surface" type="object" interface="wl_surface" > + summary="the child surface"/> > + </request> > + > + <event name="destroyed"> > + <description summary="the imported surface handle has been destroyed"> > + The imported surface handle has been destroyed and any relationship set > + up has been invalidated. This may happen for various reasons, for > + example if the exported surface or the exported surface handle has been > + destroeyed, if the handle used for importing was invalid. destroyed, > + </description> > + </event> > + </interface> > + > +</protocol> One blank line at the end, please. Thank you, yong > -- > 2.7.4 > > _______________________________________________ > wayland-devel mailing list > [email protected] > https://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
