1 /* 2 * Copyright © 2013 Jonas Ådahl 3 * Copyright © 2013-2015 Red Hat, Inc. 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a 6 * copy of this software and associated documentation files (the "Software"), 7 * to deal in the Software without restriction, including without limitation 8 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 9 * and/or sell copies of the Software, and to permit persons to whom the 10 * Software is furnished to do so, subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice (including the next 13 * paragraph) shall be included in all copies or substantial portions of the 14 * Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 19 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 22 * DEALINGS IN THE SOFTWARE. 23 */ 24 25 #ifndef LIBINPUT_H 26 #define LIBINPUT_H 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 #include <stdlib.h> 33 #include <stdint.h> 34 #include <stdarg.h> 35 #include <libudev.h> 36 37 #define LIBINPUT_ATTRIBUTE_PRINTF(_format, _args) \ 38 __attribute__ ((format (printf, _format, _args))) 39 #define LIBINPUT_ATTRIBUTE_DEPRECATED __attribute__ ((deprecated)) 40 41 /** 42 * @ingroup base 43 * @struct libinput 44 * 45 * A handle for accessing libinput. This struct is refcounted, use 46 * libinput_ref() and libinput_unref(). 47 */ 48 struct libinput; 49 50 /** 51 * @ingroup device 52 * @struct libinput_device 53 * 54 * A base handle for accessing libinput devices. This struct is 55 * refcounted, use libinput_device_ref() and libinput_device_unref(). 56 */ 57 struct libinput_device; 58 59 /** 60 * @ingroup device 61 * @struct libinput_device_group 62 * 63 * A base handle for accessing libinput device groups. This struct is 64 * refcounted, use libinput_device_group_ref() and 65 * libinput_device_group_unref(). 66 */ 67 struct libinput_device_group; 68 69 /** 70 * @ingroup seat 71 * @struct libinput_seat 72 * 73 * The base handle for accessing libinput seats. This struct is 74 * refcounted, use libinput_seat_ref() and libinput_seat_unref(). 75 */ 76 struct libinput_seat; 77 78 /** 79 * @ingroup device 80 * @struct libinput_tablet_tool 81 * 82 * An object representing a tool being used by a device with the @ref 83 * LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. 84 * 85 * Tablet events generated by such a device are bound to a specific tool 86 * rather than coming from the device directly. Depending on the hardware it 87 * is possible to track the same physical tool across multiple 88 * struct libinput_device devices. 89 * See libinput_tablet_tool_get_serial() for more details. 90 * 91 * This struct is refcounted, use libinput_tablet_tool_ref() and 92 * libinput_tablet_tool_unref(). 93 * 94 * @since 1.2 95 */ 96 struct libinput_tablet_tool; 97 98 /** 99 * @ingroup event 100 * @struct libinput_event 101 * 102 * The base event type. Use libinput_event_get_pointer_event() or similar to 103 * get the actual event type. 104 * 105 * @warning Unlike other structs events are considered transient and 106 * <b>not</b> refcounted. 107 */ 108 struct libinput_event; 109 110 /** 111 * @ingroup event 112 * @struct libinput_event_device_notify 113 * 114 * An event notifying the caller of a device being added or removed. 115 */ 116 struct libinput_event_device_notify; 117 118 /** 119 * @ingroup event_keyboard 120 * @struct libinput_event_keyboard 121 * 122 * A keyboard event representing a key press/release. 123 */ 124 struct libinput_event_keyboard; 125 126 /** 127 * @ingroup event_pointer 128 * @struct libinput_event_pointer 129 * 130 * A pointer event representing relative or absolute pointer movement, 131 * a button press/release or scroll axis events. 132 */ 133 struct libinput_event_pointer; 134 135 /** 136 * @ingroup event_touch 137 * @struct libinput_event_touch 138 * 139 * Touch event representing a touch down, move or up, as well as a touch 140 * cancel and touch frame events. Valid event types for this event are @ref 141 * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref 142 * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref 143 * LIBINPUT_EVENT_TOUCH_FRAME. 144 */ 145 struct libinput_event_touch; 146 147 /** 148 * @ingroup event_tablet 149 * @struct libinput_event_tablet_tool 150 * 151 * Tablet tool event representing an axis update, button press, or tool 152 * update. Valid event types for this event are @ref 153 * LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 154 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY and @ref 155 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 156 * 157 * @since 1.2 158 */ 159 struct libinput_event_tablet_tool; 160 161 /** 162 * @ingroup event_tablet_pad 163 * @struct libinput_event_tablet_pad 164 * 165 * Tablet pad event representing a button press, or ring/strip update on 166 * the tablet pad itself. Valid event types for this event are @ref 167 * LIBINPUT_EVENT_TABLET_PAD_BUTTON, @ref LIBINPUT_EVENT_TABLET_PAD_RING and 168 * @ref LIBINPUT_EVENT_TABLET_PAD_STRIP. 169 * 170 * @since 1.3 171 */ 172 struct libinput_event_tablet_pad; 173 174 /** 175 * @ingroup base 176 * 177 * Log priority for internal logging messages. 178 */ 179 enum libinput_log_priority { 180 LIBINPUT_LOG_PRIORITY_DEBUG = 10, 181 LIBINPUT_LOG_PRIORITY_INFO = 20, 182 LIBINPUT_LOG_PRIORITY_ERROR = 30, 183 }; 184 185 /** 186 * @ingroup device 187 * 188 * Capabilities on a device. A device may have one or more capabilities 189 * at a time, capabilities remain static for the lifetime of the device. 190 */ 191 enum libinput_device_capability { 192 LIBINPUT_DEVICE_CAP_KEYBOARD = 0, 193 LIBINPUT_DEVICE_CAP_POINTER = 1, 194 LIBINPUT_DEVICE_CAP_TOUCH = 2, 195 LIBINPUT_DEVICE_CAP_TABLET_TOOL = 3, 196 LIBINPUT_DEVICE_CAP_TABLET_PAD = 4, 197 LIBINPUT_DEVICE_CAP_GESTURE = 5, 198 LIBINPUT_DEVICE_CAP_SWITCH = 6, 199 }; 200 201 /** 202 * @ingroup device 203 * 204 * Logical state of a key. Note that the logical state may not represent 205 * the physical state of the key. 206 */ 207 enum libinput_key_state { 208 LIBINPUT_KEY_STATE_RELEASED = 0, 209 LIBINPUT_KEY_STATE_PRESSED = 1 210 }; 211 212 /** 213 * @ingroup device 214 * 215 * Mask reflecting LEDs on a device. 216 */ 217 enum libinput_led { 218 LIBINPUT_LED_NUM_LOCK = (1 << 0), 219 LIBINPUT_LED_CAPS_LOCK = (1 << 1), 220 LIBINPUT_LED_SCROLL_LOCK = (1 << 2) 221 }; 222 223 /** 224 * @ingroup device 225 * 226 * Logical state of a physical button. Note that the logical state may not 227 * represent the physical state of the button. 228 */ 229 enum libinput_button_state { 230 LIBINPUT_BUTTON_STATE_RELEASED = 0, 231 LIBINPUT_BUTTON_STATE_PRESSED = 1 232 }; 233 234 /** 235 * @ingroup device 236 * 237 * Axes on a device with the capability @ref LIBINPUT_DEVICE_CAP_POINTER 238 * that are not x or y coordinates. 239 * 240 * The two scroll axes @ref LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and 241 * @ref LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL are engaged separately, 242 * depending on the device. libinput provides some scroll direction locking 243 * but it is up to the caller to determine which axis is needed and 244 * appropriate in the current interaction 245 */ 246 enum libinput_pointer_axis { 247 LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0, 248 LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1, 249 }; 250 251 /** 252 * @ingroup device 253 * 254 * The source for a libinput_pointer_axis event. See 255 * libinput_event_pointer_get_axis_source() for details. 256 */ 257 enum libinput_pointer_axis_source { 258 /** 259 * The event is caused by the rotation of a wheel. 260 */ 261 LIBINPUT_POINTER_AXIS_SOURCE_WHEEL = 1, 262 /** 263 * The event is caused by the movement of one or more fingers on a 264 * device. 265 */ 266 LIBINPUT_POINTER_AXIS_SOURCE_FINGER, 267 /** 268 * The event is caused by the motion of some device. 269 */ 270 LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS, 271 /** 272 * The event is caused by the tilting of a mouse wheel rather than 273 * its rotation. This method is commonly used on mice without 274 * separate horizontal scroll wheels. 275 * 276 * @deprecated This axis source is deprecated as of libinput 1.16. 277 * It was never used by any device before libinput 1.16. All wheel 278 * tilt devices use @ref LIBINPUT_POINTER_AXIS_SOURCE_WHEEL instead. 279 */ 280 LIBINPUT_POINTER_AXIS_SOURCE_WHEEL_TILT, 281 }; 282 283 /** 284 * @ingroup event_tablet_pad 285 * 286 * The source for a @ref LIBINPUT_EVENT_TABLET_PAD_RING event. See 287 * libinput_event_tablet_pad_get_ring_source() for details. 288 * 289 * @since 1.3 290 */ 291 enum libinput_tablet_pad_ring_axis_source { 292 LIBINPUT_TABLET_PAD_RING_SOURCE_UNKNOWN = 1, 293 /** 294 * The event is caused by the movement of one or more fingers on 295 * the ring. 296 */ 297 LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER, 298 }; 299 300 /** 301 * @ingroup event_tablet_pad 302 * 303 * The source for a @ref LIBINPUT_EVENT_TABLET_PAD_STRIP event. See 304 * libinput_event_tablet_pad_get_strip_source() for details. 305 * 306 * @since 1.3 307 */ 308 enum libinput_tablet_pad_strip_axis_source { 309 LIBINPUT_TABLET_PAD_STRIP_SOURCE_UNKNOWN = 1, 310 /** 311 * The event is caused by the movement of one or more fingers on 312 * the strip. 313 */ 314 LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER, 315 }; 316 317 /** 318 * @ingroup device 319 * 320 * Available tool types for a device with the @ref 321 * LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. The tool type defines the default 322 * usage of the tool as advertised by the manufacturer. Multiple different 323 * physical tools may share the same tool type, e.g. a Wacom Classic Pen, 324 * Wacom Pro Pen and a Wacom Grip Pen are all of type @ref 325 * LIBINPUT_TABLET_TOOL_TYPE_PEN. 326 * Use libinput_tablet_tool_get_tool_id() to get a specific model where applicable. 327 * 328 * Note that on some device, the eraser tool is on the tail end of a pen 329 * device. On other devices, e.g. MS Surface 3, the eraser is the pen tip 330 * while a button is held down. 331 * 332 * @note The @ref libinput_tablet_tool_type can only describe the default physical 333 * type of the device. For devices with adjustable physical properties 334 * the tool type remains the same, i.e. putting a Wacom stroke nib into a 335 * classic pen leaves the tool type as @ref LIBINPUT_TABLET_TOOL_TYPE_PEN. 336 * 337 * @since 1.2 338 */ 339 enum libinput_tablet_tool_type { 340 LIBINPUT_TABLET_TOOL_TYPE_PEN = 1, /**< A generic pen */ 341 LIBINPUT_TABLET_TOOL_TYPE_ERASER, /**< Eraser */ 342 LIBINPUT_TABLET_TOOL_TYPE_BRUSH, /**< A paintbrush-like tool */ 343 LIBINPUT_TABLET_TOOL_TYPE_PENCIL, /**< Physical drawing tool, e.g. 344 Wacom Inking Pen */ 345 LIBINPUT_TABLET_TOOL_TYPE_AIRBRUSH, /**< An airbrush-like tool */ 346 LIBINPUT_TABLET_TOOL_TYPE_MOUSE, /**< A mouse bound to the tablet */ 347 LIBINPUT_TABLET_TOOL_TYPE_LENS, /**< A mouse tool with a lens */ 348 LIBINPUT_TABLET_TOOL_TYPE_TOTEM, /**< A rotary device with 349 positional and rotation 350 data */ 351 }; 352 353 /** 354 * @ingroup device 355 * 356 * The state of proximity for a tool on a device. The device must have the @ref 357 * LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. 358 * 359 * The proximity of a tool is a binary state signalling whether the tool is 360 * within a detectable distance of the tablet device. A tool that is out of 361 * proximity cannot generate events. 362 * 363 * On some hardware a tool goes out of proximity when it ceases to touch the 364 * surface. On other hardware, the tool is still detectable within a short 365 * distance (a few cm) off the surface. 366 * 367 * @since 1.2 368 */ 369 enum libinput_tablet_tool_proximity_state { 370 LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_OUT = 0, 371 LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_IN = 1, 372 }; 373 374 /** 375 * @ingroup device 376 * 377 * The tip contact state for a tool on a device. The device must have 378 * the @ref LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. 379 * 380 * The tip contact state of a tool is a binary state signalling whether the tool is 381 * touching the surface of the tablet device. 382 * 383 * @since 1.2 384 */ 385 enum libinput_tablet_tool_tip_state { 386 LIBINPUT_TABLET_TOOL_TIP_UP = 0, 387 LIBINPUT_TABLET_TOOL_TIP_DOWN = 1, 388 }; 389 390 /** 391 * @defgroup tablet_pad_modes Tablet pad modes 392 * 393 * Handling the virtual mode groups of buttons, strips and rings on tablet 394 * pad devices. See the libinput documentation for more details. 395 */ 396 397 /** 398 * @ingroup tablet_pad_modes 399 * @struct libinput_tablet_pad_mode_group 400 * 401 * A mode on a tablet pad is a virtual grouping of functionality, usually 402 * based on some visual feedback like LEDs on the pad. The set of buttons, 403 * rings and strips that share the same mode are a "mode group". Whenever 404 * the mode changes, all buttons, rings and strips within this mode group 405 * are affected. 406 * 407 * Most tablets only have a single mode group, some tablets provide multiple 408 * mode groups through independent banks of LEDs (e.g. the Wacom Cintiq 409 * 24HD). libinput guarantees that at least one mode group is always 410 * available. 411 * 412 * This struct is refcounted, use libinput_tablet_pad_mode_group_ref() and 413 * libinput_tablet_pad_mode_group_unref(). 414 * 415 * @since 1.4 416 */ 417 struct libinput_tablet_pad_mode_group; 418 419 /** 420 * @ingroup tablet_pad_modes 421 * 422 * Most devices only provide a single mode group, however devices such as 423 * the Wacom Cintiq 22HD provide two mode groups. If multiple mode groups 424 * are available, a caller should use 425 * libinput_tablet_pad_mode_group_has_button(), 426 * libinput_tablet_pad_mode_group_has_ring() and 427 * libinput_tablet_pad_mode_group_has_strip() to associate each button, 428 * ring and strip with the correct mode group. 429 * 430 * @return the number of mode groups available on this device 431 * 432 * @since 1.4 433 */ 434 int 435 libinput_device_tablet_pad_get_num_mode_groups(struct libinput_device *device); 436 437 /** 438 * @ingroup tablet_pad_modes 439 * 440 * The returned mode group is not refcounted and may become invalid after 441 * the next call to libinput. Use libinput_tablet_pad_mode_group_ref() and 442 * libinput_tablet_pad_mode_group_unref() to continue using the handle 443 * outside of the immediate scope. 444 * 445 * While at least one reference is kept by the caller, the returned mode 446 * group will be identical for each subsequent call of this function with 447 * the same index and that same struct is returned from 448 * libinput_event_tablet_pad_get_mode_group(), provided the event was 449 * generated by this mode group. 450 * 451 * @param device A device with the @ref LIBINPUT_DEVICE_CAP_TABLET_PAD 452 * capability 453 * @param index A mode group index 454 * @return the mode group with the given index or NULL if an invalid index 455 * is given. 456 * 457 * @since 1.4 458 */ 459 struct libinput_tablet_pad_mode_group* 460 libinput_device_tablet_pad_get_mode_group(struct libinput_device *device, 461 unsigned int index); 462 463 /** 464 * @ingroup tablet_pad_modes 465 * 466 * The returned number is the same index as passed to 467 * libinput_device_tablet_pad_get_mode_group(). For tablets with only one 468 * mode this number is always 0. 469 * 470 * @param group A previously obtained mode group 471 * @return the numeric index this mode group represents, starting at 0 472 * 473 * @since 1.4 474 */ 475 unsigned int 476 libinput_tablet_pad_mode_group_get_index(struct libinput_tablet_pad_mode_group *group); 477 478 /** 479 * @ingroup tablet_pad_modes 480 * 481 * Query the mode group for the number of available modes. The number of 482 * modes is usually decided by the number of physical LEDs available on the 483 * device. Different mode groups may have a different number of modes. Use 484 * libinput_tablet_pad_mode_group_get_mode() to get the currently active 485 * mode. 486 * 487 * libinput guarantees that at least one mode is available. A device without 488 * mode switching capability has a single mode group and a single mode. 489 * 490 * @param group A previously obtained mode group 491 * @return the number of modes available in this mode group 492 * 493 * @since 1.4 494 */ 495 unsigned int 496 libinput_tablet_pad_mode_group_get_num_modes(struct libinput_tablet_pad_mode_group *group); 497 498 /** 499 * @ingroup tablet_pad_modes 500 * 501 * Return the current mode this mode group is in. Note that the returned 502 * mode is the mode valid as of completing the last libinput_dispatch(). 503 * The returned mode may thus be different than the mode returned by 504 * libinput_event_tablet_pad_get_mode(). 505 * 506 * For example, if the mode was toggled three times between the call to 507 * libinput_dispatch(), this function returns the third mode but the events 508 * in the event queue will return the modes 1, 2 and 3, respectively. 509 * 510 * @param group A previously obtained mode group 511 * @return the numeric index of the current mode in this group, starting at 0 512 * 513 * @see libinput_event_tablet_pad_get_mode 514 * 515 * @since 1.4 516 */ 517 unsigned int 518 libinput_tablet_pad_mode_group_get_mode(struct libinput_tablet_pad_mode_group *group); 519 520 /** 521 * @ingroup tablet_pad_modes 522 * 523 * Devices without mode switching capabilities return true for every button. 524 * 525 * @param group A previously obtained mode group 526 * @param button A button index, starting at 0 527 * @return true if the given button index is part of this mode group or 528 * false otherwise 529 * 530 * @since 1.4 531 */ 532 int 533 libinput_tablet_pad_mode_group_has_button(struct libinput_tablet_pad_mode_group *group, 534 unsigned int button); 535 536 /** 537 * @ingroup tablet_pad_modes 538 * 539 * Devices without mode switching capabilities return true for every ring. 540 * 541 * @param group A previously obtained mode group 542 * @param ring A ring index, starting at 0 543 * @return true if the given ring index is part of this mode group or 544 * false otherwise 545 * 546 * @since 1.4 547 */ 548 int 549 libinput_tablet_pad_mode_group_has_ring(struct libinput_tablet_pad_mode_group *group, 550 unsigned int ring); 551 552 /** 553 * @ingroup tablet_pad_modes 554 * 555 * Devices without mode switching capabilities return true for every strip. 556 * 557 * @param group A previously obtained mode group 558 * @param strip A strip index, starting at 0 559 * @return true if the given strip index is part of this mode group or 560 * false otherwise 561 * 562 * @since 1.4 563 */ 564 int 565 libinput_tablet_pad_mode_group_has_strip(struct libinput_tablet_pad_mode_group *group, 566 unsigned int strip); 567 568 /** 569 * @ingroup tablet_pad_modes 570 * 571 * The toggle button in a mode group is the button assigned to cycle to or 572 * directly assign a new mode when pressed. Not all devices have a toggle 573 * button and some devices may have more than one toggle button. For 574 * example, the Wacom Cintiq 24HD has six toggle buttons in two groups, each 575 * directly selecting one of the three modes per group. 576 * 577 * Devices without mode switching capabilities return false for every button. 578 * 579 * @param group A previously obtained mode group 580 * @param button A button index, starting at 0 581 * @retval non-zero if the button is a mode toggle button for this group, or 582 * zero otherwise 583 * 584 * @since 1.4 585 */ 586 int 587 libinput_tablet_pad_mode_group_button_is_toggle(struct libinput_tablet_pad_mode_group *group, 588 unsigned int button); 589 590 /** 591 * @ingroup tablet_pad_modes 592 * 593 * Increase the refcount of the mode group. A mode group will be 594 * freed whenever the refcount reaches 0. 595 * 596 * @param group A previously obtained mode group 597 * @return The passed mode group 598 * 599 * @since 1.4 600 */ 601 struct libinput_tablet_pad_mode_group * 602 libinput_tablet_pad_mode_group_ref( 603 struct libinput_tablet_pad_mode_group *group); 604 605 /** 606 * @ingroup tablet_pad_modes 607 * 608 * Decrease the refcount of the mode group. A mode group will be 609 * freed whenever the refcount reaches 0. 610 * 611 * @param group A previously obtained mode group 612 * @return NULL if the group was destroyed, otherwise the passed mode group 613 * 614 * @since 1.4 615 */ 616 struct libinput_tablet_pad_mode_group * 617 libinput_tablet_pad_mode_group_unref( 618 struct libinput_tablet_pad_mode_group *group); 619 620 /** 621 * @ingroup tablet_pad_modes 622 * 623 * Set caller-specific data associated with this mode group. libinput does 624 * not manage, look at, or modify this data. The caller must ensure the 625 * data is valid. 626 * 627 * @param group A previously obtained mode group 628 * @param user_data Caller-specific data pointer 629 * @see libinput_tablet_pad_mode_group_get_user_data 630 * 631 * @since 1.4 632 */ 633 void 634 libinput_tablet_pad_mode_group_set_user_data( 635 struct libinput_tablet_pad_mode_group *group, 636 void *user_data); 637 638 /** 639 * @ingroup tablet_pad_modes 640 * 641 * Get the caller-specific data associated with this mode group, if any. 642 * 643 * @param group A previously obtained mode group 644 * @return Caller-specific data pointer or NULL if none was set 645 * @see libinput_tablet_pad_mode_group_set_user_data 646 * 647 * @since 1.4 648 */ 649 void * 650 libinput_tablet_pad_mode_group_get_user_data( 651 struct libinput_tablet_pad_mode_group *group); 652 653 /** 654 * @ingroup device 655 * 656 * The state of a switch. The default state of a switch is @ref 657 * LIBINPUT_SWITCH_STATE_OFF and no event is sent to confirm a switch in the 658 * off position. If a switch is logically on during initialization, libinput 659 * sends an event of type @ref LIBINPUT_EVENT_SWITCH_TOGGLE with a state 660 * @ref LIBINPUT_SWITCH_STATE_ON. 661 * 662 * @since 1.7 663 */ 664 enum libinput_switch_state { 665 LIBINPUT_SWITCH_STATE_OFF = 0, 666 LIBINPUT_SWITCH_STATE_ON = 1, 667 }; 668 669 /** 670 * @ingroup device 671 * 672 * The type of a switch. 673 * 674 * @since 1.7 675 */ 676 enum libinput_switch { 677 /** 678 * The laptop lid was closed when the switch state is @ref 679 * LIBINPUT_SWITCH_STATE_ON, or was opened when it is @ref 680 * LIBINPUT_SWITCH_STATE_OFF. 681 */ 682 LIBINPUT_SWITCH_LID = 1, 683 684 /** 685 * This switch indicates whether the device is in normal laptop mode 686 * or behaves like a tablet-like device where the primary 687 * interaction is usually a touch screen. When in tablet mode, the 688 * keyboard and touchpad are usually inaccessible. 689 * 690 * If the switch is in state @ref LIBINPUT_SWITCH_STATE_OFF, the 691 * device is in laptop mode. If the switch is in state @ref 692 * LIBINPUT_SWITCH_STATE_ON, the device is in tablet mode and the 693 * keyboard or touchpad may not be accessible. 694 * 695 * It is up to the caller to identify which devices are inaccessible 696 * in tablet mode. 697 */ 698 LIBINPUT_SWITCH_TABLET_MODE, 699 }; 700 701 /** 702 * @ingroup event_switch 703 * @struct libinput_event_switch 704 * 705 * A switch event representing a changed state in a switch. 706 * 707 * @since 1.7 708 */ 709 struct libinput_event_switch; 710 711 /** 712 * @ingroup base 713 * 714 * Event type for events returned by libinput_get_event(). 715 */ 716 enum libinput_event_type { 717 /** 718 * This is not a real event type, and is only used to tell the user that 719 * no new event is available in the queue. See 720 * libinput_next_event_type(). 721 */ 722 LIBINPUT_EVENT_NONE = 0, 723 724 /** 725 * Signals that a device has been added to the context. The device will 726 * not be read until the next time the user calls libinput_dispatch() 727 * and data is available. 728 * 729 * This allows setting up initial device configuration before any events 730 * are created. 731 */ 732 LIBINPUT_EVENT_DEVICE_ADDED, 733 734 /** 735 * Signals that a device has been removed. No more events from the 736 * associated device will be in the queue or be queued after this event. 737 */ 738 LIBINPUT_EVENT_DEVICE_REMOVED, 739 740 LIBINPUT_EVENT_KEYBOARD_KEY = 300, 741 742 LIBINPUT_EVENT_POINTER_MOTION = 400, 743 LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, 744 LIBINPUT_EVENT_POINTER_BUTTON, 745 LIBINPUT_EVENT_POINTER_AXIS, 746 747 LIBINPUT_EVENT_TOUCH_DOWN = 500, 748 LIBINPUT_EVENT_TOUCH_UP, 749 LIBINPUT_EVENT_TOUCH_MOTION, 750 LIBINPUT_EVENT_TOUCH_CANCEL, 751 /** 752 * Signals the end of a set of touchpoints at one device sample 753 * time. This event has no coordinate information attached. 754 */ 755 LIBINPUT_EVENT_TOUCH_FRAME, 756 757 /** 758 * One or more axes have changed state on a device with the @ref 759 * LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. This event is only sent 760 * when the tool is in proximity, see @ref 761 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY for details. 762 * 763 * The proximity event contains the initial state of the axis as the 764 * tool comes into proximity. An event of type @ref 765 * LIBINPUT_EVENT_TABLET_TOOL_AXIS is only sent when an axis value 766 * changes from this initial state. It is possible for a tool to 767 * enter and leave proximity without sending an event of type @ref 768 * LIBINPUT_EVENT_TABLET_TOOL_AXIS. 769 * 770 * An event of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS is sent 771 * when the tip state does not change. See the documentation for 772 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP for more details. 773 * 774 * @since 1.2 775 */ 776 LIBINPUT_EVENT_TABLET_TOOL_AXIS = 600, 777 /** 778 * Signals that a tool has come in or out of proximity of a device with 779 * the @ref LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. 780 * 781 * Proximity events contain each of the current values for each axis, 782 * and these values may be extracted from them in the same way they are 783 * with @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS events. 784 * 785 * Some tools may always be in proximity. For these tools, events of 786 * type @ref LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_IN are sent only once after @ref 787 * LIBINPUT_EVENT_DEVICE_ADDED, and events of type @ref 788 * LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_OUT are sent only once before @ref 789 * LIBINPUT_EVENT_DEVICE_REMOVED. 790 * 791 * If the tool that comes into proximity supports x/y coordinates, 792 * libinput guarantees that both x and y are set in the proximity 793 * event. 794 * 795 * When a tool goes out of proximity, the value of every axis should be 796 * assumed to have an undefined state and any buttons that are currently held 797 * down on the stylus are marked as released. Button release events for 798 * each button that was held down on the stylus are sent before the 799 * proximity out event. 800 * 801 * @since 1.2 802 */ 803 LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, 804 /** 805 * Signals that a tool has come in contact with the surface of a 806 * device with the @ref LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. 807 * 808 * On devices without distance proximity detection, the @ref 809 * LIBINPUT_EVENT_TABLET_TOOL_TIP is sent immediately after @ref 810 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY for the tip down event, and 811 * immediately before for the tip up event. 812 * 813 * The decision when a tip touches the surface is device-dependent 814 * and may be derived from pressure data or other means. If the tip 815 * state is changed by axes changing state, the 816 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP event includes the changed 817 * axes and no additional axis event is sent for this state change. 818 * In other words, a caller must look at both @ref 819 * LIBINPUT_EVENT_TABLET_TOOL_AXIS and @ref 820 * LIBINPUT_EVENT_TABLET_TOOL_TIP events to know the current state 821 * of the axes. 822 * 823 * If a button state change occurs at the same time as a tip state 824 * change, the order of events is device-dependent. 825 * 826 * @since 1.2 827 */ 828 LIBINPUT_EVENT_TABLET_TOOL_TIP, 829 /** 830 * Signals that a tool has changed a logical button state on a 831 * device with the @ref LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. 832 * 833 * Button state changes occur on their own and do not include axis 834 * state changes. If button and axis state changes occur within the 835 * same logical hardware event, the order of the @ref 836 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON and @ref 837 * LIBINPUT_EVENT_TABLET_TOOL_AXIS event is device-specific. 838 * 839 * This event is not to be confused with the button events emitted 840 * by the tablet pad. See @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON. 841 * 842 * @see LIBINPUT_EVENT_TABLET_PAD_BUTTON 843 * 844 * @since 1.2 845 */ 846 LIBINPUT_EVENT_TABLET_TOOL_BUTTON, 847 848 /** 849 * A button pressed on a device with the @ref 850 * LIBINPUT_DEVICE_CAP_TABLET_PAD capability. 851 * 852 * A button differs from @ref LIBINPUT_EVENT_TABLET_PAD_KEY in that 853 * buttons are sequentially indexed from 0 and do not carry any 854 * other information. Keys have a specific functionality assigned 855 * to them. The key code thus carries a semantic meaning, a button 856 * number does not. 857 * 858 * This event is not to be confused with the button events emitted 859 * by tools on a tablet (@ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON). 860 * 861 * @since 1.3 862 */ 863 LIBINPUT_EVENT_TABLET_PAD_BUTTON = 700, 864 /** 865 * A status change on a tablet ring with the @ref 866 * LIBINPUT_DEVICE_CAP_TABLET_PAD capability. 867 * 868 * @since 1.3 869 */ 870 LIBINPUT_EVENT_TABLET_PAD_RING, 871 872 /** 873 * A status change on a strip on a device with the @ref 874 * LIBINPUT_DEVICE_CAP_TABLET_PAD capability. 875 * 876 * @since 1.3 877 */ 878 LIBINPUT_EVENT_TABLET_PAD_STRIP, 879 880 /** 881 * A key pressed on a device with the @ref 882 * LIBINPUT_DEVICE_CAP_TABLET_PAD capability. 883 * 884 * A key differs from @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON in that 885 * keys have a specific functionality assigned to them (buttons are 886 * sequentially ordered). The key code thus carries a semantic 887 * meaning, a button number does not. 888 * 889 * @since 1.15 890 */ 891 LIBINPUT_EVENT_TABLET_PAD_KEY, 892 893 LIBINPUT_EVENT_GESTURE_SWIPE_BEGIN = 800, 894 LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE, 895 LIBINPUT_EVENT_GESTURE_SWIPE_END, 896 LIBINPUT_EVENT_GESTURE_PINCH_BEGIN, 897 LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, 898 LIBINPUT_EVENT_GESTURE_PINCH_END, 899 900 /** 901 * @since 1.7 902 */ 903 LIBINPUT_EVENT_SWITCH_TOGGLE = 900, 904 }; 905 906 /** 907 * @defgroup event Accessing and destruction of events 908 */ 909 910 /** 911 * @ingroup event 912 * 913 * Destroy the event, freeing all associated resources. Resources obtained 914 * from this event must be considered invalid after this call. 915 * 916 * @warning Unlike other structs events are considered transient and 917 * <b>not</b> refcounted. Calling libinput_event_destroy() <b>will</b> 918 * destroy the event. 919 * 920 * @param event An event retrieved by libinput_get_event(). 921 */ 922 void 923 libinput_event_destroy(struct libinput_event *event); 924 925 /** 926 * @ingroup event 927 * 928 * Get the type of the event. 929 * 930 * @param event An event retrieved by libinput_get_event(). 931 */ 932 enum libinput_event_type 933 libinput_event_get_type(struct libinput_event *event); 934 935 /** 936 * @ingroup event 937 * 938 * Get the libinput context from the event. 939 * 940 * @param event The libinput event 941 * @return The libinput context for this event. 942 */ 943 struct libinput * 944 libinput_event_get_context(struct libinput_event *event); 945 946 /** 947 * @ingroup event 948 * 949 * Return the device associated with this event. For device added/removed 950 * events this is the device added or removed. For all other device events, 951 * this is the device that generated the event. 952 * 953 * This device is not refcounted and its lifetime is that of the event. Use 954 * libinput_device_ref() before using the device outside of this scope. 955 * 956 * @return The device associated with this event 957 */ 958 959 struct libinput_device * 960 libinput_event_get_device(struct libinput_event *event); 961 962 /** 963 * @ingroup event 964 * 965 * Return the pointer event that is this input event. If the event type does 966 * not match the pointer event types, this function returns NULL. 967 * 968 * The inverse of this function is libinput_event_pointer_get_base_event(). 969 * 970 * @return A pointer event, or NULL for other events 971 */ 972 struct libinput_event_pointer * 973 libinput_event_get_pointer_event(struct libinput_event *event); 974 975 /** 976 * @ingroup event 977 * 978 * Return the keyboard event that is this input event. If the event type does 979 * not match the keyboard event types, this function returns NULL. 980 * 981 * The inverse of this function is libinput_event_keyboard_get_base_event(). 982 * 983 * @return A keyboard event, or NULL for other events 984 */ 985 struct libinput_event_keyboard * 986 libinput_event_get_keyboard_event(struct libinput_event *event); 987 988 /** 989 * @ingroup event 990 * 991 * Return the touch event that is this input event. If the event type does 992 * not match the touch event types, this function returns NULL. 993 * 994 * The inverse of this function is libinput_event_touch_get_base_event(). 995 * 996 * @return A touch event, or NULL for other events 997 */ 998 struct libinput_event_touch * 999 libinput_event_get_touch_event(struct libinput_event *event); 1000 1001 /** 1002 * @ingroup event 1003 * 1004 * Return the gesture event that is this input event. If the event type does 1005 * not match the gesture event types, this function returns NULL. 1006 * 1007 * A gesture's lifetime has three distinct stages: begin, update and end, each 1008 * with their own event types. Begin is sent when the fingers are first set 1009 * down or libinput decides that the gesture begins. For @ref 1010 * LIBINPUT_EVENT_GESTURE_PINCH_BEGIN this sets the initial scale. Any 1011 * events changing properties of the gesture are sent as update events. On 1012 * termination of the gesture, an end event is sent. 1013 * 1014 * The inverse of this function is libinput_event_gesture_get_base_event(). 1015 * 1016 * @return A gesture event, or NULL for other events 1017 */ 1018 struct libinput_event_gesture * 1019 libinput_event_get_gesture_event(struct libinput_event *event); 1020 1021 /** 1022 * @ingroup event 1023 * 1024 * Return the tablet tool event that is this input event. If the event type 1025 * does not match the tablet tool event types, this function returns NULL. 1026 * 1027 * The inverse of this function is libinput_event_tablet_tool_get_base_event(). 1028 * 1029 * @return A tablet tool event, or NULL for other events 1030 * 1031 * @since 1.2 1032 */ 1033 struct libinput_event_tablet_tool * 1034 libinput_event_get_tablet_tool_event(struct libinput_event *event); 1035 1036 /** 1037 * @ingroup event 1038 * 1039 * Return the tablet pad event that is this input event. If the event type does not 1040 * match the tablet pad event types, this function returns NULL. 1041 * 1042 * The inverse of this function is libinput_event_tablet_pad_get_base_event(). 1043 * 1044 * @return A tablet pad event, or NULL for other events 1045 */ 1046 struct libinput_event_tablet_pad * 1047 libinput_event_get_tablet_pad_event(struct libinput_event *event); 1048 1049 /** 1050 * @ingroup event 1051 * 1052 * Return the switch event that is this input event. If the event type does 1053 * not match the switch event types, this function returns NULL. 1054 * 1055 * The inverse of this function is libinput_event_switch_get_base_event(). 1056 * 1057 * @return A switch event, or NULL for other events 1058 * 1059 * @since 1.7 1060 */ 1061 struct libinput_event_switch * 1062 libinput_event_get_switch_event(struct libinput_event *event); 1063 1064 /** 1065 * @ingroup event 1066 * 1067 * Return the device event that is this input event. If the event type does 1068 * not match the device event types, this function returns NULL. 1069 * 1070 * The inverse of this function is 1071 * libinput_event_device_notify_get_base_event(). 1072 * 1073 * @return A device event, or NULL for other events 1074 */ 1075 struct libinput_event_device_notify * 1076 libinput_event_get_device_notify_event(struct libinput_event *event); 1077 1078 /** 1079 * @ingroup event 1080 * 1081 * @return The generic libinput_event of this event 1082 */ 1083 struct libinput_event * 1084 libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event); 1085 1086 /** 1087 * @defgroup event_keyboard Keyboard events 1088 * 1089 * Key events are generated when a key changes its logical state, usually by 1090 * being pressed or released. 1091 */ 1092 1093 /** 1094 * @ingroup event_keyboard 1095 * 1096 * @note Timestamps may not always increase. See the libinput documentation 1097 * for more details. 1098 * 1099 * @return The event time for this event 1100 */ 1101 uint32_t 1102 libinput_event_keyboard_get_time(struct libinput_event_keyboard *event); 1103 1104 /** 1105 * @ingroup event_keyboard 1106 * 1107 * @note Timestamps may not always increase. See the libinput documentation 1108 * for more details. 1109 * 1110 * @return The event time for this event in microseconds 1111 */ 1112 uint64_t 1113 libinput_event_keyboard_get_time_usec(struct libinput_event_keyboard *event); 1114 1115 /** 1116 * @ingroup event_keyboard 1117 * 1118 * @return The keycode that triggered this key event 1119 */ 1120 uint32_t 1121 libinput_event_keyboard_get_key(struct libinput_event_keyboard *event); 1122 1123 /** 1124 * @ingroup event_keyboard 1125 * 1126 * @return The state change of the key 1127 */ 1128 enum libinput_key_state 1129 libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event); 1130 1131 /** 1132 * @ingroup event_keyboard 1133 * 1134 * @return The generic libinput_event of this event 1135 */ 1136 struct libinput_event * 1137 libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event); 1138 1139 /** 1140 * @ingroup event_keyboard 1141 * 1142 * For the key of a @ref LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number 1143 * of keys pressed on all devices on the associated seat after the event was 1144 * triggered. 1145 * 1146 * @note It is an application bug to call this function for events other than 1147 * @ref LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0. 1148 * 1149 * @return The seat wide pressed key count for the key of this event 1150 */ 1151 uint32_t 1152 libinput_event_keyboard_get_seat_key_count( 1153 struct libinput_event_keyboard *event); 1154 1155 /** 1156 * @defgroup event_pointer Pointer events 1157 * 1158 * Pointer events reflect motion, button and scroll events, as well as 1159 * events from other axes. 1160 */ 1161 1162 /** 1163 * @ingroup event_pointer 1164 * 1165 * @note Timestamps may not always increase. See the libinput documentation 1166 * for more details. 1167 * 1168 * @return The event time for this event 1169 */ 1170 uint32_t 1171 libinput_event_pointer_get_time(struct libinput_event_pointer *event); 1172 1173 /** 1174 * @ingroup event_pointer 1175 * 1176 * @note Timestamps may not always increase. See the libinput documentation 1177 * for more details. 1178 * 1179 * @return The event time for this event in microseconds 1180 */ 1181 uint64_t 1182 libinput_event_pointer_get_time_usec(struct libinput_event_pointer *event); 1183 1184 /** 1185 * @ingroup event_pointer 1186 * 1187 * Return the delta between the last event and the current event. For pointer 1188 * events that are not of type @ref LIBINPUT_EVENT_POINTER_MOTION, this 1189 * function returns 0. 1190 * 1191 * If a device employs pointer acceleration, the delta returned by this 1192 * function is the accelerated delta. 1193 * 1194 * Relative motion deltas are to be interpreted as pixel movement of a 1195 * standardized mouse. See the libinput documentation for more details. 1196 * 1197 * @note It is an application bug to call this function for events other than 1198 * @ref LIBINPUT_EVENT_POINTER_MOTION. 1199 * 1200 * @return The relative x movement since the last event 1201 */ 1202 double 1203 libinput_event_pointer_get_dx(struct libinput_event_pointer *event); 1204 1205 /** 1206 * @ingroup event_pointer 1207 * 1208 * Return the delta between the last event and the current event. For pointer 1209 * events that are not of type @ref LIBINPUT_EVENT_POINTER_MOTION, this 1210 * function returns 0. 1211 * 1212 * If a device employs pointer acceleration, the delta returned by this 1213 * function is the accelerated delta. 1214 * 1215 * Relative motion deltas are to be interpreted as pixel movement of a 1216 * standardized mouse. See the libinput documentation for more details. 1217 * 1218 * @note It is an application bug to call this function for events other than 1219 * @ref LIBINPUT_EVENT_POINTER_MOTION. 1220 * 1221 * @return The relative y movement since the last event 1222 */ 1223 double 1224 libinput_event_pointer_get_dy(struct libinput_event_pointer *event); 1225 1226 /** 1227 * @ingroup event_pointer 1228 * 1229 * Return the relative delta of the unaccelerated motion vector of the 1230 * current event. For pointer events that are not of type @ref 1231 * LIBINPUT_EVENT_POINTER_MOTION, this function returns 0. 1232 * 1233 * Relative unaccelerated motion deltas are raw device coordinates. 1234 * Note that these coordinates are subject to the device's native 1235 * resolution. Touchpad coordinates represent raw device coordinates in the 1236 * X resolution of the touchpad. See the libinput documentation for more 1237 * details. 1238 * 1239 * Any rotation applied to the device also applies to unaccelerated motion 1240 * (see libinput_device_config_rotation_set_angle()). 1241 * 1242 * @note It is an application bug to call this function for events other than 1243 * @ref LIBINPUT_EVENT_POINTER_MOTION. 1244 * 1245 * @return The unaccelerated relative x movement since the last event 1246 */ 1247 double 1248 libinput_event_pointer_get_dx_unaccelerated( 1249 struct libinput_event_pointer *event); 1250 1251 /** 1252 * @ingroup event_pointer 1253 * 1254 * Return the relative delta of the unaccelerated motion vector of the 1255 * current event. For pointer events that are not of type @ref 1256 * LIBINPUT_EVENT_POINTER_MOTION, this function returns 0. 1257 * 1258 * Relative unaccelerated motion deltas are raw device coordinates. 1259 * Note that these coordinates are subject to the device's native 1260 * resolution. Touchpad coordinates represent raw device coordinates in the 1261 * X resolution of the touchpad. See the libinput documentation for more 1262 * details. 1263 * 1264 * Any rotation applied to the device also applies to unaccelerated motion 1265 * (see libinput_device_config_rotation_set_angle()). 1266 * 1267 * @note It is an application bug to call this function for events other than 1268 * @ref LIBINPUT_EVENT_POINTER_MOTION. 1269 * 1270 * @return The unaccelerated relative y movement since the last event 1271 */ 1272 double 1273 libinput_event_pointer_get_dy_unaccelerated( 1274 struct libinput_event_pointer *event); 1275 1276 /** 1277 * @ingroup event_pointer 1278 * 1279 * Return the current absolute x coordinate of the pointer event, in mm from 1280 * the top left corner of the device. To get the corresponding output screen 1281 * coordinate, use libinput_event_pointer_get_absolute_x_transformed(). 1282 * 1283 * For pointer events that are not of type 1284 * @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0. 1285 * 1286 * @note It is an application bug to call this function for events other than 1287 * @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE. 1288 * 1289 * @return The current absolute x coordinate 1290 */ 1291 double 1292 libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event); 1293 1294 /** 1295 * @ingroup event_pointer 1296 * 1297 * Return the current absolute y coordinate of the pointer event, in mm from 1298 * the top left corner of the device. To get the corresponding output screen 1299 * coordinate, use libinput_event_pointer_get_absolute_y_transformed(). 1300 * 1301 * For pointer events that are not of type 1302 * @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0. 1303 * 1304 * @note It is an application bug to call this function for events other than 1305 * @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE. 1306 * 1307 * @return The current absolute y coordinate 1308 */ 1309 double 1310 libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event); 1311 1312 /** 1313 * @ingroup event_pointer 1314 * 1315 * Return the current absolute x coordinate of the pointer event, transformed to 1316 * screen coordinates. 1317 * 1318 * For pointer events that are not of type 1319 * @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this 1320 * function is undefined. 1321 * 1322 * @note It is an application bug to call this function for events other than 1323 * @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE. 1324 * 1325 * @param event The libinput pointer event 1326 * @param width The current output screen width 1327 * @return The current absolute x coordinate transformed to a screen coordinate 1328 */ 1329 double 1330 libinput_event_pointer_get_absolute_x_transformed( 1331 struct libinput_event_pointer *event, 1332 uint32_t width); 1333 1334 /** 1335 * @ingroup event_pointer 1336 * 1337 * Return the current absolute y coordinate of the pointer event, transformed to 1338 * screen coordinates. 1339 * 1340 * For pointer events that are not of type 1341 * @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is 1342 * undefined. 1343 * 1344 * @note It is an application bug to call this function for events other than 1345 * @ref LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE. 1346 * 1347 * @param event The libinput pointer event 1348 * @param height The current output screen height 1349 * @return The current absolute y coordinate transformed to a screen coordinate 1350 */ 1351 double 1352 libinput_event_pointer_get_absolute_y_transformed( 1353 struct libinput_event_pointer *event, 1354 uint32_t height); 1355 1356 /** 1357 * @ingroup event_pointer 1358 * 1359 * Return the button that triggered this event. 1360 * For pointer events that are not of type @ref 1361 * LIBINPUT_EVENT_POINTER_BUTTON, this function returns 0. 1362 * 1363 * @note It is an application bug to call this function for events other than 1364 * @ref LIBINPUT_EVENT_POINTER_BUTTON. 1365 * 1366 * @return The button triggering this event 1367 */ 1368 uint32_t 1369 libinput_event_pointer_get_button(struct libinput_event_pointer *event); 1370 1371 /** 1372 * @ingroup event_pointer 1373 * 1374 * Return the button state that triggered this event. 1375 * For pointer events that are not of type @ref 1376 * LIBINPUT_EVENT_POINTER_BUTTON, this function returns 0. 1377 * 1378 * @note It is an application bug to call this function for events other than 1379 * @ref LIBINPUT_EVENT_POINTER_BUTTON. 1380 * 1381 * @return The button state triggering this event 1382 */ 1383 enum libinput_button_state 1384 libinput_event_pointer_get_button_state(struct libinput_event_pointer *event); 1385 1386 /** 1387 * @ingroup event_pointer 1388 * 1389 * For the button of a @ref LIBINPUT_EVENT_POINTER_BUTTON event, return the 1390 * total number of buttons pressed on all devices on the associated seat 1391 * after the event was triggered. 1392 * 1393 * @note It is an application bug to call this function for events other than 1394 * @ref LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function 1395 * returns 0. 1396 * 1397 * @return The seat wide pressed button count for the key of this event 1398 */ 1399 uint32_t 1400 libinput_event_pointer_get_seat_button_count( 1401 struct libinput_event_pointer *event); 1402 1403 /** 1404 * @ingroup event_pointer 1405 * 1406 * Check if the event has a valid value for the given axis. 1407 * 1408 * If this function returns non-zero for an axis and 1409 * libinput_event_pointer_get_axis_value() returns a value of 0, the event 1410 * is a scroll stop event. 1411 * 1412 * For pointer events that are not of type @ref LIBINPUT_EVENT_POINTER_AXIS, 1413 * this function returns 0. 1414 * 1415 * @note It is an application bug to call this function for events other than 1416 * @ref LIBINPUT_EVENT_POINTER_AXIS. 1417 * 1418 * @return Non-zero if this event contains a value for this axis 1419 */ 1420 int 1421 libinput_event_pointer_has_axis(struct libinput_event_pointer *event, 1422 enum libinput_pointer_axis axis); 1423 1424 /** 1425 * @ingroup event_pointer 1426 * 1427 * Return the axis value of the given axis. The interpretation of the value 1428 * depends on the axis. For the two scrolling axes 1429 * @ref LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and 1430 * @ref LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in 1431 * relative scroll units, with the positive direction being down or right, 1432 * respectively. For the interpretation of the value, see 1433 * libinput_event_pointer_get_axis_source(). 1434 * 1435 * If libinput_event_pointer_has_axis() returns 0 for an axis, this function 1436 * returns 0 for that axis. 1437 * 1438 * For pointer events that are not of type @ref LIBINPUT_EVENT_POINTER_AXIS, 1439 * this function returns 0. 1440 * 1441 * @note It is an application bug to call this function for events other than 1442 * @ref LIBINPUT_EVENT_POINTER_AXIS. 1443 * 1444 * @return The axis value of this event 1445 * 1446 * @see libinput_event_pointer_get_axis_value_discrete 1447 */ 1448 double 1449 libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event, 1450 enum libinput_pointer_axis axis); 1451 1452 /** 1453 * @ingroup event_pointer 1454 * 1455 * Return the source for a given axis event. Axis events (scroll events) can 1456 * be caused by a hardware item such as a scroll wheel or emulated from 1457 * other input sources, such as two-finger or edge scrolling on a 1458 * touchpad. 1459 * 1460 * If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_FINGER, libinput 1461 * guarantees that a scroll sequence is terminated with a scroll value of 0. 1462 * A caller may use this information to decide on whether kinetic scrolling 1463 * should be triggered on this scroll sequence. 1464 * The coordinate system is identical to the cursor movement, i.e. a 1465 * scroll value of 1 represents the equivalent relative motion of 1. 1466 * 1467 * If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_WHEEL, no terminating 1468 * event is guaranteed (though it may happen). 1469 * Scrolling is in discrete steps, the value is the angle the wheel moved 1470 * in degrees. The default is 15 degrees per wheel click, but some mice may 1471 * have differently grained wheels. It is up to the caller how to interpret 1472 * such different step sizes. 1473 * 1474 * If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS, no 1475 * terminating event is guaranteed (though it may happen). 1476 * The coordinate system is identical to the cursor movement, i.e. a 1477 * scroll value of 1 represents the equivalent relative motion of 1. 1478 * 1479 * @deprecated The source @ref LIBINPUT_POINTER_AXIS_SOURCE_WHEEL_TILT is 1480 * deprecated as of libinput 1.16. No device has ever sent this source. 1481 * 1482 * For pointer events that are not of type @ref LIBINPUT_EVENT_POINTER_AXIS, 1483 * this function returns 0. 1484 * 1485 * @note It is an application bug to call this function for events other than 1486 * @ref LIBINPUT_EVENT_POINTER_AXIS. 1487 * 1488 * @return The source for this axis event 1489 */ 1490 enum libinput_pointer_axis_source 1491 libinput_event_pointer_get_axis_source(struct libinput_event_pointer *event); 1492 1493 /** 1494 * @ingroup event_pointer 1495 * 1496 * Return the axis value in discrete steps for a given axis event. How a 1497 * value translates into a discrete step depends on the source. 1498 * 1499 * If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_WHEEL, the discrete 1500 * value correspond to the number of physical mouse wheel clicks. 1501 * 1502 * If the source is @ref LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS or @ref 1503 * LIBINPUT_POINTER_AXIS_SOURCE_FINGER, the discrete value is always 0. 1504 * 1505 * @return The discrete value for the given event. 1506 * 1507 * @see libinput_event_pointer_get_axis_value 1508 */ 1509 double 1510 libinput_event_pointer_get_axis_value_discrete(struct libinput_event_pointer *event, 1511 enum libinput_pointer_axis axis); 1512 1513 /** 1514 * @ingroup event_pointer 1515 * 1516 * @return The generic libinput_event of this event 1517 */ 1518 struct libinput_event * 1519 libinput_event_pointer_get_base_event(struct libinput_event_pointer *event); 1520 1521 /** 1522 * @defgroup event_touch Touch events 1523 * 1524 * Events from absolute touch devices. 1525 */ 1526 1527 /** 1528 * @ingroup event_touch 1529 * 1530 * @note Timestamps may not always increase. See the libinput documentation 1531 * for more details. 1532 * 1533 * @return The event time for this event 1534 */ 1535 uint32_t 1536 libinput_event_touch_get_time(struct libinput_event_touch *event); 1537 1538 /** 1539 * @ingroup event_touch 1540 * 1541 * @note Timestamps may not always increase. See the libinput documentation 1542 * for more details. 1543 * 1544 * @return The event time for this event in microseconds 1545 */ 1546 uint64_t 1547 libinput_event_touch_get_time_usec(struct libinput_event_touch *event); 1548 1549 /** 1550 * @ingroup event_touch 1551 * 1552 * Get the slot of this touch event. See the kernel's multitouch 1553 * protocol B documentation for more information. 1554 * 1555 * If the touch event has no assigned slot, for example if it is from a 1556 * single touch device, this function returns -1. 1557 * 1558 * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref 1559 * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_MOTION or @ref 1560 * LIBINPUT_EVENT_TOUCH_CANCEL, this function returns 0. 1561 * 1562 * @note It is an application bug to call this function for events of type 1563 * other than @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_UP, 1564 * @ref LIBINPUT_EVENT_TOUCH_MOTION or @ref LIBINPUT_EVENT_TOUCH_CANCEL. 1565 * 1566 * @return The slot of this touch event 1567 */ 1568 int32_t 1569 libinput_event_touch_get_slot(struct libinput_event_touch *event); 1570 1571 /** 1572 * @ingroup event_touch 1573 * 1574 * Get the seat slot of the touch event. A seat slot is a non-negative seat 1575 * wide unique identifier of an active touch point. 1576 * 1577 * Events from single touch devices will be represented as one individual 1578 * touch point per device. 1579 * 1580 * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref 1581 * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_MOTION or @ref 1582 * LIBINPUT_EVENT_TOUCH_CANCEL, this function returns 0. 1583 * 1584 * @note It is an application bug to call this function for events of type 1585 * other than @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_UP, 1586 * @ref LIBINPUT_EVENT_TOUCH_MOTION or @ref LIBINPUT_EVENT_TOUCH_CANCEL. 1587 * 1588 * @return The seat slot of the touch event 1589 */ 1590 int32_t 1591 libinput_event_touch_get_seat_slot(struct libinput_event_touch *event); 1592 1593 /** 1594 * @ingroup event_touch 1595 * 1596 * Return the current absolute x coordinate of the touch event, in mm from 1597 * the top left corner of the device. To get the corresponding output screen 1598 * coordinate, use libinput_event_touch_get_x_transformed(). 1599 * 1600 * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref 1601 * LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0. 1602 * 1603 * @note It is an application bug to call this function for events of type 1604 * other than @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref 1605 * LIBINPUT_EVENT_TOUCH_MOTION. 1606 * 1607 * @param event The libinput touch event 1608 * @return The current absolute x coordinate 1609 */ 1610 double 1611 libinput_event_touch_get_x(struct libinput_event_touch *event); 1612 1613 /** 1614 * @ingroup event_touch 1615 * 1616 * Return the current absolute y coordinate of the touch event, in mm from 1617 * the top left corner of the device. To get the corresponding output screen 1618 * coordinate, use libinput_event_touch_get_y_transformed(). 1619 * 1620 * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref 1621 * LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0. 1622 * 1623 * @note It is an application bug to call this function for events of type 1624 * other than @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref 1625 * LIBINPUT_EVENT_TOUCH_MOTION. 1626 * 1627 * @param event The libinput touch event 1628 * @return The current absolute y coordinate 1629 */ 1630 double 1631 libinput_event_touch_get_y(struct libinput_event_touch *event); 1632 1633 /** 1634 * @ingroup event_touch 1635 * 1636 * Return the current absolute x coordinate of the touch event, transformed to 1637 * screen coordinates. 1638 * 1639 * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref 1640 * LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0. 1641 * 1642 * @note It is an application bug to call this function for events of type 1643 * other than @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref 1644 * LIBINPUT_EVENT_TOUCH_MOTION. 1645 * 1646 * @param event The libinput touch event 1647 * @param width The current output screen width 1648 * @return The current absolute x coordinate transformed to a screen coordinate 1649 */ 1650 double 1651 libinput_event_touch_get_x_transformed(struct libinput_event_touch *event, 1652 uint32_t width); 1653 1654 /** 1655 * @ingroup event_touch 1656 * 1657 * Return the current absolute y coordinate of the touch event, transformed to 1658 * screen coordinates. 1659 * 1660 * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref 1661 * LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0. 1662 * 1663 * @note It is an application bug to call this function for events of type 1664 * other than @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref 1665 * LIBINPUT_EVENT_TOUCH_MOTION. 1666 * 1667 * @param event The libinput touch event 1668 * @param height The current output screen height 1669 * @return The current absolute y coordinate transformed to a screen coordinate 1670 */ 1671 double 1672 libinput_event_touch_get_y_transformed(struct libinput_event_touch *event, 1673 uint32_t height); 1674 1675 /** 1676 * @ingroup event_touch 1677 * 1678 * @return The generic libinput_event of this event 1679 */ 1680 struct libinput_event * 1681 libinput_event_touch_get_base_event(struct libinput_event_touch *event); 1682 1683 /** 1684 * @defgroup event_gesture Gesture events 1685 * 1686 * Gesture events are generated when a gesture is recognized on a touchpad. 1687 * 1688 * Gesture sequences always start with a LIBINPUT_EVENT_GESTURE_FOO_START 1689 * event. All following gesture events will be of the 1690 * LIBINPUT_EVENT_GESTURE_FOO_UPDATE type until a 1691 * LIBINPUT_EVENT_GESTURE_FOO_END is generated which signals the end of the 1692 * gesture. 1693 * 1694 * See the libinput documentation for details on gesture handling. 1695 */ 1696 1697 /** 1698 * @ingroup event_gesture 1699 * 1700 * @note Timestamps may not always increase. See the libinput documentation 1701 * for more details. 1702 * 1703 * @return The event time for this event 1704 */ 1705 uint32_t 1706 libinput_event_gesture_get_time(struct libinput_event_gesture *event); 1707 1708 /** 1709 * @ingroup event_gesture 1710 * 1711 * @note Timestamps may not always increase. See the libinput documentation 1712 * for more details. 1713 * 1714 * @return The event time for this event in microseconds 1715 */ 1716 uint64_t 1717 libinput_event_gesture_get_time_usec(struct libinput_event_gesture *event); 1718 1719 /** 1720 * @ingroup event_gesture 1721 * 1722 * @return The generic libinput_event of this event 1723 */ 1724 struct libinput_event * 1725 libinput_event_gesture_get_base_event(struct libinput_event_gesture *event); 1726 1727 /** 1728 * @ingroup event_gesture 1729 * 1730 * Return the number of fingers used for a gesture. This can be used e.g. 1731 * to differentiate between 3 or 4 finger swipes. 1732 * 1733 * This function can be called on all gesture events and the returned finger 1734 * count value remains the same for the lifetime of a gesture. Thus, if a 1735 * user puts down a fourth finger during a three-finger swipe gesture, 1736 * libinput will end the three-finger gesture and, if applicable, start a 1737 * four-finger swipe gesture. A caller may decide that those gestures are 1738 * semantically identical and continue the two gestures as one single gesture. 1739 * 1740 * @return the number of fingers used for a gesture 1741 */ 1742 int 1743 libinput_event_gesture_get_finger_count(struct libinput_event_gesture *event); 1744 1745 /** 1746 * @ingroup event_gesture 1747 * 1748 * Return if the gesture ended normally, or if it was cancelled. 1749 * For gesture events that are not of type 1750 * @ref LIBINPUT_EVENT_GESTURE_SWIPE_END or 1751 * @ref LIBINPUT_EVENT_GESTURE_PINCH_END, this function returns 0. 1752 * 1753 * @note It is an application bug to call this function for events other than 1754 * @ref LIBINPUT_EVENT_GESTURE_SWIPE_END or 1755 * @ref LIBINPUT_EVENT_GESTURE_PINCH_END. 1756 * 1757 * @return 0 or 1, with 1 indicating that the gesture was cancelled. 1758 */ 1759 int 1760 libinput_event_gesture_get_cancelled(struct libinput_event_gesture *event); 1761 1762 /** 1763 * @ingroup event_gesture 1764 * 1765 * Return the delta between the last event and the current event. For gesture 1766 * events that are not of type @ref LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE or 1767 * @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this function returns 0. 1768 * 1769 * If a device employs pointer acceleration, the delta returned by this 1770 * function is the accelerated delta. 1771 * 1772 * Relative motion deltas are normalized to represent those of a device with 1773 * 1000dpi resolution. See the libinput documentation for more details. 1774 * 1775 * @return the relative x movement since the last event 1776 */ 1777 double 1778 libinput_event_gesture_get_dx(struct libinput_event_gesture *event); 1779 1780 /** 1781 * @ingroup event_gesture 1782 * 1783 * Return the delta between the last event and the current event. For gesture 1784 * events that are not of type @ref LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE or 1785 * @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this function returns 0. 1786 * 1787 * If a device employs pointer acceleration, the delta returned by this 1788 * function is the accelerated delta. 1789 * 1790 * Relative motion deltas are normalized to represent those of a device with 1791 * 1000dpi resolution. See the libinput documentation for more details. 1792 * 1793 * @return the relative y movement since the last event 1794 */ 1795 double 1796 libinput_event_gesture_get_dy(struct libinput_event_gesture *event); 1797 1798 /** 1799 * @ingroup event_gesture 1800 * 1801 * Return the relative delta of the unaccelerated motion vector of the 1802 * current event. For gesture events that are not of type 1803 * @ref LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE or 1804 * @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this function returns 0. 1805 * 1806 * Relative unaccelerated motion deltas are normalized to represent those of a 1807 * device with 1000dpi resolution. See the libinput documentation for more 1808 * details. Note that unaccelerated events are not equivalent to 'raw' events 1809 * as read from the device. 1810 * 1811 * Any rotation applied to the device also applies to gesture motion 1812 * (see libinput_device_config_rotation_set_angle()). 1813 * 1814 * @return the unaccelerated relative x movement since the last event 1815 */ 1816 double 1817 libinput_event_gesture_get_dx_unaccelerated( 1818 struct libinput_event_gesture *event); 1819 1820 /** 1821 * @ingroup event_gesture 1822 * 1823 * Return the relative delta of the unaccelerated motion vector of the 1824 * current event. For gesture events that are not of type 1825 * @ref LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE or 1826 * @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this function returns 0. 1827 * 1828 * Relative unaccelerated motion deltas are normalized to represent those of a 1829 * device with 1000dpi resolution. See the libinput documentation for more 1830 * details. Note that unaccelerated events are not equivalent to 'raw' events 1831 * as read from the device. 1832 * 1833 * Any rotation applied to the device also applies to gesture motion 1834 * (see libinput_device_config_rotation_set_angle()). 1835 * 1836 * @return the unaccelerated relative y movement since the last event 1837 */ 1838 double 1839 libinput_event_gesture_get_dy_unaccelerated( 1840 struct libinput_event_gesture *event); 1841 1842 /** 1843 * @ingroup event_gesture 1844 * 1845 * Return the absolute scale of a pinch gesture, the scale is the division 1846 * of the current distance between the fingers and the distance at the start 1847 * of the gesture. The scale begins at 1.0, and if e.g. the fingers moved 1848 * together by 50% then the scale will become 0.5, if they move twice as far 1849 * apart as initially the scale becomes 2.0, etc. 1850 * 1851 * For gesture events that are of type @ref 1852 * LIBINPUT_EVENT_GESTURE_PINCH_BEGIN, this function returns 1.0. 1853 * 1854 * For gesture events that are of type @ref 1855 * LIBINPUT_EVENT_GESTURE_PINCH_END, this function returns the scale value 1856 * of the most recent @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE event (if 1857 * any) or 1.0 otherwise. 1858 * 1859 * For all other events this function returns 0. 1860 * 1861 * @note It is an application bug to call this function for events other than 1862 * @ref LIBINPUT_EVENT_GESTURE_PINCH_BEGIN, @ref 1863 * LIBINPUT_EVENT_GESTURE_PINCH_END or 1864 * @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE. 1865 * 1866 * @return the absolute scale of a pinch gesture 1867 */ 1868 double 1869 libinput_event_gesture_get_scale(struct libinput_event_gesture *event); 1870 1871 /** 1872 * @ingroup event_gesture 1873 * 1874 * Return the angle delta in degrees between the last and the current @ref 1875 * LIBINPUT_EVENT_GESTURE_PINCH_UPDATE event. For gesture events that 1876 * are not of type @ref LIBINPUT_EVENT_GESTURE_PINCH_UPDATE, this 1877 * function returns 0. 1878 * 1879 * The angle delta is defined as the change in angle of the line formed by 1880 * the 2 fingers of a pinch gesture. Clockwise rotation is represented 1881 * by a positive delta, counter-clockwise by a negative delta. If e.g. the 1882 * fingers are on the 12 and 6 location of a clock face plate and they move 1883 * to the 1 resp. 7 location in a single event then the angle delta is 1884 * 30 degrees. 1885 * 1886 * If more than two fingers are present, the angle represents the rotation 1887 * around the center of gravity. The calculation of the center of gravity is 1888 * implementation-dependent. 1889 * 1890 * @return the angle delta since the last event 1891 */ 1892 double 1893 libinput_event_gesture_get_angle_delta(struct libinput_event_gesture *event); 1894 1895 /** 1896 * @defgroup event_tablet Tablet events 1897 * 1898 * Events that come from tools on tablet devices. For events from the pad, 1899 * see @ref event_tablet_pad. 1900 * 1901 * Events from tablet devices are exposed by two interfaces, tools and pads. 1902 * Tool events originate (usually) from a stylus-like device, pad events 1903 * reflect any events originating from the physical tablet itself. 1904 * 1905 * Note that many tablets support touch events. These are exposed through 1906 * the @ref LIBINPUT_DEVICE_CAP_POINTER interface (for external touchpad-like 1907 * devices such as the Wacom Intuos series) or @ref 1908 * LIBINPUT_DEVICE_CAP_TOUCH interface (for built-in touchscreen-like 1909 * devices such as the Wacom Cintiq series). 1910 */ 1911 1912 /** 1913 * @ingroup event_tablet 1914 * 1915 * @return The generic libinput_event of this event 1916 * 1917 * @since 1.2 1918 */ 1919 struct libinput_event * 1920 libinput_event_tablet_tool_get_base_event(struct libinput_event_tablet_tool *event); 1921 1922 /** 1923 * @ingroup event_tablet 1924 * 1925 * Check if the x axis was updated in this event. 1926 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 1927 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 1928 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 1929 * 1930 * @note It is an application bug to call this function for events other 1931 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 1932 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 1933 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 1934 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 1935 * 1936 * @param event The libinput tablet tool event 1937 * @return 1 if the axis was updated or 0 otherwise 1938 * 1939 * @since 1.2 1940 */ 1941 int 1942 libinput_event_tablet_tool_x_has_changed( 1943 struct libinput_event_tablet_tool *event); 1944 1945 /** 1946 * @ingroup event_tablet 1947 * 1948 * Check if the y axis was updated in this event. 1949 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 1950 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 1951 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 1952 * 1953 * @note It is an application bug to call this function for events other 1954 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 1955 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 1956 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 1957 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 1958 * 1959 * @param event The libinput tablet tool event 1960 * @return 1 if the axis was updated or 0 otherwise 1961 * 1962 * @since 1.2 1963 */ 1964 int 1965 libinput_event_tablet_tool_y_has_changed( 1966 struct libinput_event_tablet_tool *event); 1967 1968 /** 1969 * @ingroup event_tablet 1970 * 1971 * Check if the pressure axis was updated in this event. 1972 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 1973 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 1974 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 1975 * 1976 * @note It is an application bug to call this function for events other 1977 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 1978 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 1979 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 1980 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 1981 * 1982 * @param event The libinput tablet tool event 1983 * @return 1 if the axis was updated or 0 otherwise 1984 * 1985 * @since 1.2 1986 */ 1987 int 1988 libinput_event_tablet_tool_pressure_has_changed( 1989 struct libinput_event_tablet_tool *event); 1990 1991 /** 1992 * @ingroup event_tablet 1993 * 1994 * Check if the distance axis was updated in this event. 1995 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 1996 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 1997 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 1998 * For tablet tool events of type @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, 1999 * this function always returns 1. 2000 * 2001 * @note It is an application bug to call this function for events other 2002 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 2003 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 2004 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 2005 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2006 * 2007 * @param event The libinput tablet tool event 2008 * @return 1 if the axis was updated or 0 otherwise 2009 * 2010 * @since 1.2 2011 */ 2012 int 2013 libinput_event_tablet_tool_distance_has_changed( 2014 struct libinput_event_tablet_tool *event); 2015 2016 /** 2017 * @ingroup event_tablet 2018 * 2019 * Check if the tilt x axis was updated in this event. 2020 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 2021 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 2022 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 2023 * 2024 * @note It is an application bug to call this function for events other 2025 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 2026 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 2027 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 2028 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2029 * 2030 * @param event The libinput tablet tool event 2031 * @return 1 if the axis was updated or 0 otherwise 2032 * 2033 * @since 1.2 2034 */ 2035 int 2036 libinput_event_tablet_tool_tilt_x_has_changed( 2037 struct libinput_event_tablet_tool *event); 2038 2039 /** 2040 * @ingroup event_tablet 2041 * 2042 * Check if the tilt y axis was updated in this event. 2043 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 2044 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 2045 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 2046 * 2047 * @note It is an application bug to call this function for events other 2048 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 2049 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 2050 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 2051 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2052 * 2053 * @param event The libinput tablet tool event 2054 * @return 1 if the axis was updated or 0 otherwise 2055 * 2056 * @since 1.2 2057 */ 2058 int 2059 libinput_event_tablet_tool_tilt_y_has_changed( 2060 struct libinput_event_tablet_tool *event); 2061 /** 2062 * @ingroup event_tablet 2063 * 2064 * Check if the z-rotation axis was updated in this event. 2065 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 2066 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 2067 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 2068 * 2069 * @note It is an application bug to call this function for events other 2070 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 2071 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 2072 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 2073 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2074 * 2075 * @param event The libinput tablet tool event 2076 * @return 1 if the axis was updated or 0 otherwise 2077 * 2078 * @since 1.2 2079 */ 2080 int 2081 libinput_event_tablet_tool_rotation_has_changed( 2082 struct libinput_event_tablet_tool *event); 2083 /** 2084 * @ingroup event_tablet 2085 * 2086 * Check if the slider axis was updated in this event. 2087 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 2088 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 2089 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 2090 * 2091 * @note It is an application bug to call this function for events other 2092 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 2093 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 2094 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 2095 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2096 * 2097 * @param event The libinput tablet tool event 2098 * @return 1 if the axis was updated or 0 otherwise 2099 * 2100 * @since 1.2 2101 */ 2102 int 2103 libinput_event_tablet_tool_slider_has_changed( 2104 struct libinput_event_tablet_tool *event); 2105 2106 /** 2107 * @ingroup event_tablet 2108 * 2109 * Check if the size major axis was updated in this event. 2110 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 2111 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 2112 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 2113 * 2114 * @note It is an application bug to call this function for events other 2115 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 2116 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 2117 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 2118 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2119 * 2120 * @param event The libinput tablet tool event 2121 * @return 1 if the axis was updated or 0 otherwise 2122 */ 2123 int 2124 libinput_event_tablet_tool_size_major_has_changed( 2125 struct libinput_event_tablet_tool *event); 2126 2127 /** 2128 * @ingroup event_tablet 2129 * 2130 * Check if the size minor axis was updated in this event. 2131 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 2132 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 2133 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 2134 * 2135 * @note It is an application bug to call this function for events other 2136 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 2137 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 2138 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 2139 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2140 * 2141 * @param event The libinput tablet tool event 2142 * @return 1 if the axis was updated or 0 otherwise 2143 */ 2144 int 2145 libinput_event_tablet_tool_size_minor_has_changed( 2146 struct libinput_event_tablet_tool *event); 2147 2148 /** 2149 * @ingroup event_tablet 2150 * 2151 * Check if the wheel axis was updated in this event. 2152 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, 2153 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, or 2154 * @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, this function returns 0. 2155 * 2156 * @note It is an application bug to call this function for events other 2157 * than @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref 2158 * LIBINPUT_EVENT_TABLET_TOOL_TIP, or @ref 2159 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY, or @ref 2160 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2161 * 2162 * @param event The libinput tablet tool event 2163 * @return 1 if the axis was updated or 0 otherwise 2164 * 2165 * @since 1.2 2166 */ 2167 int 2168 libinput_event_tablet_tool_wheel_has_changed( 2169 struct libinput_event_tablet_tool *event); 2170 2171 /** 2172 * @ingroup event_tablet 2173 * 2174 * Returns the X coordinate of the tablet tool, in mm from the top left 2175 * corner of the tablet in its current logical orientation. Use 2176 * libinput_event_tablet_tool_get_x_transformed() for transforming the axis 2177 * value into a different coordinate space. 2178 * 2179 * @note On some devices, returned value may be negative or larger than the 2180 * width of the device. See the libinput documentation for more details. 2181 * 2182 * @param event The libinput tablet tool event 2183 * @return The current value of the the axis 2184 * 2185 * @since 1.2 2186 */ 2187 double 2188 libinput_event_tablet_tool_get_x(struct libinput_event_tablet_tool *event); 2189 2190 /** 2191 * @ingroup event_tablet 2192 * 2193 * Returns the Y coordinate of the tablet tool, in mm from the top left 2194 * corner of the tablet in its current logical orientation. Use 2195 * libinput_event_tablet_tool_get_y_transformed() for transforming the axis 2196 * value into a different coordinate space. 2197 * 2198 * @note On some devices, returned value may be negative or larger than the 2199 * width of the device. See the libinput documentation for more details. 2200 * 2201 * @param event The libinput tablet tool event 2202 * @return The current value of the the axis 2203 * 2204 * @since 1.2 2205 */ 2206 double 2207 libinput_event_tablet_tool_get_y(struct libinput_event_tablet_tool *event); 2208 2209 /** 2210 * @ingroup event_tablet 2211 * 2212 * Return the delta between the last event and the current event. 2213 * If the tool employs pointer acceleration, the delta returned by this 2214 * function is the accelerated delta. 2215 * 2216 * This value is in screen coordinate space, the delta is to be interpreted 2217 * like the return value of libinput_event_pointer_get_dx(). 2218 * See the libinput documentation for more details. 2219 * 2220 * @param event The libinput tablet event 2221 * @return The relative x movement since the last event 2222 * 2223 * @since 1.2 2224 */ 2225 double 2226 libinput_event_tablet_tool_get_dx(struct libinput_event_tablet_tool *event); 2227 2228 /** 2229 * @ingroup event_tablet 2230 * 2231 * Return the delta between the last event and the current event. 2232 * If the tool employs pointer acceleration, the delta returned by this 2233 * function is the accelerated delta. 2234 * 2235 * This value is in screen coordinate space, the delta is to be interpreted 2236 * like the return value of libinput_event_pointer_get_dx(). 2237 * See the libinput documentation for more details. 2238 * 2239 * @param event The libinput tablet event 2240 * @return The relative y movement since the last event 2241 * 2242 * @since 1.2 2243 */ 2244 double 2245 libinput_event_tablet_tool_get_dy(struct libinput_event_tablet_tool *event); 2246 2247 /** 2248 * @ingroup event_tablet 2249 * 2250 * Returns the current pressure being applied on the tool in use, normalized 2251 * to the range [0, 1]. 2252 * 2253 * If this axis does not exist on the current tool, this function returns 0. 2254 * 2255 * @param event The libinput tablet tool event 2256 * @return The current value of the the axis 2257 * 2258 * @since 1.2 2259 */ 2260 double 2261 libinput_event_tablet_tool_get_pressure(struct libinput_event_tablet_tool *event); 2262 2263 /** 2264 * @ingroup event_tablet 2265 * 2266 * Returns the current distance from the tablet's sensor, normalized to the 2267 * range [0, 1]. 2268 * 2269 * If this axis does not exist on the current tool, this function returns 0. 2270 * 2271 * @param event The libinput tablet tool event 2272 * @return The current value of the the axis 2273 * 2274 * @since 1.2 2275 */ 2276 double 2277 libinput_event_tablet_tool_get_distance(struct libinput_event_tablet_tool *event); 2278 2279 /** 2280 * @ingroup event_tablet 2281 * 2282 * Returns the current tilt along the X axis of the tablet's current logical 2283 * orientation, in degrees off the tablet's z axis. That is, if the tool is 2284 * perfectly orthogonal to the tablet, the tilt angle is 0. When the top 2285 * tilts towards the logical top/left of the tablet, the x/y tilt angles are 2286 * negative, if the top tilts towards the logical bottom/right of the 2287 * tablet, the x/y tilt angles are positive. 2288 * 2289 * If this axis does not exist on the current tool, this function returns 0. 2290 * 2291 * @param event The libinput tablet tool event 2292 * @return The current value of the axis in degrees 2293 * 2294 * @since 1.2 2295 */ 2296 double 2297 libinput_event_tablet_tool_get_tilt_x(struct libinput_event_tablet_tool *event); 2298 2299 /** 2300 * @ingroup event_tablet 2301 * 2302 * Returns the current tilt along the Y axis of the tablet's current logical 2303 * orientation, in degrees off the tablet's z axis. That is, if the tool is 2304 * perfectly orthogonal to the tablet, the tilt angle is 0. When the top 2305 * tilts towards the logical top/left of the tablet, the x/y tilt angles are 2306 * negative, if the top tilts towards the logical bottom/right of the 2307 * tablet, the x/y tilt angles are positive. 2308 * 2309 * If this axis does not exist on the current tool, this function returns 0. 2310 * 2311 * @param event The libinput tablet tool event 2312 * @return The current value of the the axis in degrees 2313 * 2314 * @since 1.2 2315 */ 2316 double 2317 libinput_event_tablet_tool_get_tilt_y(struct libinput_event_tablet_tool *event); 2318 2319 /** 2320 * @ingroup event_tablet 2321 * 2322 * Returns the current z rotation of the tool in degrees, clockwise from the 2323 * tool's logical neutral position. 2324 * 2325 * For tools of type @ref LIBINPUT_TABLET_TOOL_TYPE_MOUSE and @ref 2326 * LIBINPUT_TABLET_TOOL_TYPE_LENS the logical neutral position is 2327 * pointing to the current logical north of the tablet. For tools of type @ref 2328 * LIBINPUT_TABLET_TOOL_TYPE_BRUSH, the logical neutral position is with the 2329 * buttons pointing up. 2330 * 2331 * If this axis does not exist on the current tool, this function returns 0. 2332 * 2333 * @param event The libinput tablet tool event 2334 * @return The current value of the the axis 2335 * 2336 * @since 1.2 2337 */ 2338 double 2339 libinput_event_tablet_tool_get_rotation(struct libinput_event_tablet_tool *event); 2340 2341 /** 2342 * @ingroup event_tablet 2343 * 2344 * Returns the current position of the slider on the tool, normalized to the 2345 * range [-1, 1]. The logical zero is the neutral position of the slider, or 2346 * the logical center of the axis. This axis is available on e.g. the Wacom 2347 * Airbrush. 2348 * 2349 * If this axis does not exist on the current tool, this function returns 0. 2350 * 2351 * @param event The libinput tablet tool event 2352 * @return The current value of the the axis 2353 * 2354 * @since 1.2 2355 */ 2356 double 2357 libinput_event_tablet_tool_get_slider_position(struct libinput_event_tablet_tool *event); 2358 2359 /** 2360 * @ingroup event_tablet 2361 * 2362 * Returns the current size in mm along the major axis of the touching 2363 * ellipse. This axis is not necessarily aligned with either x or y, the 2364 * rotation must be taken into account. 2365 * 2366 * Where no rotation is available on a tool, or where rotation is zero, the 2367 * major axis aligns with the y axis and the minor axis with the x axis. 2368 * 2369 * If this axis does not exist on the current tool, this function returns 0. 2370 * 2371 * @param event The libinput tablet tool event 2372 * @return The current value of the axis major in mm 2373 */ 2374 double 2375 libinput_event_tablet_tool_get_size_major(struct libinput_event_tablet_tool *event); 2376 2377 /** 2378 * @ingroup event_tablet 2379 * 2380 * Returns the current size in mm along the minor axis of the touching 2381 * ellipse. This axis is not necessarily aligned with either x or y, the 2382 * rotation must be taken into account. 2383 * 2384 * Where no rotation is available on a tool, or where rotation is zero, the 2385 * minor axis aligns with the y axis and the minor axis with the x axis. 2386 * 2387 * If this axis does not exist on the current tool, this function returns 0. 2388 * 2389 * @param event The libinput tablet tool event 2390 * @return The current value of the axis minor in mm 2391 */ 2392 double 2393 libinput_event_tablet_tool_get_size_minor(struct libinput_event_tablet_tool *event); 2394 2395 /** 2396 * @ingroup event_tablet 2397 * 2398 * Return the delta for the wheel in degrees. 2399 * 2400 * @param event The libinput tablet tool event 2401 * @return The delta of the wheel, in degrees, compared to the last event 2402 * 2403 * @see libinput_event_tablet_tool_get_wheel_delta_discrete 2404 */ 2405 double 2406 libinput_event_tablet_tool_get_wheel_delta( 2407 struct libinput_event_tablet_tool *event); 2408 2409 /** 2410 * @ingroup event_tablet 2411 * 2412 * Return the delta for the wheel in discrete steps (e.g. wheel clicks). 2413 2414 * @param event The libinput tablet tool event 2415 * @return The delta of the wheel, in discrete steps, compared to the last event 2416 * 2417 * @see libinput_event_tablet_tool_get_wheel_delta_discrete 2418 * 2419 * @since 1.2 2420 */ 2421 int 2422 libinput_event_tablet_tool_get_wheel_delta_discrete( 2423 struct libinput_event_tablet_tool *event); 2424 2425 /** 2426 * @ingroup event_tablet 2427 * 2428 * Return the current absolute x coordinate of the tablet tool event, 2429 * transformed to screen coordinates. 2430 * 2431 * @note This function may be called for a specific axis even if 2432 * libinput_event_tablet_tool_*_has_changed() returns 0 for that axis. 2433 * libinput always includes all device axes in the event. 2434 * 2435 * @note On some devices, returned value may be negative or larger than the 2436 * width of the device. See the libinput documentation for more details. 2437 * 2438 * @param event The libinput tablet tool event 2439 * @param width The current output screen width 2440 * @return the current absolute x coordinate transformed to a screen coordinate 2441 * 2442 * @since 1.2 2443 */ 2444 double 2445 libinput_event_tablet_tool_get_x_transformed(struct libinput_event_tablet_tool *event, 2446 uint32_t width); 2447 2448 /** 2449 * @ingroup event_tablet 2450 * 2451 * Return the current absolute y coordinate of the tablet tool event, 2452 * transformed to screen coordinates. 2453 * 2454 * @note This function may be called for a specific axis even if 2455 * libinput_event_tablet_tool_*_has_changed() returns 0 for that axis. 2456 * libinput always includes all device axes in the event. 2457 * 2458 * @note On some devices, returned value may be negative or larger than the 2459 * width of the device. See the libinput documentation for more details. 2460 * 2461 * @param event The libinput tablet tool event 2462 * @param height The current output screen height 2463 * @return the current absolute y coordinate transformed to a screen coordinate 2464 * 2465 * @since 1.2 2466 */ 2467 double 2468 libinput_event_tablet_tool_get_y_transformed(struct libinput_event_tablet_tool *event, 2469 uint32_t height); 2470 2471 /** 2472 * @ingroup event_tablet 2473 * 2474 * Returns the tool that was in use during this event. 2475 * 2476 * The returned tablet tool is not refcounted and may become invalid after 2477 * the next call to libinput. Use libinput_tablet_tool_ref() and 2478 * libinput_tablet_tool_unref() to continue using the handle outside of the 2479 * immediate scope. 2480 * 2481 * If the caller holds at least one reference, this struct is used 2482 * whenever the tools enters proximity again. 2483 * 2484 * @note Physical tool tracking requires hardware support. If unavailable, 2485 * libinput creates one tool per type per tablet. See 2486 * libinput_tablet_tool_get_serial() for more details. 2487 * 2488 * @param event The libinput tablet tool event 2489 * @return The new tool triggering this event 2490 * 2491 * @since 1.2 2492 */ 2493 struct libinput_tablet_tool * 2494 libinput_event_tablet_tool_get_tool(struct libinput_event_tablet_tool *event); 2495 2496 /** 2497 * @ingroup event_tablet 2498 * 2499 * Returns the new proximity state of a tool from a proximity event. 2500 * Used to check whether or not a tool came in or out of proximity during an 2501 * event of type @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY. 2502 * 2503 * The proximity state represents the logical proximity state which does not 2504 * necessarily match when a tool comes into sensor range or leaves the 2505 * sensor range. On some tools this range does not represent the physical 2506 * range but a reduced tool-specific logical range. If the range is reduced, 2507 * this is done transparent to the caller. 2508 * 2509 * For example, the Wacom mouse and lens cursor tools are usually 2510 * used in relative mode, lying flat on the tablet. Movement typically follows 2511 * the interaction normal mouse movements have, i.e. slightly lift the tool and 2512 * place it in a separate location. The proximity detection on Wacom 2513 * tablets however extends further than the user may lift the mouse, i.e. the 2514 * tool may not be lifted out of physical proximity. For such tools, libinput 2515 * provides software-emulated proximity. 2516 * 2517 * @param event The libinput tablet tool event 2518 * @return The new proximity state of the tool from the event. 2519 * 2520 * @since 1.2 2521 */ 2522 enum libinput_tablet_tool_proximity_state 2523 libinput_event_tablet_tool_get_proximity_state(struct libinput_event_tablet_tool *event); 2524 2525 /** 2526 * @ingroup event_tablet 2527 * 2528 * Returns the new tip state of a tool from a tip event. 2529 * Used to check whether or not a tool came in contact with the tablet 2530 * surface or left contact with the tablet surface during an 2531 * event of type @ref LIBINPUT_EVENT_TABLET_TOOL_TIP. 2532 * 2533 * @param event The libinput tablet tool event 2534 * @return The new tip state of the tool from the event. 2535 * 2536 * @since 1.2 2537 */ 2538 enum libinput_tablet_tool_tip_state 2539 libinput_event_tablet_tool_get_tip_state(struct libinput_event_tablet_tool *event); 2540 2541 /** 2542 * @ingroup event_tablet 2543 * 2544 * Return the button that triggered this event. For events that are not of 2545 * type @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON, this function returns 0. 2546 * 2547 * @note It is an application bug to call this function for events other than 2548 * @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2549 * 2550 * @param event The libinput tablet tool event 2551 * @return the button triggering this event 2552 * 2553 * @since 1.2 2554 */ 2555 uint32_t 2556 libinput_event_tablet_tool_get_button(struct libinput_event_tablet_tool *event); 2557 2558 /** 2559 * @ingroup event_tablet 2560 * 2561 * Return the button state of the event. 2562 * 2563 * @note It is an application bug to call this function for events other than 2564 * @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON. 2565 * 2566 * @param event The libinput tablet tool event 2567 * @return the button state triggering this event 2568 * 2569 * @since 1.2 2570 */ 2571 enum libinput_button_state 2572 libinput_event_tablet_tool_get_button_state(struct libinput_event_tablet_tool *event); 2573 2574 /** 2575 * @ingroup event_tablet 2576 * 2577 * For the button of a @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON event, return the total 2578 * number of buttons pressed on all devices on the associated seat after the 2579 * the event was triggered. 2580 * 2581 " @note It is an application bug to call this function for events other than 2582 * @ref LIBINPUT_EVENT_TABLET_TOOL_BUTTON. For other events, this function returns 0. 2583 * 2584 * @param event The libinput tablet tool event 2585 * @return the seat wide pressed button count for the key of this event 2586 * 2587 * @since 1.2 2588 */ 2589 uint32_t 2590 libinput_event_tablet_tool_get_seat_button_count(struct libinput_event_tablet_tool *event); 2591 2592 /** 2593 * @ingroup event_tablet 2594 * 2595 * @note Timestamps may not always increase. See the libinput documentation 2596 * for more details. 2597 * 2598 * @param event The libinput tablet tool event 2599 * @return The event time for this event 2600 * 2601 * @since 1.2 2602 */ 2603 uint32_t 2604 libinput_event_tablet_tool_get_time(struct libinput_event_tablet_tool *event); 2605 2606 /** 2607 * @ingroup event_tablet 2608 * 2609 * @note Timestamps may not always increase. See the libinput documentation 2610 * for more details. 2611 * 2612 * @param event The libinput tablet tool event 2613 * @return The event time for this event in microseconds 2614 * 2615 * @since 1.2 2616 */ 2617 uint64_t 2618 libinput_event_tablet_tool_get_time_usec(struct libinput_event_tablet_tool *event); 2619 2620 /** 2621 * @ingroup event_tablet 2622 * 2623 * Return the high-level tool type for a tool object. 2624 * 2625 * The high level tool describes general interaction expected with the tool. 2626 * For example, a user would expect a tool of type @ref 2627 * LIBINPUT_TABLET_TOOL_TYPE_PEN to interact with a graphics application 2628 * taking pressure and tilt into account. The default virtual tool assigned 2629 * should be a drawing tool, e.g. a virtual pen or brush. 2630 * A tool of type @ref LIBINPUT_TABLET_TOOL_TYPE_ERASER would normally be 2631 * mapped to an eraser-like virtual tool. 2632 * 2633 * If supported by the hardware, a more specific tool id is always 2634 * available, see libinput_tablet_tool_get_tool_id(). 2635 * 2636 * @param tool The libinput tool 2637 * @return The tool type for this tool object 2638 * 2639 * @see libinput_tablet_tool_get_tool_id 2640 * 2641 * @since 1.2 2642 */ 2643 enum libinput_tablet_tool_type 2644 libinput_tablet_tool_get_type(struct libinput_tablet_tool *tool); 2645 2646 /** 2647 * @ingroup event_tablet 2648 * 2649 * Return the tool ID for a tool object. If nonzero, this number identifies 2650 * the specific type of the tool with more precision than the type returned in 2651 * libinput_tablet_tool_get_type(). Not all tablets support a tool ID. 2652 * 2653 * Tablets known to support tool IDs include the Wacom Intuos 3, 4, 5, Wacom 2654 * Cintiq and Wacom Intuos Pro series. The tool ID can be used to 2655 * distinguish between e.g. a Wacom Classic Pen or a Wacom Pro Pen. It is 2656 * the caller's responsibility to interpret the tool ID. 2657 * 2658 * @param tool The libinput tool 2659 * @return The tool ID for this tool object or 0 if none is provided 2660 * 2661 * @see libinput_tablet_tool_get_type 2662 * 2663 * @since 1.2 2664 */ 2665 uint64_t 2666 libinput_tablet_tool_get_tool_id(struct libinput_tablet_tool *tool); 2667 2668 /** 2669 * @ingroup event_tablet 2670 * 2671 * Increment the reference count of the tool by one. A tool is destroyed 2672 * whenever the reference count reaches 0. See libinput_tablet_tool_unref(). 2673 * 2674 * @param tool The tool to increment the ref count of 2675 * @return The passed tool 2676 * 2677 * @see libinput_tablet_tool_unref 2678 * 2679 * @since 1.2 2680 */ 2681 struct libinput_tablet_tool * 2682 libinput_tablet_tool_ref(struct libinput_tablet_tool *tool); 2683 2684 /** 2685 * @ingroup event_tablet 2686 * 2687 * Decrement the reference count of the tool by one. When the reference 2688 * count of the tool reaches 0, the memory allocated for the tool will be 2689 * freed. 2690 * 2691 * @param tool The tool to decrement the ref count of 2692 * @return NULL if the tool was destroyed otherwise the passed tool 2693 * 2694 * @see libinput_tablet_tool_ref 2695 * 2696 * @since 1.2 2697 */ 2698 struct libinput_tablet_tool * 2699 libinput_tablet_tool_unref(struct libinput_tablet_tool *tool); 2700 2701 /** 2702 * @ingroup event_tablet 2703 * 2704 * Return whether the tablet tool supports pressure. 2705 * 2706 * @param tool The tool to check the axis capabilities of 2707 * @return Nonzero if the axis is available, zero otherwise. 2708 * 2709 * @since 1.2 2710 */ 2711 int 2712 libinput_tablet_tool_has_pressure(struct libinput_tablet_tool *tool); 2713 2714 /** 2715 * @ingroup event_tablet 2716 * 2717 * Return whether the tablet tool supports distance. 2718 * 2719 * @param tool The tool to check the axis capabilities of 2720 * @return Nonzero if the axis is available, zero otherwise. 2721 * 2722 * @since 1.2 2723 */ 2724 int 2725 libinput_tablet_tool_has_distance(struct libinput_tablet_tool *tool); 2726 2727 /** 2728 * @ingroup event_tablet 2729 * 2730 * Return whether the tablet tool supports tilt. 2731 * 2732 * @param tool The tool to check the axis capabilities of 2733 * @return Nonzero if the axis is available, zero otherwise. 2734 * 2735 * @since 1.2 2736 */ 2737 int 2738 libinput_tablet_tool_has_tilt(struct libinput_tablet_tool *tool); 2739 2740 /** 2741 * @ingroup event_tablet 2742 * 2743 * Return whether the tablet tool supports z-rotation. 2744 * 2745 * @param tool The tool to check the axis capabilities of 2746 * @return Nonzero if the axis is available, zero otherwise. 2747 * 2748 * @since 1.2 2749 */ 2750 int 2751 libinput_tablet_tool_has_rotation(struct libinput_tablet_tool *tool); 2752 2753 /** 2754 * @ingroup event_tablet 2755 * 2756 * Return whether the tablet tool has a slider axis. 2757 * 2758 * @param tool The tool to check the axis capabilities of 2759 * @return Nonzero if the axis is available, zero otherwise. 2760 * 2761 * @since 1.2 2762 */ 2763 int 2764 libinput_tablet_tool_has_slider(struct libinput_tablet_tool *tool); 2765 2766 /** 2767 * @ingroup event_tablet 2768 * 2769 * Return whether the tablet tool has a ellipsis major and minor. 2770 * Where the underlying hardware only supports one of either major or minor, 2771 * libinput emulates the other axis as a circular contact, i.e. major == 2772 * minor for all values of major. 2773 * 2774 * @param tool The tool to check the axis capabilities of 2775 * @return Nonzero if the axis is available, zero otherwise. 2776 */ 2777 int 2778 libinput_tablet_tool_has_size(struct libinput_tablet_tool *tool); 2779 2780 /** 2781 * @ingroup event_tablet 2782 * 2783 * Return whether the tablet tool has a relative wheel. 2784 * 2785 * @param tool The tool to check the axis capabilities of 2786 * @return Nonzero if the axis is available, zero otherwise. 2787 * 2788 * @since 1.2 2789 */ 2790 int 2791 libinput_tablet_tool_has_wheel(struct libinput_tablet_tool *tool); 2792 2793 /** 2794 * @ingroup event_tablet 2795 * 2796 * Check if a tablet tool has a button with the 2797 * passed-in code (see linux/input.h). 2798 * 2799 * @param tool A tablet tool 2800 * @param code button code to check for 2801 * 2802 * @return 1 if the tool supports this button code, 0 if it does not 2803 * 2804 * @since 1.2 2805 */ 2806 int 2807 libinput_tablet_tool_has_button(struct libinput_tablet_tool *tool, 2808 uint32_t code); 2809 2810 /** 2811 * @ingroup event_tablet 2812 * 2813 * Return nonzero if the physical tool can be uniquely identified by 2814 * libinput, or nonzero otherwise. If a tool can be uniquely identified, 2815 * keeping a reference to the tool allows tracking the tool across 2816 * proximity out sequences and across compatible tablets. 2817 * See libinput_tablet_tool_get_serial() for more details. 2818 * 2819 * @param tool A tablet tool 2820 * @return 1 if the tool can be uniquely identified, 0 otherwise. 2821 * 2822 * @see libinput_tablet_tool_get_serial 2823 * 2824 * @since 1.2 2825 */ 2826 int 2827 libinput_tablet_tool_is_unique(struct libinput_tablet_tool *tool); 2828 2829 /** 2830 * @ingroup event_tablet 2831 * 2832 * Return the serial number of a tool. If the tool does not report a serial 2833 * number, this function returns zero. 2834 * 2835 * Some tools provide hardware information that enables libinput to uniquely 2836 * identify the physical device. For example, tools compatible with the 2837 * Wacom Intuos 4, Intuos 5, Intuos Pro and Cintiq series are uniquely 2838 * identifiable through a serial number. libinput does not specify how a 2839 * tool can be identified uniquely, a caller should use 2840 * libinput_tablet_tool_is_unique() to check if the tool is unique. 2841 * 2842 * libinput creates a struct @ref libinput_tablet_tool on the first 2843 * proximity in of this tool. By default, this struct is destroyed on 2844 * proximity out and re-initialized on the next proximity in. If a caller 2845 * keeps a reference to the tool by using libinput_tablet_tool_ref() 2846 * libinput re-uses this struct whenever that same physical tool comes into 2847 * proximity on any tablet 2848 * recognized by libinput. It is possible to attach tool-specific virtual 2849 * state to the tool. For example, a graphics program such as the GIMP may 2850 * assign a specific color to each tool, allowing the artist to use the 2851 * tools like physical pens of different color. In multi-tablet setups it is 2852 * also possible to track the tool across devices. 2853 * 2854 * If the tool does not have a unique identifier, libinput creates a single 2855 * struct @ref libinput_tablet_tool per tool type on each tablet the tool is 2856 * used on. 2857 * 2858 * @param tool The libinput tool 2859 * @return The tool serial number 2860 * 2861 * @see libinput_tablet_tool_is_unique 2862 * 2863 * @since 1.2 2864 */ 2865 uint64_t 2866 libinput_tablet_tool_get_serial(struct libinput_tablet_tool *tool); 2867 2868 /** 2869 * @ingroup event_tablet 2870 * 2871 * Return the user data associated with a tool object. libinput does 2872 * not manage, look at, or modify this data. The caller must ensure the 2873 * data is valid. 2874 * 2875 * @param tool The libinput tool 2876 * @return The user data associated with the tool object 2877 * 2878 * @since 1.2 2879 */ 2880 void * 2881 libinput_tablet_tool_get_user_data(struct libinput_tablet_tool *tool); 2882 2883 /** 2884 * @ingroup event_tablet 2885 * 2886 * Set the user data associated with a tool object, if any. 2887 * 2888 * @param tool The libinput tool 2889 * @param user_data The user data to associate with the tool object 2890 * 2891 * @since 1.2 2892 */ 2893 void 2894 libinput_tablet_tool_set_user_data(struct libinput_tablet_tool *tool, 2895 void *user_data); 2896 2897 /** 2898 * @defgroup event_tablet_pad Tablet pad events 2899 * 2900 * Events that come from the pad of tablet devices. For events from the 2901 * tablet tools, see @ref event_tablet. 2902 * 2903 * @since 1.3 2904 */ 2905 2906 /** 2907 * @ingroup event_tablet_pad 2908 * 2909 * @return The generic libinput_event of this event 2910 * 2911 * @since 1.3 2912 */ 2913 struct libinput_event * 2914 libinput_event_tablet_pad_get_base_event(struct libinput_event_tablet_pad *event); 2915 2916 /** 2917 * @ingroup event_tablet_pad 2918 * 2919 * Returns the current position of the ring, in degrees counterclockwise 2920 * from the northern-most point of the ring in the tablet's current logical 2921 * orientation. 2922 * 2923 * If the source is @ref LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER, 2924 * libinput sends a terminating event with a ring value of -1 when the 2925 * finger is lifted from the ring. A caller may use this information to e.g. 2926 * determine if kinetic scrolling should be triggered. 2927 * 2928 * @note It is an application bug to call this function for events other than 2929 * @ref LIBINPUT_EVENT_TABLET_PAD_RING. For other events, this function 2930 * returns 0. 2931 * 2932 * @param event The libinput tablet pad event 2933 * @return The current value of the the axis 2934 * @retval -1 The finger was lifted 2935 * 2936 * @since 1.3 2937 */ 2938 double 2939 libinput_event_tablet_pad_get_ring_position(struct libinput_event_tablet_pad *event); 2940 2941 /** 2942 * @ingroup event_tablet_pad 2943 * 2944 * Returns the number of the ring that has changed state, with 0 being the 2945 * first ring. On tablets with only one ring, this function always returns 2946 * 0. 2947 * 2948 * @note It is an application bug to call this function for events other than 2949 * @ref LIBINPUT_EVENT_TABLET_PAD_RING. For other events, this function 2950 * returns 0. 2951 * 2952 * @param event The libinput tablet pad event 2953 * @return The index of the ring that changed state 2954 * 2955 * @since 1.3 2956 */ 2957 unsigned int 2958 libinput_event_tablet_pad_get_ring_number(struct libinput_event_tablet_pad *event); 2959 2960 /** 2961 * @ingroup event_tablet_pad 2962 * 2963 * Returns the source of the interaction with the ring. If the source is 2964 * @ref LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER, libinput sends a ring 2965 * position value of -1 to terminate the current interaction. 2966 * 2967 * @note It is an application bug to call this function for events other than 2968 * @ref LIBINPUT_EVENT_TABLET_PAD_RING. For other events, this function 2969 * returns 0. 2970 * 2971 * @param event The libinput tablet pad event 2972 * @return The source of the ring interaction 2973 * 2974 * @since 1.3 2975 */ 2976 enum libinput_tablet_pad_ring_axis_source 2977 libinput_event_tablet_pad_get_ring_source(struct libinput_event_tablet_pad *event); 2978 2979 /** 2980 * @ingroup event_tablet_pad 2981 * 2982 * Returns the current position of the strip, normalized to the range 2983 * [0, 1], with 0 being the top/left-most point in the tablet's current 2984 * logical orientation. 2985 * 2986 * If the source is @ref LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER, 2987 * libinput sends a terminating event with a ring value of -1 when the 2988 * finger is lifted from the ring. A caller may use this information to e.g. 2989 * determine if kinetic scrolling should be triggered. 2990 * 2991 * @note It is an application bug to call this function for events other than 2992 * @ref LIBINPUT_EVENT_TABLET_PAD_STRIP. For other events, this function 2993 * returns 0. 2994 * 2995 * @param event The libinput tablet pad event 2996 * @return The current value of the the axis 2997 * @retval -1 The finger was lifted 2998 * 2999 * @since 1.3 3000 */ 3001 double 3002 libinput_event_tablet_pad_get_strip_position(struct libinput_event_tablet_pad *event); 3003 3004 /** 3005 * @ingroup event_tablet_pad 3006 * 3007 * Returns the number of the strip that has changed state, with 0 being the 3008 * first strip. On tablets with only one strip, this function always returns 3009 * 0. 3010 * 3011 * @note It is an application bug to call this function for events other than 3012 * @ref LIBINPUT_EVENT_TABLET_PAD_STRIP. For other events, this function 3013 * returns 0. 3014 * 3015 * @param event The libinput tablet pad event 3016 * @return The index of the strip that changed state 3017 * 3018 * @since 1.3 3019 */ 3020 unsigned int 3021 libinput_event_tablet_pad_get_strip_number(struct libinput_event_tablet_pad *event); 3022 3023 /** 3024 * @ingroup event_tablet_pad 3025 * 3026 * Returns the source of the interaction with the strip. If the source is 3027 * @ref LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER, libinput sends a strip 3028 * position value of -1 to terminate the current interaction. 3029 * 3030 * @note It is an application bug to call this function for events other than 3031 * @ref LIBINPUT_EVENT_TABLET_PAD_STRIP. For other events, this function 3032 * returns 0. 3033 * 3034 * @param event The libinput tablet pad event 3035 * @return The source of the strip interaction 3036 * 3037 * @since 1.3 3038 */ 3039 enum libinput_tablet_pad_strip_axis_source 3040 libinput_event_tablet_pad_get_strip_source(struct libinput_event_tablet_pad *event); 3041 3042 /** 3043 * @ingroup event_tablet_pad 3044 * 3045 * Return the button number that triggered this event, starting at 0. 3046 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON, 3047 * this function returns 0. 3048 * 3049 * Note that the number returned is a generic sequential button number and 3050 * not a semantic button code as defined in linux/input.h. 3051 * See the libinput documentation for more details. 3052 * 3053 * @note It is an application bug to call this function for events other than 3054 * @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON. For other events, this function 3055 * returns 0. 3056 * 3057 * @param event The libinput tablet pad event 3058 * @return the button triggering this event 3059 * 3060 * @since 1.3 3061 */ 3062 uint32_t 3063 libinput_event_tablet_pad_get_button_number(struct libinput_event_tablet_pad *event); 3064 3065 /** 3066 * @ingroup event_tablet_pad 3067 * 3068 * Return the button state of the event. 3069 * 3070 * @note It is an application bug to call this function for events other than 3071 * @ref LIBINPUT_EVENT_TABLET_PAD_BUTTON. For other events, this function 3072 * returns 0. 3073 * 3074 * @param event The libinput tablet pad event 3075 * @return the button state triggering this event 3076 * 3077 * @since 1.3 3078 */ 3079 enum libinput_button_state 3080 libinput_event_tablet_pad_get_button_state(struct libinput_event_tablet_pad *event); 3081 3082 /** 3083 * @ingroup event_tablet_pad 3084 * 3085 * Return the key code that triggered this event, e.g. KEY_CONTROLPANEL. The 3086 * list of key codes is defined in linux/input-event-codes.h. 3087 * 3088 * For events that are not of type @ref LIBINPUT_EVENT_TABLET_PAD_KEY, 3089 * this function returns 0. 3090 * 3091 * @note It is an application bug to call this function for events other than 3092 * @ref LIBINPUT_EVENT_TABLET_PAD_KEY. For other events, this function 3093 * returns 0. 3094 * 3095 * @param event The libinput tablet pad event 3096 * @return the key code triggering this event 3097 * 3098 * @since 1.15 3099 */ 3100 uint32_t 3101 libinput_event_tablet_pad_get_key(struct libinput_event_tablet_pad *event); 3102 3103 /** 3104 * @ingroup event_tablet_pad 3105 * 3106 * Return the key state of the event. 3107 * 3108 * @note It is an application bug to call this function for events other than 3109 * @ref LIBINPUT_EVENT_TABLET_PAD_KEY. For other events, this function 3110 * returns 0. 3111 * 3112 * @param event The libinput tablet pad event 3113 * @return the key state triggering this event 3114 * 3115 * @since 1.15 3116 */ 3117 enum libinput_key_state 3118 libinput_event_tablet_pad_get_key_state(struct libinput_event_tablet_pad *event); 3119 3120 /** 3121 * @ingroup event_tablet_pad 3122 * 3123 * Returns the mode the button, ring, or strip that triggered this event is 3124 * in, at the time of the event. 3125 * 3126 * The mode is a virtual grouping of functionality, usually based on some 3127 * visual feedback like LEDs on the pad. Mode indices start at 0, a device 3128 * that does not support modes always returns 0. 3129 * 3130 * @note Pad keys are not part of a mode group. It is an application bug to 3131 * call this function for @ref LIBINPUT_EVENT_TABLET_PAD_KEY. 3132 * 3133 * Mode switching is controlled by libinput and more than one mode may exist 3134 * on the tablet. This function returns the mode that this event's button, 3135 * ring or strip is logically in. If the button is a mode toggle button 3136 * and the button event caused a new mode to be toggled, the mode returned 3137 * is the new mode the button is in. 3138 * 3139 * Note that the returned mode is the mode valid as of the time of the 3140 * event. The returned mode may thus be different to the mode returned by 3141 * libinput_tablet_pad_mode_group_get_mode(). See 3142 * libinput_tablet_pad_mode_group_get_mode() for details. 3143 * 3144 * @param event The libinput tablet pad event 3145 * @return the 0-indexed mode of this button, ring or strip at the time of 3146 * the event 3147 * 3148 * @see libinput_tablet_pad_mode_group_get_mode 3149 * 3150 * @since 1.4 3151 */ 3152 unsigned int 3153 libinput_event_tablet_pad_get_mode(struct libinput_event_tablet_pad *event); 3154 3155 /** 3156 * @ingroup event_tablet_pad 3157 * 3158 * Returns the mode group that the button, ring, or strip that triggered 3159 * this event is considered in. The mode is a virtual grouping of 3160 * functionality, usually based on some visual feedback like LEDs on the 3161 * pad. 3162 * 3163 * @note Pad keys are not part of a mode group. It is an application bug to 3164 * call this function for @ref LIBINPUT_EVENT_TABLET_PAD_KEY. 3165 * 3166 * The returned mode group is not refcounted and may become invalid after 3167 * the next call to libinput. Use libinput_tablet_pad_mode_group_ref() and 3168 * libinput_tablet_pad_mode_group_unref() to continue using the handle 3169 * outside of the immediate scope. 3170 * 3171 * @param event The libinput tablet pad event 3172 * @return the mode group of the button, ring or strip that caused this event 3173 * 3174 * @see libinput_device_tablet_pad_get_mode_group 3175 * 3176 * @since 1.4 3177 */ 3178 struct libinput_tablet_pad_mode_group * 3179 libinput_event_tablet_pad_get_mode_group(struct libinput_event_tablet_pad *event); 3180 3181 /** 3182 * @ingroup event_tablet_pad 3183 * 3184 * @note Timestamps may not always increase. See the libinput documentation 3185 * for more details. 3186 * 3187 * @param event The libinput tablet pad event 3188 * @return The event time for this event 3189 * 3190 * @since 1.3 3191 */ 3192 uint32_t 3193 libinput_event_tablet_pad_get_time(struct libinput_event_tablet_pad *event); 3194 3195 /** 3196 * @ingroup event_tablet_pad 3197 * 3198 * @note Timestamps may not always increase. See the libinput documentation 3199 * for more details. 3200 * 3201 * @param event The libinput tablet pad event 3202 * @return The event time for this event in microseconds 3203 * 3204 * @since 1.3 3205 */ 3206 uint64_t 3207 libinput_event_tablet_pad_get_time_usec(struct libinput_event_tablet_pad *event); 3208 3209 /** 3210 * @defgroup event_switch Switch events 3211 * 3212 * Events that come from switch devices. 3213 */ 3214 3215 /** 3216 * @ingroup event_switch 3217 * 3218 * Return the switch that triggered this event. 3219 * For pointer events that are not of type @ref 3220 * LIBINPUT_EVENT_SWITCH_TOGGLE, this function returns 0. 3221 * 3222 * @note It is an application bug to call this function for events other than 3223 * @ref LIBINPUT_EVENT_SWITCH_TOGGLE. 3224 * 3225 * @param event The libinput switch event 3226 * @return The switch triggering this event 3227 * 3228 * @since 1.7 3229 */ 3230 enum libinput_switch 3231 libinput_event_switch_get_switch(struct libinput_event_switch *event); 3232 3233 /** 3234 * @ingroup event_switch 3235 * 3236 * Return the switch state that triggered this event. 3237 * For switch events that are not of type @ref 3238 * LIBINPUT_EVENT_SWITCH_TOGGLE, this function returns 0. 3239 * 3240 * @note It is an application bug to call this function for events other than 3241 * @ref LIBINPUT_EVENT_SWITCH_TOGGLE. 3242 * 3243 * @param event The libinput switch event 3244 * @return The switch state triggering this event 3245 * 3246 * @since 1.7 3247 */ 3248 enum libinput_switch_state 3249 libinput_event_switch_get_switch_state(struct libinput_event_switch *event); 3250 3251 /** 3252 * @ingroup event_switch 3253 * 3254 * @return The generic libinput_event of this event 3255 * 3256 * @since 1.7 3257 */ 3258 struct libinput_event * 3259 libinput_event_switch_get_base_event(struct libinput_event_switch *event); 3260 3261 /** 3262 * @ingroup event_switch 3263 * 3264 * @note Timestamps may not always increase. See the libinput documentation 3265 * for more details. 3266 * 3267 * @param event The libinput switch event 3268 * @return The event time for this event 3269 * 3270 * @since 1.7 3271 */ 3272 uint32_t 3273 libinput_event_switch_get_time(struct libinput_event_switch *event); 3274 3275 /** 3276 * @ingroup event_switch 3277 * 3278 * @note Timestamps may not always increase. See the libinput documentation 3279 * for more details. 3280 * 3281 * @param event The libinput switch event 3282 * @return The event time for this event in microseconds 3283 * 3284 * @since 1.7 3285 */ 3286 uint64_t 3287 libinput_event_switch_get_time_usec(struct libinput_event_switch *event); 3288 3289 /** 3290 * @defgroup base Initialization and manipulation of libinput contexts 3291 */ 3292 3293 /** 3294 * @ingroup base 3295 * @struct libinput_interface 3296 * 3297 * libinput does not open file descriptors to devices directly, instead 3298 * open_restricted() and close_restricted() are called for each path that 3299 * must be opened. 3300 * 3301 * @see libinput_udev_create_context 3302 * @see libinput_path_create_context 3303 */ 3304 struct libinput_interface { 3305 /** 3306 * Open the device at the given path with the flags provided and 3307 * return the fd. 3308 * 3309 * @param path The device path to open 3310 * @param flags Flags as defined by open(2) 3311 * @param user_data The user_data provided in 3312 * libinput_udev_create_context() 3313 * 3314 * @return The file descriptor, or a negative errno on failure. 3315 */ 3316 int (*open_restricted)(const char *path, int flags, void *user_data); 3317 /** 3318 * Close the file descriptor. 3319 * 3320 * @param fd The file descriptor to close 3321 * @param user_data The user_data provided in 3322 * libinput_udev_create_context() 3323 */ 3324 void (*close_restricted)(int fd, void *user_data); 3325 }; 3326 3327 /** 3328 * @ingroup base 3329 * 3330 * Create a new libinput context from udev. This context is inactive until 3331 * assigned a seat ID with libinput_udev_assign_seat(). 3332 * 3333 * @param interface The callback interface 3334 * @param user_data Caller-specific data passed to the various callback 3335 * interfaces. 3336 * @param udev An already initialized udev context 3337 * 3338 * @return An initialized, but inactive libinput context or NULL on error 3339 */ 3340 struct libinput * 3341 libinput_udev_create_context(const struct libinput_interface *interface, 3342 void *user_data, 3343 struct udev *udev); 3344 3345 /** 3346 * @ingroup base 3347 * 3348 * Assign a seat to this libinput context. New devices or the removal of 3349 * existing devices will appear as events during libinput_dispatch(). 3350 * 3351 * libinput_udev_assign_seat() succeeds even if no input devices are currently 3352 * available on this seat, or if devices are available but fail to open in 3353 * @ref libinput_interface::open_restricted. Devices that do not have the 3354 * minimum capabilities to be recognized as pointer, keyboard or touch 3355 * device are ignored. Such devices and those that failed to open 3356 * ignored until the next call to libinput_resume(). 3357 * 3358 * This function may only be called once per context. 3359 * 3360 * @param libinput A libinput context initialized with 3361 * libinput_udev_create_context() 3362 * @param seat_id A seat identifier. This string must not be NULL. 3363 * 3364 * @return 0 on success or -1 on failure. 3365 */ 3366 int 3367 libinput_udev_assign_seat(struct libinput *libinput, 3368 const char *seat_id); 3369 3370 /** 3371 * @ingroup base 3372 * 3373 * Create a new libinput context that requires the caller to manually add or 3374 * remove devices with libinput_path_add_device() and 3375 * libinput_path_remove_device(). 3376 * 3377 * The context is fully initialized but will not generate events until at 3378 * least one device has been added. 3379 * 3380 * The reference count of the context is initialized to 1. See @ref 3381 * libinput_unref. 3382 * 3383 * @param interface The callback interface 3384 * @param user_data Caller-specific data passed to the various callback 3385 * interfaces. 3386 * 3387 * @return An initialized, empty libinput context. 3388 */ 3389 struct libinput * 3390 libinput_path_create_context(const struct libinput_interface *interface, 3391 void *user_data); 3392 3393 /** 3394 * @ingroup base 3395 * 3396 * Add a device to a libinput context initialized with 3397 * libinput_path_create_context(). If successful, the device will be 3398 * added to the internal list and re-opened on libinput_resume(). The device 3399 * can be removed with libinput_path_remove_device(). 3400 * 3401 * If the device was successfully initialized, it is returned in the device 3402 * argument. The lifetime of the returned device pointer is limited until 3403 * the next libinput_dispatch(), use libinput_device_ref() to keep a permanent 3404 * reference. 3405 * 3406 * @param libinput A previously initialized libinput context 3407 * @param path Path to an input device 3408 * @return The newly initiated device on success, or NULL on failure. 3409 * 3410 * @note It is an application bug to call this function on a libinput 3411 * context initialized with libinput_udev_create_context(). 3412 */ 3413 struct libinput_device * 3414 libinput_path_add_device(struct libinput *libinput, 3415 const char *path); 3416 3417 /** 3418 * @ingroup base 3419 * 3420 * Remove a device from a libinput context initialized with 3421 * libinput_path_create_context() or added to such a context with 3422 * libinput_path_add_device(). 3423 * 3424 * Events already processed from this input device are kept in the queue, 3425 * the @ref LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for 3426 * this device. 3427 * 3428 * If no matching device exists, this function does nothing. 3429 * 3430 * @param device A libinput device 3431 * 3432 * @note It is an application bug to call this function on a libinput 3433 * context initialized with libinput_udev_create_context(). 3434 */ 3435 void 3436 libinput_path_remove_device(struct libinput_device *device); 3437 3438 /** 3439 * @ingroup base 3440 * 3441 * libinput keeps a single file descriptor for all events. Call into 3442 * libinput_dispatch() if any events become available on this fd. 3443 * 3444 * @return The file descriptor used to notify of pending events. 3445 */ 3446 int 3447 libinput_get_fd(struct libinput *libinput); 3448 3449 /** 3450 * @ingroup base 3451 * 3452 * Main event dispatchment function. Reads events of the file descriptors 3453 * and processes them internally. Use libinput_get_event() to retrieve the 3454 * events. 3455 * 3456 * Dispatching does not necessarily queue libinput events. This function 3457 * should be called immediately once data is available on the file 3458 * descriptor returned by libinput_get_fd(). libinput has a number of 3459 * timing-sensitive features (e.g. tap-to-click), any delay in calling 3460 * libinput_dispatch() may prevent these features from working correctly. 3461 * 3462 * @param libinput A previously initialized libinput context 3463 * 3464 * @return 0 on success, or a negative errno on failure 3465 */ 3466 int 3467 libinput_dispatch(struct libinput *libinput); 3468 3469 /** 3470 * @ingroup base 3471 * 3472 * Retrieve the next event from libinput's internal event queue. 3473 * 3474 * After handling the retrieved event, the caller must destroy it using 3475 * libinput_event_destroy(). 3476 * 3477 * @param libinput A previously initialized libinput context 3478 * @return The next available event, or NULL if no event is available. 3479 */ 3480 struct libinput_event * 3481 libinput_get_event(struct libinput *libinput); 3482 3483 /** 3484 * @ingroup base 3485 * 3486 * Return the type of the next event in the internal queue. This function 3487 * does not pop the event off the queue and the next call to 3488 * libinput_get_event() returns that event. 3489 * 3490 * @param libinput A previously initialized libinput context 3491 * @return The event type of the next available event or @ref 3492 * LIBINPUT_EVENT_NONE if no event is available. 3493 */ 3494 enum libinput_event_type 3495 libinput_next_event_type(struct libinput *libinput); 3496 3497 /** 3498 * @ingroup base 3499 * 3500 * Set caller-specific data associated with this context. libinput does 3501 * not manage, look at, or modify this data. The caller must ensure the 3502 * data is valid. 3503 * 3504 * @param libinput A previously initialized libinput context 3505 * @param user_data Caller-specific data passed to the various callback 3506 * interfaces. 3507 */ 3508 void 3509 libinput_set_user_data(struct libinput *libinput, 3510 void *user_data); 3511 3512 /** 3513 * @ingroup base 3514 * 3515 * Get the caller-specific data associated with this context, if any. 3516 * 3517 * @param libinput A previously initialized libinput context 3518 * @return The caller-specific data previously assigned in 3519 * libinput_set_user_data(), libinput_path_create_context() or 3520 * libinput_udev_create_context(). 3521 */ 3522 void * 3523 libinput_get_user_data(struct libinput *libinput); 3524 3525 /** 3526 * @ingroup base 3527 * 3528 * Resume a suspended libinput context. This re-enables device 3529 * monitoring and adds existing devices. 3530 * 3531 * @param libinput A previously initialized libinput context 3532 * @see libinput_suspend 3533 * 3534 * @return 0 on success or -1 on failure 3535 */ 3536 int 3537 libinput_resume(struct libinput *libinput); 3538 3539 /** 3540 * @ingroup base 3541 * 3542 * Suspend monitoring for new devices and close existing devices. 3543 * This all but terminates libinput but does keep the context 3544 * valid to be resumed with libinput_resume(). 3545 * 3546 * @param libinput A previously initialized libinput context 3547 */ 3548 void 3549 libinput_suspend(struct libinput *libinput); 3550 3551 /** 3552 * @ingroup base 3553 * 3554 * Add a reference to the context. A context is destroyed whenever the 3555 * reference count reaches 0. See @ref libinput_unref. 3556 * 3557 * @param libinput A previously initialized valid libinput context 3558 * @return The passed libinput context 3559 */ 3560 struct libinput * 3561 libinput_ref(struct libinput *libinput); 3562 3563 /** 3564 * @ingroup base 3565 * 3566 * Dereference the libinput context. After this, the context may have been 3567 * destroyed, if the last reference was dereferenced. If so, the context is 3568 * invalid and may not be interacted with. 3569 * 3570 * @bug When the refcount reaches zero, libinput_unref() releases resources 3571 * even if a caller still holds refcounted references to related resources 3572 * (e.g. a libinput_device). When libinput_unref() returns 3573 * NULL, the caller must consider any resources related to that context 3574 * invalid. See https://bugs.freedesktop.org/show_bug.cgi?id=91872. 3575 * 3576 * Example code: 3577 * @code 3578 * li = libinput_path_create_context(&interface, NULL); 3579 * device = libinput_path_add_device(li, "/dev/input/event0"); 3580 * // get extra reference to device 3581 * libinput_device_ref(device); 3582 * 3583 * // refcount reaches 0, so *all* resources are cleaned up, 3584 * // including device 3585 * libinput_unref(li); 3586 * 3587 * // INCORRECT: device has been cleaned up and must not be used 3588 * // li = libinput_device_get_context(device); 3589 * @endcode 3590 * 3591 * @param libinput A previously initialized libinput context 3592 * @return NULL if context was destroyed otherwise the passed context 3593 */ 3594 struct libinput * 3595 libinput_unref(struct libinput *libinput); 3596 3597 /** 3598 * @ingroup base 3599 * 3600 * Set the log priority for the libinput context. Messages with priorities 3601 * equal to or higher than the argument will be printed to the context's 3602 * log handler. 3603 * 3604 * The default log priority is @ref LIBINPUT_LOG_PRIORITY_ERROR. 3605 * 3606 * @param libinput A previously initialized libinput context 3607 * @param priority The minimum priority of log messages to print. 3608 * 3609 * @see libinput_log_set_handler 3610 * @see libinput_log_get_priority 3611 */ 3612 void 3613 libinput_log_set_priority(struct libinput *libinput, 3614 enum libinput_log_priority priority); 3615 3616 /** 3617 * @ingroup base 3618 * 3619 * Get the context's log priority. Messages with priorities equal to or 3620 * higher than the argument will be printed to the current log handler. 3621 * 3622 * The default log priority is @ref LIBINPUT_LOG_PRIORITY_ERROR. 3623 * 3624 * @param libinput A previously initialized libinput context 3625 * @return The minimum priority of log messages to print. 3626 * 3627 * @see libinput_log_set_handler 3628 * @see libinput_log_set_priority 3629 */ 3630 enum libinput_log_priority 3631 libinput_log_get_priority(const struct libinput *libinput); 3632 3633 /** 3634 * @ingroup base 3635 * 3636 * Log handler type for custom logging. 3637 * 3638 * @param libinput The libinput context 3639 * @param priority The priority of the current message 3640 * @param format Message format in printf-style 3641 * @param args Message arguments 3642 * 3643 * @see libinput_log_set_priority 3644 * @see libinput_log_get_priority 3645 * @see libinput_log_set_handler 3646 */ 3647 typedef void (*libinput_log_handler)(struct libinput *libinput, 3648 enum libinput_log_priority priority, 3649 const char *format, va_list args) 3650 LIBINPUT_ATTRIBUTE_PRINTF(3, 0); 3651 3652 /** 3653 * @ingroup base 3654 * 3655 * Set the context's log handler. Messages with priorities equal to or 3656 * higher than the context's log priority will be passed to the given 3657 * log handler. 3658 * 3659 * The default log handler prints to stderr. 3660 * 3661 * @param libinput A previously initialized libinput context 3662 * @param log_handler The log handler for library messages. 3663 * 3664 * @see libinput_log_set_priority 3665 * @see libinput_log_get_priority 3666 */ 3667 void 3668 libinput_log_set_handler(struct libinput *libinput, 3669 libinput_log_handler log_handler); 3670 3671 /** 3672 * @defgroup seat Initialization and manipulation of seats 3673 * 3674 * A seat has two identifiers, the physical name and the logical name. A 3675 * device is always assigned to exactly one seat. It may change to a 3676 * different logical seat but it cannot change physical seats. 3677 * 3678 * See the libinput documentation for more information on seats. 3679 */ 3680 3681 /** 3682 * @ingroup seat 3683 * 3684 * Increase the refcount of the seat. A seat will be freed whenever the 3685 * refcount reaches 0. This may happen during libinput_dispatch() if the 3686 * seat was removed from the system. A caller must ensure to reference 3687 * the seat correctly to avoid dangling pointers. 3688 * 3689 * @param seat A previously obtained seat 3690 * @return The passed seat 3691 */ 3692 struct libinput_seat * 3693 libinput_seat_ref(struct libinput_seat *seat); 3694 3695 /** 3696 * @ingroup seat 3697 * 3698 * Decrease the refcount of the seat. A seat will be freed whenever the 3699 * refcount reaches 0. This may happen during libinput_dispatch() if the 3700 * seat was removed from the system. A caller must ensure to reference 3701 * the seat correctly to avoid dangling pointers. 3702 * 3703 * @param seat A previously obtained seat 3704 * @return NULL if seat was destroyed, otherwise the passed seat 3705 */ 3706 struct libinput_seat * 3707 libinput_seat_unref(struct libinput_seat *seat); 3708 3709 /** 3710 * @ingroup seat 3711 * 3712 * Set caller-specific data associated with this seat. libinput does 3713 * not manage, look at, or modify this data. The caller must ensure the 3714 * data is valid. 3715 * 3716 * @param seat A previously obtained seat 3717 * @param user_data Caller-specific data pointer 3718 * @see libinput_seat_get_user_data 3719 */ 3720 void 3721 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data); 3722 3723 /** 3724 * @ingroup seat 3725 * 3726 * Get the caller-specific data associated with this seat, if any. 3727 * 3728 * @param seat A previously obtained seat 3729 * @return Caller-specific data pointer or NULL if none was set 3730 * @see libinput_seat_set_user_data 3731 */ 3732 void * 3733 libinput_seat_get_user_data(struct libinput_seat *seat); 3734 3735 /** 3736 * @ingroup seat 3737 * 3738 * Get the libinput context from the seat. 3739 * 3740 * @param seat A previously obtained seat 3741 * @return The libinput context for this seat. 3742 */ 3743 struct libinput * 3744 libinput_seat_get_context(struct libinput_seat *seat); 3745 3746 /** 3747 * @ingroup seat 3748 * 3749 * Return the physical name of the seat. For libinput contexts created from 3750 * udev, this is always the same value as passed into 3751 * libinput_udev_assign_seat() and all seats from that context will have 3752 * the same physical name. 3753 * 3754 * The physical name of the seat is one that is usually set by the system or 3755 * lower levels of the stack. In most cases, this is the base filter for 3756 * devices - devices assigned to seats outside the current seat will not 3757 * be available to the caller. 3758 * 3759 * @param seat A previously obtained seat 3760 * @return The physical name of this seat 3761 */ 3762 const char * 3763 libinput_seat_get_physical_name(struct libinput_seat *seat); 3764 3765 /** 3766 * @ingroup seat 3767 * 3768 * Return the logical name of the seat. This is an identifier to group sets 3769 * of devices within the compositor. 3770 * 3771 * @param seat A previously obtained seat 3772 * @return The logical name of this seat 3773 */ 3774 const char * 3775 libinput_seat_get_logical_name(struct libinput_seat *seat); 3776 3777 /** 3778 * @defgroup device Initialization and manipulation of input devices 3779 */ 3780 3781 /** 3782 * @ingroup device 3783 * 3784 * Increase the refcount of the input device. An input device will be freed 3785 * whenever the refcount reaches 0. This may happen during 3786 * libinput_dispatch() if the device was removed from the system. A caller 3787 * must ensure to reference the device correctly to avoid dangling pointers. 3788 * 3789 * @param device A previously obtained device 3790 * @return The passed device 3791 */ 3792 struct libinput_device * 3793 libinput_device_ref(struct libinput_device *device); 3794 3795 /** 3796 * @ingroup device 3797 * 3798 * Decrease the refcount of the input device. An input device will be freed 3799 * whenever the refcount reaches 0. This may happen during libinput_dispatch 3800 * if the device was removed from the system. A caller must ensure to 3801 * reference the device correctly to avoid dangling pointers. 3802 * 3803 * @param device A previously obtained device 3804 * @return NULL if the device was destroyed, otherwise the passed device 3805 */ 3806 struct libinput_device * 3807 libinput_device_unref(struct libinput_device *device); 3808 3809 /** 3810 * @ingroup device 3811 * 3812 * Set caller-specific data associated with this input device. libinput does 3813 * not manage, look at, or modify this data. The caller must ensure the 3814 * data is valid. 3815 * 3816 * @param device A previously obtained device 3817 * @param user_data Caller-specific data pointer 3818 * @see libinput_device_get_user_data 3819 */ 3820 void 3821 libinput_device_set_user_data(struct libinput_device *device, void *user_data); 3822 3823 /** 3824 * @ingroup device 3825 * 3826 * Get the caller-specific data associated with this input device, if any. 3827 * 3828 * @param device A previously obtained device 3829 * @return Caller-specific data pointer or NULL if none was set 3830 * @see libinput_device_set_user_data 3831 */ 3832 void * 3833 libinput_device_get_user_data(struct libinput_device *device); 3834 3835 /** 3836 * @ingroup device 3837 * 3838 * Get the libinput context from the device. 3839 * 3840 * @param device A previously obtained device 3841 * @return The libinput context for this device. 3842 */ 3843 struct libinput * 3844 libinput_device_get_context(struct libinput_device *device); 3845 3846 /** 3847 * @ingroup device 3848 * 3849 * Get the device group this device is assigned to. Some physical 3850 * devices like graphics tablets are represented by multiple kernel 3851 * devices and thus by multiple struct @ref libinput_device. 3852 * 3853 * libinput assigns these devices to the same @ref libinput_device_group 3854 * allowing the caller to identify such devices and adjust configuration 3855 * settings accordingly. For example, setting a tablet to left-handed often 3856 * means turning it upside down. A touch device on the same tablet would 3857 * need to be turned upside down too to work correctly. 3858 * 3859 * All devices are part of a device group though for most devices the group 3860 * will be a singleton. A device is assigned to a device group on @ref 3861 * LIBINPUT_EVENT_DEVICE_ADDED and removed from that group on @ref 3862 * LIBINPUT_EVENT_DEVICE_REMOVED. It is up to the caller to track how many 3863 * devices are in each device group. 3864 * 3865 * @dot 3866 * digraph groups_libinput { 3867 * rankdir="TB"; 3868 * node [ 3869 * shape="box"; 3870 * ] 3871 * 3872 * mouse [ label="mouse"; URL="\ref libinput_device"]; 3873 * kbd [ label="keyboard"; URL="\ref libinput_device"]; 3874 * 3875 * pen [ label="tablet pen"; URL="\ref libinput_device"]; 3876 * touch [ label="tablet touch"; URL="\ref libinput_device"]; 3877 * pad [ label="tablet pad"; URL="\ref libinput_device"]; 3878 * 3879 * group1 [ label="group 1"; URL="\ref libinput_device_group"]; 3880 * group2 [ label="group 2"; URL="\ref libinput_device_group"]; 3881 * group3 [ label="group 3"; URL="\ref libinput_device_group"]; 3882 * 3883 * mouse -> group1 3884 * kbd -> group2 3885 * 3886 * pen -> group3; 3887 * touch -> group3; 3888 * pad -> group3; 3889 * } 3890 * @enddot 3891 * 3892 * Device groups do not get re-used once the last device in the group was 3893 * removed, i.e. unplugging and re-plugging a physical device with grouped 3894 * devices will return a different device group after every unplug. 3895 * 3896 * The returned device group is not refcounted and may become invalid after 3897 * the next call to libinput. Use libinput_device_group_ref() and 3898 * libinput_device_group_unref() to continue using the handle outside of the 3899 * immediate scope. 3900 * 3901 * Device groups are assigned based on the <b>LIBINPUT_DEVICE_GROUP</b> udev 3902 * property, see the libinput documentation for more details. 3903 * 3904 * @return The device group this device belongs to 3905 */ 3906 struct libinput_device_group * 3907 libinput_device_get_device_group(struct libinput_device *device); 3908 3909 /** 3910 * @ingroup device 3911 * 3912 * Get the system name of the device. 3913 * 3914 * To get the descriptive device name, use libinput_device_get_name(). 3915 * 3916 * @param device A previously obtained device 3917 * @return System name of the device 3918 * 3919 */ 3920 const char * 3921 libinput_device_get_sysname(struct libinput_device *device); 3922 3923 /** 3924 * @ingroup device 3925 * 3926 * The descriptive device name as advertised by the kernel and/or the 3927 * hardware itself. To get the sysname for this device, use 3928 * libinput_device_get_sysname(). 3929 * 3930 * The lifetime of the returned string is tied to the struct 3931 * libinput_device. The string may be the empty string but is never NULL. 3932 * 3933 * @param device A previously obtained device 3934 * @return The device name 3935 */ 3936 const char * 3937 libinput_device_get_name(struct libinput_device *device); 3938 3939 /** 3940 * @ingroup device 3941 * 3942 * Get the product ID for this device. 3943 * 3944 * @param device A previously obtained device 3945 * @return The product ID of this device 3946 */ 3947 unsigned int 3948 libinput_device_get_id_product(struct libinput_device *device); 3949 3950 /** 3951 * @ingroup device 3952 * 3953 * Get the vendor ID for this device. 3954 * 3955 * @param device A previously obtained device 3956 * @return The vendor ID of this device 3957 */ 3958 unsigned int 3959 libinput_device_get_id_vendor(struct libinput_device *device); 3960 3961 /** 3962 * @ingroup device 3963 * 3964 * A device may be mapped to a single output, or all available outputs. If a 3965 * device is mapped to a single output only, a relative device may not move 3966 * beyond the boundaries of this output. An absolute device has its input 3967 * coordinates mapped to the extents of this output. 3968 * 3969 * @note <b>Use of this function is discouraged.</b> Its return value is not 3970 * precisely defined and may not be understood by the caller or may be 3971 * insufficient to map the device. Instead, the system configuration could 3972 * set a udev property the caller understands and interprets correctly. The 3973 * caller could then obtain device with libinput_device_get_udev_device() 3974 * and query it for this property. For more complex cases, the caller 3975 * must implement monitor-to-device association heuristics. 3976 * 3977 * @return The name of the output this device is mapped to, or NULL if no 3978 * output is set 3979 */ 3980 const char * 3981 libinput_device_get_output_name(struct libinput_device *device); 3982 3983 /** 3984 * @ingroup device 3985 * 3986 * Get the seat associated with this input device. 3987 * 3988 * A seat can be uniquely identified by the physical and logical seat name. 3989 * There will ever be only one seat instance with a given physical and logical 3990 * seat name pair at any given time, but if no external reference is kept, it 3991 * may be destroyed if no device belonging to it is left. 3992 * 3993 * The returned seat is not refcounted and may become invalid after 3994 * the next call to libinput. Use libinput_seat_ref() and 3995 * libinput_seat_unref() to continue using the handle outside of the 3996 * immediate scope. 3997 * 3998 * See the libinput documentation for more information on seats. 3999 * 4000 * @param device A previously obtained device 4001 * @return The seat this input device belongs to 4002 */ 4003 struct libinput_seat * 4004 libinput_device_get_seat(struct libinput_device *device); 4005 4006 /** 4007 * @ingroup device 4008 * 4009 * Change the logical seat associated with this device by removing the 4010 * device and adding it to the new seat. 4011 * 4012 * This command is identical to physically unplugging the device, then 4013 * re-plugging it as a member of the new seat. libinput will generate a 4014 * @ref LIBINPUT_EVENT_DEVICE_REMOVED event and this @ref libinput_device is 4015 * considered removed from the context; it will not generate further events 4016 * and will be freed when the refcount reaches zero. 4017 * A @ref LIBINPUT_EVENT_DEVICE_ADDED event is generated with a new @ref 4018 * libinput_device handle. It is the caller's responsibility to update 4019 * references to the new device accordingly. 4020 * 4021 * If the logical seat name already exists in the device's physical seat, 4022 * the device is added to this seat. Otherwise, a new seat is created. 4023 * 4024 * @note This change applies to this device until removal or @ref 4025 * libinput_suspend(), whichever happens earlier. 4026 * 4027 * @param device A previously obtained device 4028 * @param name The new logical seat name 4029 * @return 0 on success, non-zero on error 4030 */ 4031 int 4032 libinput_device_set_seat_logical_name(struct libinput_device *device, 4033 const char *name); 4034 4035 /** 4036 * @ingroup device 4037 * 4038 * Return a udev handle to the device that is this libinput device, if any. 4039 * The returned handle has a refcount of at least 1, the caller must call 4040 * <i>udev_device_unref()</i> once to release the associated resources. 4041 * See the [libudev documentation] 4042 * (http://www.freedesktop.org/software/systemd/libudev/) for details. 4043 * 4044 * Some devices may not have a udev device, or the udev device may be 4045 * unobtainable. This function returns NULL if no udev device was available. 4046 * 4047 * Calling this function multiple times for the same device may not 4048 * return the same udev handle each time. 4049 * 4050 * @param device A previously obtained device 4051 * @return A udev handle to the device with a refcount of >= 1 or NULL. 4052 * @retval NULL This device is not represented by a udev device 4053 */ 4054 struct udev_device * 4055 libinput_device_get_udev_device(struct libinput_device *device); 4056 4057 /** 4058 * @ingroup device 4059 * 4060 * Update the LEDs on the device, if any. If the device does not have 4061 * LEDs, or does not have one or more of the LEDs given in the mask, this 4062 * function does nothing. 4063 * 4064 * @param device A previously obtained device 4065 * @param leds A mask of the LEDs to set, or unset. 4066 */ 4067 void 4068 libinput_device_led_update(struct libinput_device *device, 4069 enum libinput_led leds); 4070 4071 /** 4072 * @ingroup device 4073 * 4074 * Check if the given device has the specified capability 4075 * 4076 * @return Non-zero if the given device has the capability or zero otherwise 4077 */ 4078 int 4079 libinput_device_has_capability(struct libinput_device *device, 4080 enum libinput_device_capability capability); 4081 4082 /** 4083 * @ingroup device 4084 * 4085 * Get the physical size of a device in mm, where meaningful. This function 4086 * only succeeds on devices with the required data, i.e. tablets, touchpads 4087 * and touchscreens. 4088 * 4089 * If this function returns nonzero, width and height are unmodified. 4090 * 4091 * @param device The device 4092 * @param width Set to the width of the device 4093 * @param height Set to the height of the device 4094 * @return 0 on success, or nonzero otherwise 4095 */ 4096 int 4097 libinput_device_get_size(struct libinput_device *device, 4098 double *width, 4099 double *height); 4100 4101 /** 4102 * @ingroup device 4103 * 4104 * Check if a @ref LIBINPUT_DEVICE_CAP_POINTER device has a button with the 4105 * given code (see linux/input-event-codes.h). 4106 * 4107 * @param device A current input device 4108 * @param code Button code to check for, e.g. <i>BTN_LEFT</i> 4109 * 4110 * @return 1 if the device supports this button code, 0 if it does not, -1 4111 * on error. 4112 */ 4113 int 4114 libinput_device_pointer_has_button(struct libinput_device *device, uint32_t code); 4115 4116 /** 4117 * @ingroup device 4118 * 4119 * Check if a @ref LIBINPUT_DEVICE_CAP_KEYBOARD device has a key with the 4120 * given code (see linux/input-event-codes.h). 4121 * 4122 * @param device A current input device 4123 * @param code Key code to check for, e.g. <i>KEY_ESC</i> 4124 * 4125 * @return 1 if the device supports this key code, 0 if it does not, -1 4126 * on error. 4127 */ 4128 int 4129 libinput_device_keyboard_has_key(struct libinput_device *device, 4130 uint32_t code); 4131 4132 /** 4133 * @ingroup device 4134 * 4135 * Check how many touches a @ref LIBINPUT_DEVICE_CAP_TOUCH device supports 4136 * simultaneously. 4137 * 4138 * @param device A current input device 4139 * 4140 * @return The number of simultaneous touches or 0 if unknown, -1 4141 * on error. 4142 * 4143 * @since 1.11 4144 */ 4145 int 4146 libinput_device_touch_get_touch_count(struct libinput_device *device); 4147 4148 /** 4149 * @ingroup device 4150 * 4151 * Check if a @ref LIBINPUT_DEVICE_CAP_SWITCH device has a switch of the 4152 * given type. 4153 * 4154 * @param device A current input device 4155 * @param sw Switch to check for 4156 * 4157 * @return 1 if the device supports this switch, 0 if it does not, -1 4158 * on error. 4159 * 4160 * @since 1.9 4161 */ 4162 int 4163 libinput_device_switch_has_switch(struct libinput_device *device, 4164 enum libinput_switch sw); 4165 4166 /** 4167 * @ingroup device 4168 * 4169 * Return the number of buttons on a device with the 4170 * @ref LIBINPUT_DEVICE_CAP_TABLET_PAD capability. 4171 * Buttons on a pad device are numbered sequentially, see the 4172 * libinput documentation for details. 4173 * 4174 * @param device A current input device 4175 * 4176 * @return The number of buttons supported by the device. 4177 * 4178 * @since 1.3 4179 */ 4180 int 4181 libinput_device_tablet_pad_get_num_buttons(struct libinput_device *device); 4182 4183 /** 4184 * @ingroup device 4185 * 4186 * Return the number of rings a device with the @ref 4187 * LIBINPUT_DEVICE_CAP_TABLET_PAD capability provides. 4188 * 4189 * @param device A current input device 4190 * 4191 * @return The number of rings or 0 if the device has no rings. 4192 * 4193 * @see libinput_event_tablet_pad_get_ring_number 4194 * 4195 * @since 1.3 4196 */ 4197 int 4198 libinput_device_tablet_pad_get_num_rings(struct libinput_device *device); 4199 4200 /** 4201 * @ingroup device 4202 * 4203 * Return the number of strips a device with the @ref 4204 * LIBINPUT_DEVICE_CAP_TABLET_PAD capability provides. 4205 * 4206 * @param device A current input device 4207 * 4208 * @return The number of strips or 0 if the device has no strips. 4209 * 4210 * @see libinput_event_tablet_pad_get_strip_number 4211 * 4212 * @since 1.3 4213 */ 4214 int 4215 libinput_device_tablet_pad_get_num_strips(struct libinput_device *device); 4216 4217 /** 4218 * @ingroup device 4219 * 4220 * Check if a @ref LIBINPUT_DEVICE_CAP_TABLET_PAD device has a key with the 4221 * given code (see linux/input-event-codes.h). 4222 * 4223 * @param device A current input device 4224 * @param code Key code to check for, e.g. <i>KEY_ESC</i> 4225 * 4226 * @return 1 if the device supports this key code, 0 if it does not, -1 4227 * on error. 4228 * 4229 * @since 1.15 4230 */ 4231 int 4232 libinput_device_tablet_pad_has_key(struct libinput_device *device, 4233 uint32_t code); 4234 4235 /** 4236 * @ingroup device 4237 * 4238 * Increase the refcount of the device group. A device group will be freed 4239 * whenever the refcount reaches 0. This may happen during 4240 * libinput_dispatch() if all devices of this group were removed from the 4241 * system. A caller must ensure to reference the device group correctly to 4242 * avoid dangling pointers. 4243 * 4244 * @param group A previously obtained device group 4245 * @return The passed device group 4246 */ 4247 struct libinput_device_group * 4248 libinput_device_group_ref(struct libinput_device_group *group); 4249 4250 /** 4251 * @ingroup device 4252 * 4253 * Decrease the refcount of the device group. A device group will be freed 4254 * whenever the refcount reaches 0. This may happen during 4255 * libinput_dispatch() if all devices of this group were removed from the 4256 * system. A caller must ensure to reference the device group correctly to 4257 * avoid dangling pointers. 4258 * 4259 * @param group A previously obtained device group 4260 * @return NULL if the device group was destroyed, otherwise the passed 4261 * device group 4262 */ 4263 struct libinput_device_group * 4264 libinput_device_group_unref(struct libinput_device_group *group); 4265 4266 /** 4267 * @ingroup device 4268 * 4269 * Set caller-specific data associated with this device group. libinput does 4270 * not manage, look at, or modify this data. The caller must ensure the 4271 * data is valid. 4272 * 4273 * @param group A previously obtained device group 4274 * @param user_data Caller-specific data pointer 4275 * @see libinput_device_group_get_user_data 4276 */ 4277 void 4278 libinput_device_group_set_user_data(struct libinput_device_group *group, 4279 void *user_data); 4280 4281 /** 4282 * @ingroup device 4283 * 4284 * Get the caller-specific data associated with this input device group, if 4285 * any. 4286 * 4287 * @param group A previously obtained group 4288 * @return Caller-specific data pointer or NULL if none was set 4289 * @see libinput_device_group_set_user_data 4290 */ 4291 void * 4292 libinput_device_group_get_user_data(struct libinput_device_group *group); 4293 4294 /** 4295 * @defgroup config Device configuration 4296 * 4297 * Enable, disable, change and/or check for device-specific features. For 4298 * all features, libinput assigns a default based on the hardware 4299 * configuration. This default can be obtained with the respective 4300 * get_default call. 4301 * 4302 * Configuration options are device dependent and not all options are 4303 * supported on all devices. For all configuration options, libinput 4304 * provides a call to check if a configuration option is available on a 4305 * device (e.g. libinput_device_config_calibration_has_matrix()) 4306 * 4307 * Some configuration option may be dependent on or mutually exclusive with 4308 * with other options. The behavior in those cases is 4309 * implementation-dependent, the caller must ensure that the options are set 4310 * in the right order. 4311 * 4312 * Below is a general grouping of configuration options according to device 4313 * type. Note that this is a guide only and not indicative of any specific 4314 * device. 4315 * - Touchpad: 4316 * - libinput_device_config_tap_set_enabled() 4317 * - libinput_device_config_tap_set_drag_enabled() 4318 * - libinput_device_config_tap_set_drag_lock_enabled() 4319 * - libinput_device_config_click_set_method() 4320 * - libinput_device_config_scroll_set_method() 4321 * - libinput_device_config_dwt_set_enabled() 4322 * - Touchscreens: 4323 * - libinput_device_config_calibration_set_matrix() 4324 * - Pointer devices (mice, trackballs, touchpads): 4325 * - libinput_device_config_accel_set_speed() 4326 * - libinput_device_config_accel_set_profile() 4327 * - libinput_device_config_scroll_set_natural_scroll_enabled() 4328 * - libinput_device_config_left_handed_set() 4329 * - libinput_device_config_middle_emulation_set_enabled() 4330 * - libinput_device_config_rotation_set_angle() 4331 * - All devices: 4332 * - libinput_device_config_send_events_set_mode() 4333 */ 4334 4335 /** 4336 * @ingroup config 4337 * 4338 * Status codes returned when applying configuration settings. 4339 */ 4340 enum libinput_config_status { 4341 LIBINPUT_CONFIG_STATUS_SUCCESS = 0, /**< Config applied successfully */ 4342 LIBINPUT_CONFIG_STATUS_UNSUPPORTED, /**< Configuration not available on 4343 this device */ 4344 LIBINPUT_CONFIG_STATUS_INVALID, /**< Invalid parameter range */ 4345 }; 4346 4347 /** 4348 * @ingroup config 4349 * 4350 * Return a string describing the error. 4351 * 4352 * @param status The status to translate to a string 4353 * @return A human-readable string representing the error or NULL for an 4354 * invalid status. 4355 */ 4356 const char * 4357 libinput_config_status_to_str(enum libinput_config_status status); 4358 4359 /** 4360 * @ingroup config 4361 */ 4362 enum libinput_config_tap_state { 4363 LIBINPUT_CONFIG_TAP_DISABLED, /**< Tapping is to be disabled, or is 4364 currently disabled */ 4365 LIBINPUT_CONFIG_TAP_ENABLED, /**< Tapping is to be enabled, or is 4366 currently enabled */ 4367 }; 4368 4369 /** 4370 * @ingroup config 4371 * 4372 * Check if the device supports tap-to-click and how many fingers can be 4373 * used for tapping. See 4374 * libinput_device_config_tap_set_enabled() for more information. 4375 * 4376 * @param device The device to configure 4377 * @return The number of fingers that can generate a tap event, or 0 if the 4378 * device does not support tapping. 4379 * 4380 * @see libinput_device_config_tap_set_enabled 4381 * @see libinput_device_config_tap_get_enabled 4382 * @see libinput_device_config_tap_get_default_enabled 4383 */ 4384 int 4385 libinput_device_config_tap_get_finger_count(struct libinput_device *device); 4386 4387 /** 4388 * @ingroup config 4389 * 4390 * Enable or disable tap-to-click on this device, with a default mapping of 4391 * 1, 2, 3 finger tap mapping to left, right, middle click, respectively. 4392 * Tapping is limited by the number of simultaneous touches 4393 * supported by the device, see 4394 * libinput_device_config_tap_get_finger_count(). 4395 * 4396 * @param device The device to configure 4397 * @param enable @ref LIBINPUT_CONFIG_TAP_ENABLED to enable tapping or @ref 4398 * LIBINPUT_CONFIG_TAP_DISABLED to disable tapping 4399 * 4400 * @return A config status code. Disabling tapping on a device that does not 4401 * support tapping always succeeds. 4402 * 4403 * @see libinput_device_config_tap_get_finger_count 4404 * @see libinput_device_config_tap_get_enabled 4405 * @see libinput_device_config_tap_get_default_enabled 4406 */ 4407 enum libinput_config_status 4408 libinput_device_config_tap_set_enabled(struct libinput_device *device, 4409 enum libinput_config_tap_state enable); 4410 4411 /** 4412 * @ingroup config 4413 * 4414 * Check if tap-to-click is enabled on this device. If the device does not 4415 * support tapping, this function always returns @ref 4416 * LIBINPUT_CONFIG_TAP_DISABLED. 4417 * 4418 * @param device The device to configure 4419 * 4420 * @retval LIBINPUT_CONFIG_TAP_ENABLED If tapping is currently enabled 4421 * @retval LIBINPUT_CONFIG_TAP_DISABLED If tapping is currently disabled 4422 * 4423 * @see libinput_device_config_tap_get_finger_count 4424 * @see libinput_device_config_tap_set_enabled 4425 * @see libinput_device_config_tap_get_default_enabled 4426 */ 4427 enum libinput_config_tap_state 4428 libinput_device_config_tap_get_enabled(struct libinput_device *device); 4429 4430 /** 4431 * @ingroup config 4432 * 4433 * Return the default setting for whether tap-to-click is enabled on this 4434 * device. 4435 * 4436 * @param device The device to configure 4437 * @retval LIBINPUT_CONFIG_TAP_ENABLED If tapping is enabled by default 4438 * @retval LIBINPUT_CONFIG_TAP_DISABLED If tapping Is disabled by default 4439 * 4440 * @see libinput_device_config_tap_get_finger_count 4441 * @see libinput_device_config_tap_set_enabled 4442 * @see libinput_device_config_tap_get_enabled 4443 */ 4444 enum libinput_config_tap_state 4445 libinput_device_config_tap_get_default_enabled(struct libinput_device *device); 4446 4447 /** 4448 * @ingroup config 4449 * 4450 * @since 1.5 4451 */ 4452 enum libinput_config_tap_button_map { 4453 /** 1/2/3 finger tap maps to left/right/middle */ 4454 LIBINPUT_CONFIG_TAP_MAP_LRM, 4455 /** 1/2/3 finger tap maps to left/middle/right*/ 4456 LIBINPUT_CONFIG_TAP_MAP_LMR, 4457 }; 4458 4459 /** 4460 * @ingroup config 4461 * 4462 * Set the finger number to button number mapping for tap-to-click. The 4463 * default mapping on most devices is to have a 1, 2 and 3 finger tap to map 4464 * to the left, right and middle button, respectively. 4465 * A device may permit changing the button mapping but disallow specific 4466 * maps. In this case @ref LIBINPUT_CONFIG_STATUS_UNSUPPORTED is returned, 4467 * the caller is expected to handle this case correctly. 4468 * 4469 * Changing the button mapping may not take effect immediately, 4470 * the device may wait until it is in a neutral state before applying any 4471 * changes. 4472 * 4473 * The mapping may be changed when tap-to-click is disabled. The new mapping 4474 * takes effect when tap-to-click is enabled in the future. 4475 * 4476 * @note It is an application bug to call this function for devices where 4477 * libinput_device_config_tap_get_finger_count() returns 0. 4478 * 4479 * @param device The device to configure 4480 * @param map The new finger-to-button number mapping 4481 * @return A config status code. Changing the order on a device that does not 4482 * support tapping always fails with @ref LIBINPUT_CONFIG_STATUS_UNSUPPORTED. 4483 * 4484 * @see libinput_device_config_tap_get_button_map 4485 * @see libinput_device_config_tap_get_default_button_map 4486 * 4487 * @since 1.5 4488 */ 4489 enum libinput_config_status 4490 libinput_device_config_tap_set_button_map(struct libinput_device *device, 4491 enum libinput_config_tap_button_map map); 4492 4493 /** 4494 * @ingroup config 4495 * 4496 * Get the finger number to button number mapping for tap-to-click. 4497 * 4498 * The return value for a device that does not support tapping is always 4499 * @ref LIBINPUT_CONFIG_TAP_MAP_LRM. 4500 * 4501 * @note It is an application bug to call this function for devices where 4502 * libinput_device_config_tap_get_finger_count() returns 0. 4503 * 4504 * @param device The device to configure 4505 * @return The current finger-to-button number mapping 4506 * 4507 * @see libinput_device_config_tap_set_button_map 4508 * @see libinput_device_config_tap_get_default_button_map 4509 * 4510 * @since 1.5 4511 */ 4512 enum libinput_config_tap_button_map 4513 libinput_device_config_tap_get_button_map(struct libinput_device *device); 4514 4515 /** 4516 * @ingroup config 4517 * 4518 * Get the default finger number to button number mapping for tap-to-click. 4519 * 4520 * The return value for a device that does not support tapping is always 4521 * @ref LIBINPUT_CONFIG_TAP_MAP_LRM. 4522 * 4523 * @note It is an application bug to call this function for devices where 4524 * libinput_device_config_tap_get_finger_count() returns 0. 4525 * 4526 * @param device The device to configure 4527 * @return The current finger-to-button number mapping 4528 * 4529 * @see libinput_device_config_tap_set_button_map 4530 * @see libinput_device_config_tap_get_default_button_map 4531 * 4532 * @since 1.5 4533 */ 4534 enum libinput_config_tap_button_map 4535 libinput_device_config_tap_get_default_button_map(struct libinput_device *device); 4536 4537 /** 4538 * @ingroup config 4539 * 4540 * A config status to distinguish or set dragging on a device. Currently 4541 * implemented for tap-and-drag only, see 4542 * libinput_device_config_tap_set_drag_enabled() 4543 * 4544 * @since 1.2 4545 */ 4546 enum libinput_config_drag_state { 4547 /** 4548 * Drag is to be disabled, or is 4549 * currently disabled. 4550 */ 4551 LIBINPUT_CONFIG_DRAG_DISABLED, 4552 /** 4553 * Drag is to be enabled, or is 4554 * currently enabled 4555 */ 4556 LIBINPUT_CONFIG_DRAG_ENABLED, 4557 }; 4558 4559 /** 4560 * @ingroup config 4561 * 4562 * Enable or disable tap-and-drag on this device. When enabled, a 4563 * single-finger tap immediately followed by a finger down results in a 4564 * button down event, subsequent finger motion thus triggers a drag. The 4565 * button is released on finger up. See the libinput documentation for more 4566 * details. 4567 * 4568 * @param device The device to configure 4569 * @param enable @ref LIBINPUT_CONFIG_DRAG_ENABLED to enable, @ref 4570 * LIBINPUT_CONFIG_DRAG_DISABLED to disable tap-and-drag 4571 * 4572 * @see libinput_device_config_tap_drag_get_enabled 4573 * @see libinput_device_config_tap_drag_get_default_enabled 4574 * 4575 * @since 1.2 4576 */ 4577 enum libinput_config_status 4578 libinput_device_config_tap_set_drag_enabled(struct libinput_device *device, 4579 enum libinput_config_drag_state enable); 4580 4581 /** 4582 * @ingroup config 4583 * 4584 * Return whether tap-and-drag is enabled or disabled on this device. 4585 * 4586 * @param device The device to check 4587 * @retval LIBINPUT_CONFIG_DRAG_ENABLED if tap-and-drag is enabled 4588 * @retval LIBINPUT_CONFIG_DRAG_DISABLED if tap-and-drag is 4589 * disabled 4590 * 4591 * @see libinput_device_config_tap_drag_set_enabled 4592 * @see libinput_device_config_tap_drag_get_default_enabled 4593 * 4594 * @since 1.2 4595 */ 4596 enum libinput_config_drag_state 4597 libinput_device_config_tap_get_drag_enabled(struct libinput_device *device); 4598 4599 /** 4600 * @ingroup config 4601 * 4602 * Return whether tap-and-drag is enabled or disabled by default on this 4603 * device. 4604 * 4605 * @param device The device to check 4606 * @retval LIBINPUT_CONFIG_DRAG_ENABLED if tap-and-drag is enabled by 4607 * default 4608 * @retval LIBINPUT_CONFIG_DRAG_DISABLED if tap-and-drag is 4609 * disabled by default 4610 * 4611 * @see libinput_device_config_tap_drag_set_enabled 4612 * @see libinput_device_config_tap_drag_get_enabled 4613 * 4614 * @since 1.2 4615 */ 4616 enum libinput_config_drag_state 4617 libinput_device_config_tap_get_default_drag_enabled(struct libinput_device *device); 4618 4619 /** 4620 * @ingroup config 4621 */ 4622 enum libinput_config_drag_lock_state { 4623 /** Drag lock is to be disabled, or is currently disabled */ 4624 LIBINPUT_CONFIG_DRAG_LOCK_DISABLED, 4625 /** Drag lock is to be enabled, or is currently disabled */ 4626 LIBINPUT_CONFIG_DRAG_LOCK_ENABLED, 4627 }; 4628 4629 /** 4630 * @ingroup config 4631 * 4632 * Enable or disable drag-lock during tapping on this device. When enabled, 4633 * a finger may be lifted and put back on the touchpad within a timeout and 4634 * the drag process continues. When disabled, lifting the finger during a 4635 * tap-and-drag will immediately stop the drag. See the libinput 4636 * documentation for more details. 4637 * 4638 * Enabling drag lock on a device that has tapping disabled is permitted, 4639 * but has no effect until tapping is enabled. 4640 * 4641 * @param device The device to configure 4642 * @param enable @ref LIBINPUT_CONFIG_DRAG_LOCK_ENABLED to enable drag lock 4643 * or @ref LIBINPUT_CONFIG_DRAG_LOCK_DISABLED to disable drag lock 4644 * 4645 * @return A config status code. Disabling drag lock on a device that does not 4646 * support tapping always succeeds. 4647 * 4648 * @see libinput_device_config_tap_get_drag_lock_enabled 4649 * @see libinput_device_config_tap_get_default_drag_lock_enabled 4650 */ 4651 enum libinput_config_status 4652 libinput_device_config_tap_set_drag_lock_enabled(struct libinput_device *device, 4653 enum libinput_config_drag_lock_state enable); 4654 4655 /** 4656 * @ingroup config 4657 * 4658 * Check if drag-lock during tapping is enabled on this device. If the 4659 * device does not support tapping, this function always returns 4660 * @ref LIBINPUT_CONFIG_DRAG_LOCK_DISABLED. 4661 * 4662 * Drag lock may be enabled even when tapping is disabled. 4663 * 4664 * @param device The device to configure 4665 * 4666 * @retval LIBINPUT_CONFIG_DRAG_LOCK_ENABLED If drag lock is currently enabled 4667 * @retval LIBINPUT_CONFIG_DRAG_LOCK_DISABLED If drag lock is currently disabled 4668 * 4669 * @see libinput_device_config_tap_set_drag_lock_enabled 4670 * @see libinput_device_config_tap_get_default_drag_lock_enabled 4671 */ 4672 enum libinput_config_drag_lock_state 4673 libinput_device_config_tap_get_drag_lock_enabled(struct libinput_device *device); 4674 4675 /** 4676 * @ingroup config 4677 * 4678 * Check if drag-lock during tapping is enabled by default on this device. 4679 * If the device does not support tapping, this function always returns 4680 * @ref LIBINPUT_CONFIG_DRAG_LOCK_DISABLED. 4681 * 4682 * Drag lock may be enabled by default even when tapping is disabled by 4683 * default. 4684 * 4685 * @param device The device to configure 4686 * 4687 * @retval LIBINPUT_CONFIG_DRAG_LOCK_ENABLED If drag lock is enabled by 4688 * default 4689 * @retval LIBINPUT_CONFIG_DRAG_LOCK_DISABLED If drag lock is disabled by 4690 * default 4691 * 4692 * @see libinput_device_config_tap_set_drag_lock_enabled 4693 * @see libinput_device_config_tap_get_drag_lock_enabled 4694 */ 4695 enum libinput_config_drag_lock_state 4696 libinput_device_config_tap_get_default_drag_lock_enabled(struct libinput_device *device); 4697 4698 /** 4699 * @ingroup config 4700 * 4701 * Check if the device can be calibrated via a calibration matrix. 4702 * 4703 * @param device The device to check 4704 * @return Non-zero if the device can be calibrated, zero otherwise. 4705 * 4706 * @see libinput_device_config_calibration_set_matrix 4707 * @see libinput_device_config_calibration_get_matrix 4708 * @see libinput_device_config_calibration_get_default_matrix 4709 */ 4710 int 4711 libinput_device_config_calibration_has_matrix(struct libinput_device *device); 4712 4713 /** 4714 * @ingroup config 4715 * 4716 * Apply the 3x3 transformation matrix to absolute device coordinates. This 4717 * matrix has no effect on relative events. 4718 * 4719 * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as 4720 * @code 4721 * [ a b c ] [ x ] 4722 * [ d e f ] * [ y ] 4723 * [ 0 0 1 ] [ 1 ] 4724 * @endcode 4725 * 4726 * The translation component (c, f) is expected to be normalized to the 4727 * device coordinate range. For example, the matrix 4728 * @code 4729 * [ 1 0 1 ] 4730 * [ 0 1 -1 ] 4731 * [ 0 0 1 ] 4732 * @endcode 4733 * moves all coordinates by 1 device-width to the right and 1 device-height 4734 * up. 4735 * 4736 * The rotation matrix for rotation around the origin is defined as 4737 * @code 4738 * [ cos(a) -sin(a) 0 ] 4739 * [ sin(a) cos(a) 0 ] 4740 * [ 0 0 1 ] 4741 * @endcode 4742 * Note that any rotation requires an additional translation component to 4743 * translate the rotated coordinates back into the original device space. 4744 * The rotation matrixes for 90, 180 and 270 degrees clockwise are: 4745 * @code 4746 * 90 deg cw: 180 deg cw: 270 deg cw: 4747 * [ 0 -1 1] [ -1 0 1] [ 0 1 0 ] 4748 * [ 1 0 0] [ 0 -1 1] [ -1 0 1 ] 4749 * [ 0 0 1] [ 0 0 1] [ 0 0 1 ] 4750 * @endcode 4751 * 4752 * @param device The device to configure 4753 * @param matrix An array representing the first two rows of a 3x3 matrix as 4754 * described above. 4755 * 4756 * @return A config status code. 4757 * 4758 * @see libinput_device_config_calibration_has_matrix 4759 * @see libinput_device_config_calibration_get_matrix 4760 * @see libinput_device_config_calibration_get_default_matrix 4761 */ 4762 enum libinput_config_status 4763 libinput_device_config_calibration_set_matrix(struct libinput_device *device, 4764 const float matrix[6]); 4765 4766 /** 4767 * @ingroup config 4768 * 4769 * Return the current calibration matrix for this device. 4770 * 4771 * @param device The device to configure 4772 * @param matrix Set to the array representing the first two rows of a 3x3 matrix as 4773 * described in libinput_device_config_calibration_set_matrix(). 4774 * 4775 * @return 0 if no calibration is set and the returned matrix is the 4776 * identity matrix, 1 otherwise 4777 * 4778 * @see libinput_device_config_calibration_has_matrix 4779 * @see libinput_device_config_calibration_set_matrix 4780 * @see libinput_device_config_calibration_get_default_matrix 4781 */ 4782 int 4783 libinput_device_config_calibration_get_matrix(struct libinput_device *device, 4784 float matrix[6]); 4785 4786 /** 4787 * @ingroup config 4788 * 4789 * Return the default calibration matrix for this device. On most devices, 4790 * this is the identity matrix. If the udev property 4791 * <b>LIBINPUT_CALIBRATION_MATRIX</b> is set on the respective udev device, 4792 * that property's value becomes the default matrix, see the libinput 4793 * documentation for more details. 4794 * 4795 * @param device The device to configure 4796 * @param matrix Set to the array representing the first two rows of a 3x3 matrix as 4797 * described in libinput_device_config_calibration_set_matrix(). 4798 * 4799 * @return 0 if no calibration is set and the returned matrix is the 4800 * identity matrix, 1 otherwise 4801 * 4802 * @see libinput_device_config_calibration_has_matrix 4803 * @see libinput_device_config_calibration_set_matrix 4804 * @see libinput_device_config_calibration_get_matrix 4805 */ 4806 int 4807 libinput_device_config_calibration_get_default_matrix(struct libinput_device *device, 4808 float matrix[6]); 4809 4810 /** 4811 * @ingroup config 4812 * 4813 * The send-event mode of a device defines when a device may generate events 4814 * and pass those events to the caller. 4815 */ 4816 enum libinput_config_send_events_mode { 4817 /** 4818 * Send events from this device normally. This is a placeholder 4819 * mode only, any device detected by libinput can be enabled. Do not 4820 * test for this value as bitmask. 4821 */ 4822 LIBINPUT_CONFIG_SEND_EVENTS_ENABLED = 0, 4823 /** 4824 * Do not send events through this device. Depending on the device, 4825 * this may close all file descriptors on the device or it may leave 4826 * the file descriptors open and route events through a different 4827 * device. 4828 * 4829 * If this bit field is set, other disable modes may be 4830 * ignored. For example, if both @ref 4831 * LIBINPUT_CONFIG_SEND_EVENTS_DISABLED and @ref 4832 * LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE are set, 4833 * the device remains disabled when all external pointer devices are 4834 * unplugged. 4835 */ 4836 LIBINPUT_CONFIG_SEND_EVENTS_DISABLED = (1 << 0), 4837 /** 4838 * If an external pointer device is plugged in, do not send events 4839 * from this device. This option may be available on built-in 4840 * touchpads. 4841 */ 4842 LIBINPUT_CONFIG_SEND_EVENTS_DISABLED_ON_EXTERNAL_MOUSE = (1 << 1), 4843 }; 4844 4845 /** 4846 * @ingroup config 4847 * 4848 * Return the possible send-event modes for this device. These modes define 4849 * when a device may process and send events. 4850 * 4851 * @param device The device to configure 4852 * 4853 * @return A bitmask of possible modes. 4854 * 4855 * @see libinput_device_config_send_events_set_mode 4856 * @see libinput_device_config_send_events_get_mode 4857 * @see libinput_device_config_send_events_get_default_mode 4858 */ 4859 uint32_t 4860 libinput_device_config_send_events_get_modes(struct libinput_device *device); 4861 4862 /** 4863 * @ingroup config 4864 * 4865 * Set the send-event mode for this device. The mode defines when the device 4866 * processes and sends events to the caller. 4867 * 4868 * The selected mode may not take effect immediately. Events already 4869 * received and processed from this device are unaffected and will be passed 4870 * to the caller on the next call to libinput_get_event(). 4871 * 4872 * If the mode is a bitmask of @ref libinput_config_send_events_mode, 4873 * the device may wait for or generate events until it is in a neutral 4874 * state. For example, this may include waiting for or generating button 4875 * release events. 4876 * 4877 * If the device is already suspended, this function does nothing and 4878 * returns success. Changing the send-event mode on a device that has been 4879 * removed is permitted. 4880 * 4881 * @param device The device to configure 4882 * @param mode A bitmask of send-events modes 4883 * 4884 * @return A config status code. 4885 * 4886 * @see libinput_device_config_send_events_get_modes 4887 * @see libinput_device_config_send_events_get_mode 4888 * @see libinput_device_config_send_events_get_default_mode 4889 */ 4890 enum libinput_config_status 4891 libinput_device_config_send_events_set_mode(struct libinput_device *device, 4892 uint32_t mode); 4893 4894 /** 4895 * @ingroup config 4896 * 4897 * Get the send-event mode for this device. The mode defines when the device 4898 * processes and sends events to the caller. 4899 * 4900 * If a caller enables the bits for multiple modes, some of which are 4901 * subsets of another mode libinput may drop the bits that are subsets. In 4902 * other words, don't expect libinput_device_config_send_events_get_mode() 4903 * to always return exactly the same bitmask as passed into 4904 * libinput_device_config_send_events_set_mode(). 4905 * 4906 * @param device The device to configure 4907 * @return The current bitmask of the send-event mode for this device. 4908 * 4909 * @see libinput_device_config_send_events_get_modes 4910 * @see libinput_device_config_send_events_set_mode 4911 * @see libinput_device_config_send_events_get_default_mode 4912 */ 4913 uint32_t 4914 libinput_device_config_send_events_get_mode(struct libinput_device *device); 4915 4916 /** 4917 * @ingroup config 4918 * 4919 * Get the default send-event mode for this device. The mode defines when 4920 * the device processes and sends events to the caller. 4921 * 4922 * @param device The device to configure 4923 * @return The bitmask of the send-event mode for this device. 4924 * 4925 * @see libinput_device_config_send_events_get_modes 4926 * @see libinput_device_config_send_events_set_mode 4927 * @see libinput_device_config_send_events_get_mode 4928 */ 4929 uint32_t 4930 libinput_device_config_send_events_get_default_mode(struct libinput_device *device); 4931 4932 /** 4933 * @ingroup config 4934 * 4935 * Check if a device uses libinput-internal pointer-acceleration. 4936 * 4937 * @param device The device to configure 4938 * 4939 * @return 0 if the device is not accelerated, nonzero if it is accelerated 4940 * 4941 * @see libinput_device_config_accel_set_speed 4942 * @see libinput_device_config_accel_get_speed 4943 * @see libinput_device_config_accel_get_default_speed 4944 */ 4945 int 4946 libinput_device_config_accel_is_available(struct libinput_device *device); 4947 4948 /** 4949 * @ingroup config 4950 * 4951 * Set the pointer acceleration speed of this pointer device within a range 4952 * of [-1, 1], where 0 is the default acceleration for this device, -1 is 4953 * the slowest acceleration and 1 is the maximum acceleration available on 4954 * this device. The actual pointer acceleration mechanism is 4955 * implementation-dependent, as is the number of steps available within the 4956 * range. libinput picks the semantically closest acceleration step if the 4957 * requested value does not match a discrete setting. 4958 * 4959 * @param device The device to configure 4960 * @param speed The normalized speed, in a range of [-1, 1] 4961 * 4962 * @return A config status code 4963 * 4964 * @see libinput_device_config_accel_is_available 4965 * @see libinput_device_config_accel_get_speed 4966 * @see libinput_device_config_accel_get_default_speed 4967 */ 4968 enum libinput_config_status 4969 libinput_device_config_accel_set_speed(struct libinput_device *device, 4970 double speed); 4971 4972 /** 4973 * @ingroup config 4974 * 4975 * Get the current pointer acceleration setting for this pointer device. The 4976 * returned value is normalized to a range of [-1, 1]. 4977 * See libinput_device_config_accel_set_speed() for details. 4978 * 4979 * @param device The device to configure 4980 * 4981 * @return The current speed, range -1 to 1 4982 * 4983 * @see libinput_device_config_accel_is_available 4984 * @see libinput_device_config_accel_set_speed 4985 * @see libinput_device_config_accel_get_default_speed 4986 */ 4987 double 4988 libinput_device_config_accel_get_speed(struct libinput_device *device); 4989 4990 /** 4991 * @ingroup config 4992 * 4993 * Return the default speed setting for this device, normalized to a range 4994 * of [-1, 1]. 4995 * See libinput_device_config_accel_set_speed() for details. 4996 * 4997 * @param device The device to configure 4998 * @return The default speed setting for this device. 4999 * 5000 * @see libinput_device_config_accel_is_available 5001 * @see libinput_device_config_accel_set_speed 5002 * @see libinput_device_config_accel_get_speed 5003 */ 5004 double 5005 libinput_device_config_accel_get_default_speed(struct libinput_device *device); 5006 5007 /** 5008 * @ingroup config 5009 * 5010 * @since 1.1 5011 */ 5012 enum libinput_config_accel_profile { 5013 /** 5014 * Placeholder for devices that don't have a configurable pointer 5015 * acceleration profile. 5016 */ 5017 LIBINPUT_CONFIG_ACCEL_PROFILE_NONE = 0, 5018 /** 5019 * A flat acceleration profile. Pointer motion is accelerated by a 5020 * constant (device-specific) factor, depending on the current 5021 * speed. 5022 * 5023 * @see libinput_device_config_accel_set_speed 5024 */ 5025 LIBINPUT_CONFIG_ACCEL_PROFILE_FLAT = (1 << 0), 5026 5027 /** 5028 * An adaptive acceleration profile. Pointer acceleration depends 5029 * on the input speed. This is the default profile for most devices. 5030 */ 5031 LIBINPUT_CONFIG_ACCEL_PROFILE_ADAPTIVE = (1 << 1), 5032 }; 5033 5034 /** 5035 * @ingroup config 5036 * 5037 * Returns a bitmask of the configurable acceleration modes available on 5038 * this device. 5039 * 5040 * @param device The device to configure 5041 * 5042 * @return A bitmask of all configurable modes available on this device. 5043 * 5044 * @since 1.1 5045 */ 5046 uint32_t 5047 libinput_device_config_accel_get_profiles(struct libinput_device *device); 5048 5049 /** 5050 * @ingroup config 5051 * 5052 * Set the pointer acceleration profile of this pointer device to the given 5053 * mode. 5054 * 5055 * @param device The device to configure 5056 * @param mode The mode to set the device to. 5057 * 5058 * @return A config status code 5059 * 5060 * @since 1.1 5061 */ 5062 enum libinput_config_status 5063 libinput_device_config_accel_set_profile(struct libinput_device *device, 5064 enum libinput_config_accel_profile mode); 5065 5066 /** 5067 * @ingroup config 5068 * 5069 * Get the current pointer acceleration profile for this pointer device. 5070 * 5071 * @param device The device to configure 5072 * 5073 * @return The currently configured pointer acceleration profile. 5074 * 5075 * @since 1.1 5076 */ 5077 enum libinput_config_accel_profile 5078 libinput_device_config_accel_get_profile(struct libinput_device *device); 5079 5080 /** 5081 * @ingroup config 5082 * 5083 * Return the default pointer acceleration profile for this pointer device. 5084 * 5085 * @param device The device to configure 5086 * 5087 * @return The default acceleration profile for this device. 5088 * 5089 * @since 1.1 5090 */ 5091 enum libinput_config_accel_profile 5092 libinput_device_config_accel_get_default_profile(struct libinput_device *device); 5093 5094 /** 5095 * @ingroup config 5096 * 5097 * Return non-zero if the device supports "natural scrolling". 5098 * 5099 * In traditional scroll mode, the movement of fingers on a touchpad when 5100 * scrolling matches the movement of the scroll bars. When the fingers move 5101 * down, the scroll bar moves down, a line of text on the screen moves 5102 * towards the upper end of the screen. This also matches scroll wheels on 5103 * mice (wheel down, content moves up). 5104 * 5105 * Natural scrolling is the term coined by Apple for inverted scrolling. 5106 * In this mode, the effect of scrolling movement of fingers on a touchpad 5107 * resemble physical manipulation of paper. When the fingers move down, a 5108 * line of text on the screen moves down (scrollbars move up). This is the 5109 * opposite of scroll wheels on mice. 5110 * 5111 * A device supporting natural scrolling can be switched between traditional 5112 * scroll mode and natural scroll mode. 5113 * 5114 * @param device The device to configure 5115 * 5116 * @return Zero if natural scrolling is not supported, non-zero if natural 5117 * scrolling is supported by this device 5118 * 5119 * @see libinput_device_config_scroll_set_natural_scroll_enabled 5120 * @see libinput_device_config_scroll_get_natural_scroll_enabled 5121 * @see libinput_device_config_scroll_get_default_natural_scroll_enabled 5122 */ 5123 int 5124 libinput_device_config_scroll_has_natural_scroll(struct libinput_device *device); 5125 5126 /** 5127 * @ingroup config 5128 * 5129 * Enable or disable natural scrolling on the device. 5130 * 5131 * @param device The device to configure 5132 * @param enable non-zero to enable, zero to disable natural scrolling 5133 * 5134 * @return A config status code 5135 * 5136 * @see libinput_device_config_scroll_has_natural_scroll 5137 * @see libinput_device_config_scroll_get_natural_scroll_enabled 5138 * @see libinput_device_config_scroll_get_default_natural_scroll_enabled 5139 */ 5140 enum libinput_config_status 5141 libinput_device_config_scroll_set_natural_scroll_enabled(struct libinput_device *device, 5142 int enable); 5143 /** 5144 * @ingroup config 5145 * 5146 * Get the current mode for scrolling on this device 5147 * 5148 * @param device The device to configure 5149 * 5150 * @return Zero if natural scrolling is disabled, non-zero if enabled 5151 * 5152 * @see libinput_device_config_scroll_has_natural_scroll 5153 * @see libinput_device_config_scroll_set_natural_scroll_enabled 5154 * @see libinput_device_config_scroll_get_default_natural_scroll_enabled 5155 */ 5156 int 5157 libinput_device_config_scroll_get_natural_scroll_enabled(struct libinput_device *device); 5158 5159 /** 5160 * @ingroup config 5161 * 5162 * Get the default mode for scrolling on this device 5163 * 5164 * @param device The device to configure 5165 * 5166 * @return Zero if natural scrolling is disabled by default, non-zero if enabled 5167 * 5168 * @see libinput_device_config_scroll_has_natural_scroll 5169 * @see libinput_device_config_scroll_set_natural_scroll_enabled 5170 * @see libinput_device_config_scroll_get_natural_scroll_enabled 5171 */ 5172 int 5173 libinput_device_config_scroll_get_default_natural_scroll_enabled(struct libinput_device *device); 5174 5175 /** 5176 * @ingroup config 5177 * 5178 * Check if a device has a configuration that supports left-handed usage. 5179 * 5180 * @param device The device to configure 5181 * @return Non-zero if the device can be set to left-handed, or zero 5182 * otherwise 5183 * 5184 * @see libinput_device_config_left_handed_set 5185 * @see libinput_device_config_left_handed_get 5186 * @see libinput_device_config_left_handed_get_default 5187 */ 5188 int 5189 libinput_device_config_left_handed_is_available(struct libinput_device *device); 5190 5191 /** 5192 * @ingroup config 5193 * 5194 * Set the left-handed configuration of the device. 5195 * 5196 * The exact behavior is device-dependent. On a mouse and most pointing 5197 * devices, left and right buttons are swapped but the middle button is 5198 * unmodified. On a touchpad, physical buttons (if present) are swapped. On a 5199 * clickpad, the top and bottom software-emulated buttons are swapped where 5200 * present, the main area of the touchpad remains a left button. Tapping and 5201 * clickfinger behavior is not affected by this setting. 5202 * 5203 * Changing the left-handed configuration of a device may not take effect 5204 * until all buttons have been logically released. 5205 * 5206 * @param device The device to configure 5207 * @param left_handed Zero to disable, non-zero to enable left-handed mode 5208 * @return A configuration status code 5209 * 5210 * @see libinput_device_config_left_handed_is_available 5211 * @see libinput_device_config_left_handed_get 5212 * @see libinput_device_config_left_handed_get_default 5213 */ 5214 enum libinput_config_status 5215 libinput_device_config_left_handed_set(struct libinput_device *device, 5216 int left_handed); 5217 5218 /** 5219 * @ingroup config 5220 * 5221 * Get the current left-handed configuration of the device. 5222 * 5223 * @param device The device to configure 5224 * @return Zero if the device is in right-handed mode, non-zero if the 5225 * device is in left-handed mode 5226 * 5227 * @see libinput_device_config_left_handed_is_available 5228 * @see libinput_device_config_left_handed_set 5229 * @see libinput_device_config_left_handed_get_default 5230 */ 5231 int 5232 libinput_device_config_left_handed_get(struct libinput_device *device); 5233 5234 /** 5235 * @ingroup config 5236 * 5237 * Get the default left-handed configuration of the device. 5238 * 5239 * @param device The device to configure 5240 * @return Zero if the device is in right-handed mode by default, or non-zero 5241 * if the device is in left-handed mode by default 5242 * 5243 * @see libinput_device_config_left_handed_is_available 5244 * @see libinput_device_config_left_handed_set 5245 * @see libinput_device_config_left_handed_get 5246 */ 5247 int 5248 libinput_device_config_left_handed_get_default(struct libinput_device *device); 5249 5250 /** 5251 * @ingroup config 5252 * 5253 * The click method defines when to generate software-emulated 5254 * buttons, usually on a device that does not have a specific physical 5255 * button available. 5256 */ 5257 enum libinput_config_click_method { 5258 /** 5259 * Do not send software-emulated button events. This has no effect 5260 * on events generated by physical buttons. 5261 */ 5262 LIBINPUT_CONFIG_CLICK_METHOD_NONE = 0, 5263 /** 5264 * Use software-button areas to generate button events. 5265 */ 5266 LIBINPUT_CONFIG_CLICK_METHOD_BUTTON_AREAS = (1 << 0), 5267 /** 5268 * The number of fingers decides which button press to generate. 5269 */ 5270 LIBINPUT_CONFIG_CLICK_METHOD_CLICKFINGER = (1 << 1), 5271 }; 5272 5273 /** 5274 * @ingroup config 5275 * 5276 * Check which button click methods a device supports. The button click 5277 * method defines when to generate software-emulated buttons, usually on a 5278 * device that does not have a specific physical button available. 5279 * 5280 * @param device The device to configure 5281 * 5282 * @return A bitmask of possible methods. 5283 * 5284 * @see libinput_device_config_click_get_methods 5285 * @see libinput_device_config_click_set_method 5286 * @see libinput_device_config_click_get_method 5287 */ 5288 uint32_t 5289 libinput_device_config_click_get_methods(struct libinput_device *device); 5290 5291 /** 5292 * @ingroup config 5293 * 5294 * Set the button click method for this device. The button click 5295 * method defines when to generate software-emulated buttons, usually on a 5296 * device that does not have a specific physical button available. 5297 * 5298 * @note The selected click method may not take effect immediately. The 5299 * device may require changing to a neutral state first before activating 5300 * the new method. 5301 * 5302 * @param device The device to configure 5303 * @param method The button click method 5304 * 5305 * @return A config status code 5306 * 5307 * @see libinput_device_config_click_get_methods 5308 * @see libinput_device_config_click_get_method 5309 * @see libinput_device_config_click_get_default_method 5310 */ 5311 enum libinput_config_status 5312 libinput_device_config_click_set_method(struct libinput_device *device, 5313 enum libinput_config_click_method method); 5314 /** 5315 * @ingroup config 5316 * 5317 * Get the button click method for this device. The button click 5318 * method defines when to generate software-emulated buttons, usually on a 5319 * device that does not have a specific physical button available. 5320 * 5321 * @param device The device to configure 5322 * 5323 * @return The current button click method for this device 5324 * 5325 * @see libinput_device_config_click_get_methods 5326 * @see libinput_device_config_click_set_method 5327 * @see libinput_device_config_click_get_default_method 5328 */ 5329 enum libinput_config_click_method 5330 libinput_device_config_click_get_method(struct libinput_device *device); 5331 5332 /** 5333 * @ingroup config 5334 * 5335 * Get the default button click method for this device. The button click 5336 * method defines when to generate software-emulated buttons, usually on a 5337 * device that does not have a specific physical button available. 5338 * 5339 * @param device The device to configure 5340 * 5341 * @return The default button click method for this device 5342 * 5343 * @see libinput_device_config_click_get_methods 5344 * @see libinput_device_config_click_set_method 5345 * @see libinput_device_config_click_get_method 5346 */ 5347 enum libinput_config_click_method 5348 libinput_device_config_click_get_default_method(struct libinput_device *device); 5349 5350 /** 5351 * @ingroup config 5352 */ 5353 enum libinput_config_middle_emulation_state { 5354 /** 5355 * Middle mouse button emulation is to be disabled, or 5356 * is currently disabled. 5357 */ 5358 LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED, 5359 /** 5360 * Middle mouse button emulation is to be enabled, or 5361 * is currently enabled. 5362 */ 5363 LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED, 5364 }; 5365 5366 /** 5367 * @ingroup config 5368 * 5369 * Check if middle mouse button emulation configuration is available on this 5370 * device. See libinput_device_config_middle_emulation_set_enabled() for 5371 * more details. 5372 * 5373 * @note Some devices provide middle mouse button emulation but do not allow 5374 * enabling/disabling that emulation. These devices return zero in 5375 * libinput_device_config_middle_emulation_is_available(). 5376 * 5377 * @param device The device to query 5378 * 5379 * @return Non-zero if middle mouse button emulation is available and can be 5380 * configured, zero otherwise. 5381 * 5382 * @see libinput_device_config_middle_emulation_set_enabled 5383 * @see libinput_device_config_middle_emulation_get_enabled 5384 * @see libinput_device_config_middle_emulation_get_default_enabled 5385 */ 5386 int 5387 libinput_device_config_middle_emulation_is_available( 5388 struct libinput_device *device); 5389 5390 /** 5391 * @ingroup config 5392 * 5393 * Enable or disable middle button emulation on this device. When enabled, a 5394 * simultaneous press of the left and right button generates a middle mouse 5395 * button event. Releasing the buttons generates a middle mouse button 5396 * release, the left and right button events are discarded otherwise. 5397 * 5398 * See the libinput documentation for more details. 5399 * 5400 * @param device The device to configure 5401 * @param enable @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED to 5402 * disable, @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED To enable 5403 * middle button emulation. 5404 * 5405 * @return A config status code. Disabling middle button emulation on a 5406 * device that does not support middle button emulation always succeeds. 5407 * 5408 * @see libinput_device_config_middle_emulation_is_available 5409 * @see libinput_device_config_middle_emulation_get_enabled 5410 * @see libinput_device_config_middle_emulation_get_default_enabled 5411 */ 5412 enum libinput_config_status 5413 libinput_device_config_middle_emulation_set_enabled( 5414 struct libinput_device *device, 5415 enum libinput_config_middle_emulation_state enable); 5416 5417 /** 5418 * @ingroup config 5419 * 5420 * Check if configurable middle button emulation is enabled on this device. 5421 * See libinput_device_config_middle_emulation_set_enabled() for more 5422 * details. 5423 * 5424 * If the device does not have configurable middle button emulation, this 5425 * function returns @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED. 5426 * 5427 * @note Some devices provide middle mouse button emulation but do not allow 5428 * enabling/disabling that emulation. These devices always return @ref 5429 * LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED. 5430 * 5431 * @param device The device to configure 5432 * @return @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED if disabled 5433 * or not available/configurable, @ref 5434 * LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED If enabled. 5435 * 5436 * @see libinput_device_config_middle_emulation_is_available 5437 * @see libinput_device_config_middle_emulation_set_enabled 5438 * @see libinput_device_config_middle_emulation_get_default_enabled 5439 */ 5440 enum libinput_config_middle_emulation_state 5441 libinput_device_config_middle_emulation_get_enabled( 5442 struct libinput_device *device); 5443 5444 /** 5445 * @ingroup config 5446 * 5447 * Check if configurable middle button emulation is enabled by default on 5448 * this device. See libinput_device_config_middle_emulation_set_enabled() 5449 * for more details. 5450 * 5451 * If the device does not have configurable middle button 5452 * emulation, this function returns @ref 5453 * LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED. 5454 * 5455 * @note Some devices provide middle mouse button emulation but do not allow 5456 * enabling/disabling that emulation. These devices always return @ref 5457 * LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED. 5458 * 5459 * @param device The device to configure 5460 * @return @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED If disabled 5461 * or not available, @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_ENABLED if 5462 * enabled. 5463 * 5464 * @see libinput_device_config_middle_emulation_is_available 5465 * @see libinput_device_config_middle_emulation_set_enabled 5466 * @see libinput_device_config_middle_emulation_get_enabled 5467 */ 5468 enum libinput_config_middle_emulation_state 5469 libinput_device_config_middle_emulation_get_default_enabled( 5470 struct libinput_device *device); 5471 5472 /** 5473 * @ingroup config 5474 * 5475 * The scroll method of a device selects when to generate scroll axis events 5476 * instead of pointer motion events. 5477 */ 5478 enum libinput_config_scroll_method { 5479 /** 5480 * Never send scroll events instead of pointer motion events. 5481 * This has no effect on events generated by scroll wheels. 5482 */ 5483 LIBINPUT_CONFIG_SCROLL_NO_SCROLL = 0, 5484 /** 5485 * Send scroll events when two fingers are logically down on the 5486 * device. 5487 */ 5488 LIBINPUT_CONFIG_SCROLL_2FG = (1 << 0), 5489 /** 5490 * Send scroll events when a finger moves along the bottom or 5491 * right edge of a device. 5492 */ 5493 LIBINPUT_CONFIG_SCROLL_EDGE = (1 << 1), 5494 /** 5495 * Send scroll events when a button is down and the device moves 5496 * along a scroll-capable axis. 5497 */ 5498 LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN = (1 << 2), 5499 }; 5500 5501 /** 5502 * @ingroup config 5503 * 5504 * Check which scroll methods a device supports. The method defines when to 5505 * generate scroll axis events instead of pointer motion events. 5506 * 5507 * @param device The device to configure 5508 * 5509 * @return A bitmask of possible methods. 5510 * 5511 * @see libinput_device_config_scroll_set_method 5512 * @see libinput_device_config_scroll_get_method 5513 * @see libinput_device_config_scroll_get_default_method 5514 * @see libinput_device_config_scroll_set_button 5515 * @see libinput_device_config_scroll_get_button 5516 * @see libinput_device_config_scroll_get_default_button 5517 */ 5518 uint32_t 5519 libinput_device_config_scroll_get_methods(struct libinput_device *device); 5520 5521 /** 5522 * @ingroup config 5523 * 5524 * Set the scroll method for this device. The method defines when to 5525 * generate scroll axis events instead of pointer motion events. 5526 * 5527 * @note Setting @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN enables 5528 * the scroll method, but scrolling is only activated when the configured 5529 * button is held down. If no button is set, i.e. 5530 * libinput_device_config_scroll_get_button() returns 0, scrolling 5531 * cannot activate. 5532 * 5533 * @param device The device to configure 5534 * @param method The scroll method for this device. 5535 * 5536 * @return A config status code. 5537 * 5538 * @see libinput_device_config_scroll_get_methods 5539 * @see libinput_device_config_scroll_get_method 5540 * @see libinput_device_config_scroll_get_default_method 5541 * @see libinput_device_config_scroll_set_button 5542 * @see libinput_device_config_scroll_get_button 5543 * @see libinput_device_config_scroll_get_default_button 5544 */ 5545 enum libinput_config_status 5546 libinput_device_config_scroll_set_method(struct libinput_device *device, 5547 enum libinput_config_scroll_method method); 5548 5549 /** 5550 * @ingroup config 5551 * 5552 * Get the scroll method for this device. The method defines when to 5553 * generate scroll axis events instead of pointer motion events. 5554 * 5555 * @param device The device to configure 5556 * @return The current scroll method for this device. 5557 * 5558 * @see libinput_device_config_scroll_get_methods 5559 * @see libinput_device_config_scroll_set_method 5560 * @see libinput_device_config_scroll_get_default_method 5561 * @see libinput_device_config_scroll_set_button 5562 * @see libinput_device_config_scroll_get_button 5563 * @see libinput_device_config_scroll_get_default_button 5564 */ 5565 enum libinput_config_scroll_method 5566 libinput_device_config_scroll_get_method(struct libinput_device *device); 5567 5568 /** 5569 * @ingroup config 5570 * 5571 * Get the default scroll method for this device. The method defines when to 5572 * generate scroll axis events instead of pointer motion events. 5573 * 5574 * @param device The device to configure 5575 * @return The default scroll method for this device. 5576 * 5577 * @see libinput_device_config_scroll_get_methods 5578 * @see libinput_device_config_scroll_set_method 5579 * @see libinput_device_config_scroll_get_method 5580 * @see libinput_device_config_scroll_set_button 5581 * @see libinput_device_config_scroll_get_button 5582 * @see libinput_device_config_scroll_get_default_button 5583 */ 5584 enum libinput_config_scroll_method 5585 libinput_device_config_scroll_get_default_method(struct libinput_device *device); 5586 5587 /** 5588 * @ingroup config 5589 * 5590 * Set the button for the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method 5591 * for this device. 5592 * 5593 * When the current scroll method is set to @ref 5594 * LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN, no button press/release events 5595 * will be send for the configured button. 5596 * 5597 * When the configured button is pressed, any motion events along a 5598 * scroll-capable axis are turned into scroll axis events. 5599 * 5600 * @note Setting the button does not change the scroll method. To change the 5601 * scroll method call libinput_device_config_scroll_set_method(). 5602 * 5603 * If the button is 0, button scrolling is effectively disabled. 5604 * 5605 * @param device The device to configure 5606 * @param button The button which when pressed switches to sending scroll events 5607 * 5608 * @return A config status code 5609 * @retval LIBINPUT_CONFIG_STATUS_SUCCESS On success 5610 * @retval LIBINPUT_CONFIG_STATUS_UNSUPPORTED If @ref 5611 * LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN is not supported 5612 * @retval LIBINPUT_CONFIG_STATUS_INVALID The given button does not 5613 * exist on this device 5614 * 5615 * @see libinput_device_config_scroll_get_methods 5616 * @see libinput_device_config_scroll_set_method 5617 * @see libinput_device_config_scroll_get_method 5618 * @see libinput_device_config_scroll_get_default_method 5619 * @see libinput_device_config_scroll_get_button 5620 * @see libinput_device_config_scroll_get_default_button 5621 */ 5622 enum libinput_config_status 5623 libinput_device_config_scroll_set_button(struct libinput_device *device, 5624 uint32_t button); 5625 5626 /** 5627 * @ingroup config 5628 * 5629 * Get the button for the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method 5630 * for this device. 5631 * 5632 * If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not 5633 * supported, or no button is set, this function returns 0. 5634 * 5635 * @note The return value is independent of the currently selected 5636 * scroll-method. For button scrolling to activate, a device must have the 5637 * @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method enabled, and a non-zero 5638 * button set as scroll button. 5639 * 5640 * @param device The device to configure 5641 * @return The button which when pressed switches to sending scroll events 5642 * 5643 * @see libinput_device_config_scroll_get_methods 5644 * @see libinput_device_config_scroll_set_method 5645 * @see libinput_device_config_scroll_get_method 5646 * @see libinput_device_config_scroll_get_default_method 5647 * @see libinput_device_config_scroll_set_button 5648 * @see libinput_device_config_scroll_get_default_button 5649 */ 5650 uint32_t 5651 libinput_device_config_scroll_get_button(struct libinput_device *device); 5652 5653 /** 5654 * @ingroup config 5655 * 5656 * Get the default button for the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN 5657 * method for this device. 5658 * 5659 * If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not supported, 5660 * or no default button is set, this function returns 0. 5661 * 5662 * @param device The device to configure 5663 * @return The default button for the @ref 5664 * LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method 5665 * 5666 * @see libinput_device_config_scroll_get_methods 5667 * @see libinput_device_config_scroll_set_method 5668 * @see libinput_device_config_scroll_get_method 5669 * @see libinput_device_config_scroll_get_default_method 5670 * @see libinput_device_config_scroll_set_button 5671 * @see libinput_device_config_scroll_get_button 5672 */ 5673 uint32_t 5674 libinput_device_config_scroll_get_default_button(struct libinput_device *device); 5675 5676 enum libinput_config_scroll_button_lock_state { 5677 LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED, 5678 LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_ENABLED, 5679 }; 5680 5681 /** 5682 * @ingroup config 5683 * 5684 * Set the scroll button lock. If the state is 5685 * @ref LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED, the button must 5686 * physically be held down for button scrolling to work. 5687 * If the state is 5688 * @ref LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_ENABLED, the button is considered 5689 * logically down after the first press and release sequence, and logically 5690 * up after the second press and release sequence. 5691 * 5692 * @param device The device to configure 5693 * @param state The state to set the scroll button lock to 5694 * 5695 * @return A config status code. Disabling the scroll button lock on 5696 * device that does not support button scrolling always succeeds. 5697 * 5698 * @see libinput_device_config_scroll_set_button 5699 * @see libinput_device_config_scroll_get_button 5700 * @see libinput_device_config_scroll_get_default_button 5701 */ 5702 enum libinput_config_status 5703 libinput_device_config_scroll_set_button_lock(struct libinput_device *device, 5704 enum libinput_config_scroll_button_lock_state state); 5705 5706 /** 5707 * @ingroup config 5708 * 5709 * Get the current scroll button lock state. 5710 * 5711 * If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not 5712 * supported, or no button is set, this function returns @ref 5713 * LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED. 5714 * 5715 * @note The return value is independent of the currently selected 5716 * scroll-method. For the scroll button lock to activate, a device must have 5717 * the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method enabled, and a 5718 * non-zero button set as scroll button. 5719 * 5720 * @param device The device to configure 5721 * @return The scroll button lock state 5722 * 5723 * @see libinput_device_config_scroll_set_button 5724 * @see libinput_device_config_scroll_set_button_lock 5725 * @see libinput_device_config_scroll_get_button_lock 5726 * @see libinput_device_config_scroll_get_default_button_lock 5727 */ 5728 enum libinput_config_scroll_button_lock_state 5729 libinput_device_config_scroll_get_button_lock(struct libinput_device *device); 5730 5731 /** 5732 * @ingroup config 5733 * 5734 * Get the default scroll button lock state. 5735 * 5736 * If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not 5737 * supported, or no button is set, this function returns @ref 5738 * LIBINPUT_CONFIG_SCROLL_BUTTON_LOCK_DISABLED. 5739 * 5740 * @param device The device to configure 5741 * @return The default scroll button lock state 5742 * 5743 * @see libinput_device_config_scroll_set_button 5744 * @see libinput_device_config_scroll_set_button_lock 5745 * @see libinput_device_config_scroll_get_button_lock 5746 * @see libinput_device_config_scroll_get_default_button_lock 5747 */ 5748 enum libinput_config_scroll_button_lock_state 5749 libinput_device_config_scroll_get_default_button_lock(struct libinput_device *device); 5750 5751 /** 5752 * @ingroup config 5753 * 5754 * Possible states for the disable-while-typing feature. 5755 */ 5756 enum libinput_config_dwt_state { 5757 LIBINPUT_CONFIG_DWT_DISABLED, 5758 LIBINPUT_CONFIG_DWT_ENABLED, 5759 }; 5760 5761 /** 5762 * @ingroup config 5763 * 5764 * Check if this device supports configurable disable-while-typing feature. 5765 * This feature is usually available on built-in touchpads and disables the 5766 * touchpad while typing. See the libinput documentation for details. 5767 * 5768 * @param device The device to configure 5769 * @return 0 if this device does not support disable-while-typing, or 1 5770 * otherwise. 5771 * 5772 * @see libinput_device_config_dwt_set_enabled 5773 * @see libinput_device_config_dwt_get_enabled 5774 * @see libinput_device_config_dwt_get_default_enabled 5775 */ 5776 int 5777 libinput_device_config_dwt_is_available(struct libinput_device *device); 5778 5779 /** 5780 * @ingroup config 5781 * 5782 * Enable or disable the disable-while-typing feature. When enabled, the 5783 * device will be disabled while typing and for a short period after. See 5784 * the libinput documentation for details. 5785 * 5786 * @note Enabling or disabling disable-while-typing may not take effect 5787 * immediately. 5788 * 5789 * @param device The device to configure 5790 * @param enable @ref LIBINPUT_CONFIG_DWT_DISABLED to disable 5791 * disable-while-typing, @ref LIBINPUT_CONFIG_DWT_ENABLED to enable 5792 * 5793 * @return A config status code. Disabling disable-while-typing on a 5794 * device that does not support the feature always succeeds. 5795 * 5796 * @see libinput_device_config_dwt_is_available 5797 * @see libinput_device_config_dwt_get_enabled 5798 * @see libinput_device_config_dwt_get_default_enabled 5799 */ 5800 enum libinput_config_status 5801 libinput_device_config_dwt_set_enabled(struct libinput_device *device, 5802 enum libinput_config_dwt_state enable); 5803 5804 /** 5805 * @ingroup config 5806 * 5807 * Check if the disable-while typing feature is currently enabled on this 5808 * device. If the device does not support disable-while-typing, this 5809 * function returns @ref LIBINPUT_CONFIG_DWT_DISABLED. 5810 * 5811 * @param device The device to configure 5812 * @return @ref LIBINPUT_CONFIG_DWT_DISABLED if disabled, @ref 5813 * LIBINPUT_CONFIG_DWT_ENABLED if enabled. 5814 * 5815 * @see libinput_device_config_dwt_is_available 5816 * @see libinput_device_config_dwt_set_enabled 5817 * @see libinput_device_config_dwt_get_default_enabled 5818 */ 5819 enum libinput_config_dwt_state 5820 libinput_device_config_dwt_get_enabled(struct libinput_device *device); 5821 5822 /** 5823 * @ingroup config 5824 * 5825 * Check if the disable-while typing feature is enabled on this device by 5826 * default. If the device does not support disable-while-typing, this 5827 * function returns @ref LIBINPUT_CONFIG_DWT_DISABLED. 5828 * 5829 * @param device The device to configure 5830 * @return @ref LIBINPUT_CONFIG_DWT_DISABLED if disabled, @ref 5831 * LIBINPUT_CONFIG_DWT_ENABLED if enabled. 5832 * 5833 * @see libinput_device_config_dwt_is_available 5834 * @see libinput_device_config_dwt_set_enabled 5835 * @see libinput_device_config_dwt_get_enabled 5836 */ 5837 enum libinput_config_dwt_state 5838 libinput_device_config_dwt_get_default_enabled(struct libinput_device *device); 5839 5840 /** 5841 * @ingroup config 5842 * 5843 * Check whether a device can have a custom rotation applied. 5844 * 5845 * @param device The device to configure 5846 * @return Non-zero if a device can be rotated, zero otherwise. 5847 * 5848 * @see libinput_device_config_rotation_set_angle 5849 * @see libinput_device_config_rotation_get_angle 5850 * @see libinput_device_config_rotation_get_default_angle 5851 * 5852 * @since 1.4 5853 */ 5854 int 5855 libinput_device_config_rotation_is_available(struct libinput_device *device); 5856 5857 /** 5858 * @ingroup config 5859 * 5860 * Set the rotation of a device in degrees clockwise off the logical neutral 5861 * position. Any subsequent motion events are adjusted according to the 5862 * given angle. 5863 * 5864 * The angle has to be in the range of [0, 360[ degrees, otherwise this 5865 * function returns LIBINPUT_CONFIG_STATUS_INVALID. If the angle is a 5866 * multiple of 360 or negative, the caller must ensure the correct ranging 5867 * before calling this function. 5868 * 5869 * libinput guarantees that this function accepts multiples of 90 degrees. 5870 * If a value is within the [0, 360[ range but not a multiple of 90 degrees, 5871 * this function may return LIBINPUT_CONFIG_STATUS_INVALID if the underlying 5872 * device or implementation does not support finer-grained rotation angles. 5873 * 5874 * The rotation angle is applied to all motion events emitted by the device. 5875 * Thus, rotating the device also changes the angle required or presented by 5876 * scrolling, gestures, etc. 5877 * 5878 * @param device The device to configure 5879 * @param degrees_cw The angle in degrees clockwise 5880 * @return A config status code. Setting a rotation of 0 degrees on a 5881 * device that does not support rotation always succeeds. 5882 * 5883 * @see libinput_device_config_rotation_is_available 5884 * @see libinput_device_config_rotation_get_angle 5885 * @see libinput_device_config_rotation_get_default_angle 5886 * 5887 * @since 1.4 5888 */ 5889 enum libinput_config_status 5890 libinput_device_config_rotation_set_angle(struct libinput_device *device, 5891 unsigned int degrees_cw); 5892 5893 /** 5894 * @ingroup config 5895 * 5896 * Get the current rotation of a device in degrees clockwise off the logical 5897 * neutral position. If this device does not support rotation, the return 5898 * value is always 0. 5899 * 5900 * @param device The device to configure 5901 * @return The angle in degrees clockwise 5902 * 5903 * @see libinput_device_config_rotation_is_available 5904 * @see libinput_device_config_rotation_set_angle 5905 * @see libinput_device_config_rotation_get_default_angle 5906 * 5907 * @since 1.4 5908 */ 5909 unsigned int 5910 libinput_device_config_rotation_get_angle(struct libinput_device *device); 5911 5912 /** 5913 * @ingroup config 5914 * 5915 * Get the default rotation of a device in degrees clockwise off the logical 5916 * neutral position. If this device does not support rotation, the return 5917 * value is always 0. 5918 * 5919 * @param device The device to configure 5920 * @return The default angle in degrees clockwise 5921 * 5922 * @see libinput_device_config_rotation_is_available 5923 * @see libinput_device_config_rotation_set_angle 5924 * @see libinput_device_config_rotation_get_angle 5925 * 5926 * @since 1.4 5927 */ 5928 unsigned int 5929 libinput_device_config_rotation_get_default_angle(struct libinput_device *device); 5930 5931 #ifdef __cplusplus 5932 } 5933 #endif 5934 #endif /* LIBINPUT_H */ 5935