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

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