<div dir="ltr"><div>Some framework-y applications have multiple apps in one process, like LibreOffice. There's also the Chrome / Firefox "web apps" system where you can launch Chrome / Firefox with a URL as if the web apps were native native. Perhaps they should create a new xdg_shell for every app they create? I don't know how difficult that would be for them to do. </div></div><div class="gmail_extra"> <div class="gmail_quote">On Mon, Dec 1, 2014 at 1:35 AM, Giulio Camuffo <<a href="mailto:giuliocamuffo@gmail.com" target="_blank">giuliocamuffo@gmail.com</a>> wrote:<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5">2014-11-22 22:28 GMT+02:00 Jasper St. Pierre <<a href="mailto:jstpierre@mecheye.net">jstpierre@mecheye.net</a>>: > This rewrites basically all of the text inside xdg-shell to be up to > date, clearer, and rid of wl_shell and X11 terminology. > --- > protocol/xdg-shell.xml | 256 ++++++++++++++++++++++++++++++------------------- > 1 file changed, 156 insertions(+), 100 deletions(-) > > diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml > index 360179d..3359cf7 100644 > --- a/protocol/xdg-shell.xml > +++ b/protocol/xdg-shell.xml > @@ -31,11 +31,15 @@ > > <interface name="xdg_shell" version="1"> > <description summary="create desktop-style surfaces"> > - This interface is implemented by servers that provide > - desktop-style user interfaces. > - > - It allows clients to associate a xdg_surface with > - a basic surface. > + xdg_shell allows clients to turn a wl_surface into a "real window" > + which can be dragged, resized, stacked, and moved around by the > + user. Everything about this interface is suited towards traditional > + desktop environments. > + > + Destroying a bound xdg_shell object while there are surfaces > + still alive with roles from this interface is illegal and will > + result in a protocol error. Make sure to destroy all surfaces > + before destroying this object. > </description> > > <enum name="version"> > @@ -65,33 +69,26 @@ > > <request name="get_xdg_surface"> > <description summary="create a shell surface from a surface"> > - Create a shell surface for an existing surface. > - > - This request gives the surface the role of xdg_surface. If the > - surface already has another role, it raises a protocol error. > - > - Only one shell or popup surface can be associated with a given > - surface. > + This creates an xdg_surface for the given surface and gives it the > + xdg_surface role. See the documentation of xdg_surface for more details. > </description> > <arg name="id" type="new_id" interface="xdg_surface"/> > <arg name="surface" type="object" interface="wl_surface"/> > </request> > > <request name="get_xdg_popup"> > - <description summary="create a shell surface from a surface"> > - Create a popup surface for an existing surface. > - > - This request gives the surface the role of xdg_popup. If the > - surface already has another role, it raises a protocol error. > + <description summary="create a popup for a surface"> > + This creates an xdg_popup for the given surface and gives it the > + xdg_popup role. See the documentation of xdg_surface for more details. > > - Only one shell or popup surface can be associated with a given > - surface. > + This request must be used in response to some sort of user action > + like a button press, key press, or touch down event. > </description> > <arg name="id" type="new_id" interface="xdg_popup"/> > <arg name="surface" type="object" interface="wl_surface"/> > <arg name="parent" type="object" interface="wl_surface"/> > - <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/> > - <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/> > + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> > + <arg name="serial" type="uint" summary="the serial of the user event"/> > <arg name="x" type="int"/> > <arg name="y" type="int"/> > </request> > @@ -107,7 +104,7 @@ > respond to the ping request, or in what timeframe. Clients should > try to respond in a reasonable amount of time. > </description> > - <arg name="serial" type="uint" summary="pass this to the callback"/> > + <arg name="serial" type="uint" summary="pass this to the pong request"/> > </event> > > <request name="pong"> > @@ -120,8 +117,7 @@ > </interface> > > <interface name="xdg_surface" version="1"> > - > - <description summary="desktop-style metadata interface"> > + <description summary="A desktop window"> > An interface that may be implemented by a wl_surface, for > implementations that provide a desktop-style user interface. > > @@ -136,20 +132,22 @@ > </description> > > <request name="destroy" type="destructor"> > - <description summary="remove xdg_surface interface"> > - The xdg_surface interface is removed from the wl_surface object > - that was turned into a xdg_surface with > - xdg_shell.get_xdg_surface request. The xdg_surface properties, > - like maximized and fullscreen, are lost. The wl_surface loses > - its role as a xdg_surface. The wl_surface is unmapped. > + <description summary="Destroy the xdg_surface"> > + Unmap and destroy the window. The window will be effectively > + hidden from the user's point of view, and all state like > + maximization, fullscreen, and so on, will be lost. > </description> > </request> > > <request name="set_parent"> > - <description summary="surface is a child of another surface"> > - Child surfaces are stacked above their parents, and will be > - unmapped if the parent is unmapped too. They should not appear > - on task bars and alt+tab. > + <description summary="set the parent of this surface"> > + Set the "parent" of this surface. This window should be stacked > + above a parent. The parent surface must be mapped as long as this > + surface is mapped. > + > + Parent windows should be set on dialogs, toolboxes, or other > + "auxilliary" surfaces, so that the parent is raised when the dialog > + is raised. > </description> > <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/> > </request> > @@ -168,14 +166,19 @@ > </request> > > <request name="set_app_id"> > - <description summary="set surface class"> > - Set an id for the surface. > + <description summary="set application ID"> > + Set an application identifier for the surface. > + > + The app ID identifies the general class of applications to which > + the surface belongs. The compositor can use this to group multiple > + applications together, or to determine how to launch a new > + application. </div></div>Given this is an application specific property why is it in xdg_surface instead of being in xdg_shell? <div class="HOEnZb"><div class="h5"> > > - The app id identifies the general class of applications to which > - the surface belongs. > + See the desktop-entry specification [0] for more details on > + application identifiers and how they relate to well-known DBus > + names and .desktop files. > > - It should be the ID that appears in the new desktop entry > - specification, the interface name. > + [0] <a href="http://standards.freedesktop.org/desktop-entry-spec/" target="_blank">http://standards.freedesktop.org/desktop-entry-spec/</a> > </description> > <arg name="app_id" type="string"/> > </request> > @@ -187,29 +190,32 @@ > user a menu that they can use to maximize or minimize the window. > > This request asks the compositor to pop up such a window menu at > - the given position, relative to the parent surface. There are > - no guarantees as to what the window menu contains. > + the given position, relative to the local surface coordinates of > + the parent surface. There are no guarantees as to what menu items > + the window menu contains. > > - Your surface must have focus on the seat passed in to pop up the > - window menu. > + This request must be used in response to some sort of user action > + like a button press, key press, or touch down event. > </description> > > - <arg name="seat" type="object" interface="wl_seat" summary="the seat to pop the window up on"/> > - <arg name="serial" type="uint" summary="serial of the event to pop up the window for"/> > + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> > + <arg name="serial" type="uint" summary="the serial of the user event"/> > <arg name="x" type="int" summary="the x position to pop up the window menu at"/> > <arg name="y" type="int" summary="the y position to pop up the window menu at"/> > </request> > > <request name="move"> > <description summary="start an interactive move"> > - Start a pointer-driven move of the surface. > + Start an interactive, user-driven move of the surface. > + > + This request must be used in response to some sort of user action > + like a button press, key press, or touch down event. > > - This request must be used in response to a button press event. > The server may ignore move requests depending on the state of > the surface (e.g. fullscreen or maximized). > </description> > - <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/> > - <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/> > + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> > + <arg name="serial" type="uint" summary="the serial of the user event"/> > </request> > > <enum name="resize_edge"> > @@ -232,14 +238,16 @@ > > <request name="resize"> > <description summary="start an interactive resize"> > - Start a pointer-driven resizing of the surface. > + Start a user-driven, interactive resize of the surface. > + > + This request must be used in response to some sort of user action > + like a button press, key press, or touch down event. > > - This request must be used in response to a button press event. > The server may ignore resize requests depending on the state of > the surface (e.g. fullscreen or maximized). > </description> > - <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/> > - <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/> > + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> > + <arg name="serial" type="uint" summary="the serial of the user event"/> > <arg name="edges" type="uint" summary="which edge or corner is being dragged"/> > </request> > > @@ -287,16 +295,21 @@ > > <event name="configure"> > <description summary="suggest a surface change"> > - The configure event asks the client to resize its surface. > + The configure event asks the client to resize its surface or to > + change its state. > > The width and height arguments specify a hint to the window > - about how its surface should be resized in window geometry > - coordinates. The states listed in the event specify how the > - width/height arguments should be interpreted. > + about how its surface should be resized in window geometry > + coordinates. > + > + The states listed in the event specify how the width/height > + arguments should be interpreted, and possibly how it should be > + drawn. > > - A client should arrange a new surface, and then send a > - ack_configure request with the serial sent in this configure > - event before attaching a new surface. > + Clients should arrange their surface for the new size and > + states, and then send a ack_configure request with the serial > + sent in this configure event at some point before committing > + the new surface. > > If the client receives multiple configure events before it > can respond to one, it is free to discard all but the last > @@ -311,14 +324,20 @@ > > <request name="ack_configure"> > <description summary="ack a configure event"> > - When a configure event is received, a client should then ack it > - using the ack_configure request to ensure that the compositor > - knows the client has seen the event. > - > - By this point, the state is confirmed, and the next attach should > - contain the buffer drawn for the configure event you are acking. > + When a configure event is received, if a client is updating > + and redrawing its state in response to the configure event, > + then the client needs to make an ack_configure request before > + point the commit to mark this next commit as being a > + reaction to the configure. > + > + The compositor might use this information to move a surface > + to the top left only when the client has drawn itself for > + the maximized or fullscreen state. > + > + If the client receives multiple configure events before it > + can respond to one, it only has to ack the last configure event. > </description> > - <arg name="serial" type="uint" summary="a serial to configure for"/> > + <arg name="serial" type="uint" summary="the serial from the configure event"/> > </request> > > <request name="set_window_geometry"> > @@ -328,15 +347,20 @@ > portions like drop-shadows which should be ignored for the > purposes of aligning, placing and constraining windows. > > - The default value is the full bounds of the surface, including any > - subsurfaces. Once the window geometry of the surface is set once, > - it is not possible to unset it, and it will remain the same until > + Once the window geometry of the surface is set once, it is not > + possible to unset it, and it will remain the same until > set_window_geometry is called again, even if a new subsurface or > buffer is attached. > > + If never set, the value is the full bounds of the surface, > + including any subsurfaces. This updates dynamically on every > + commit. This unset mode is meant for extremely simple clients. > + > If responding to a configure event, the window geometry in here > must respect the sizing negotiations specified by the states in > the configure event. > + > + The width and height must be greater than zero. > </description> > <arg name="x" type="int"/> > <arg name="y" type="int"/> > @@ -359,7 +383,18 @@ > </request> > <request name="unset_fullscreen" /> > > - <request name="set_minimized" /> > + <request name="set_minimized"> > + <description summary="set the window as minimized"> > + Request that the compositor minimize your surface. There is no > + way to know if the surface is currently minimized, nor is there > + any way to unset minimization on this surface. > + > + If you are looking to throttle redrawing when minimized, please > + instead use the wl_surface.frame event for this, as this will > + also work with live previews on windows in Alt-Tab, Expose or > + similar compositor features. > + </description> > + </request> > > <event name="close"> > <description summary="surface wants to be closed"> > @@ -376,26 +411,48 @@ > </interface> > > <interface name="xdg_popup" version="1"> > - <description summary="desktop-style metadata interface"> > - An interface that may be implemented by a wl_surface, for > - implementations that provide a desktop-style popups/menus. A popup > - surface is a transient surface with an added pointer grab. > - > - An existing implicit grab will be changed to owner-events mode, > - and the popup grab will continue after the implicit grab ends > - (i.e. releasing the mouse button does not cause the popup to be > - unmapped). > - > - The popup grab continues until the window is destroyed or a mouse > - button is pressed in any other clients window. A click in any of > - the clients surfaces is reported as normal, however, clicks in > - other clients surfaces will be discarded and trigger the callback. > - > - The x and y arguments specify the locations of the upper left > - corner of the surface relative to the upper left corner of the > - parent surface, in surface local coordinates. > - > - xdg_popup surfaces are always transient for another surface. > + <description summary="short-lived, popup surfaces for menus"> > + A popup surface is a short-lived, temporary surface that can be > + used to implement menus. It takes an explicit grab on the surface > + that will be dismissed when the user dismisses the popup. This can > + be done by the user clicking outside the surface, using the keyboard, > + or even locking the screen through closing the lid or a timeout. > + > + When the popup is dismissed, a popup_done event will be sent out, > + and at the same time the surface will be unmapped. The xdg_popup > + object is now inert and cannot be reactivated, so clients should > + destroy it. Explicitly destroying the xdg_popup object will also > + dismiss the popup, and unmap the surface. > + > + Clients will receive events for all their surfaces during this > + grab (which is an "owner-events" grab in X11 parlance). This is > + done so that users can navigate through submenus and other > + "nested" popup windows without having to dismiss the topmost > + popup. > + > + Clients that want to dismiss the popup when another surface of > + their own is clicked should dismiss the popup using the destroy > + request. > + > + The parent surface must have either an xdg_surface or xdg_popup > + role. > + > + Specifying an xdg_popup for the parent means that the popups are > + nested, with this popup now being the topmost popup. Nested > + popups must be destroyed in the reverse order they were created > + in, e.g. the only popup you are allowed to destroy at all times > + is the topmost one. > + > + If there is an existing popup when creating a new popup, the > + parent must be the current topmost popup. > + > + When compositors choose to dismiss a popup if the user clicks > + outside the window, they will likely dismiss every nested popup > + as well. > + > + The x and y arguments specify where the top left of the popup > + should be placed, relative to the local surface coordinates of the > + parent surface. > </description> > > <enum name="error"> > @@ -407,19 +464,18 @@ > > <request name="destroy" type="destructor"> > <description summary="remove xdg_surface interface"> > - The xdg_surface interface is removed from the wl_surface object > - that was turned into a xdg_surface with > - xdg_shell.get_xdg_surface request. The xdg_surface properties, > - like maximized and fullscreen, are lost. The wl_surface loses > - its role as a xdg_surface. The wl_surface is unmapped. > + This destroys the popup. Explicitly destroying the xdg_popup > + object will also dismiss the popup, and unmap the surface. > + > + If this xdg_popup is not the "topmost" popup, a protocol error > + will be sent. > </description> > </request> > > <event name="popup_done"> > <description summary="popup interaction is done"> > - The popup_done event is sent out when a popup grab is broken, > - that is, when the users clicks a surface that doesn't belong > - to the client owning the popup surface. > + The popup_done event is sent out when a popup is dismissed > + by the compositor. > </description> > </event> > > -- > 2.1.0 > </div></div><div class="HOEnZb"><div class="h5">> _______________________________________________ > wayland-devel mailing list > <a href="mailto:wayland-devel@lists.freedesktop.org">wayland-devel@lists.freedesktop.org</a> > <a href="http://lists.freedesktop.org/mailman/listinfo/wayland-devel" target="_blank">http://lists.freedesktop.org/mailman/listinfo/wayland-devel</a> </div></div></blockquote></div> -- <div class="gmail_signature"> Jasper </div> </div>