wayland-protocols/xdg-shell.xml
author Sylvain Becker <sylvain.becker@gmail.com>
Mon, 21 Jan 2019 23:41:43 +0100
changeset 12569 05aff4771d9a
parent 12035 1a7dec71e8e0
permissions -rw-r--r--
Fixed bug 4024 - GameController error "Unexpected controller element"

If mapping string is terminated with a comma, there is no more values to parse.
     1 <?xml version="1.0" encoding="UTF-8"?>
     2 <protocol name="xdg_shell">
     3 
     4   <copyright>
     5     Copyright © 2008-2013 Kristian Høgsberg
     6     Copyright © 2013      Rafael Antognolli
     7     Copyright © 2013      Jasper St. Pierre
     8     Copyright © 2010-2013 Intel Corporation
     9     Copyright © 2015-2017 Samsung Electronics Co., Ltd
    10     Copyright © 2015-2017 Red Hat Inc.
    11 
    12     Permission is hereby granted, free of charge, to any person obtaining a
    13     copy of this software and associated documentation files (the "Software"),
    14     to deal in the Software without restriction, including without limitation
    15     the rights to use, copy, modify, merge, publish, distribute, sublicense,
    16     and/or sell copies of the Software, and to permit persons to whom the
    17     Software is furnished to do so, subject to the following conditions:
    18 
    19     The above copyright notice and this permission notice (including the next
    20     paragraph) shall be included in all copies or substantial portions of the
    21     Software.
    22 
    23     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    24     IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    25     FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
    26     THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    27     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    28     FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    29     DEALINGS IN THE SOFTWARE.
    30   </copyright>
    31 
    32   <interface name="xdg_wm_base" version="1">
    33     <description summary="create desktop-style surfaces">
    34       The xdg_wm_base interface is exposed as a global object enabling clients
    35       to turn their wl_surfaces into windows in a desktop environment. It
    36       defines the basic functionality needed for clients and the compositor to
    37       create windows that can be dragged, resized, maximized, etc, as well as
    38       creating transient windows such as popup menus.
    39     </description>
    40 
    41     <enum name="error">
    42       <entry name="role" value="0" summary="given wl_surface has another role"/>
    43       <entry name="defunct_surfaces" value="1"
    44 	     summary="xdg_wm_base was destroyed before children"/>
    45       <entry name="not_the_topmost_popup" value="2"
    46 	     summary="the client tried to map or destroy a non-topmost popup"/>
    47       <entry name="invalid_popup_parent" value="3"
    48 	     summary="the client specified an invalid popup parent surface"/>
    49       <entry name="invalid_surface_state" value="4"
    50 	     summary="the client provided an invalid surface state"/>
    51       <entry name="invalid_positioner" value="5"
    52 	     summary="the client provided an invalid positioner"/>
    53     </enum>
    54 
    55     <request name="destroy" type="destructor">
    56       <description summary="destroy xdg_wm_base">
    57 	Destroy this xdg_wm_base object.
    58 
    59 	Destroying a bound xdg_wm_base object while there are surfaces
    60 	still alive created by this xdg_wm_base object instance is illegal
    61 	and will result in a protocol error.
    62       </description>
    63     </request>
    64 
    65     <request name="create_positioner">
    66       <description summary="create a positioner object">
    67 	Create a positioner object. A positioner object is used to position
    68 	surfaces relative to some parent surface. See the interface description
    69 	and xdg_surface.get_popup for details.
    70       </description>
    71       <arg name="id" type="new_id" interface="xdg_positioner"/>
    72     </request>
    73 
    74     <request name="get_xdg_surface">
    75       <description summary="create a shell surface from a surface">
    76 	This creates an xdg_surface for the given surface. While xdg_surface
    77 	itself is not a role, the corresponding surface may only be assigned
    78 	a role extending xdg_surface, such as xdg_toplevel or xdg_popup.
    79 
    80 	This creates an xdg_surface for the given surface. An xdg_surface is
    81 	used as basis to define a role to a given surface, such as xdg_toplevel
    82 	or xdg_popup. It also manages functionality shared between xdg_surface
    83 	based surface roles.
    84 
    85 	See the documentation of xdg_surface for more details about what an
    86 	xdg_surface is and how it is used.
    87       </description>
    88       <arg name="id" type="new_id" interface="xdg_surface"/>
    89       <arg name="surface" type="object" interface="wl_surface"/>
    90     </request>
    91 
    92     <request name="pong">
    93       <description summary="respond to a ping event">
    94 	A client must respond to a ping event with a pong request or
    95 	the client may be deemed unresponsive. See xdg_wm_base.ping.
    96       </description>
    97       <arg name="serial" type="uint" summary="serial of the ping event"/>
    98     </request>
    99 
   100     <event name="ping">
   101       <description summary="check if the client is alive">
   102 	The ping event asks the client if it's still alive. Pass the
   103 	serial specified in the event back to the compositor by sending
   104 	a "pong" request back with the specified serial. See xdg_wm_base.ping.
   105 
   106 	Compositors can use this to determine if the client is still
   107 	alive. It's unspecified what will happen if the client doesn't
   108 	respond to the ping request, or in what timeframe. Clients should
   109 	try to respond in a reasonable amount of time.
   110 
   111 	A compositor is free to ping in any way it wants, but a client must
   112 	always respond to any xdg_wm_base object it created.
   113       </description>
   114       <arg name="serial" type="uint" summary="pass this to the pong request"/>
   115     </event>
   116   </interface>
   117 
   118   <interface name="xdg_positioner" version="1">
   119     <description summary="child surface positioner">
   120       The xdg_positioner provides a collection of rules for the placement of a
   121       child surface relative to a parent surface. Rules can be defined to ensure
   122       the child surface remains within the visible area's borders, and to
   123       specify how the child surface changes its position, such as sliding along
   124       an axis, or flipping around a rectangle. These positioner-created rules are
   125       constrained by the requirement that a child surface must intersect with or
   126       be at least partially adjacent to its parent surface.
   127 
   128       See the various requests for details about possible rules.
   129 
   130       At the time of the request, the compositor makes a copy of the rules
   131       specified by the xdg_positioner. Thus, after the request is complete the
   132       xdg_positioner object can be destroyed or reused; further changes to the
   133       object will have no effect on previous usages.
   134 
   135       For an xdg_positioner object to be considered complete, it must have a
   136       non-zero size set by set_size, and a non-zero anchor rectangle set by
   137       set_anchor_rect. Passing an incomplete xdg_positioner object when
   138       positioning a surface raises an error.
   139     </description>
   140 
   141     <enum name="error">
   142       <entry name="invalid_input" value="0" summary="invalid input provided"/>
   143     </enum>
   144 
   145     <request name="destroy" type="destructor">
   146       <description summary="destroy the xdg_positioner object">
   147 	Notify the compositor that the xdg_positioner will no longer be used.
   148       </description>
   149     </request>
   150 
   151     <request name="set_size">
   152       <description summary="set the size of the to-be positioned rectangle">
   153 	Set the size of the surface that is to be positioned with the positioner
   154 	object. The size is in surface-local coordinates and corresponds to the
   155 	window geometry. See xdg_surface.set_window_geometry.
   156 
   157 	If a zero or negative size is set the invalid_input error is raised.
   158       </description>
   159       <arg name="width" type="int" summary="width of positioned rectangle"/>
   160       <arg name="height" type="int" summary="height of positioned rectangle"/>
   161     </request>
   162 
   163     <request name="set_anchor_rect">
   164       <description summary="set the anchor rectangle within the parent surface">
   165 	Specify the anchor rectangle within the parent surface that the child
   166 	surface will be placed relative to. The rectangle is relative to the
   167 	window geometry as defined by xdg_surface.set_window_geometry of the
   168 	parent surface.
   169 
   170 	When the xdg_positioner object is used to position a child surface, the
   171 	anchor rectangle may not extend outside the window geometry of the
   172 	positioned child's parent surface.
   173 
   174 	If a negative size is set the invalid_input error is raised.
   175       </description>
   176       <arg name="x" type="int" summary="x position of anchor rectangle"/>
   177       <arg name="y" type="int" summary="y position of anchor rectangle"/>
   178       <arg name="width" type="int" summary="width of anchor rectangle"/>
   179       <arg name="height" type="int" summary="height of anchor rectangle"/>
   180     </request>
   181 
   182     <enum name="anchor">
   183       <entry name="none" value="0"/>
   184       <entry name="top" value="1"/>
   185       <entry name="bottom" value="2"/>
   186       <entry name="left" value="3"/>
   187       <entry name="right" value="4"/>
   188       <entry name="top_left" value="5"/>
   189       <entry name="bottom_left" value="6"/>
   190       <entry name="top_right" value="7"/>
   191       <entry name="bottom_right" value="8"/>
   192     </enum>
   193 
   194     <request name="set_anchor">
   195       <description summary="set anchor rectangle anchor">
   196 	Defines the anchor point for the anchor rectangle. The specified anchor
   197 	is used derive an anchor point that the child surface will be
   198 	positioned relative to. If a corner anchor is set (e.g. 'top_left' or
   199 	'bottom_right'), the anchor point will be at the specified corner;
   200 	otherwise, the derived anchor point will be centered on the specified
   201 	edge, or in the center of the anchor rectangle if no edge is specified.
   202       </description>
   203       <arg name="anchor" type="uint" enum="anchor"
   204 	   summary="anchor"/>
   205     </request>
   206 
   207     <enum name="gravity">
   208       <entry name="none" value="0"/>
   209       <entry name="top" value="1"/>
   210       <entry name="bottom" value="2"/>
   211       <entry name="left" value="3"/>
   212       <entry name="right" value="4"/>
   213       <entry name="top_left" value="5"/>
   214       <entry name="bottom_left" value="6"/>
   215       <entry name="top_right" value="7"/>
   216       <entry name="bottom_right" value="8"/>
   217     </enum>
   218 
   219     <request name="set_gravity">
   220       <description summary="set child surface gravity">
   221 	Defines in what direction a surface should be positioned, relative to
   222 	the anchor point of the parent surface. If a corner gravity is
   223 	specified (e.g. 'bottom_right' or 'top_left'), then the child surface
   224 	will be placed towards the specified gravity; otherwise, the child
   225 	surface will be centered over the anchor point on any axis that had no
   226 	gravity specified.
   227       </description>
   228       <arg name="gravity" type="uint" enum="gravity"
   229 	   summary="gravity direction"/>
   230     </request>
   231 
   232     <enum name="constraint_adjustment" bitfield="true">
   233       <description summary="constraint adjustments">
   234 	The constraint adjustment value define ways the compositor will adjust
   235 	the position of the surface, if the unadjusted position would result
   236 	in the surface being partly constrained.
   237 
   238 	Whether a surface is considered 'constrained' is left to the compositor
   239 	to determine. For example, the surface may be partly outside the
   240 	compositor's defined 'work area', thus necessitating the child surface's
   241 	position be adjusted until it is entirely inside the work area.
   242 
   243 	The adjustments can be combined, according to a defined precedence: 1)
   244 	Flip, 2) Slide, 3) Resize.
   245       </description>
   246       <entry name="none" value="0">
   247 	<description summary="don't move the child surface when constrained">
   248 	  Don't alter the surface position even if it is constrained on some
   249 	  axis, for example partially outside the edge of an output.
   250 	</description>
   251       </entry>
   252       <entry name="slide_x" value="1">
   253 	<description summary="move along the x axis until unconstrained">
   254 	  Slide the surface along the x axis until it is no longer constrained.
   255 
   256 	  First try to slide towards the direction of the gravity on the x axis
   257 	  until either the edge in the opposite direction of the gravity is
   258 	  unconstrained or the edge in the direction of the gravity is
   259 	  constrained.
   260 
   261 	  Then try to slide towards the opposite direction of the gravity on the
   262 	  x axis until either the edge in the direction of the gravity is
   263 	  unconstrained or the edge in the opposite direction of the gravity is
   264 	  constrained.
   265 	</description>
   266       </entry>
   267       <entry name="slide_y" value="2">
   268 	<description summary="move along the y axis until unconstrained">
   269 	  Slide the surface along the y axis until it is no longer constrained.
   270 
   271 	  First try to slide towards the direction of the gravity on the y axis
   272 	  until either the edge in the opposite direction of the gravity is
   273 	  unconstrained or the edge in the direction of the gravity is
   274 	  constrained.
   275 
   276 	  Then try to slide towards the opposite direction of the gravity on the
   277 	  y axis until either the edge in the direction of the gravity is
   278 	  unconstrained or the edge in the opposite direction of the gravity is
   279 	  constrained.
   280 	</description>
   281       </entry>
   282       <entry name="flip_x" value="4">
   283 	<description summary="invert the anchor and gravity on the x axis">
   284 	  Invert the anchor and gravity on the x axis if the surface is
   285 	  constrained on the x axis. For example, if the left edge of the
   286 	  surface is constrained, the gravity is 'left' and the anchor is
   287 	  'left', change the gravity to 'right' and the anchor to 'right'.
   288 
   289 	  If the adjusted position also ends up being constrained, the resulting
   290 	  position of the flip_x adjustment will be the one before the
   291 	  adjustment.
   292 	</description>
   293       </entry>
   294       <entry name="flip_y" value="8">
   295 	<description summary="invert the anchor and gravity on the y axis">
   296 	  Invert the anchor and gravity on the y axis if the surface is
   297 	  constrained on the y axis. For example, if the bottom edge of the
   298 	  surface is constrained, the gravity is 'bottom' and the anchor is
   299 	  'bottom', change the gravity to 'top' and the anchor to 'top'.
   300 
   301 	  The adjusted position is calculated given the original anchor
   302 	  rectangle and offset, but with the new flipped anchor and gravity
   303 	  values.
   304 
   305 	  If the adjusted position also ends up being constrained, the resulting
   306 	  position of the flip_y adjustment will be the one before the
   307 	  adjustment.
   308 	</description>
   309       </entry>
   310       <entry name="resize_x" value="16">
   311 	<description summary="horizontally resize the surface">
   312 	  Resize the surface horizontally so that it is completely
   313 	  unconstrained.
   314 	</description>
   315       </entry>
   316       <entry name="resize_y" value="32">
   317 	<description summary="vertically resize the surface">
   318 	  Resize the surface vertically so that it is completely unconstrained.
   319 	</description>
   320       </entry>
   321     </enum>
   322 
   323     <request name="set_constraint_adjustment">
   324       <description summary="set the adjustment to be done when constrained">
   325 	Specify how the window should be positioned if the originally intended
   326 	position caused the surface to be constrained, meaning at least
   327 	partially outside positioning boundaries set by the compositor. The
   328 	adjustment is set by constructing a bitmask describing the adjustment to
   329 	be made when the surface is constrained on that axis.
   330 
   331 	If no bit for one axis is set, the compositor will assume that the child
   332 	surface should not change its position on that axis when constrained.
   333 
   334 	If more than one bit for one axis is set, the order of how adjustments
   335 	are applied is specified in the corresponding adjustment descriptions.
   336 
   337 	The default adjustment is none.
   338       </description>
   339       <arg name="constraint_adjustment" type="uint"
   340 	   summary="bit mask of constraint adjustments"/>
   341     </request>
   342 
   343     <request name="set_offset">
   344       <description summary="set surface position offset">
   345 	Specify the surface position offset relative to the position of the
   346 	anchor on the anchor rectangle and the anchor on the surface. For
   347 	example if the anchor of the anchor rectangle is at (x, y), the surface
   348 	has the gravity bottom|right, and the offset is (ox, oy), the calculated
   349 	surface position will be (x + ox, y + oy). The offset position of the
   350 	surface is the one used for constraint testing. See
   351 	set_constraint_adjustment.
   352 
   353 	An example use case is placing a popup menu on top of a user interface
   354 	element, while aligning the user interface element of the parent surface
   355 	with some user interface element placed somewhere in the popup surface.
   356       </description>
   357       <arg name="x" type="int" summary="surface position x offset"/>
   358       <arg name="y" type="int" summary="surface position y offset"/>
   359     </request>
   360   </interface>
   361 
   362   <interface name="xdg_surface" version="1">
   363     <description summary="desktop user interface surface base interface">
   364       An interface that may be implemented by a wl_surface, for
   365       implementations that provide a desktop-style user interface.
   366 
   367       It provides a base set of functionality required to construct user
   368       interface elements requiring management by the compositor, such as
   369       toplevel windows, menus, etc. The types of functionality are split into
   370       xdg_surface roles.
   371 
   372       Creating an xdg_surface does not set the role for a wl_surface. In order
   373       to map an xdg_surface, the client must create a role-specific object
   374       using, e.g., get_toplevel, get_popup. The wl_surface for any given
   375       xdg_surface can have at most one role, and may not be assigned any role
   376       not based on xdg_surface.
   377 
   378       A role must be assigned before any other requests are made to the
   379       xdg_surface object.
   380 
   381       The client must call wl_surface.commit on the corresponding wl_surface
   382       for the xdg_surface state to take effect.
   383 
   384       Creating an xdg_surface from a wl_surface which has a buffer attached or
   385       committed is a client error, and any attempts by a client to attach or
   386       manipulate a buffer prior to the first xdg_surface.configure call must
   387       also be treated as errors.
   388 
   389       Mapping an xdg_surface-based role surface is defined as making it
   390       possible for the surface to be shown by the compositor. Note that
   391       a mapped surface is not guaranteed to be visible once it is mapped.
   392 
   393       For an xdg_surface to be mapped by the compositor, the following
   394       conditions must be met:
   395       (1) the client has assigned an xdg_surface-based role to the surface
   396       (2) the client has set and committed the xdg_surface state and the
   397 	  role-dependent state to the surface
   398       (3) the client has committed a buffer to the surface
   399 
   400       A newly-unmapped surface is considered to have met condition (1) out
   401       of the 3 required conditions for mapping a surface if its role surface
   402       has not been destroyed.
   403     </description>
   404 
   405     <enum name="error">
   406       <entry name="not_constructed" value="1"/>
   407       <entry name="already_constructed" value="2"/>
   408       <entry name="unconfigured_buffer" value="3"/>
   409     </enum>
   410 
   411     <request name="destroy" type="destructor">
   412       <description summary="destroy the xdg_surface">
   413 	Destroy the xdg_surface object. An xdg_surface must only be destroyed
   414 	after its role object has been destroyed.
   415       </description>
   416     </request>
   417 
   418     <request name="get_toplevel">
   419       <description summary="assign the xdg_toplevel surface role">
   420 	This creates an xdg_toplevel object for the given xdg_surface and gives
   421 	the associated wl_surface the xdg_toplevel role.
   422 
   423 	See the documentation of xdg_toplevel for more details about what an
   424 	xdg_toplevel is and how it is used.
   425       </description>
   426       <arg name="id" type="new_id" interface="xdg_toplevel"/>
   427     </request>
   428 
   429     <request name="get_popup">
   430       <description summary="assign the xdg_popup surface role">
   431 	This creates an xdg_popup object for the given xdg_surface and gives
   432 	the associated wl_surface the xdg_popup role.
   433 
   434 	If null is passed as a parent, a parent surface must be specified using
   435 	some other protocol, before committing the initial state.
   436 
   437 	See the documentation of xdg_popup for more details about what an
   438 	xdg_popup is and how it is used.
   439       </description>
   440       <arg name="id" type="new_id" interface="xdg_popup"/>
   441       <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
   442       <arg name="positioner" type="object" interface="xdg_positioner"/>
   443     </request>
   444 
   445     <request name="set_window_geometry">
   446       <description summary="set the new window geometry">
   447 	The window geometry of a surface is its "visible bounds" from the
   448 	user's perspective. Client-side decorations often have invisible
   449 	portions like drop-shadows which should be ignored for the
   450 	purposes of aligning, placing and constraining windows.
   451 
   452 	The window geometry is double buffered, and will be applied at the
   453 	time wl_surface.commit of the corresponding wl_surface is called.
   454 
   455 	When maintaining a position, the compositor should treat the (x, y)
   456 	coordinate of the window geometry as the top left corner of the window.
   457 	A client changing the (x, y) window geometry coordinate should in
   458 	general not alter the position of the window.
   459 
   460 	Once the window geometry of the surface is set, it is not possible to
   461 	unset it, and it will remain the same until set_window_geometry is
   462 	called again, even if a new subsurface or buffer is attached.
   463 
   464 	If never set, the value is the full bounds of the surface,
   465 	including any subsurfaces. This updates dynamically on every
   466 	commit. This unset is meant for extremely simple clients.
   467 
   468 	The arguments are given in the surface-local coordinate space of
   469 	the wl_surface associated with this xdg_surface.
   470 
   471 	The width and height must be greater than zero. Setting an invalid size
   472 	will raise an error. When applied, the effective window geometry will be
   473 	the set window geometry clamped to the bounding rectangle of the
   474 	combined geometry of the surface of the xdg_surface and the associated
   475 	subsurfaces.
   476       </description>
   477       <arg name="x" type="int"/>
   478       <arg name="y" type="int"/>
   479       <arg name="width" type="int"/>
   480       <arg name="height" type="int"/>
   481     </request>
   482 
   483     <request name="ack_configure">
   484       <description summary="ack a configure event">
   485 	When a configure event is received, if a client commits the
   486 	surface in response to the configure event, then the client
   487 	must make an ack_configure request sometime before the commit
   488 	request, passing along the serial of the configure event.
   489 
   490 	For instance, for toplevel surfaces the compositor might use this
   491 	information to move a surface to the top left only when the client has
   492 	drawn itself for the maximized or fullscreen state.
   493 
   494 	If the client receives multiple configure events before it
   495 	can respond to one, it only has to ack the last configure event.
   496 
   497 	A client is not required to commit immediately after sending
   498 	an ack_configure request - it may even ack_configure several times
   499 	before its next surface commit.
   500 
   501 	A client may send multiple ack_configure requests before committing, but
   502 	only the last request sent before a commit indicates which configure
   503 	event the client really is responding to.
   504       </description>
   505       <arg name="serial" type="uint" summary="the serial from the configure event"/>
   506     </request>
   507 
   508     <event name="configure">
   509       <description summary="suggest a surface change">
   510 	The configure event marks the end of a configure sequence. A configure
   511 	sequence is a set of one or more events configuring the state of the
   512 	xdg_surface, including the final xdg_surface.configure event.
   513 
   514 	Where applicable, xdg_surface surface roles will during a configure
   515 	sequence extend this event as a latched state sent as events before the
   516 	xdg_surface.configure event. Such events should be considered to make up
   517 	a set of atomically applied configuration states, where the
   518 	xdg_surface.configure commits the accumulated state.
   519 
   520 	Clients should arrange their surface for the new states, and then send
   521 	an ack_configure request with the serial sent in this configure event at
   522 	some point before committing the new surface.
   523 
   524 	If the client receives multiple configure events before it can respond
   525 	to one, it is free to discard all but the last event it received.
   526       </description>
   527       <arg name="serial" type="uint" summary="serial of the configure event"/>
   528     </event>
   529   </interface>
   530 
   531   <interface name="xdg_toplevel" version="1">
   532     <description summary="toplevel surface">
   533       This interface defines an xdg_surface role which allows a surface to,
   534       among other things, set window-like properties such as maximize,
   535       fullscreen, and minimize, set application-specific metadata like title and
   536       id, and well as trigger user interactive operations such as interactive
   537       resize and move.
   538 
   539       Unmapping an xdg_toplevel means that the surface cannot be shown
   540       by the compositor until it is explicitly mapped again.
   541       All active operations (e.g., move, resize) are canceled and all
   542       attributes (e.g. title, state, stacking, ...) are discarded for
   543       an xdg_toplevel surface when it is unmapped.
   544 
   545       Attaching a null buffer to a toplevel unmaps the surface.
   546     </description>
   547 
   548     <request name="destroy" type="destructor">
   549       <description summary="destroy the xdg_toplevel">
   550 	This request destroys the role surface and unmaps the surface;
   551 	see "Unmapping" behavior in interface section for details.
   552       </description>
   553     </request>
   554 
   555     <request name="set_parent">
   556       <description summary="set the parent of this surface">
   557 	Set the "parent" of this surface. This surface should be stacked
   558 	above the parent surface and all other ancestor surfaces.
   559 
   560 	Parent windows should be set on dialogs, toolboxes, or other
   561 	"auxiliary" surfaces, so that the parent is raised when the dialog
   562 	is raised.
   563 
   564 	Setting a null parent for a child window removes any parent-child
   565 	relationship for the child. Setting a null parent for a window which
   566 	currently has no parent is a no-op.
   567 
   568 	If the parent is unmapped then its children are managed as
   569 	though the parent of the now-unmapped parent has become the
   570 	parent of this surface. If no parent exists for the now-unmapped
   571 	parent then the children are managed as though they have no
   572 	parent surface.
   573       </description>
   574       <arg name="parent" type="object" interface="xdg_toplevel" allow-null="true"/>
   575     </request>
   576 
   577     <request name="set_title">
   578       <description summary="set surface title">
   579 	Set a short title for the surface.
   580 
   581 	This string may be used to identify the surface in a task bar,
   582 	window list, or other user interface elements provided by the
   583 	compositor.
   584 
   585 	The string must be encoded in UTF-8.
   586       </description>
   587       <arg name="title" type="string"/>
   588     </request>
   589 
   590     <request name="set_app_id">
   591       <description summary="set application ID">
   592 	Set an application identifier for the surface.
   593 
   594 	The app ID identifies the general class of applications to which
   595 	the surface belongs. The compositor can use this to group multiple
   596 	surfaces together, or to determine how to launch a new application.
   597 
   598 	For D-Bus activatable applications, the app ID is used as the D-Bus
   599 	service name.
   600 
   601 	The compositor shell will try to group application surfaces together
   602 	by their app ID. As a best practice, it is suggested to select app
   603 	ID's that match the basename of the application's .desktop file.
   604 	For example, "org.freedesktop.FooViewer" where the .desktop file is
   605 	"org.freedesktop.FooViewer.desktop".
   606 
   607 	See the desktop-entry specification [0] for more details on
   608 	application identifiers and how they relate to well-known D-Bus
   609 	names and .desktop files.
   610 
   611 	[0] http://standards.freedesktop.org/desktop-entry-spec/
   612       </description>
   613       <arg name="app_id" type="string"/>
   614     </request>
   615 
   616     <request name="show_window_menu">
   617       <description summary="show the window menu">
   618 	Clients implementing client-side decorations might want to show
   619 	a context menu when right-clicking on the decorations, giving the
   620 	user a menu that they can use to maximize or minimize the window.
   621 
   622 	This request asks the compositor to pop up such a window menu at
   623 	the given position, relative to the local surface coordinates of
   624 	the parent surface. There are no guarantees as to what menu items
   625 	the window menu contains.
   626 
   627 	This request must be used in response to some sort of user action
   628 	like a button press, key press, or touch down event.
   629       </description>
   630       <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
   631       <arg name="serial" type="uint" summary="the serial of the user event"/>
   632       <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
   633       <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
   634     </request>
   635 
   636     <request name="move">
   637       <description summary="start an interactive move">
   638 	Start an interactive, user-driven move of the surface.
   639 
   640 	This request must be used in response to some sort of user action
   641 	like a button press, key press, or touch down event. The passed
   642 	serial is used to determine the type of interactive move (touch,
   643 	pointer, etc).
   644 
   645 	The server may ignore move requests depending on the state of
   646 	the surface (e.g. fullscreen or maximized), or if the passed serial
   647 	is no longer valid.
   648 
   649 	If triggered, the surface will lose the focus of the device
   650 	(wl_pointer, wl_touch, etc) used for the move. It is up to the
   651 	compositor to visually indicate that the move is taking place, such as
   652 	updating a pointer cursor, during the move. There is no guarantee
   653 	that the device focus will return when the move is completed.
   654       </description>
   655       <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
   656       <arg name="serial" type="uint" summary="the serial of the user event"/>
   657     </request>
   658 
   659     <enum name="resize_edge">
   660       <description summary="edge values for resizing">
   661 	These values are used to indicate which edge of a surface
   662 	is being dragged in a resize operation.
   663       </description>
   664       <entry name="none" value="0"/>
   665       <entry name="top" value="1"/>
   666       <entry name="bottom" value="2"/>
   667       <entry name="left" value="4"/>
   668       <entry name="top_left" value="5"/>
   669       <entry name="bottom_left" value="6"/>
   670       <entry name="right" value="8"/>
   671       <entry name="top_right" value="9"/>
   672       <entry name="bottom_right" value="10"/>
   673     </enum>
   674 
   675     <request name="resize">
   676       <description summary="start an interactive resize">
   677 	Start a user-driven, interactive resize of the surface.
   678 
   679 	This request must be used in response to some sort of user action
   680 	like a button press, key press, or touch down event. The passed
   681 	serial is used to determine the type of interactive resize (touch,
   682 	pointer, etc).
   683 
   684 	The server may ignore resize requests depending on the state of
   685 	the surface (e.g. fullscreen or maximized).
   686 
   687 	If triggered, the client will receive configure events with the
   688 	"resize" state enum value and the expected sizes. See the "resize"
   689 	enum value for more details about what is required. The client
   690 	must also acknowledge configure events using "ack_configure". After
   691 	the resize is completed, the client will receive another "configure"
   692 	event without the resize state.
   693 
   694 	If triggered, the surface also will lose the focus of the device
   695 	(wl_pointer, wl_touch, etc) used for the resize. It is up to the
   696 	compositor to visually indicate that the resize is taking place,
   697 	such as updating a pointer cursor, during the resize. There is no
   698 	guarantee that the device focus will return when the resize is
   699 	completed.
   700 
   701 	The edges parameter specifies how the surface should be resized,
   702 	and is one of the values of the resize_edge enum. The compositor
   703 	may use this information to update the surface position for
   704 	example when dragging the top left corner. The compositor may also
   705 	use this information to adapt its behavior, e.g. choose an
   706 	appropriate cursor image.
   707       </description>
   708       <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
   709       <arg name="serial" type="uint" summary="the serial of the user event"/>
   710       <arg name="edges" type="uint" summary="which edge or corner is being dragged"/>
   711     </request>
   712 
   713     <enum name="state">
   714       <description summary="types of state on the surface">
   715 	The different state values used on the surface. This is designed for
   716 	state values like maximized, fullscreen. It is paired with the
   717 	configure event to ensure that both the client and the compositor
   718 	setting the state can be synchronized.
   719 
   720 	States set in this way are double-buffered. They will get applied on
   721 	the next commit.
   722       </description>
   723       <entry name="maximized" value="1" summary="the surface is maximized">
   724 	<description summary="the surface is maximized">
   725 	  The surface is maximized. The window geometry specified in the configure
   726 	  event must be obeyed by the client.
   727 	</description>
   728       </entry>
   729       <entry name="fullscreen" value="2" summary="the surface is fullscreen">
   730 	<description summary="the surface is fullscreen">
   731 	  The surface is fullscreen. The window geometry specified in the
   732 	  configure event is a maximum; the client cannot resize beyond it. For
   733 	  a surface to cover the whole fullscreened area, the geometry
   734 	  dimensions must be obeyed by the client. For more details, see
   735 	  xdg_toplevel.set_fullscreen.
   736 	</description>
   737       </entry>
   738       <entry name="resizing" value="3" summary="the surface is being resized">
   739 	<description summary="the surface is being resized">
   740 	  The surface is being resized. The window geometry specified in the
   741 	  configure event is a maximum; the client cannot resize beyond it.
   742 	  Clients that have aspect ratio or cell sizing configuration can use
   743 	  a smaller size, however.
   744 	</description>
   745       </entry>
   746       <entry name="activated" value="4" summary="the surface is now activated">
   747 	<description summary="the surface is now activated">
   748 	  Client window decorations should be painted as if the window is
   749 	  active. Do not assume this means that the window actually has
   750 	  keyboard or pointer focus.
   751 	</description>
   752       </entry>
   753     </enum>
   754 
   755     <request name="set_max_size">
   756       <description summary="set the maximum size">
   757 	Set a maximum size for the window.
   758 
   759 	The client can specify a maximum size so that the compositor does
   760 	not try to configure the window beyond this size.
   761 
   762 	The width and height arguments are in window geometry coordinates.
   763 	See xdg_surface.set_window_geometry.
   764 
   765 	Values set in this way are double-buffered. They will get applied
   766 	on the next commit.
   767 
   768 	The compositor can use this information to allow or disallow
   769 	different states like maximize or fullscreen and draw accurate
   770 	animations.
   771 
   772 	Similarly, a tiling window manager may use this information to
   773 	place and resize client windows in a more effective way.
   774 
   775 	The client should not rely on the compositor to obey the maximum
   776 	size. The compositor may decide to ignore the values set by the
   777 	client and request a larger size.
   778 
   779 	If never set, or a value of zero in the request, means that the
   780 	client has no expected maximum size in the given dimension.
   781 	As a result, a client wishing to reset the maximum size
   782 	to an unspecified state can use zero for width and height in the
   783 	request.
   784 
   785 	Requesting a maximum size to be smaller than the minimum size of
   786 	a surface is illegal and will result in a protocol error.
   787 
   788 	The width and height must be greater than or equal to zero. Using
   789 	strictly negative values for width and height will result in a
   790 	protocol error.
   791       </description>
   792       <arg name="width" type="int"/>
   793       <arg name="height" type="int"/>
   794     </request>
   795 
   796     <request name="set_min_size">
   797       <description summary="set the minimum size">
   798 	Set a minimum size for the window.
   799 
   800 	The client can specify a minimum size so that the compositor does
   801 	not try to configure the window below this size.
   802 
   803 	The width and height arguments are in window geometry coordinates.
   804 	See xdg_surface.set_window_geometry.
   805 
   806 	Values set in this way are double-buffered. They will get applied
   807 	on the next commit.
   808 
   809 	The compositor can use this information to allow or disallow
   810 	different states like maximize or fullscreen and draw accurate
   811 	animations.
   812 
   813 	Similarly, a tiling window manager may use this information to
   814 	place and resize client windows in a more effective way.
   815 
   816 	The client should not rely on the compositor to obey the minimum
   817 	size. The compositor may decide to ignore the values set by the
   818 	client and request a smaller size.
   819 
   820 	If never set, or a value of zero in the request, means that the
   821 	client has no expected minimum size in the given dimension.
   822 	As a result, a client wishing to reset the minimum size
   823 	to an unspecified state can use zero for width and height in the
   824 	request.
   825 
   826 	Requesting a minimum size to be larger than the maximum size of
   827 	a surface is illegal and will result in a protocol error.
   828 
   829 	The width and height must be greater than or equal to zero. Using
   830 	strictly negative values for width and height will result in a
   831 	protocol error.
   832       </description>
   833       <arg name="width" type="int"/>
   834       <arg name="height" type="int"/>
   835     </request>
   836 
   837     <request name="set_maximized">
   838       <description summary="maximize the window">
   839 	Maximize the surface.
   840 
   841 	After requesting that the surface should be maximized, the compositor
   842 	will respond by emitting a configure event with the "maximized" state
   843 	and the required window geometry. The client should then update its
   844 	content, drawing it in a maximized state, i.e. without shadow or other
   845 	decoration outside of the window geometry. The client must also
   846 	acknowledge the configure when committing the new content (see
   847 	ack_configure).
   848 
   849 	It is up to the compositor to decide how and where to maximize the
   850 	surface, for example which output and what region of the screen should
   851 	be used.
   852 
   853 	If the surface was already maximized, the compositor will still emit
   854 	a configure event with the "maximized" state.
   855 
   856 	If the surface is in a fullscreen state, this request has no direct
   857 	effect. It will alter the state the surface is returned to when
   858 	unmaximized if not overridden by the compositor.
   859       </description>
   860     </request>
   861 
   862     <request name="unset_maximized">
   863       <description summary="unmaximize the window">
   864 	Unmaximize the surface.
   865 
   866 	After requesting that the surface should be unmaximized, the compositor
   867 	will respond by emitting a configure event without the "maximized"
   868 	state. If available, the compositor will include the window geometry
   869 	dimensions the window had prior to being maximized in the configure
   870 	event. The client must then update its content, drawing it in a
   871 	regular state, i.e. potentially with shadow, etc. The client must also
   872 	acknowledge the configure when committing the new content (see
   873 	ack_configure).
   874 
   875 	It is up to the compositor to position the surface after it was
   876 	unmaximized; usually the position the surface had before maximizing, if
   877 	applicable.
   878 
   879 	If the surface was already not maximized, the compositor will still
   880 	emit a configure event without the "maximized" state.
   881 
   882 	If the surface is in a fullscreen state, this request has no direct
   883 	effect. It will alter the state the surface is returned to when
   884 	unmaximized if not overridden by the compositor.
   885       </description>
   886     </request>
   887 
   888     <request name="set_fullscreen">
   889       <description summary="set the window as fullscreen on an output">
   890 	Make the surface fullscreen.
   891 
   892 	After requesting that the surface should be fullscreened, the
   893 	compositor will respond by emitting a configure event with the
   894 	"fullscreen" state and the fullscreen window geometry. The client must
   895 	also acknowledge the configure when committing the new content (see
   896 	ack_configure).
   897 
   898 	The output passed by the request indicates the client's preference as
   899 	to which display it should be set fullscreen on. If this value is NULL,
   900 	it's up to the compositor to choose which display will be used to map
   901 	this surface.
   902 
   903 	If the surface doesn't cover the whole output, the compositor will
   904 	position the surface in the center of the output and compensate with
   905 	with border fill covering the rest of the output. The content of the
   906 	border fill is undefined, but should be assumed to be in some way that
   907 	attempts to blend into the surrounding area (e.g. solid black).
   908 
   909 	If the fullscreened surface is not opaque, the compositor must make
   910 	sure that other screen content not part of the same surface tree (made
   911 	up of subsurfaces, popups or similarly coupled surfaces) are not
   912 	visible below the fullscreened surface.
   913       </description>
   914       <arg name="output" type="object" interface="wl_output" allow-null="true"/>
   915     </request>
   916 
   917     <request name="unset_fullscreen">
   918       <description summary="unset the window as fullscreen">
   919 	Make the surface no longer fullscreen.
   920 
   921 	After requesting that the surface should be unfullscreened, the
   922 	compositor will respond by emitting a configure event without the
   923 	"fullscreen" state.
   924 
   925 	Making a surface unfullscreen sets states for the surface based on the following:
   926 	* the state(s) it may have had before becoming fullscreen
   927 	* any state(s) decided by the compositor
   928 	* any state(s) requested by the client while the surface was fullscreen
   929 
   930 	The compositor may include the previous window geometry dimensions in
   931 	the configure event, if applicable.
   932 
   933 	The client must also acknowledge the configure when committing the new
   934 	content (see ack_configure).
   935       </description>
   936     </request>
   937 
   938     <request name="set_minimized">
   939       <description summary="set the window as minimized">
   940 	Request that the compositor minimize your surface. There is no
   941 	way to know if the surface is currently minimized, nor is there
   942 	any way to unset minimization on this surface.
   943 
   944 	If you are looking to throttle redrawing when minimized, please
   945 	instead use the wl_surface.frame event for this, as this will
   946 	also work with live previews on windows in Alt-Tab, Expose or
   947 	similar compositor features.
   948       </description>
   949     </request>
   950 
   951     <event name="configure">
   952       <description summary="suggest a surface change">
   953 	This configure event asks the client to resize its toplevel surface or
   954 	to change its state. The configured state should not be applied
   955 	immediately. See xdg_surface.configure for details.
   956 
   957 	The width and height arguments specify a hint to the window
   958 	about how its surface should be resized in window geometry
   959 	coordinates. See set_window_geometry.
   960 
   961 	If the width or height arguments are zero, it means the client
   962 	should decide its own window dimension. This may happen when the
   963 	compositor needs to configure the state of the surface but doesn't
   964 	have any information about any previous or expected dimension.
   965 
   966 	The states listed in the event specify how the width/height
   967 	arguments should be interpreted, and possibly how it should be
   968 	drawn.
   969 
   970 	Clients must send an ack_configure in response to this event. See
   971 	xdg_surface.configure and xdg_surface.ack_configure for details.
   972       </description>
   973       <arg name="width" type="int"/>
   974       <arg name="height" type="int"/>
   975       <arg name="states" type="array"/>
   976     </event>
   977 
   978     <event name="close">
   979       <description summary="surface wants to be closed">
   980 	The close event is sent by the compositor when the user
   981 	wants the surface to be closed. This should be equivalent to
   982 	the user clicking the close button in client-side decorations,
   983 	if your application has any.
   984 
   985 	This is only a request that the user intends to close the
   986 	window. The client may choose to ignore this request, or show
   987 	a dialog to ask the user to save their data, etc.
   988       </description>
   989     </event>
   990   </interface>
   991 
   992   <interface name="xdg_popup" version="1">
   993     <description summary="short-lived, popup surfaces for menus">
   994       A popup surface is a short-lived, temporary surface. It can be used to
   995       implement for example menus, popovers, tooltips and other similar user
   996       interface concepts.
   997 
   998       A popup can be made to take an explicit grab. See xdg_popup.grab for
   999       details.
  1000 
  1001       When the popup is dismissed, a popup_done event will be sent out, and at
  1002       the same time the surface will be unmapped. See the xdg_popup.popup_done
  1003       event for details.
  1004 
  1005       Explicitly destroying the xdg_popup object will also dismiss the popup and
  1006       unmap the surface. Clients that want to dismiss the popup when another
  1007       surface of their own is clicked should dismiss the popup using the destroy
  1008       request.
  1009 
  1010       The parent surface must have either the xdg_toplevel or xdg_popup surface
  1011       role.
  1012 
  1013       A newly created xdg_popup will be stacked on top of all previously created
  1014       xdg_popup surfaces associated with the same xdg_toplevel.
  1015 
  1016       The parent of an xdg_popup must be mapped (see the xdg_surface
  1017       description) before the xdg_popup itself.
  1018 
  1019       The x and y arguments passed when creating the popup object specify
  1020       where the top left of the popup should be placed, relative to the
  1021       local surface coordinates of the parent surface. See
  1022       xdg_surface.get_popup. An xdg_popup must intersect with or be at least
  1023       partially adjacent to its parent surface.
  1024 
  1025       The client must call wl_surface.commit on the corresponding wl_surface
  1026       for the xdg_popup state to take effect.
  1027     </description>
  1028 
  1029     <enum name="error">
  1030       <entry name="invalid_grab" value="0"
  1031 	     summary="tried to grab after being mapped"/>
  1032     </enum>
  1033 
  1034     <request name="destroy" type="destructor">
  1035       <description summary="remove xdg_popup interface">
  1036 	This destroys the popup. Explicitly destroying the xdg_popup
  1037 	object will also dismiss the popup, and unmap the surface.
  1038 
  1039 	If this xdg_popup is not the "topmost" popup, a protocol error
  1040 	will be sent.
  1041       </description>
  1042     </request>
  1043 
  1044     <request name="grab">
  1045       <description summary="make the popup take an explicit grab">
  1046 	This request makes the created popup take an explicit grab. An explicit
  1047 	grab will be dismissed when the user dismisses the popup, or when the
  1048 	client destroys the xdg_popup. This can be done by the user clicking
  1049 	outside the surface, using the keyboard, or even locking the screen
  1050 	through closing the lid or a timeout.
  1051 
  1052 	If the compositor denies the grab, the popup will be immediately
  1053 	dismissed.
  1054 
  1055 	This request must be used in response to some sort of user action like a
  1056 	button press, key press, or touch down event. The serial number of the
  1057 	event should be passed as 'serial'.
  1058 
  1059 	The parent of a grabbing popup must either be an xdg_toplevel surface or
  1060 	another xdg_popup with an explicit grab. If the parent is another
  1061 	xdg_popup it means that the popups are nested, with this popup now being
  1062 	the topmost popup.
  1063 
  1064 	Nested popups must be destroyed in the reverse order they were created
  1065 	in, e.g. the only popup you are allowed to destroy at all times is the
  1066 	topmost one.
  1067 
  1068 	When compositors choose to dismiss a popup, they may dismiss every
  1069 	nested grabbing popup as well. When a compositor dismisses popups, it
  1070 	will follow the same dismissing order as required from the client.
  1071 
  1072 	The parent of a grabbing popup must either be another xdg_popup with an
  1073 	active explicit grab, or an xdg_popup or xdg_toplevel, if there are no
  1074 	explicit grabs already taken.
  1075 
  1076 	If the topmost grabbing popup is destroyed, the grab will be returned to
  1077 	the parent of the popup, if that parent previously had an explicit grab.
  1078 
  1079 	If the parent is a grabbing popup which has already been dismissed, this
  1080 	popup will be immediately dismissed. If the parent is a popup that did
  1081 	not take an explicit grab, an error will be raised.
  1082 
  1083 	During a popup grab, the client owning the grab will receive pointer
  1084 	and touch events for all their surfaces as normal (similar to an
  1085 	"owner-events" grab in X11 parlance), while the top most grabbing popup
  1086 	will always have keyboard focus.
  1087       </description>
  1088       <arg name="seat" type="object" interface="wl_seat"
  1089 	   summary="the wl_seat of the user event"/>
  1090       <arg name="serial" type="uint" summary="the serial of the user event"/>
  1091     </request>
  1092 
  1093     <event name="configure">
  1094       <description summary="configure the popup surface">
  1095 	This event asks the popup surface to configure itself given the
  1096 	configuration. The configured state should not be applied immediately.
  1097 	See xdg_surface.configure for details.
  1098 
  1099 	The x and y arguments represent the position the popup was placed at
  1100 	given the xdg_positioner rule, relative to the upper left corner of the
  1101 	window geometry of the parent surface.
  1102       </description>
  1103       <arg name="x" type="int"
  1104 	   summary="x position relative to parent surface window geometry"/>
  1105       <arg name="y" type="int"
  1106 	   summary="y position relative to parent surface window geometry"/>
  1107       <arg name="width" type="int" summary="window geometry width"/>
  1108       <arg name="height" type="int" summary="window geometry height"/>
  1109     </event>
  1110 
  1111     <event name="popup_done">
  1112       <description summary="popup interaction is done">
  1113 	The popup_done event is sent out when a popup is dismissed by the
  1114 	compositor. The client should destroy the xdg_popup object at this
  1115 	point.
  1116       </description>
  1117     </event>
  1118 
  1119   </interface>
  1120 </protocol>