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