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