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