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