wayland-protocols/xdg-shell-unstable-v6.xml
author Ryan C. Gordon <icculus@icculus.org>
Wed, 03 Oct 2018 16:54:24 -0400
changeset 12284 fe9bafcd47ba
parent 12035 1a7dec71e8e0
permissions -rw-r--r--
evdev: Don't initialize struct sigaction with "{ 0 }".

It causes warnings on some platforms, depending on the actual definition of
sigaction, and since this is static data, it'll be zero'd out anyhow.
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>