pointer-constraints-unstable-v1-protocol.h (21934B)
1 /* Generated by wayland-scanner 1.22.0 */ 2 3 #ifndef POINTER_CONSTRAINTS_UNSTABLE_V1_SERVER_PROTOCOL_H 4 #define POINTER_CONSTRAINTS_UNSTABLE_V1_SERVER_PROTOCOL_H 5 6 #include <stdint.h> 7 #include <stddef.h> 8 #include "wayland-server.h" 9 10 #ifdef __cplusplus 11 extern "C" { 12 #endif 13 14 struct wl_client; 15 struct wl_resource; 16 17 /** 18 * @page page_pointer_constraints_unstable_v1 The pointer_constraints_unstable_v1 protocol 19 * protocol for constraining pointer motions 20 * 21 * @section page_desc_pointer_constraints_unstable_v1 Description 22 * 23 * This protocol specifies a set of interfaces used for adding constraints to 24 * the motion of a pointer. Possible constraints include confining pointer 25 * motions to a given region, or locking it to its current position. 26 * 27 * In order to constrain the pointer, a client must first bind the global 28 * interface "wp_pointer_constraints" which, if a compositor supports pointer 29 * constraints, is exposed by the registry. Using the bound global object, the 30 * client uses the request that corresponds to the type of constraint it wants 31 * to make. See wp_pointer_constraints for more details. 32 * 33 * Warning! The protocol described in this file is experimental and backward 34 * incompatible changes may be made. Backward compatible changes may be added 35 * together with the corresponding interface version bump. Backward 36 * incompatible changes are done by bumping the version number in the protocol 37 * and interface names and resetting the interface version. Once the protocol 38 * is to be declared stable, the 'z' prefix and the version number in the 39 * protocol and interface names are removed and the interface version number is 40 * reset. 41 * 42 * @section page_ifaces_pointer_constraints_unstable_v1 Interfaces 43 * - @subpage page_iface_zwp_pointer_constraints_v1 - constrain the movement of a pointer 44 * - @subpage page_iface_zwp_locked_pointer_v1 - receive relative pointer motion events 45 * - @subpage page_iface_zwp_confined_pointer_v1 - confined pointer object 46 * @section page_copyright_pointer_constraints_unstable_v1 Copyright 47 * <pre> 48 * 49 * Copyright © 2014 Jonas Ådahl 50 * Copyright © 2015 Red Hat Inc. 51 * 52 * Permission is hereby granted, free of charge, to any person obtaining a 53 * copy of this software and associated documentation files (the "Software"), 54 * to deal in the Software without restriction, including without limitation 55 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 56 * and/or sell copies of the Software, and to permit persons to whom the 57 * Software is furnished to do so, subject to the following conditions: 58 * 59 * The above copyright notice and this permission notice (including the next 60 * paragraph) shall be included in all copies or substantial portions of the 61 * Software. 62 * 63 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 64 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 65 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 66 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 67 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 68 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 69 * DEALINGS IN THE SOFTWARE. 70 * </pre> 71 */ 72 struct wl_pointer; 73 struct wl_region; 74 struct wl_surface; 75 struct zwp_confined_pointer_v1; 76 struct zwp_locked_pointer_v1; 77 struct zwp_pointer_constraints_v1; 78 79 #ifndef ZWP_POINTER_CONSTRAINTS_V1_INTERFACE 80 #define ZWP_POINTER_CONSTRAINTS_V1_INTERFACE 81 /** 82 * @page page_iface_zwp_pointer_constraints_v1 zwp_pointer_constraints_v1 83 * @section page_iface_zwp_pointer_constraints_v1_desc Description 84 * 85 * The global interface exposing pointer constraining functionality. It 86 * exposes two requests: lock_pointer for locking the pointer to its 87 * position, and confine_pointer for locking the pointer to a region. 88 * 89 * The lock_pointer and confine_pointer requests create the objects 90 * wp_locked_pointer and wp_confined_pointer respectively, and the client can 91 * use these objects to interact with the lock. 92 * 93 * For any surface, only one lock or confinement may be active across all 94 * wl_pointer objects of the same seat. If a lock or confinement is requested 95 * when another lock or confinement is active or requested on the same surface 96 * and with any of the wl_pointer objects of the same seat, an 97 * 'already_constrained' error will be raised. 98 * @section page_iface_zwp_pointer_constraints_v1_api API 99 * See @ref iface_zwp_pointer_constraints_v1. 100 */ 101 /** 102 * @defgroup iface_zwp_pointer_constraints_v1 The zwp_pointer_constraints_v1 interface 103 * 104 * The global interface exposing pointer constraining functionality. It 105 * exposes two requests: lock_pointer for locking the pointer to its 106 * position, and confine_pointer for locking the pointer to a region. 107 * 108 * The lock_pointer and confine_pointer requests create the objects 109 * wp_locked_pointer and wp_confined_pointer respectively, and the client can 110 * use these objects to interact with the lock. 111 * 112 * For any surface, only one lock or confinement may be active across all 113 * wl_pointer objects of the same seat. If a lock or confinement is requested 114 * when another lock or confinement is active or requested on the same surface 115 * and with any of the wl_pointer objects of the same seat, an 116 * 'already_constrained' error will be raised. 117 */ 118 extern const struct wl_interface zwp_pointer_constraints_v1_interface; 119 #endif 120 #ifndef ZWP_LOCKED_POINTER_V1_INTERFACE 121 #define ZWP_LOCKED_POINTER_V1_INTERFACE 122 /** 123 * @page page_iface_zwp_locked_pointer_v1 zwp_locked_pointer_v1 124 * @section page_iface_zwp_locked_pointer_v1_desc Description 125 * 126 * The wp_locked_pointer interface represents a locked pointer state. 127 * 128 * While the lock of this object is active, the wl_pointer objects of the 129 * associated seat will not emit any wl_pointer.motion events. 130 * 131 * This object will send the event 'locked' when the lock is activated. 132 * Whenever the lock is activated, it is guaranteed that the locked surface 133 * will already have received pointer focus and that the pointer will be 134 * within the region passed to the request creating this object. 135 * 136 * To unlock the pointer, send the destroy request. This will also destroy 137 * the wp_locked_pointer object. 138 * 139 * If the compositor decides to unlock the pointer the unlocked event is 140 * sent. See wp_locked_pointer.unlock for details. 141 * 142 * When unlocking, the compositor may warp the cursor position to the set 143 * cursor position hint. If it does, it will not result in any relative 144 * motion events emitted via wp_relative_pointer. 145 * 146 * If the surface the lock was requested on is destroyed and the lock is not 147 * yet activated, the wp_locked_pointer object is now defunct and must be 148 * destroyed. 149 * @section page_iface_zwp_locked_pointer_v1_api API 150 * See @ref iface_zwp_locked_pointer_v1. 151 */ 152 /** 153 * @defgroup iface_zwp_locked_pointer_v1 The zwp_locked_pointer_v1 interface 154 * 155 * The wp_locked_pointer interface represents a locked pointer state. 156 * 157 * While the lock of this object is active, the wl_pointer objects of the 158 * associated seat will not emit any wl_pointer.motion events. 159 * 160 * This object will send the event 'locked' when the lock is activated. 161 * Whenever the lock is activated, it is guaranteed that the locked surface 162 * will already have received pointer focus and that the pointer will be 163 * within the region passed to the request creating this object. 164 * 165 * To unlock the pointer, send the destroy request. This will also destroy 166 * the wp_locked_pointer object. 167 * 168 * If the compositor decides to unlock the pointer the unlocked event is 169 * sent. See wp_locked_pointer.unlock for details. 170 * 171 * When unlocking, the compositor may warp the cursor position to the set 172 * cursor position hint. If it does, it will not result in any relative 173 * motion events emitted via wp_relative_pointer. 174 * 175 * If the surface the lock was requested on is destroyed and the lock is not 176 * yet activated, the wp_locked_pointer object is now defunct and must be 177 * destroyed. 178 */ 179 extern const struct wl_interface zwp_locked_pointer_v1_interface; 180 #endif 181 #ifndef ZWP_CONFINED_POINTER_V1_INTERFACE 182 #define ZWP_CONFINED_POINTER_V1_INTERFACE 183 /** 184 * @page page_iface_zwp_confined_pointer_v1 zwp_confined_pointer_v1 185 * @section page_iface_zwp_confined_pointer_v1_desc Description 186 * 187 * The wp_confined_pointer interface represents a confined pointer state. 188 * 189 * This object will send the event 'confined' when the confinement is 190 * activated. Whenever the confinement is activated, it is guaranteed that 191 * the surface the pointer is confined to will already have received pointer 192 * focus and that the pointer will be within the region passed to the request 193 * creating this object. It is up to the compositor to decide whether this 194 * requires some user interaction and if the pointer will warp to within the 195 * passed region if outside. 196 * 197 * To unconfine the pointer, send the destroy request. This will also destroy 198 * the wp_confined_pointer object. 199 * 200 * If the compositor decides to unconfine the pointer the unconfined event is 201 * sent. The wp_confined_pointer object is at this point defunct and should 202 * be destroyed. 203 * @section page_iface_zwp_confined_pointer_v1_api API 204 * See @ref iface_zwp_confined_pointer_v1. 205 */ 206 /** 207 * @defgroup iface_zwp_confined_pointer_v1 The zwp_confined_pointer_v1 interface 208 * 209 * The wp_confined_pointer interface represents a confined pointer state. 210 * 211 * This object will send the event 'confined' when the confinement is 212 * activated. Whenever the confinement is activated, it is guaranteed that 213 * the surface the pointer is confined to will already have received pointer 214 * focus and that the pointer will be within the region passed to the request 215 * creating this object. It is up to the compositor to decide whether this 216 * requires some user interaction and if the pointer will warp to within the 217 * passed region if outside. 218 * 219 * To unconfine the pointer, send the destroy request. This will also destroy 220 * the wp_confined_pointer object. 221 * 222 * If the compositor decides to unconfine the pointer the unconfined event is 223 * sent. The wp_confined_pointer object is at this point defunct and should 224 * be destroyed. 225 */ 226 extern const struct wl_interface zwp_confined_pointer_v1_interface; 227 #endif 228 229 #ifndef ZWP_POINTER_CONSTRAINTS_V1_ERROR_ENUM 230 #define ZWP_POINTER_CONSTRAINTS_V1_ERROR_ENUM 231 /** 232 * @ingroup iface_zwp_pointer_constraints_v1 233 * wp_pointer_constraints error values 234 * 235 * These errors can be emitted in response to wp_pointer_constraints 236 * requests. 237 */ 238 enum zwp_pointer_constraints_v1_error { 239 /** 240 * pointer constraint already requested on that surface 241 */ 242 ZWP_POINTER_CONSTRAINTS_V1_ERROR_ALREADY_CONSTRAINED = 1, 243 }; 244 #endif /* ZWP_POINTER_CONSTRAINTS_V1_ERROR_ENUM */ 245 246 #ifndef ZWP_POINTER_CONSTRAINTS_V1_LIFETIME_ENUM 247 #define ZWP_POINTER_CONSTRAINTS_V1_LIFETIME_ENUM 248 /** 249 * @ingroup iface_zwp_pointer_constraints_v1 250 * constraint lifetime 251 * 252 * These values represent different lifetime semantics. They are passed 253 * as arguments to the factory requests to specify how the constraint 254 * lifetimes should be managed. 255 */ 256 enum zwp_pointer_constraints_v1_lifetime { 257 /** 258 * the pointer constraint is defunct once deactivated 259 * 260 * A oneshot pointer constraint will never reactivate once it has 261 * been deactivated. See the corresponding deactivation event 262 * (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) 263 * for details. 264 */ 265 ZWP_POINTER_CONSTRAINTS_V1_LIFETIME_ONESHOT = 1, 266 /** 267 * the pointer constraint may reactivate 268 * 269 * A persistent pointer constraint may again reactivate once it 270 * has been deactivated. See the corresponding deactivation event 271 * (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) 272 * for details. 273 */ 274 ZWP_POINTER_CONSTRAINTS_V1_LIFETIME_PERSISTENT = 2, 275 }; 276 #endif /* ZWP_POINTER_CONSTRAINTS_V1_LIFETIME_ENUM */ 277 278 /** 279 * @ingroup iface_zwp_pointer_constraints_v1 280 * @struct zwp_pointer_constraints_v1_interface 281 */ 282 struct zwp_pointer_constraints_v1_interface { 283 /** 284 * destroy the pointer constraints manager object 285 * 286 * Used by the client to notify the server that it will no longer 287 * use this pointer constraints object. 288 */ 289 void (*destroy)(struct wl_client *client, 290 struct wl_resource *resource); 291 /** 292 * lock pointer to a position 293 * 294 * The lock_pointer request lets the client request to disable 295 * movements of the virtual pointer (i.e. the cursor), effectively 296 * locking the pointer to a position. This request may not take 297 * effect immediately; in the future, when the compositor deems 298 * implementation-specific constraints are satisfied, the pointer 299 * lock will be activated and the compositor sends a locked event. 300 * 301 * The protocol provides no guarantee that the constraints are ever 302 * satisfied, and does not require the compositor to send an error 303 * if the constraints cannot ever be satisfied. It is thus possible 304 * to request a lock that will never activate. 305 * 306 * There may not be another pointer constraint of any kind 307 * requested or active on the surface for any of the wl_pointer 308 * objects of the seat of the passed pointer when requesting a 309 * lock. If there is, an error will be raised. See general pointer 310 * lock documentation for more details. 311 * 312 * The intersection of the region passed with this request and the 313 * input region of the surface is used to determine where the 314 * pointer must be in order for the lock to activate. It is up to 315 * the compositor whether to warp the pointer or require some kind 316 * of user interaction for the lock to activate. If the region is 317 * null the surface input region is used. 318 * 319 * A surface may receive pointer focus without the lock being 320 * activated. 321 * 322 * The request creates a new object wp_locked_pointer which is used 323 * to interact with the lock as well as receive updates about its 324 * state. See the the description of wp_locked_pointer for further 325 * information. 326 * 327 * Note that while a pointer is locked, the wl_pointer objects of 328 * the corresponding seat will not emit any wl_pointer.motion 329 * events, but relative motion events will still be emitted via 330 * wp_relative_pointer objects of the same seat. wl_pointer.axis 331 * and wl_pointer.button events are unaffected. 332 * @param surface surface to lock pointer to 333 * @param pointer the pointer that should be locked 334 * @param region region of surface 335 * @param lifetime lock lifetime 336 */ 337 void (*lock_pointer)(struct wl_client *client, 338 struct wl_resource *resource, 339 uint32_t id, 340 struct wl_resource *surface, 341 struct wl_resource *pointer, 342 struct wl_resource *region, 343 uint32_t lifetime); 344 /** 345 * confine pointer to a region 346 * 347 * The confine_pointer request lets the client request to confine 348 * the pointer cursor to a given region. This request may not take 349 * effect immediately; in the future, when the compositor deems 350 * implementation- specific constraints are satisfied, the pointer 351 * confinement will be activated and the compositor sends a 352 * confined event. 353 * 354 * The intersection of the region passed with this request and the 355 * input region of the surface is used to determine where the 356 * pointer must be in order for the confinement to activate. It is 357 * up to the compositor whether to warp the pointer or require some 358 * kind of user interaction for the confinement to activate. If the 359 * region is null the surface input region is used. 360 * 361 * The request will create a new object wp_confined_pointer which 362 * is used to interact with the confinement as well as receive 363 * updates about its state. See the the description of 364 * wp_confined_pointer for further information. 365 * @param surface surface to lock pointer to 366 * @param pointer the pointer that should be confined 367 * @param region region of surface 368 * @param lifetime confinement lifetime 369 */ 370 void (*confine_pointer)(struct wl_client *client, 371 struct wl_resource *resource, 372 uint32_t id, 373 struct wl_resource *surface, 374 struct wl_resource *pointer, 375 struct wl_resource *region, 376 uint32_t lifetime); 377 }; 378 379 380 /** 381 * @ingroup iface_zwp_pointer_constraints_v1 382 */ 383 #define ZWP_POINTER_CONSTRAINTS_V1_DESTROY_SINCE_VERSION 1 384 /** 385 * @ingroup iface_zwp_pointer_constraints_v1 386 */ 387 #define ZWP_POINTER_CONSTRAINTS_V1_LOCK_POINTER_SINCE_VERSION 1 388 /** 389 * @ingroup iface_zwp_pointer_constraints_v1 390 */ 391 #define ZWP_POINTER_CONSTRAINTS_V1_CONFINE_POINTER_SINCE_VERSION 1 392 393 /** 394 * @ingroup iface_zwp_locked_pointer_v1 395 * @struct zwp_locked_pointer_v1_interface 396 */ 397 struct zwp_locked_pointer_v1_interface { 398 /** 399 * destroy the locked pointer object 400 * 401 * Destroy the locked pointer object. If applicable, the 402 * compositor will unlock the pointer. 403 */ 404 void (*destroy)(struct wl_client *client, 405 struct wl_resource *resource); 406 /** 407 * set the pointer cursor position hint 408 * 409 * Set the cursor position hint relative to the top left corner 410 * of the surface. 411 * 412 * If the client is drawing its own cursor, it should update the 413 * position hint to the position of its own cursor. A compositor 414 * may use this information to warp the pointer upon unlock in 415 * order to avoid pointer jumps. 416 * 417 * The cursor position hint is double buffered. The new hint will 418 * only take effect when the associated surface gets it pending 419 * state applied. See wl_surface.commit for details. 420 * @param surface_x surface-local x coordinate 421 * @param surface_y surface-local y coordinate 422 */ 423 void (*set_cursor_position_hint)(struct wl_client *client, 424 struct wl_resource *resource, 425 wl_fixed_t surface_x, 426 wl_fixed_t surface_y); 427 /** 428 * set a new lock region 429 * 430 * Set a new region used to lock the pointer. 431 * 432 * The new lock region is double-buffered. The new lock region will 433 * only take effect when the associated surface gets its pending 434 * state applied. See wl_surface.commit for details. 435 * 436 * For details about the lock region, see wp_locked_pointer. 437 * @param region region of surface 438 */ 439 void (*set_region)(struct wl_client *client, 440 struct wl_resource *resource, 441 struct wl_resource *region); 442 }; 443 444 #define ZWP_LOCKED_POINTER_V1_LOCKED 0 445 #define ZWP_LOCKED_POINTER_V1_UNLOCKED 1 446 447 /** 448 * @ingroup iface_zwp_locked_pointer_v1 449 */ 450 #define ZWP_LOCKED_POINTER_V1_LOCKED_SINCE_VERSION 1 451 /** 452 * @ingroup iface_zwp_locked_pointer_v1 453 */ 454 #define ZWP_LOCKED_POINTER_V1_UNLOCKED_SINCE_VERSION 1 455 456 /** 457 * @ingroup iface_zwp_locked_pointer_v1 458 */ 459 #define ZWP_LOCKED_POINTER_V1_DESTROY_SINCE_VERSION 1 460 /** 461 * @ingroup iface_zwp_locked_pointer_v1 462 */ 463 #define ZWP_LOCKED_POINTER_V1_SET_CURSOR_POSITION_HINT_SINCE_VERSION 1 464 /** 465 * @ingroup iface_zwp_locked_pointer_v1 466 */ 467 #define ZWP_LOCKED_POINTER_V1_SET_REGION_SINCE_VERSION 1 468 469 /** 470 * @ingroup iface_zwp_locked_pointer_v1 471 * Sends an locked event to the client owning the resource. 472 * @param resource_ The client's resource 473 */ 474 static inline void 475 zwp_locked_pointer_v1_send_locked(struct wl_resource *resource_) 476 { 477 wl_resource_post_event(resource_, ZWP_LOCKED_POINTER_V1_LOCKED); 478 } 479 480 /** 481 * @ingroup iface_zwp_locked_pointer_v1 482 * Sends an unlocked event to the client owning the resource. 483 * @param resource_ The client's resource 484 */ 485 static inline void 486 zwp_locked_pointer_v1_send_unlocked(struct wl_resource *resource_) 487 { 488 wl_resource_post_event(resource_, ZWP_LOCKED_POINTER_V1_UNLOCKED); 489 } 490 491 /** 492 * @ingroup iface_zwp_confined_pointer_v1 493 * @struct zwp_confined_pointer_v1_interface 494 */ 495 struct zwp_confined_pointer_v1_interface { 496 /** 497 * destroy the confined pointer object 498 * 499 * Destroy the confined pointer object. If applicable, the 500 * compositor will unconfine the pointer. 501 */ 502 void (*destroy)(struct wl_client *client, 503 struct wl_resource *resource); 504 /** 505 * set a new confine region 506 * 507 * Set a new region used to confine the pointer. 508 * 509 * The new confine region is double-buffered. The new confine 510 * region will only take effect when the associated surface gets 511 * its pending state applied. See wl_surface.commit for details. 512 * 513 * If the confinement is active when the new confinement region is 514 * applied and the pointer ends up outside of newly applied region, 515 * the pointer may warped to a position within the new confinement 516 * region. If warped, a wl_pointer.motion event will be emitted, 517 * but no wp_relative_pointer.relative_motion event. 518 * 519 * The compositor may also, instead of using the new region, 520 * unconfine the pointer. 521 * 522 * For details about the confine region, see wp_confined_pointer. 523 * @param region region of surface 524 */ 525 void (*set_region)(struct wl_client *client, 526 struct wl_resource *resource, 527 struct wl_resource *region); 528 }; 529 530 #define ZWP_CONFINED_POINTER_V1_CONFINED 0 531 #define ZWP_CONFINED_POINTER_V1_UNCONFINED 1 532 533 /** 534 * @ingroup iface_zwp_confined_pointer_v1 535 */ 536 #define ZWP_CONFINED_POINTER_V1_CONFINED_SINCE_VERSION 1 537 /** 538 * @ingroup iface_zwp_confined_pointer_v1 539 */ 540 #define ZWP_CONFINED_POINTER_V1_UNCONFINED_SINCE_VERSION 1 541 542 /** 543 * @ingroup iface_zwp_confined_pointer_v1 544 */ 545 #define ZWP_CONFINED_POINTER_V1_DESTROY_SINCE_VERSION 1 546 /** 547 * @ingroup iface_zwp_confined_pointer_v1 548 */ 549 #define ZWP_CONFINED_POINTER_V1_SET_REGION_SINCE_VERSION 1 550 551 /** 552 * @ingroup iface_zwp_confined_pointer_v1 553 * Sends an confined event to the client owning the resource. 554 * @param resource_ The client's resource 555 */ 556 static inline void 557 zwp_confined_pointer_v1_send_confined(struct wl_resource *resource_) 558 { 559 wl_resource_post_event(resource_, ZWP_CONFINED_POINTER_V1_CONFINED); 560 } 561 562 /** 563 * @ingroup iface_zwp_confined_pointer_v1 564 * Sends an unconfined event to the client owning the resource. 565 * @param resource_ The client's resource 566 */ 567 static inline void 568 zwp_confined_pointer_v1_send_unconfined(struct wl_resource *resource_) 569 { 570 wl_resource_post_event(resource_, ZWP_CONFINED_POINTER_V1_UNCONFINED); 571 } 572 573 #ifdef __cplusplus 574 } 575 #endif 576 577 #endif