commit 4c7ecab

Update xdg-shell.xml to the latest version

  1@@ -49,6 +49,9 @@
  2 
  3     <enum name="error">
  4       <entry name="role" value="0" summary="given wl_surface has another role"/>
  5+      <entry name="defunct_surfaces" value="1" summary="xdg_shell was destroyed before children"/>
  6+      <entry name="not_the_topmost_popup" value="2" summary="the client tried to map or destroy a non-topmost popup"/>
  7+      <entry name="invalid_popup_parent" value="3" summary="the client specified an invalid popup parent surface"/>
  8     </enum>
  9 
 10     <request name="destroy" type="destructor">
 11@@ -56,9 +59,8 @@
 12         Destroy this xdg_shell object.
 13 
 14         Destroying a bound xdg_shell object while there are surfaces
 15-        still alive with roles from this interface is illegal and will
 16-        result in a protocol error. Make sure to destroy all surfaces
 17-        before destroying this object.
 18+        still alive created by this xdg_shell object instance is illegal
 19+        and will result in a protocol error.
 20       </description>
 21     </request>
 22 
 23@@ -130,6 +132,19 @@
 24       It provides requests to treat surfaces like windows, allowing to set
 25       properties like maximized, fullscreen, minimized, and to move and resize
 26       them, and associate metadata like title and app id.
 27+
 28+      The client must call wl_surface.commit on the corresponding wl_surface
 29+      for the xdg_surface state to take effect. Prior to committing the new
 30+      state, it can set up initial configuration, such as maximizing or setting
 31+      a window geometry.
 32+
 33+      Even without attaching a buffer the compositor must respond to initial
 34+      committed configuration, for instance sending a configure event with
 35+      expected window geometry if the client maximized its surface during
 36+      initialization.
 37+
 38+      For a surface to be mapped by the compositor the client must have
 39+      committed both an xdg_surface state and a buffer.
 40     </description>
 41 
 42     <request name="destroy" type="destructor">
 43@@ -147,7 +162,7 @@
 44 	surface is mapped.
 45 
 46 	Parent windows should be set on dialogs, toolboxes, or other
 47-	"auxilliary" surfaces, so that the parent is raised when the dialog
 48+	"auxiliary" surfaces, so that the parent is raised when the dialog
 49 	is raised.
 50       </description>
 51       <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
 52@@ -172,11 +187,10 @@
 53 
 54 	The app ID identifies the general class of applications to which
 55 	the surface belongs. The compositor can use this to group multiple
 56-	applications together, or to determine how to launch a new
 57-	application.
 58+	surfaces together, or to determine how to launch a new application.
 59 
 60 	See the desktop-entry specification [0] for more details on
 61-	application identifiers and how they relate to well-known DBus
 62+	application identifiers and how they relate to well-known D-Bus
 63 	names and .desktop files.
 64 
 65 	[0] http://standards.freedesktop.org/desktop-entry-spec/
 66@@ -301,7 +315,12 @@
 67 
 68 	The width and height arguments specify a hint to the window
 69 	about how its surface should be resized in window geometry
 70-	coordinates.
 71+	coordinates. See set_window_geometry.
 72+
 73+	If the width or height arguments are zero, it means the client
 74+	should decide its own window dimension. This may happen when the
 75+	compositor need to configure the state of the surface but doesn't
 76+	have any information about any previous or expected dimension.
 77 
 78 	The states listed in the event specify how the width/height
 79 	arguments should be interpreted, and possibly how it should be
 80@@ -330,9 +349,9 @@
 81         must make a ack_configure request before the commit request,
 82         passing along the serial of the configure event.
 83 
 84-        The compositor might use this information to move a surface
 85-        to the top left only when the client has drawn itself for
 86-        the maximized or fullscreen state.
 87+        For instance, the compositor might use this information to move
 88+        a surface to the top left only when the client has drawn itself
 89+        for the maximized or fullscreen state.
 90 
 91         If the client receives multiple configure events before it
 92         can respond to one, it only has to ack the last configure event.
 93@@ -347,6 +366,9 @@
 94         portions like drop-shadows which should be ignored for the
 95         purposes of aligning, placing and constraining windows.
 96 
 97+        The window geometry is double buffered, and will be applied at the
 98+        time wl_surface.commit of the corresponding wl_surface is called.
 99+
100         Once the window geometry of the surface is set once, it is not
101         possible to unset it, and it will remain the same until
102         set_window_geometry is called again, even if a new subsurface or
103@@ -360,6 +382,9 @@
104         must respect the sizing negotiations specified by the states in
105         the configure event.
106 
107+        The arguments are given in the surface local coordinate space of
108+        the wl_surface associated with this xdg_surface.
109+
110         The width and height must be greater than zero.
111       </description>
112       <arg name="x" type="int"/>
113@@ -378,6 +403,10 @@
114         You can specify an output that you would prefer to be fullscreen.
115 	If this value is NULL, it's up to the compositor to choose which
116         display will be used to map this surface.
117+
118+        If the surface doesn't cover the whole output, the compositor will
119+        position the surface in the center of the output and compensate with
120+        black borders filling the rest of the output.
121       </description>
122       <arg name="output" type="object" interface="wl_output" allow-null="true"/>
123     </request>
124@@ -449,20 +478,21 @@
125       A parent surface must be mapped before the new popup is mapped.
126 
127       When compositors choose to dismiss a popup, they will likely
128-      dismiss every nested popup as well.
129+      dismiss every nested popup as well. When a compositor dismisses
130+      popups, it will follow the same dismissing order as required
131+      from the client.
132 
133-      The x and y arguments specify where the top left of the popup
134-      should be placed, relative to the local surface coordinates of the
135-      parent surface.
136-    </description>
137+      The x and y arguments passed when creating the popup object specify
138+      where the top left of the popup should be placed, relative to the
139+      local surface coordinates of the parent surface. See
140+      xdg_shell.get_xdg_popup.
141 
142-    <enum name="error">
143-      <description summary="xdg_popup error values">
144-	These errors can be emitted in response to xdg_popup requests.
145-      </description>
146-      <entry name="not_the_topmost_popup" value="0" summary="The client tried to map or destroy a non-topmost popup"/>
147-      <entry name="invalid_parent" value="1" summary="The client specified an invalid parent surface"/>
148-    </enum>
149+      The client must call wl_surface.commit on the corresponding wl_surface
150+      for the xdg_popup state to take effect.
151+
152+      For a surface to be mapped by the compositor the client must have
153+      committed both the xdg_popup state and a buffer.
154+    </description>
155 
156     <request name="destroy" type="destructor">
157       <description summary="remove xdg_popup interface">
158@@ -476,8 +506,9 @@
159 
160     <event name="popup_done">
161       <description summary="popup interaction is done">
162-	The popup_done event is sent out when a popup is dismissed
163-	by the compositor.
164+	The popup_done event is sent out when a popup is dismissed by the
165+	compositor. The client should destroy the xdg_popup object at this
166+	point.
167       </description>
168     </event>
169