wayland-protocols/xdg-shell-unstable-v6.xml
author Ryan C. Gordon <icculus@icculus.org>
Mon, 25 Jun 2018 09:37:25 -0700
changeset 12035 1a7dec71e8e0
permissions -rw-r--r--
wayland: Keep protocol XML files in-tree.

Now you don't need the latest Wayland installed to build with
newer protocols supported, as they'll build correctly; even if
your system can't use them, we can make intelligent decisions
at runtime about what's available on the current machine anyhow.

This also simplifies some logic and possible failure cases in
the configure and CMake scripts.

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