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

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

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

Fixes Bugzilla #4207.
icculus@12035
     1
<?xml version="1.0" encoding="UTF-8"?>
icculus@12035
     2
<protocol name="pointer_constraints_unstable_v1">
icculus@12035
     3
icculus@12035
     4
  <copyright>
icculus@12035
     5
    Copyright © 2014      Jonas Ådahl
icculus@12035
     6
    Copyright © 2015      Red Hat Inc.
icculus@12035
     7
icculus@12035
     8
    Permission is hereby granted, free of charge, to any person obtaining a
icculus@12035
     9
    copy of this software and associated documentation files (the "Software"),
icculus@12035
    10
    to deal in the Software without restriction, including without limitation
icculus@12035
    11
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
icculus@12035
    12
    and/or sell copies of the Software, and to permit persons to whom the
icculus@12035
    13
    Software is furnished to do so, subject to the following conditions:
icculus@12035
    14
icculus@12035
    15
    The above copyright notice and this permission notice (including the next
icculus@12035
    16
    paragraph) shall be included in all copies or substantial portions of the
icculus@12035
    17
    Software.
icculus@12035
    18
icculus@12035
    19
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
icculus@12035
    20
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
icculus@12035
    21
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
icculus@12035
    22
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
icculus@12035
    23
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
icculus@12035
    24
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
icculus@12035
    25
    DEALINGS IN THE SOFTWARE.
icculus@12035
    26
  </copyright>
icculus@12035
    27
icculus@12035
    28
  <description summary="protocol for constraining pointer motions">
icculus@12035
    29
    This protocol specifies a set of interfaces used for adding constraints to
icculus@12035
    30
    the motion of a pointer. Possible constraints include confining pointer
icculus@12035
    31
    motions to a given region, or locking it to its current position.
icculus@12035
    32
icculus@12035
    33
    In order to constrain the pointer, a client must first bind the global
icculus@12035
    34
    interface "wp_pointer_constraints" which, if a compositor supports pointer
icculus@12035
    35
    constraints, is exposed by the registry. Using the bound global object, the
icculus@12035
    36
    client uses the request that corresponds to the type of constraint it wants
icculus@12035
    37
    to make. See wp_pointer_constraints for more details.
icculus@12035
    38
icculus@12035
    39
    Warning! The protocol described in this file is experimental and backward
icculus@12035
    40
    incompatible changes may be made. Backward compatible changes may be added
icculus@12035
    41
    together with the corresponding interface version bump. Backward
icculus@12035
    42
    incompatible changes are done by bumping the version number in the protocol
icculus@12035
    43
    and interface names and resetting the interface version. Once the protocol
icculus@12035
    44
    is to be declared stable, the 'z' prefix and the version number in the
icculus@12035
    45
    protocol and interface names are removed and the interface version number is
icculus@12035
    46
    reset.
icculus@12035
    47
  </description>
icculus@12035
    48
icculus@12035
    49
  <interface name="zwp_pointer_constraints_v1" version="1">
icculus@12035
    50
    <description summary="constrain the movement of a pointer">
icculus@12035
    51
      The global interface exposing pointer constraining functionality. It
icculus@12035
    52
      exposes two requests: lock_pointer for locking the pointer to its
icculus@12035
    53
      position, and confine_pointer for locking the pointer to a region.
icculus@12035
    54
icculus@12035
    55
      The lock_pointer and confine_pointer requests create the objects
icculus@12035
    56
      wp_locked_pointer and wp_confined_pointer respectively, and the client can
icculus@12035
    57
      use these objects to interact with the lock.
icculus@12035
    58
icculus@12035
    59
      For any surface, only one lock or confinement may be active across all
icculus@12035
    60
      wl_pointer objects of the same seat. If a lock or confinement is requested
icculus@12035
    61
      when another lock or confinement is active or requested on the same surface
icculus@12035
    62
      and with any of the wl_pointer objects of the same seat, an
icculus@12035
    63
      'already_constrained' error will be raised.
icculus@12035
    64
    </description>
icculus@12035
    65
icculus@12035
    66
    <enum name="error">
icculus@12035
    67
      <description summary="wp_pointer_constraints error values">
icculus@12035
    68
	These errors can be emitted in response to wp_pointer_constraints
icculus@12035
    69
	requests.
icculus@12035
    70
      </description>
icculus@12035
    71
      <entry name="already_constrained" value="1"
icculus@12035
    72
	     summary="pointer constraint already requested on that surface"/>
icculus@12035
    73
    </enum>
icculus@12035
    74
icculus@12035
    75
    <enum name="lifetime">
icculus@12035
    76
      <description summary="constraint lifetime">
icculus@12035
    77
	These values represent different lifetime semantics. They are passed
icculus@12035
    78
	as arguments to the factory requests to specify how the constraint
icculus@12035
    79
	lifetimes should be managed.
icculus@12035
    80
      </description>
icculus@12035
    81
      <entry name="oneshot" value="1">
icculus@12035
    82
	<description summary="the pointer constraint is defunct once deactivated">
icculus@12035
    83
	  A oneshot pointer constraint will never reactivate once it has been
icculus@12035
    84
	  deactivated. See the corresponding deactivation event
icculus@12035
    85
	  (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) for
icculus@12035
    86
	  details.
icculus@12035
    87
	</description>
icculus@12035
    88
      </entry>
icculus@12035
    89
      <entry name="persistent" value="2">
icculus@12035
    90
	<description summary="the pointer constraint may reactivate">
icculus@12035
    91
	  A persistent pointer constraint may again reactivate once it has
icculus@12035
    92
	  been deactivated. See the corresponding deactivation event
icculus@12035
    93
	  (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) for
icculus@12035
    94
	  details.
icculus@12035
    95
	</description>
icculus@12035
    96
      </entry>
icculus@12035
    97
    </enum>
icculus@12035
    98
icculus@12035
    99
    <request name="destroy" type="destructor">
icculus@12035
   100
      <description summary="destroy the pointer constraints manager object">
icculus@12035
   101
	Used by the client to notify the server that it will no longer use this
icculus@12035
   102
	pointer constraints object.
icculus@12035
   103
      </description>
icculus@12035
   104
    </request>
icculus@12035
   105
icculus@12035
   106
    <request name="lock_pointer">
icculus@12035
   107
      <description summary="lock pointer to a position">
icculus@12035
   108
	The lock_pointer request lets the client request to disable movements of
icculus@12035
   109
	the virtual pointer (i.e. the cursor), effectively locking the pointer
icculus@12035
   110
	to a position. This request may not take effect immediately; in the
icculus@12035
   111
	future, when the compositor deems implementation-specific constraints
icculus@12035
   112
	are satisfied, the pointer lock will be activated and the compositor
icculus@12035
   113
	sends a locked event.
icculus@12035
   114
icculus@12035
   115
	The protocol provides no guarantee that the constraints are ever
icculus@12035
   116
	satisfied, and does not require the compositor to send an error if the
icculus@12035
   117
	constraints cannot ever be satisfied. It is thus possible to request a
icculus@12035
   118
	lock that will never activate.
icculus@12035
   119
icculus@12035
   120
	There may not be another pointer constraint of any kind requested or
icculus@12035
   121
	active on the surface for any of the wl_pointer objects of the seat of
icculus@12035
   122
	the passed pointer when requesting a lock. If there is, an error will be
icculus@12035
   123
	raised. See general pointer lock documentation for more details.
icculus@12035
   124
icculus@12035
   125
	The intersection of the region passed with this request and the input
icculus@12035
   126
	region of the surface is used to determine where the pointer must be
icculus@12035
   127
	in order for the lock to activate. It is up to the compositor whether to
icculus@12035
   128
	warp the pointer or require some kind of user interaction for the lock
icculus@12035
   129
	to activate. If the region is null the surface input region is used.
icculus@12035
   130
icculus@12035
   131
	A surface may receive pointer focus without the lock being activated.
icculus@12035
   132
icculus@12035
   133
	The request creates a new object wp_locked_pointer which is used to
icculus@12035
   134
	interact with the lock as well as receive updates about its state. See
icculus@12035
   135
	the the description of wp_locked_pointer for further information.
icculus@12035
   136
icculus@12035
   137
	Note that while a pointer is locked, the wl_pointer objects of the
icculus@12035
   138
	corresponding seat will not emit any wl_pointer.motion events, but
icculus@12035
   139
	relative motion events will still be emitted via wp_relative_pointer
icculus@12035
   140
	objects of the same seat. wl_pointer.axis and wl_pointer.button events
icculus@12035
   141
	are unaffected.
icculus@12035
   142
      </description>
icculus@12035
   143
      <arg name="id" type="new_id" interface="zwp_locked_pointer_v1"/>
icculus@12035
   144
      <arg name="surface" type="object" interface="wl_surface"
icculus@12035
   145
	   summary="surface to lock pointer to"/>
icculus@12035
   146
      <arg name="pointer" type="object" interface="wl_pointer"
icculus@12035
   147
	   summary="the pointer that should be locked"/>
icculus@12035
   148
      <arg name="region" type="object" interface="wl_region" allow-null="true"
icculus@12035
   149
	   summary="region of surface"/>
icculus@12035
   150
      <arg name="lifetime" type="uint" summary="lock lifetime"/>
icculus@12035
   151
    </request>
icculus@12035
   152
icculus@12035
   153
    <request name="confine_pointer">
icculus@12035
   154
      <description summary="confine pointer to a region">
icculus@12035
   155
	The confine_pointer request lets the client request to confine the
icculus@12035
   156
	pointer cursor to a given region. This request may not take effect
icculus@12035
   157
	immediately; in the future, when the compositor deems implementation-
icculus@12035
   158
	specific constraints are satisfied, the pointer confinement will be
icculus@12035
   159
	activated and the compositor sends a confined event.
icculus@12035
   160
icculus@12035
   161
	The intersection of the region passed with this request and the input
icculus@12035
   162
	region of the surface is used to determine where the pointer must be
icculus@12035
   163
	in order for the confinement to activate. It is up to the compositor
icculus@12035
   164
	whether to warp the pointer or require some kind of user interaction for
icculus@12035
   165
	the confinement to activate. If the region is null the surface input
icculus@12035
   166
	region is used.
icculus@12035
   167
icculus@12035
   168
	The request will create a new object wp_confined_pointer which is used
icculus@12035
   169
	to interact with the confinement as well as receive updates about its
icculus@12035
   170
	state. See the the description of wp_confined_pointer for further
icculus@12035
   171
	information.
icculus@12035
   172
      </description>
icculus@12035
   173
      <arg name="id" type="new_id" interface="zwp_confined_pointer_v1"/>
icculus@12035
   174
      <arg name="surface" type="object" interface="wl_surface"
icculus@12035
   175
	   summary="surface to lock pointer to"/>
icculus@12035
   176
      <arg name="pointer" type="object" interface="wl_pointer"
icculus@12035
   177
	   summary="the pointer that should be confined"/>
icculus@12035
   178
      <arg name="region" type="object" interface="wl_region" allow-null="true"
icculus@12035
   179
	   summary="region of surface"/>
icculus@12035
   180
      <arg name="lifetime" type="uint" summary="confinement lifetime"/>
icculus@12035
   181
    </request>
icculus@12035
   182
  </interface>
icculus@12035
   183
icculus@12035
   184
  <interface name="zwp_locked_pointer_v1" version="1">
icculus@12035
   185
    <description summary="receive relative pointer motion events">
icculus@12035
   186
      The wp_locked_pointer interface represents a locked pointer state.
icculus@12035
   187
icculus@12035
   188
      While the lock of this object is active, the wl_pointer objects of the
icculus@12035
   189
      associated seat will not emit any wl_pointer.motion events.
icculus@12035
   190
icculus@12035
   191
      This object will send the event 'locked' when the lock is activated.
icculus@12035
   192
      Whenever the lock is activated, it is guaranteed that the locked surface
icculus@12035
   193
      will already have received pointer focus and that the pointer will be
icculus@12035
   194
      within the region passed to the request creating this object.
icculus@12035
   195
icculus@12035
   196
      To unlock the pointer, send the destroy request. This will also destroy
icculus@12035
   197
      the wp_locked_pointer object.
icculus@12035
   198
icculus@12035
   199
      If the compositor decides to unlock the pointer the unlocked event is
icculus@12035
   200
      sent. See wp_locked_pointer.unlock for details.
icculus@12035
   201
icculus@12035
   202
      When unlocking, the compositor may warp the cursor position to the set
icculus@12035
   203
      cursor position hint. If it does, it will not result in any relative
icculus@12035
   204
      motion events emitted via wp_relative_pointer.
icculus@12035
   205
icculus@12035
   206
      If the surface the lock was requested on is destroyed and the lock is not
icculus@12035
   207
      yet activated, the wp_locked_pointer object is now defunct and must be
icculus@12035
   208
      destroyed.
icculus@12035
   209
    </description>
icculus@12035
   210
icculus@12035
   211
    <request name="destroy" type="destructor">
icculus@12035
   212
      <description summary="destroy the locked pointer object">
icculus@12035
   213
	Destroy the locked pointer object. If applicable, the compositor will
icculus@12035
   214
	unlock the pointer.
icculus@12035
   215
      </description>
icculus@12035
   216
    </request>
icculus@12035
   217
icculus@12035
   218
    <request name="set_cursor_position_hint">
icculus@12035
   219
      <description summary="set the pointer cursor position hint">
icculus@12035
   220
	Set the cursor position hint relative to the top left corner of the
icculus@12035
   221
	surface.
icculus@12035
   222
icculus@12035
   223
	If the client is drawing its own cursor, it should update the position
icculus@12035
   224
	hint to the position of its own cursor. A compositor may use this
icculus@12035
   225
	information to warp the pointer upon unlock in order to avoid pointer
icculus@12035
   226
	jumps.
icculus@12035
   227
icculus@12035
   228
	The cursor position hint is double buffered. The new hint will only take
icculus@12035
   229
	effect when the associated surface gets it pending state applied. See
icculus@12035
   230
	wl_surface.commit for details.
icculus@12035
   231
      </description>
icculus@12035
   232
      <arg name="surface_x" type="fixed"
icculus@12035
   233
	   summary="surface-local x coordinate"/>
icculus@12035
   234
      <arg name="surface_y" type="fixed"
icculus@12035
   235
	   summary="surface-local y coordinate"/>
icculus@12035
   236
    </request>
icculus@12035
   237
icculus@12035
   238
    <request name="set_region">
icculus@12035
   239
      <description summary="set a new lock region">
icculus@12035
   240
	Set a new region used to lock the pointer.
icculus@12035
   241
icculus@12035
   242
	The new lock region is double-buffered. The new lock region will
icculus@12035
   243
	only take effect when the associated surface gets its pending state
icculus@12035
   244
	applied. See wl_surface.commit for details.
icculus@12035
   245
icculus@12035
   246
	For details about the lock region, see wp_locked_pointer.
icculus@12035
   247
      </description>
icculus@12035
   248
      <arg name="region" type="object" interface="wl_region" allow-null="true"
icculus@12035
   249
	   summary="region of surface"/>
icculus@12035
   250
    </request>
icculus@12035
   251
icculus@12035
   252
    <event name="locked">
icculus@12035
   253
      <description summary="lock activation event">
icculus@12035
   254
	Notification that the pointer lock of the seat's pointer is activated.
icculus@12035
   255
      </description>
icculus@12035
   256
    </event>
icculus@12035
   257
icculus@12035
   258
    <event name="unlocked">
icculus@12035
   259
      <description summary="lock deactivation event">
icculus@12035
   260
	Notification that the pointer lock of the seat's pointer is no longer
icculus@12035
   261
	active. If this is a oneshot pointer lock (see
icculus@12035
   262
	wp_pointer_constraints.lifetime) this object is now defunct and should
icculus@12035
   263
	be destroyed. If this is a persistent pointer lock (see
icculus@12035
   264
	wp_pointer_constraints.lifetime) this pointer lock may again
icculus@12035
   265
	reactivate in the future.
icculus@12035
   266
      </description>
icculus@12035
   267
    </event>
icculus@12035
   268
  </interface>
icculus@12035
   269
icculus@12035
   270
  <interface name="zwp_confined_pointer_v1" version="1">
icculus@12035
   271
    <description summary="confined pointer object">
icculus@12035
   272
      The wp_confined_pointer interface represents a confined pointer state.
icculus@12035
   273
icculus@12035
   274
      This object will send the event 'confined' when the confinement is
icculus@12035
   275
      activated. Whenever the confinement is activated, it is guaranteed that
icculus@12035
   276
      the surface the pointer is confined to will already have received pointer
icculus@12035
   277
      focus and that the pointer will be within the region passed to the request
icculus@12035
   278
      creating this object. It is up to the compositor to decide whether this
icculus@12035
   279
      requires some user interaction and if the pointer will warp to within the
icculus@12035
   280
      passed region if outside.
icculus@12035
   281
icculus@12035
   282
      To unconfine the pointer, send the destroy request. This will also destroy
icculus@12035
   283
      the wp_confined_pointer object.
icculus@12035
   284
icculus@12035
   285
      If the compositor decides to unconfine the pointer the unconfined event is
icculus@12035
   286
      sent. The wp_confined_pointer object is at this point defunct and should
icculus@12035
   287
      be destroyed.
icculus@12035
   288
    </description>
icculus@12035
   289
icculus@12035
   290
    <request name="destroy" type="destructor">
icculus@12035
   291
      <description summary="destroy the confined pointer object">
icculus@12035
   292
	Destroy the confined pointer object. If applicable, the compositor will
icculus@12035
   293
	unconfine the pointer.
icculus@12035
   294
      </description>
icculus@12035
   295
    </request>
icculus@12035
   296
icculus@12035
   297
    <request name="set_region">
icculus@12035
   298
      <description summary="set a new confine region">
icculus@12035
   299
	Set a new region used to confine the pointer.
icculus@12035
   300
icculus@12035
   301
	The new confine region is double-buffered. The new confine region will
icculus@12035
   302
	only take effect when the associated surface gets its pending state
icculus@12035
   303
	applied. See wl_surface.commit for details.
icculus@12035
   304
icculus@12035
   305
	If the confinement is active when the new confinement region is applied
icculus@12035
   306
	and the pointer ends up outside of newly applied region, the pointer may
icculus@12035
   307
	warped to a position within the new confinement region. If warped, a
icculus@12035
   308
	wl_pointer.motion event will be emitted, but no
icculus@12035
   309
	wp_relative_pointer.relative_motion event.
icculus@12035
   310
icculus@12035
   311
	The compositor may also, instead of using the new region, unconfine the
icculus@12035
   312
	pointer.
icculus@12035
   313
icculus@12035
   314
	For details about the confine region, see wp_confined_pointer.
icculus@12035
   315
      </description>
icculus@12035
   316
      <arg name="region" type="object" interface="wl_region" allow-null="true"
icculus@12035
   317
	   summary="region of surface"/>
icculus@12035
   318
    </request>
icculus@12035
   319
icculus@12035
   320
    <event name="confined">
icculus@12035
   321
      <description summary="pointer confined">
icculus@12035
   322
	Notification that the pointer confinement of the seat's pointer is
icculus@12035
   323
	activated.
icculus@12035
   324
      </description>
icculus@12035
   325
    </event>
icculus@12035
   326
icculus@12035
   327
    <event name="unconfined">
icculus@12035
   328
      <description summary="pointer unconfined">
icculus@12035
   329
	Notification that the pointer confinement of the seat's pointer is no
icculus@12035
   330
	longer active. If this is a oneshot pointer confinement (see
icculus@12035
   331
	wp_pointer_constraints.lifetime) this object is now defunct and should
icculus@12035
   332
	be destroyed. If this is a persistent pointer confinement (see
icculus@12035
   333
	wp_pointer_constraints.lifetime) this pointer confinement may again
icculus@12035
   334
	reactivate in the future.
icculus@12035
   335
      </description>
icculus@12035
   336
    </event>
icculus@12035
   337
  </interface>
icculus@12035
   338
icculus@12035
   339
</protocol>