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