src/libinput.h

   1 /*
   2  * Copyright © 2013 Jonas Ådahl
   3  *
   4  * Permission to use, copy, modify, distribute, and sell this software and
   5  * its documentation for any purpose is hereby granted without fee, provided
   6  * that the above copyright notice appear in all copies and that both that
   7  * copyright notice and this permission notice appear in supporting
   8  * documentation, and that the name of the copyright holders not be used in
   9  * advertising or publicity pertaining to distribution of the software
  10  * without specific, written prior permission.  The copyright holders make
  11  * no representations about the suitability of this software for any
  12  * purpose.  It is provided "as is" without express or implied warranty.
  13  *
  14  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
  15  * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  16  * FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
  17  * SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
  18  * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
  19  * CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  20  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  21  */
  22
  23 #ifndef LIBINPUT_H
  24 #define LIBINPUT_H
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #include <stdlib.h>
  31 #include <stdint.h>
  32 #include <libudev.h>
  33
  34 #define LIBINPUT_ATTRIBUTE_PRINTF(_format, _args) \
  35         __attribute__ ((format (printf, _format, _args)))
  36 #define LIBINPUT_ATTRIBUTE_DEPRECATED __attribute__ ((deprecated))
  37
  38 /**
  39  * @mainpage
  40  * libinput is a generic input device handling library. It abstracts
  41  * commonly-used concepts such as keyboard, pointer and touchpad handling
  42  * behind an API.
  43  */
  44
  45 /**
  46  * @page tpbuttons Touchpad button behavior
  47  *
  48  * For touchpad devices without physical buttons, libinput enables an
  49  * emulated right button area through either of two methods.
  50  *
  51  * Software button areas
  52  * =====================
  53  * On most touchpads, the bottom area of the touchpad is split into a left
  54  * and a right-button area. Pressing the touchpad down with a finger in
  55  * those areas will generate clicks as shown in the diagram below:
  56  *
  57  * @code
  58     +------------------------+
  59     |                        |
  60     |                        |
  61     |          LEFT          |
  62     |                        |
  63     |                        |
  64     +------------------------+
  65     |    LEFT    |   RIGHT   |
  66     +------------------------+
  67  * @endcode
  68  *
  69  * Generally, the touchpad will emulate a right-button click if the finger
  70  * was set down in the right button area and did not leave the
  71  * right button area before clicking, even if another finger was already
  72  * down on the touchpad in another area.
  73  * A middle click is generated by clicking the touchpad when one finger is
  74  * in the bottom left button area, and one finger is in the botton right
  75  * button area.
  76  * The exact behavior of the touchpad is implementation-dependent.
  77  *
  78  * Top software button area
  79  * ========================
  80  * On selected touchpads, the top area of the touchpad is a separate set of
  81  * software buttons split into a left, middle and right button area.
  82  * Pressing the touchpad down with a finger in those areas will generate
  83  * clicks as shown in the diagram below:
  84  *
  85  * @code
  86     +------------------------+
  87     |  LEFT | MIDDLE | RIGHT |
  88     +------------------------+
  89     |                        |
  90     |          LEFT          |
  91     |                        |
  92     +------------------------+
  93     |    LEFT    |   RIGHT   |
  94     +------------------------+
  95  * @endcode
  96  * This behavior is enabled on the Lenovo *40 series (T440, T540, T240...)
  97  * and the Lenovo Helix, Yoga S1 and Carbon X1 2nd.
  98  *
  99  * Clickfinger
 100  * ===========
 101  * On Apple touchpads, no button areas are provided. Instead, use a
 102  * two-finger click for a right button click, and a three-finger click for a
 103  * middle button click.
 104  */
 105
 106 /**
 107  * Log priority for internal logging messages.
 108  */
 109 enum libinput_log_priority {
 110         LIBINPUT_LOG_PRIORITY_DEBUG = 10,
 111         LIBINPUT_LOG_PRIORITY_INFO = 20,
 112         LIBINPUT_LOG_PRIORITY_ERROR = 30,
 113 };
 114
 115 /**
 116  * @ingroup device
 117  *
 118  * Capabilities on a device. A device may have one or more capabilities
 119  * at a time, and capabilities may appear or disappear during the
 120  * lifetime of the device.
 121  */
 122 enum libinput_device_capability {
 123         LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
 124         LIBINPUT_DEVICE_CAP_POINTER = 1,
 125         LIBINPUT_DEVICE_CAP_TOUCH = 2
 126 };
 127
 128 /**
 129  * @ingroup device
 130  *
 131  * Logical state of a key. Note that the logical state may not represent
 132  * the physical state of the key.
 133  */
 134 enum libinput_key_state {
 135         LIBINPUT_KEY_STATE_RELEASED = 0,
 136         LIBINPUT_KEY_STATE_PRESSED = 1
 137 };
 138
 139 /**
 140  * @ingroup device
 141  *
 142  * Mask reflecting LEDs on a device.
 143  */
 144 enum libinput_led {
 145         LIBINPUT_LED_NUM_LOCK = (1 << 0),
 146         LIBINPUT_LED_CAPS_LOCK = (1 << 1),
 147         LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
 148 };
 149
 150 /**
 151  * @ingroup device
 152  *
 153  * Logical state of a physical button. Note that the logical state may not
 154  * represent the physical state of the button.
 155  */
 156 enum libinput_button_state {
 157         LIBINPUT_BUTTON_STATE_RELEASED = 0,
 158         LIBINPUT_BUTTON_STATE_PRESSED = 1
 159 };
 160
 161
 162 /**
 163  * @ingroup device
 164  *
 165  * Axes on a device that are not x or y coordinates.
 166  */
 167 enum libinput_pointer_axis {
 168         LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0,
 169         LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1,
 170 };
 171
 172 /**
 173  * @ingroup base
 174  *
 175  * Event type for events returned by libinput_get_event().
 176  */
 177 enum libinput_event_type {
 178         /**
 179          * This is not a real event type, and is only used to tell the user that
 180          * no new event is available in the queue. See
 181          * libinput_next_event_type().
 182          */
 183         LIBINPUT_EVENT_NONE = 0,
 184
 185         /**
 186          * Signals that a device has been added to the context. The device will
 187          * not be read until the next time the user calls libinput_dispatch()
 188          * and data is available.
 189          *
 190          * This allows setting up initial device configuration before any events
 191          * are created.
 192          */
 193         LIBINPUT_EVENT_DEVICE_ADDED,
 194
 195         /**
 196          * Signals that a device has been removed. No more events from the
 197          * associated device will be in the queue or be queued after this event.
 198          */
 199         LIBINPUT_EVENT_DEVICE_REMOVED,
 200
 201         LIBINPUT_EVENT_KEYBOARD_KEY = 300,
 202
 203         LIBINPUT_EVENT_POINTER_MOTION = 400,
 204         LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
 205         LIBINPUT_EVENT_POINTER_BUTTON,
 206         LIBINPUT_EVENT_POINTER_AXIS,
 207
 208         LIBINPUT_EVENT_TOUCH_DOWN = 500,
 209         LIBINPUT_EVENT_TOUCH_UP,
 210         LIBINPUT_EVENT_TOUCH_MOTION,
 211         LIBINPUT_EVENT_TOUCH_CANCEL,
 212         /**
 213          * Signals the end of a set of touchpoints at one device sample
 214          * time. This event has no coordinate information attached.
 215          */
 216         LIBINPUT_EVENT_TOUCH_FRAME
 217 };
 218
 219 struct libinput;
 220 struct libinput_device;
 221 struct libinput_seat;
 222
 223 struct libinput_event;
 224 struct libinput_event_device_notify;
 225 struct libinput_event_keyboard;
 226 struct libinput_event_pointer;
 227
 228 /**
 229  * @ingroup event_touch
 230  * @struct libinput_event_touch
 231  *
 232  * Touch event representing a touch down, move or up, as well as a touch
 233  * cancel and touch frame events. Valid event types for this event are @ref
 234  * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
 235  * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
 236  * LIBINPUT_EVENT_TOUCH_FRAME.
 237  */
 238 struct libinput_event_touch;
 239
 240 /**
 241  * @defgroup event Accessing and destruction of events
 242  */
 243
 244 /**
 245  * @ingroup event
 246  *
 247  * Destroy the event.
 248  *
 249  * @param event An event retrieved by libinput_get_event().
 250  */
 251 void
 252 libinput_event_destroy(struct libinput_event *event);
 253
 254 /**
 255  * @ingroup event
 256  *
 257  * Get the type of the event.
 258  *
 259  * @param event An event retrieved by libinput_get_event().
 260  */
 261 enum libinput_event_type
 262 libinput_event_get_type(struct libinput_event *event);
 263
 264 /**
 265  * @ingroup event
 266  *
 267  * Get the libinput context from the event.
 268  *
 269  * @param event The libinput event
 270  * @return The libinput context for this event.
 271  */
 272 struct libinput *
 273 libinput_event_get_context(struct libinput_event *event);
 274
 275 /**
 276  * @ingroup event
 277  *
 278  * Return the device associated with this event, if applicable. For device
 279  * added/removed events this is the device added or removed. For all other
 280  * device events, this is the device that generated the event.
 281  *
 282  * This device is not refcounted and its lifetime is that of the event. Use
 283  * libinput_device_ref() before using the device outside of this scope.
 284  *
 285  * @return The device associated with this event
 286  */
 287
 288 struct libinput_device *
 289 libinput_event_get_device(struct libinput_event *event);
 290
 291 /**
 292  * @ingroup event
 293  *
 294  * Return the pointer event that is this input event. If the event type does
 295  * not match the pointer event types, this function returns NULL.
 296  *
 297  * The inverse of this function is libinput_event_pointer_get_base_event().
 298  *
 299  * @return A pointer event, or NULL for other events
 300  */
 301 struct libinput_event_pointer *
 302 libinput_event_get_pointer_event(struct libinput_event *event);
 303
 304 /**
 305  * @ingroup event
 306  *
 307  * Return the keyboard event that is this input event. If the event type does
 308  * not match the keyboard event types, this function returns NULL.
 309  *
 310  * The inverse of this function is libinput_event_keyboard_get_base_event().
 311  *
 312  * @return A keyboard event, or NULL for other events
 313  */
 314 struct libinput_event_keyboard *
 315 libinput_event_get_keyboard_event(struct libinput_event *event);
 316
 317 /**
 318  * @ingroup event
 319  *
 320  * Return the touch event that is this input event. If the event type does
 321  * not match the touch event types, this function returns NULL.
 322  *
 323  * The inverse of this function is libinput_event_touch_get_base_event().
 324  *
 325  * @return A touch event, or NULL for other events
 326  */
 327 struct libinput_event_touch *
 328 libinput_event_get_touch_event(struct libinput_event *event);
 329
 330 /**
 331  * @ingroup event
 332  *
 333  * Return the device event that is this input event. If the event type does
 334  * not match the device event types, this function returns NULL.
 335  *
 336  * The inverse of this function is
 337  * libinput_event_device_notify_get_base_event().
 338  *
 339  * @return A device event, or NULL for other events
 340  */
 341 struct libinput_event_device_notify *
 342 libinput_event_get_device_notify_event(struct libinput_event *event);
 343
 344 /**
 345  * @ingroup event
 346  *
 347  * @return The generic libinput_event of this event
 348  */
 349 struct libinput_event *
 350 libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
 351
 352 /**
 353  * @defgroup event_keyboard Keyboard events
 354  *
 355  * Key events are generated when a key changes its logical state, usually by
 356  * being pressed or released.
 357  */
 358
 359 /**
 360  * @ingroup event_keyboard
 361  *
 362  * @return The event time for this event
 363  */
 364 uint32_t
 365 libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
 366
 367 /**
 368  * @ingroup event_keyboard
 369  *
 370  * @return The keycode that triggered this key event
 371  */
 372 uint32_t
 373 libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
 374
 375 /**
 376  * @ingroup event_keyboard
 377  *
 378  * @return The state change of the key
 379  */
 380 enum libinput_key_state
 381 libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
 382
 383
 384 /**
 385  * @ingroup event_keyboard
 386  *
 387  * @return The generic libinput_event of this event
 388  */
 389 struct libinput_event *
 390 libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
 391
 392 /**
 393  * @ingroup event_keyboard
 394  *
 395  * For the key of a LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number
 396  * of keys pressed on all devices on the associated seat after the event was
 397  * triggered.
 398  *
 399  " @note It is an application bug to call this function for events other than
 400  * LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0.
 401  *
 402  * @return the seat wide pressed key count for the key of this event
 403  */
 404 uint32_t
 405 libinput_event_keyboard_get_seat_key_count(
 406         struct libinput_event_keyboard *event);
 407
 408 /**
 409  * @defgroup event_pointer Pointer events
 410  *
 411  * Pointer events reflect motion, button and scroll events, as well as
 412  * events from other axes.
 413  */
 414
 415 /**
 416  * @ingroup event_pointer
 417  *
 418  * @return The event time for this event
 419  */
 420 uint32_t
 421 libinput_event_pointer_get_time(struct libinput_event_pointer *event);
 422
 423 /**
 424  * @ingroup event_pointer
 425  *
 426  * Return the delta between the last event and the current event. For pointer
 427  * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
 428  * returns 0.
 429  *
 430  * If a device employs pointer acceleration, the delta returned by this
 431  * function is the accelerated delta.
 432  *
 433  * @note It is an application bug to call this function for events other than
 434  * LIBINPUT_EVENT_POINTER_MOTION.
 435  *
 436  * @return the relative x movement since the last event
 437  */
 438 double
 439 libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
 440
 441 /**
 442  * @ingroup event_pointer
 443  *
 444  * Return the delta between the last event and the current event. For pointer
 445  * events that are not of type LIBINPUT_EVENT_POINTER_MOTION, this function
 446  * returns 0.
 447  *
 448  * If a device employs pointer acceleration, the delta returned by this
 449  * function is the accelerated delta.
 450  *
 451  * @note It is an application bug to call this function for events other than
 452  * LIBINPUT_EVENT_POINTER_MOTION.
 453  *
 454  * @return the relative y movement since the last event
 455  */
 456 double
 457 libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
 458
 459 /**
 460  * @ingroup event_pointer
 461  *
 462  * Return the current absolute x coordinate of the pointer event, in mm from
 463  * the top left corner of the device. To get the corresponding output screen
 464  * coordinate, use libinput_event_pointer_get_absolute_x_transformed().
 465  *
 466  * For pointer events that are not of type
 467  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
 468  *
 469  * @note It is an application bug to call this function for events other than
 470  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
 471  *
 472  * @return the current absolute x coordinate
 473  */
 474 double
 475 libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
 476
 477 /**
 478  * @ingroup event_pointer
 479  *
 480  * Return the current absolute y coordinate of the pointer event, in mm from
 481  * the top left corner of the device. To get the corresponding output screen
 482  * coordinate, use libinput_event_pointer_get_absolute_y_transformed().
 483  *
 484  * For pointer events that are not of type
 485  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function returns 0.
 486  *
 487  * @note It is an application bug to call this function for events other than
 488  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
 489  *
 490  * @return the current absolute y coordinate
 491  */
 492 double
 493 libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
 494
 495 /**
 496  * @ingroup event_pointer
 497  *
 498  * Return the current absolute x coordinate of the pointer event, transformed to
 499  * screen coordinates.
 500  *
 501  * For pointer events that are not of type
 502  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
 503  * undefined.
 504  *
 505  * @note It is an application bug to call this function for events other than
 506  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
 507  *
 508  * @param event The libinput pointer event
 509  * @param width The current output screen width
 510  * @return the current absolute x coordinate transformed to a screen coordinate
 511  */
 512 double
 513 libinput_event_pointer_get_absolute_x_transformed(
 514         struct libinput_event_pointer *event,
 515         uint32_t width);
 516
 517 /**
 518  * @ingroup event_pointer
 519  *
 520  * Return the current absolute y coordinate of the pointer event, transformed to
 521  * screen coordinates.
 522  *
 523  * For pointer events that are not of type
 524  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is
 525  * undefined.
 526  *
 527  * @note It is an application bug to call this function for events other than
 528  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
 529  *
 530  * @param event The libinput pointer event
 531  * @param height The current output screen height
 532  * @return the current absolute y coordinate transformed to a screen coordinate
 533  */
 534 double
 535 libinput_event_pointer_get_absolute_y_transformed(
 536         struct libinput_event_pointer *event,
 537         uint32_t height);
 538
 539 /**
 540  * @ingroup event_pointer
 541  *
 542  * Return the button that triggered this event.
 543  * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
 544  * this function returns 0.
 545  *
 546  * @note It is an application bug to call this function for events other than
 547  * LIBINPUT_EVENT_POINTER_BUTTON.
 548  *
 549  * @return the button triggering this event
 550  */
 551 uint32_t
 552 libinput_event_pointer_get_button(struct libinput_event_pointer *event);
 553
 554 /**
 555  * @ingroup event_pointer
 556  *
 557  * Return the button state that triggered this event.
 558  * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
 559  * this function returns 0.
 560  *
 561  * @note It is an application bug to call this function for events other than
 562  * LIBINPUT_EVENT_POINTER_BUTTON.
 563  *
 564  * @return the button state triggering this event
 565  */
 566 enum libinput_button_state
 567 libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
 568
 569 /**
 570  * @ingroup event_pointer
 571  *
 572  * For the button of a LIBINPUT_EVENT_POINTER_BUTTON event, return the total
 573  * number of buttons pressed on all devices on the associated seat after the
 574  * the event was triggered.
 575  *
 576  " @note It is an application bug to call this function for events other than
 577  * LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function returns 0.
 578  *
 579  * @return the seat wide pressed button count for the key of this event
 580  */
 581 uint32_t
 582 libinput_event_pointer_get_seat_button_count(
 583         struct libinput_event_pointer *event);
 584
 585 /**
 586  * @ingroup event_pointer
 587  *
 588  * Return the axis that triggered this event.
 589  * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
 590  * this function returns 0.
 591  *
 592  * @note It is an application bug to call this function for events other than
 593  * LIBINPUT_EVENT_POINTER_AXIS.
 594  *
 595  * @return the axis triggering this event
 596  */
 597 enum libinput_pointer_axis
 598 libinput_event_pointer_get_axis(struct libinput_event_pointer *event);
 599
 600 /**
 601  * @ingroup event_pointer
 602  *
 603  * Return the axis value of the given axis. The interpretation of the value
 604  * is dependent on the axis. For the two scrolling axes
 605  * LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and
 606  * LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in
 607  * relative scroll units, with the positive direction being down or right,
 608  * respectively. The dimension of a scroll unit is equal to one unit of
 609  * motion in the respective axis, where applicable (e.g. touchpad two-finger
 610  * scrolling).
 611  *
 612  * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
 613  * this function returns 0.
 614  *
 615  * @note It is an application bug to call this function for events other than
 616  * LIBINPUT_EVENT_POINTER_AXIS.
 617  *
 618  * @return the axis value of this event
 619  */
 620 double
 621 libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event);
 622
 623 /**
 624  * @ingroup event_pointer
 625  *
 626  * @return The generic libinput_event of this event
 627  */
 628 struct libinput_event *
 629 libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
 630
 631
 632 /**
 633  * @defgroup event_touch Touch events
 634  *
 635  * Events from absolute touch devices.
 636  */
 637
 638 /**
 639  * @ingroup event_touch
 640  *
 641  * @return The event time for this event
 642  */
 643 uint32_t
 644 libinput_event_touch_get_time(struct libinput_event_touch *event);
 645
 646 /**
 647  * @ingroup event_touch
 648  *
 649  * Get the slot of this touch event. See the kernel's multitouch
 650  * protocol B documentation for more information.
 651  *
 652  * If the touch event has no assigned slot, for example if it is from a
 653  * single touch device, this function returns -1.
 654  *
 655  * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
 656  * LIBINPUT_EVENT_TOUCH_FRAME.
 657  *
 658  * @return The slot of this touch event
 659  */
 660 int32_t
 661 libinput_event_touch_get_slot(struct libinput_event_touch *event);
 662
 663 /**
 664  * @ingroup event_touch
 665  *
 666  * Get the seat slot of the touch event. A seat slot is a non-negative seat
 667  * wide unique identifier of an active touch point.
 668  *
 669  * Events from single touch devices will be represented as one individual
 670  * touch point per device.
 671  *
 672  * @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
 673  * LIBINPUT_EVENT_TOUCH_FRAME.
 674  *
 675  * @return The seat slot of the touch event
 676  */
 677 int32_t
 678 libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
 679
 680 /**
 681  * @ingroup event_touch
 682  *
 683  * Return the current absolute x coordinate of the touch event, in mm from
 684  * the top left corner of the device. To get the corresponding output screen
 685  * coordinate, use libinput_event_touch_get_x_transformed().
 686  *
 687  * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
 688  * LIBINPUT_EVENT_TOUCH_MOTION.
 689  *
 690  * @param event The libinput touch event
 691  * @return the current absolute x coordinate
 692  */
 693 double
 694 libinput_event_touch_get_x(struct libinput_event_touch *event);
 695
 696 /**
 697  * @ingroup event_touch
 698  *
 699  * Return the current absolute y coordinate of the touch event, in mm from
 700  * the top left corner of the device. To get the corresponding output screen
 701  * coordinate, use libinput_event_touch_get_y_transformed().
 702  *
 703  * For LIBINPUT_EVENT_TOUCH_UP 0 is returned.
 704  *
 705  * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
 706  * LIBINPUT_EVENT_TOUCH_MOTION.
 707  *
 708  * @param event The libinput touch event
 709  * @return the current absolute y coordinate
 710  */
 711 double
 712 libinput_event_touch_get_y(struct libinput_event_touch *event);
 713
 714 /**
 715  * @ingroup event_touch
 716  *
 717  * Return the current absolute x coordinate of the touch event, transformed to
 718  * screen coordinates.
 719  *
 720  * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
 721  * LIBINPUT_EVENT_TOUCH_MOTION.
 722  *
 723  * @param event The libinput touch event
 724  * @param width The current output screen width
 725  * @return the current absolute x coordinate transformed to a screen coordinate
 726  */
 727 double
 728 libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
 729                                        uint32_t width);
 730
 731 /**
 732  * @ingroup event_touch
 733  *
 734  * Return the current absolute y coordinate of the touch event, transformed to
 735  * screen coordinates.
 736  *
 737  * @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
 738  * LIBINPUT_EVENT_TOUCH_MOTION.
 739  *
 740  * @param event The libinput touch event
 741  * @param height The current output screen height
 742  * @return the current absolute y coordinate transformed to a screen coordinate
 743  */
 744 double
 745 libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
 746                                        uint32_t height);
 747
 748 /**
 749  * @ingroup event_touch
 750  *
 751  * @return The generic libinput_event of this event
 752  */
 753 struct libinput_event *
 754 libinput_event_touch_get_base_event(struct libinput_event_touch *event);
 755
 756 /**
 757  * @defgroup base Initialization and manipulation of libinput contexts
 758  */
 759
 760 struct libinput_interface {
 761         /**
 762          * Open the device at the given path with the flags provided and
 763          * return the fd.
 764          *
 765          * @param path The device path to open
 766          * @param flags Flags as defined by open(2)
 767          * @param user_data The user_data provided in
 768          * libinput_udev_create_context()
 769          *
 770          * @return the file descriptor, or a negative errno on failure.
 771          */
 772         int (*open_restricted)(const char *path, int flags, void *user_data);
 773         /**
 774          * Close the file descriptor.
 775          *
 776          * @param fd The file descriptor to close
 777          * @param user_data The user_data provided in
 778          * libinput_udev_create_context()
 779          */
 780         void (*close_restricted)(int fd, void *user_data);
 781 };
 782
 783 /**
 784  * @ingroup base
 785  *
 786  * Create a new libinput context from udev. This context is inactive until
 787  * assigned a seat ID with libinput_udev_assign_seat().
 788  *
 789  * @param interface The callback interface
 790  * @param user_data Caller-specific data passed to the various callback
 791  * interfaces.
 792  * @param udev An already initialized udev context
 793  *
 794  * @return An initialized, but inactive libinput context or NULL on error
 795  */
 796 struct libinput *
 797 libinput_udev_create_context(const struct libinput_interface *interface,
 798                              void *user_data,
 799                              struct udev *udev);
 800
 801 /**
 802  * @ingroup base
 803  *
 804  * Assign a seat to this libinput context. New devices or the removal of
 805  * existing devices will appear as events during libinput_dispatch().
 806  *
 807  * libinput_udev_assign_seat() succeeds even if no input devices are currently
 808  * available on this seat, or if devices are available but fail to open in
 809  * @ref libinput_interface::open_restricted. Devices that do not have the
 810  * minimum capabilities to be recognized as pointer, keyboard or touch
 811  * device are ignored. Such devices and those that failed to open
 812  * ignored until the next call to libinput_resume().
 813  *
 814  * This function may only be called once per context.
 815  *
 816  * @param libinput A libinput context initialized with
 817  * libinput_udev_create_context()
 818  * @param seat_id A seat identifier. This string must not be NULL.
 819  *
 820  * @return 0 on success or -1 on failure.
 821  */
 822 int
 823 libinput_udev_assign_seat(struct libinput *libinput,
 824                           const char *seat_id);
 825
 826 /**
 827  * @ingroup base
 828  *
 829  * Create a new libinput context that requires the caller to manually add or
 830  * remove devices with libinput_path_add_device() and
 831  * libinput_path_remove_device().
 832  *
 833  * The context is fully initialized but will not generate events until at
 834  * least one device has been added.
 835  *
 836  * The reference count of the context is initialized to 1. See @ref
 837  * libinput_unref.
 838  *
 839  * @param interface The callback interface
 840  * @param user_data Caller-specific data passed to the various callback
 841  * interfaces.
 842  *
 843  * @return An initialized, empty libinput context.
 844  */
 845 struct libinput *
 846 libinput_path_create_context(const struct libinput_interface *interface,
 847                              void *user_data);
 848
 849 /**
 850  * @ingroup base
 851  *
 852  * Add a device to a libinput context initialized with
 853  * libinput_path_create_context(). If successful, the device will be
 854  * added to the internal list and re-opened on libinput_resume(). The device
 855  * can be removed with libinput_path_remove_device().
 856  *
 857  * If the device was successfully initialized, it is returned in the device
 858  * argument. The lifetime of the returned device pointer is limited until
 859  * the next libinput_dispatch(), use libinput_device_ref() to keep a permanent
 860  * reference.
 861  *
 862  * @param libinput A previously initialized libinput context
 863  * @param path Path to an input device
 864  * @return The newly initiated device on success, or NULL on failure.
 865  *
 866  * @note It is an application bug to call this function on a libinput
 867  * context initialized with libinput_udev_create_context().
 868  */
 869 struct libinput_device *
 870 libinput_path_add_device(struct libinput *libinput,
 871                          const char *path);
 872
 873 /**
 874  * @ingroup base
 875  *
 876  * Remove a device from a libinput context initialized with
 877  * libinput_path_create_context() or added to such a context with
 878  * libinput_path_add_device().
 879  *
 880  * Events already processed from this input device are kept in the queue,
 881  * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
 882  * device.
 883  *
 884  * If no matching device exists, this function does nothing.
 885  *
 886  * @param device A libinput device
 887  *
 888  * @note It is an application bug to call this function on a libinput
 889  * context initialized with libinput_udev_create_context().
 890  */
 891 void
 892 libinput_path_remove_device(struct libinput_device *device);
 893
 894 /**
 895  * @ingroup base
 896  *
 897  * libinput keeps a single file descriptor for all events. Call into
 898  * libinput_dispatch() if any events become available on this fd.
 899  *
 900  * @return the file descriptor used to notify of pending events.
 901  */
 902 int
 903 libinput_get_fd(struct libinput *libinput);
 904
 905 /**
 906  * @ingroup base
 907  *
 908  * Main event dispatchment function. Reads events of the file descriptors
 909  * and processes them internally. Use libinput_get_event() to retrieve the
 910  * events.
 911  *
 912  * Dispatching does not necessarily queue libinput events.
 913  *
 914  * @param libinput A previously initialized libinput context
 915  *
 916  * @return 0 on success, or a negative errno on failure
 917  */
 918 int
 919 libinput_dispatch(struct libinput *libinput);
 920
 921 /**
 922  * @ingroup base
 923  *
 924  * Retrieve the next event from libinput's internal event queue.
 925  *
 926  * After handling the retrieved event, the caller must destroy it using
 927  * libinput_event_destroy().
 928  *
 929  * @param libinput A previously initialized libinput context
 930  * @return The next available event, or NULL if no event is available.
 931  */
 932 struct libinput_event *
 933 libinput_get_event(struct libinput *libinput);
 934
 935 /**
 936  * @ingroup base
 937  *
 938  * Return the type of the next event in the internal queue. This function
 939  * does not pop the event off the queue and the next call to
 940  * libinput_get_event() returns that event.
 941  *
 942  * @param libinput A previously initialized libinput context
 943  * @return The event type of the next available event or LIBINPUT_EVENT_NONE
 944  * if no event is availble.
 945  */
 946 enum libinput_event_type
 947 libinput_next_event_type(struct libinput *libinput);
 948
 949 /**
 950  * @ingroup base
 951  *
 952  * @param libinput A previously initialized libinput context
 953  * @return the caller-specific data previously assigned in
 954  * libinput_create_udev().
 955  */
 956 void *
 957 libinput_get_user_data(struct libinput *libinput);
 958
 959 /**
 960  * @ingroup base
 961  *
 962  * Resume a suspended libinput context. This re-enables device
 963  * monitoring and adds existing devices.
 964  *
 965  * @param libinput A previously initialized libinput context
 966  * @see libinput_suspend
 967  *
 968  * @return 0 on success or -1 on failure
 969  */
 970 int
 971 libinput_resume(struct libinput *libinput);
 972
 973 /**
 974  * @ingroup base
 975  *
 976  * Suspend monitoring for new devices and close existing devices.
 977  * This all but terminates libinput but does keep the context
 978  * valid to be resumed with libinput_resume().
 979  *
 980  * @param libinput A previously initialized libinput context
 981  */
 982 void
 983 libinput_suspend(struct libinput *libinput);
 984
 985 /**
 986  * @ingroup base
 987  *
 988  * Add a reference to the context. A context is destroyed whenever the
 989  * reference count reaches 0. See @ref libinput_unref.
 990  *
 991  * @param libinput A previously initialized valid libinput context
 992  * @return The passed libinput context
 993  */
 994 struct libinput *
 995 libinput_ref(struct libinput *libinput);
 996
 997 /**
 998  * @ingroup base
 999  *
1000  * Dereference the libinput context. After this, the context may have been
1001  * destroyed, if the last reference was dereferenced. If so, the context is
1002  * invalid and may not be interacted with.
1003  *
1004  * @param libinput A previously initialized libinput context
1005  * @return NULL if context was destroyed otherwise the passed context
1006  */
1007 struct libinput *
1008 libinput_unref(struct libinput *libinput);
1009
1010 /**
1011  * @ingroup base
1012  *
1013  * Set the global log priority. Messages with priorities equal to or
1014  * higher than the argument will be printed to the current log handler.
1015  *
1016  * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1017  *
1018  * @param libinput A previously initialized libinput context
1019  * @param priority The minimum priority of log messages to print.
1020  *
1021  * @see libinput_log_set_handler
1022  * @see libinput_log_get_priority
1023  */
1024 void
1025 libinput_log_set_priority(struct libinput *libinput,
1026                           enum libinput_log_priority priority);
1027
1028 /**
1029  * @ingroup base
1030  *
1031  * Get the global log priority. Messages with priorities equal to or
1032  * higher than the argument will be printed to the current log handler.
1033  *
1034  * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
1035  *
1036  * @param libinput A previously initialized libinput context
1037  * @return The minimum priority of log messages to print.
1038  *
1039  * @see libinput_log_set_handler
1040  * @see libinput_log_set_priority
1041  */
1042 enum libinput_log_priority
1043 libinput_log_get_priority(const struct libinput *libinput);
1044
1045 /**
1046  * @ingroup base
1047  *
1048  * Log handler type for custom logging.
1049  *
1050  * @param libinput The libinput context
1051  * @param priority The priority of the current message
1052  * @param format Message format in printf-style
1053  * @param args Message arguments
1054  *
1055  * @see libinput_set_log_priority
1056  * @see libinput_log_set_handler
1057  */
1058 typedef void (*libinput_log_handler)(struct libinput *libinput,
1059                                      enum libinput_log_priority priority,
1060                                      const char *format, va_list args)
1061            LIBINPUT_ATTRIBUTE_PRINTF(3, 0);
1062
1063 /**
1064  * @ingroup base
1065  *
1066  * Set the global log handler. Messages with priorities equal to or higher
1067  * than the current log priority will be passed to the given
1068  * log handler.
1069  *
1070  * The default log handler prints to stderr.
1071  *
1072  * @param libinput A previously initialized libinput context
1073  * @param log_handler The log handler for library messages.
1074  * @param user_data Caller-specific data pointer, passed into the log
1075  * handler.
1076  *
1077  * @see libinput_log_set_handler
1078  */
1079 void
1080 libinput_log_set_handler(struct libinput *libinput,
1081                          libinput_log_handler log_handler);
1082
1083 /**
1084  * @defgroup seat Initialization and manipulation of seats
1085  *
1086  * A seat has two identifiers, the physical name and the logical name. The
1087  * physical name is summarized as the list of devices a process on the same
1088  * physical seat has access to.
1089  *
1090  * The logical seat name is the seat name for a logical group of devices. A
1091  * compositor may use that to create additonal seats as independent device
1092  * sets. Alternatively, a compositor may limit itself to a single logical
1093  * seat, leaving a second compositor to manage devices on the other logical
1094  * seats.
1095  *
1096  * @code
1097  * +---+--------+------------+------------------------+------------+
1098  * |   | event0 |            |                        | log seat A |
1099  * | K +--------+            |                        +------------+
1100  * | e | event1 | phys seat0 |    libinput context 1  |            |
1101  * | r +--------+            |                        | log seat B |
1102  * | n | event2 |            |                        |            |
1103  * | e +--------+------------+------------------------+------------+
1104  * | l | event3 | phys seat1 |    libinput context 2  | log seat C |
1105  * +---+--------+------------+------------------------+------------+
1106  * @endcode
1107  */
1108
1109 /**
1110  * @ingroup seat
1111  *
1112  * Increase the refcount of the seat. A seat will be freed whenever the
1113  * refcount reaches 0. This may happen during dispatch if the
1114  * seat was removed from the system. A caller must ensure to reference
1115  * the seat correctly to avoid dangling pointers.
1116  *
1117  * @param seat A previously obtained seat
1118  * @return The passed seat
1119  */
1120 struct libinput_seat *
1121 libinput_seat_ref(struct libinput_seat *seat);
1122
1123 /**
1124  * @ingroup seat
1125  *
1126  * Decrease the refcount of the seat. A seat will be freed whenever the
1127  * refcount reaches 0. This may happen during dispatch if the
1128  * seat was removed from the system. A caller must ensure to reference
1129  * the seat correctly to avoid dangling pointers.
1130  *
1131  * @param seat A previously obtained seat
1132  * @return NULL if seat was destroyed, otherwise the passed seat
1133  */
1134 struct libinput_seat *
1135 libinput_seat_unref(struct libinput_seat *seat);
1136
1137 /**
1138  * @ingroup seat
1139  *
1140  * Set caller-specific data associated with this seat. libinput does
1141  * not manage, look at, or modify this data. The caller must ensure the
1142  * data is valid.
1143  *
1144  * @param seat A previously obtained seat
1145  * @param user_data Caller-specific data pointer
1146  * @see libinput_seat_get_user_data
1147  */
1148 void
1149 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
1150
1151 /**
1152  * @ingroup seat
1153  *
1154  * Get the caller-specific data associated with this seat, if any.
1155  *
1156  * @param seat A previously obtained seat
1157  * @return Caller-specific data pointer or NULL if none was set
1158  * @see libinput_seat_set_user_data
1159  */
1160 void *
1161 libinput_seat_get_user_data(struct libinput_seat *seat);
1162
1163 /**
1164  * @ingroup seat
1165  *
1166  * Return the physical name of the seat. For libinput contexts created from
1167  * udev, this is always the same value as passed into
1168  * libinput_udev_assign_seat() and all seats from that context will have
1169  * the same physical name.
1170  *
1171  * The physical name of the seat is one that is usually set by the system or
1172  * lower levels of the stack. In most cases, this is the base filter for
1173  * devices - devices assigned to seats outside the current seat will not
1174  * be available to the caller.
1175  *
1176  * @param seat A previously obtained seat
1177  * @return the physical name of this seat
1178  */
1179 const char *
1180 libinput_seat_get_physical_name(struct libinput_seat *seat);
1181
1182 /**
1183  * @ingroup seat
1184  *
1185  * Return the logical name of the seat. This is an identifier to group sets
1186  * of devices within the compositor.
1187  *
1188  * @param seat A previously obtained seat
1189  * @return the logical name of this seat
1190  */
1191 const char *
1192 libinput_seat_get_logical_name(struct libinput_seat *seat);
1193
1194 /**
1195  * @defgroup device Initialization and manipulation of input devices
1196  */
1197
1198 /**
1199  * @ingroup device
1200  *
1201  * Increase the refcount of the input device. An input device will be freed
1202  * whenever the refcount reaches 0. This may happen during dispatch if the
1203  * device was removed from the system. A caller must ensure to reference
1204  * the device correctly to avoid dangling pointers.
1205  *
1206  * @param device A previously obtained device
1207  * @return The passed device
1208  */
1209 struct libinput_device *
1210 libinput_device_ref(struct libinput_device *device);
1211
1212 /**
1213  * @ingroup device
1214  *
1215  * Decrease the refcount of the input device. An input device will be freed
1216  * whenever the refcount reaches 0. This may happen during dispatch if the
1217  * device was removed from the system. A caller must ensure to reference
1218  * the device correctly to avoid dangling pointers.
1219  *
1220  * @param device A previously obtained device
1221  * @return NULL if device was destroyed, otherwise the passed device
1222  */
1223 struct libinput_device *
1224 libinput_device_unref(struct libinput_device *device);
1225
1226 /**
1227  * @ingroup device
1228  *
1229  * Set caller-specific data associated with this input device. libinput does
1230  * not manage, look at, or modify this data. The caller must ensure the
1231  * data is valid.
1232  *
1233  * @param device A previously obtained device
1234  * @param user_data Caller-specific data pointer
1235  * @see libinput_device_get_user_data
1236  */
1237 void
1238 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
1239
1240 /**
1241  * @ingroup device
1242  *
1243  * Get the caller-specific data associated with this input device, if any.
1244  *
1245  * @param device A previously obtained device
1246  * @return Caller-specific data pointer or NULL if none was set
1247  * @see libinput_device_set_user_data
1248  */
1249 void *
1250 libinput_device_get_user_data(struct libinput_device *device);
1251
1252 /**
1253  * @ingroup device
1254  *
1255  * Get the system name of the device.
1256  *
1257  * To get the descriptive device name, use libinput_device_get_name().
1258  *
1259  * @param device A previously obtained device
1260  * @return System name of the device
1261  *
1262  */
1263 const char *
1264 libinput_device_get_sysname(struct libinput_device *device);
1265
1266 /**
1267  * @ingroup device
1268  *
1269  * The descriptive device name as advertised by the kernel and/or the
1270  * hardware itself. To get the sysname for this device, use
1271  * libinput_device_get_sysname().
1272  *
1273  * The lifetime of the returned string is tied to the struct
1274  * libinput_device. The string may be the empty string but is never NULL.
1275  *
1276  * @param device A previously obtained device
1277  * @return The device name
1278  */
1279 const char *
1280 libinput_device_get_name(struct libinput_device *device);
1281
1282 /**
1283  * @ingroup device
1284  *
1285  * Get the product ID for this device.
1286  *
1287  * @param device A previously obtained device
1288  * @return The product ID of this device
1289  */
1290 unsigned int
1291 libinput_device_get_id_product(struct libinput_device *device);
1292
1293 /**
1294  * @ingroup device
1295  *
1296  * Get the vendor ID for this device.
1297  *
1298  * @param device A previously obtained device
1299  * @return The vendor ID of this device
1300  */
1301 unsigned int
1302 libinput_device_get_id_vendor(struct libinput_device *device);
1303
1304 /**
1305  * @ingroup device
1306  *
1307  * A device may be mapped to a single output, or all available outputs. If a
1308  * device is mapped to a single output only, a relative device may not move
1309  * beyond the boundaries of this output. An absolute device has its input
1310  * coordinates mapped to the extents of this output.
1311  *
1312  * @return the name of the output this device is mapped to, or NULL if no
1313  * output is set
1314  */
1315 const char *
1316 libinput_device_get_output_name(struct libinput_device *device);
1317
1318 /**
1319  * @ingroup device
1320  *
1321  * Get the seat associated with this input device.
1322  *
1323  * A seat can be uniquely identified by the physical and logical seat name.
1324  * There will ever be only one seat instance with a given physical and logical
1325  * seat name pair at any given time, but if no external reference is kept, it
1326  * may be destroyed if no device belonging to it is left.
1327  *
1328  * @param device A previously obtained device
1329  * @return The seat this input device belongs to
1330  */
1331 struct libinput_seat *
1332 libinput_device_get_seat(struct libinput_device *device);
1333
1334 /**
1335  * @ingroup device
1336  *
1337  * Update the LEDs on the device, if any. If the device does not have
1338  * LEDs, or does not have one or more of the LEDs given in the mask, this
1339  * function does nothing.
1340  *
1341  * @param device A previously obtained device
1342  * @param leds A mask of the LEDs to set, or unset.
1343  */
1344 void
1345 libinput_device_led_update(struct libinput_device *device,
1346                            enum libinput_led leds);
1347
1348 /**
1349  * @ingroup device
1350  *
1351  * Set the bitmask in keys to the bitmask of the keys present on the device
1352  * (see linux/input.h), up to size characters.
1353  *
1354  * @param device A current input device
1355  * @param keys An array filled with the bitmask for the keys
1356  * @param size Size of the keys array
1357  *
1358  * @return The number of valid bytes in keys, or a negative errno on failure
1359  */
1360 int
1361 libinput_device_get_keys(struct libinput_device *device,
1362                          char *keys, size_t size)
1363         LIBINPUT_ATTRIBUTE_DEPRECATED;
1364
1365 /**
1366  * @ingroup device
1367  *
1368  * Apply the 3x3 transformation matrix to absolute device coordinates. This
1369  * matrix has no effect on relative events.
1370  *
1371  * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
1372  * @code
1373  * [ a  b  c ]   [ x ]
1374  * [ d  e  f ] * [ y ]
1375  * [ 0  0  1 ]   [ 1 ]
1376  * @endcode
1377  */
1378 void
1379 libinput_device_calibrate(struct libinput_device *device,
1380                           float calibration[6]);
1381
1382 /**
1383  * @ingroup device
1384  *
1385  * Check if the given device has the specified capability
1386  *
1387  * @return 1 if the given device has the capability or 0 if not
1388  */
1389 int
1390 libinput_device_has_capability(struct libinput_device *device,
1391                                enum libinput_device_capability capability);
1392
1393 /**
1394  * @ingroup device
1395  *
1396  * Get the physical size of a device in mm, where meaningful. This function
1397  * only succeeds on devices with the required data, i.e. tablets, touchpads
1398  * and touchscreens.
1399  *
1400  * If this function returns nonzero, width and height are unmodified.
1401  *
1402  * @param device The device
1403  * @param width Set to the width of the device
1404  * @param height Set to the height of the device
1405  * @return 0 on success, or nonzero otherwise
1406  */
1407 int
1408 libinput_device_get_size(struct libinput_device *device,
1409                          double *width,
1410                          double *height);
1411
1412
1413 /**
1414  * @defgroup config Device configuration
1415  *
1416  * Enable, disable, change and/or check for device-specific features. For
1417  * all features, libinput assigns a default based on the hardware
1418  * configuration. This default can be obtained with the respective
1419  * get_default call.
1420  *
1421  * Some configuration option may be dependent on or mutually exclusive with
1422  * with other options. The behavior in those cases is
1423  * implementation-defined, the caller must ensure that the options are set
1424  * in the right order.
1425  */
1426
1427 /**
1428  * @ingroup config
1429  *
1430  * Status codes returned when applying configuration settings.
1431  */
1432 enum libinput_config_status {
1433         LIBINPUT_CONFIG_STATUS_SUCCESS = 0,     /**< Config applied successfully */
1434         LIBINPUT_CONFIG_STATUS_UNSUPPORTED,     /**< Configuration not available on
1435                                                      this device */
1436         LIBINPUT_CONFIG_STATUS_INVALID,         /**< Invalid parameter range */
1437 };
1438
1439 /**
1440  * @ingroup config
1441  *
1442  * Return a string describing the error.
1443  *
1444  * @param status The status to translate to a string
1445  * @return A human-readable string representing the error or NULL for an
1446  * invalid status.
1447  */
1448 const char *
1449 libinput_config_status_to_str(enum libinput_config_status status);
1450
1451 /**
1452  * @ingroup config
1453  */
1454 enum libinput_config_tap_state {
1455         LIBINPUT_CONFIG_TAP_DISABLED, /**< Tapping is to be disabled, or is
1456                                         currently disabled */
1457         LIBINPUT_CONFIG_TAP_ENABLED, /**< Tapping is to be enabled, or is
1458                                        currently enabled */
1459 };
1460
1461 /**
1462  * @ingroup config
1463  *
1464  * Check if the device supports tap-to-click. See
1465  * libinput_device_config_tap_set_enabled() for more information.
1466  *
1467  * @param device The device to configure
1468  * @return The number of fingers that can generate a tap event, or 0 if the
1469  * device does not support tapping.
1470  *
1471  * @see libinput_device_config_tap_set_enabled
1472  * @see libinput_device_config_tap_get_enabled
1473  * @see libinput_device_config_tap_set_enabled_get_default
1474  */
1475 int
1476 libinput_device_config_tap_get_finger_count(struct libinput_device *device);
1477
1478 /**
1479  * @ingroup config
1480  *
1481  * Enable or disable tap-to-click on this device, with a default mapping of
1482  * 1, 2, 3 finger tap mapping to left, right, middle click, respectively.
1483  * Tapping is limited by the number of simultaneous touches
1484  * supported by the device, see
1485  * libinput_device_config_tap_get_finger_count().
1486  *
1487  * @param device The device to configure
1488  * @param enable @ref LIBINPUT_CONFIG_TAP_ENABLED to enable tapping or @ref
1489  * LIBINPUT_CONFIG_TAP_DISABLED to disable tapping
1490  *
1491  * @return A config status code. Disabling tapping on a device that does not
1492  * support tapping always succeeds.
1493  *
1494  * @see libinput_device_config_tap_get_finger_count
1495  * @see libinput_device_config_tap_get_enabled
1496  * @see libinput_device_config_tap_get_default_enabled
1497  */
1498 enum libinput_config_status
1499 libinput_device_config_tap_set_enabled(struct libinput_device *device,
1500                                        enum libinput_config_tap_state enable);
1501
1502 /**
1503  * @ingroup config
1504  *
1505  * Check if tap-to-click is enabled on this device. If the device does not
1506  * support tapping, this function always returns 0.
1507  *
1508  * @param device The device to configure
1509  *
1510  * @return @ref LIBINPUT_CONFIG_TAP_ENABLED if tapping is currently enabled,
1511  * or @ref LIBINPUT_CONFIG_TAP_DISABLED is currently disabled
1512  *
1513  * @see libinput_device_config_tap_get_finger_count
1514  * @see libinput_device_config_tap_set_enabled
1515  * @see libinput_device_config_tap_get_default_enabled
1516  */
1517 enum libinput_config_tap_state
1518 libinput_device_config_tap_get_enabled(struct libinput_device *device);
1519
1520 /**
1521  * @ingroup config
1522  *
1523  * Return the default setting for whether tapping is enabled on this device.
1524  *
1525  * @param device The device to configure
1526  * @return @ref LIBINPUT_CONFIG_TAP_ENABLED if tapping is enabled by default,
1527  * or @ref LIBINPUT_CONFIG_TAP_DISABLED is disabled by default
1528  *
1529  * @see libinput_device_config_tap_get_finger_count
1530  * @see libinput_device_config_tap_set_enabled
1531  * @see libinput_device_config_tap_get_enabled
1532  */
1533 enum libinput_config_tap_state
1534 libinput_device_config_tap_get_default_enabled(struct libinput_device *device);
1535
1536 #ifdef __cplusplus
1537 }
1538 #endif
1539 #endif /* LIBINPUT_H */