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 #include <stdlib.h>
  27 #include <stdint.h>
  28 #include <libudev.h>
  29
  30 /**
  31  * @mainpage
  32  * libinput is a generic input device handling library. It abstracts
  33  * commonly-used concepts such as keyboard, pointer and touchpad handling
  34  * behind an API.
  35  */
  36
  37 /**
  38  * @ingroup fixed_point
  39  *
  40  * libinput 24.8 fixed point real number.
  41  */
  42 typedef int32_t li_fixed_t;
  43
  44 /**
  45  * @ingroup device
  46  *
  47  * Capabilities on a device. A device may have one or more capabilities
  48  * at a time, and capabilities may appear or disappear during the
  49  * lifteime of the device.
  50  */
  51 enum libinput_device_capability {
  52         LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
  53         LIBINPUT_DEVICE_CAP_POINTER = 1,
  54         LIBINPUT_DEVICE_CAP_TOUCH = 2
  55 };
  56
  57 /**
  58  * @ingroup device
  59  *
  60  * Logical state of a key. Note that the logical state may not represent
  61  * the physical state of the key.
  62  */
  63 enum libinput_keyboard_key_state {
  64         LIBINPUT_KEYBOARD_KEY_STATE_RELEASED = 0,
  65         LIBINPUT_KEYBOARD_KEY_STATE_PRESSED = 1
  66 };
  67
  68 /**
  69  * @ingroup device
  70  *
  71  * Mask reflecting LEDs on a device.
  72  */
  73 enum libinput_led {
  74         LIBINPUT_LED_NUM_LOCK = (1 << 0),
  75         LIBINPUT_LED_CAPS_LOCK = (1 << 1),
  76         LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
  77 };
  78
  79 /**
  80  * @ingroup device
  81  *
  82  * Logical state of a physical button. Note that the logical state may not
  83  * represent the physical state of the button.
  84  */
  85 enum libinput_pointer_button_state {
  86         LIBINPUT_POINTER_BUTTON_STATE_RELEASED = 0,
  87         LIBINPUT_POINTER_BUTTON_STATE_PRESSED = 1
  88 };
  89
  90
  91 /**
  92  * @ingroup device
  93  *
  94  * Axes on a device that are not x or y coordinates.
  95  */
  96 enum libinput_pointer_axis {
  97         LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = 0,
  98         LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = 1
  99 };
 100
 101 /**
 102  * @ingroup device
 103  *
 104  * Logical touch state of a touch point. A touch point usually follows the
 105  * sequence down, motion, up, with the number of motion events being zero or
 106  * greater. If a touch point was used for gesture interpretation internally
 107  * and will not generate any further events, the touchpoint is cancelled.
 108  */
 109 enum libinput_touch_type {
 110         LIBINPUT_TOUCH_TYPE_DOWN = 0,
 111         LIBINPUT_TOUCH_TYPE_UP = 1,
 112         LIBINPUT_TOUCH_TYPE_MOTION = 2,
 113         LIBINPUT_TOUCH_TYPE_CANCEL = 4
 114 };
 115
 116 /**
 117  * @ingroup base
 118  *
 119  * Event type for events returned by libinput_get_event().
 120  */
 121 enum libinput_event_type {
 122         LIBINPUT_EVENT_NONE = 0,
 123         LIBINPUT_EVENT_DEVICE_ADDED,
 124         LIBINPUT_EVENT_DEVICE_REMOVED,
 125
 126         LIBINPUT_EVENT_KEYBOARD_KEY = 300,
 127
 128         LIBINPUT_EVENT_POINTER_MOTION = 400,
 129         LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
 130         LIBINPUT_EVENT_POINTER_BUTTON,
 131         LIBINPUT_EVENT_POINTER_AXIS,
 132
 133         LIBINPUT_EVENT_TOUCH_TOUCH = 500,
 134         /**
 135          * Signals the end of a set of touchpoints at one device sample
 136          * time. This event has no coordinate information attached.
 137          */
 138         LIBINPUT_EVENT_TOUCH_FRAME
 139 };
 140
 141 struct libinput;
 142 struct libinput_device;
 143 struct libinput_seat;
 144
 145 struct libinput_event;
 146 struct libinput_event_device_notify;
 147 struct libinput_event_keyboard;
 148 struct libinput_event_pointer;
 149
 150 /**
 151  * @ingroup event_touch
 152  * @struct libinput_event_touch
 153  *
 154  * Touch event representing a touch down, move or up, as well as a touch
 155  * cancel and touch frame events. Valid event types for this event are @ref
 156  * LIBINPUT_EVENT_TOUCH_TOUCH and @ref LIBINPUT_EVENT_TOUCH_FRAME.
 157  */
 158 struct libinput_event_touch;
 159
 160 /**
 161  * @defgroup fixed_point Fixed point utilities
 162  */
 163
 164 /**
 165  * @ingroup fixed_point
 166  *
 167  * Convert li_fixed_t to a double
 168  *
 169  * @param f fixed point number
 170  * @return Converted double
 171  */
 172 static inline double
 173 li_fixed_to_double (li_fixed_t f)
 174 {
 175         union {
 176                 double d;
 177                 int64_t i;
 178         } u;
 179
 180         u.i = ((1023LL + 44LL) << 52) + (1LL << 51) + f;
 181
 182         return u.d - (3LL << 43);
 183 }
 184
 185 /**
 186  * @ingroup fixed_point
 187  *
 188  * Convert li_fixed_t to a int. The fraction part is discarded.
 189  *
 190  * @param f fixed point number
 191  * @return Converted int
 192  */
 193 static inline int
 194 li_fixed_to_int(li_fixed_t f)
 195 {
 196         return f / 256;
 197 }
 198
 199 /**
 200  * @defgroup event Acessing and destruction of events
 201  */
 202
 203 /**
 204  * @ingroup event
 205  *
 206  * Destroy the event.
 207  *
 208  * @param event An event retrieved by libinput_get_event().
 209  */
 210 void
 211 libinput_event_destroy(struct libinput_event *event);
 212
 213 /**
 214  * @ingroup event
 215  *
 216  * Get the type of the event.
 217  *
 218  * @param event An event retrieved by libinput_get_event().
 219  */
 220 enum libinput_event_type
 221 libinput_event_get_type(struct libinput_event *event);
 222
 223 /**
 224  * @ingroup event
 225  *
 226  * Get the libinput context from the event.
 227  *
 228  * @param event The libinput event
 229  * @return The libinput context for this event.
 230  */
 231 struct libinput *
 232 libinput_event_get_context(struct libinput_event *event);
 233
 234 /**
 235  * @ingroup event
 236  *
 237  * Return the device associated with this event, if applicable. For device
 238  * added/removed events this is the device added or removed. For all other
 239  * device events, this is the device that generated the event.
 240  *
 241  * This device is not refcounted and its lifetime is that of the event. Use
 242  * libinput_device_ref() before using the device outside of this scope.
 243  *
 244  * @return The device associated with this event
 245  */
 246
 247 struct libinput_device *
 248 libinput_event_get_device(struct libinput_event *event);
 249
 250 /**
 251  * @ingroup event
 252  *
 253  * Return the pointer event that is this input event. If the event type does
 254  * not match the pointer event types, this function returns NULL.
 255  *
 256  * @return A pointer event, or NULL for other events
 257  */
 258 struct libinput_event_pointer *
 259 libinput_event_get_pointer_event(struct libinput_event *event);
 260
 261 /**
 262  * @ingroup event
 263  *
 264  * Return the keyboard event that is this input event. If the event type does
 265  * not match the keyboard event types, this function returns NULL.
 266  *
 267  * @return A keyboard event, or NULL for other events
 268  */
 269 struct libinput_event_keyboard *
 270 libinput_event_get_keyboard_event(struct libinput_event *event);
 271
 272 /**
 273  * @ingroup event
 274  *
 275  * Return the touch event that is this input event. If the event type does
 276  * not match the touch event types, this function returns NULL.
 277  *
 278  * @return A touch event, or NULL for other events
 279  */
 280 struct libinput_event_touch *
 281 libinput_event_get_touch_event(struct libinput_event *event);
 282
 283 /**
 284  * @ingroup event
 285  *
 286  * Return the device event that is this input event. If the event type does
 287  * not match the device event types, this function returns NULL.
 288  *
 289  * @return A device event, or NULL for other events
 290  */
 291 struct libinput_event_device_notify *
 292 libinput_event_get_device_notify_event(struct libinput_event *event);
 293
 294 /**
 295  * @defgroup event_keyboard Keyboard events
 296  *
 297  * Key events are generated when a key changes its logical state, usually by
 298  * being pressed or released.
 299  */
 300
 301 /**
 302  * @ingroup event_keyboard
 303  *
 304  * @return The event time for this event
 305  */
 306 uint32_t
 307 libinput_event_keyboard_get_time(
 308         struct libinput_event_keyboard *event);
 309
 310 /**
 311  * @ingroup event_keyboard
 312  *
 313  * @return The keycode that triggered this key event
 314  */
 315 uint32_t
 316 libinput_event_keyboard_get_key(
 317         struct libinput_event_keyboard *event);
 318
 319 /**
 320  * @ingroup event_keyboard
 321  *
 322  * @return The state change of the key
 323  */
 324 enum libinput_keyboard_key_state
 325 libinput_event_keyboard_get_key_state(
 326         struct libinput_event_keyboard *event);
 327
 328 /**
 329  * @defgroup event_pointer Pointer events
 330  *
 331  * Pointer events reflect motion, button and scroll events, as well as
 332  * events from other axes.
 333  */
 334
 335 /**
 336  * @ingroup event_pointer
 337  *
 338  * @return The event time for this event
 339  */
 340 uint32_t
 341 libinput_event_pointer_get_time(
 342         struct libinput_event_pointer *event);
 343
 344 /**
 345  * @ingroup event_pointer
 346  *
 347  * Return the delta between the last event and the current event. The axis'
 348  * positive direction is device-specific. For pointer events that are
 349  * not of type LIBINPUT_EVENT_POINTER_MOTION, this function returns 0.
 350  *
 351  * @note It is an application bug to call this function for events other than
 352  * LIBINPUT_EVENT_POINTER_MOTION.
 353  *
 354  * @return the relative x movement since the last event
 355  */
 356 li_fixed_t
 357 libinput_event_pointer_get_dx(
 358         struct libinput_event_pointer *event);
 359
 360 /**
 361  * @ingroup event_pointer
 362  *
 363  * Return the delta between the last event and the current event. The
 364  * axis' positive direction is device-specific. For pointer events that are
 365  * not of type LIBINPUT_EVENT_POINTER_MOTION, this function returns 0.
 366  *
 367  * @note It is an application bug to call this function for events other than
 368  * LIBINPUT_EVENT_POINTER_MOTION.
 369  *
 370  * @return the relative y movement since the last event
 371  */
 372 li_fixed_t
 373 libinput_event_pointer_get_dy(
 374         struct libinput_event_pointer *event);
 375
 376 /**
 377  * @ingroup event_pointer
 378  *
 379  * Return the absolute x coordinate of the device, scaled to screen
 380  * coordinates.
 381  * The axes' positive direction is device-specific. For pointer events that
 382  * are not of type LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function
 383  * returns 0.
 384  *
 385  * @note It is an application bug to call this function for events other than
 386  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
 387  *
 388  * @return the current absolute x coordinate scaled to screen coordinates.
 389  */
 390 li_fixed_t
 391 libinput_event_pointer_get_absolute_x(
 392         struct libinput_event_pointer *event);
 393
 394 /**
 395  * @ingroup event_pointer
 396  *
 397  * Return the absolute y coordinate of the device, scaled to screen coordinates.
 398  * The axes' positive direction is device-specific. For pointer events that
 399  * are not of type LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, this function
 400  * returns 0.
 401  *
 402  * @note It is an application bug to call this function for events other than
 403  * LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
 404  *
 405  * @return the current absolute y coordinate scaled to screen coordinates.
 406  */
 407 li_fixed_t
 408 libinput_event_pointer_get_absolute_y(
 409         struct libinput_event_pointer *event);
 410
 411 /**
 412  * @ingroup event_pointer
 413  *
 414  * Return the button that triggered this event.
 415  * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
 416  * this function returns 0.
 417  *
 418  * @note It is an application bug to call this function for events other than
 419  * LIBINPUT_EVENT_POINTER_BUTTON.
 420  *
 421  * @return the button triggering this event
 422  */
 423 uint32_t
 424 libinput_event_pointer_get_button(
 425         struct libinput_event_pointer *event);
 426
 427 /**
 428  * @ingroup event_pointer
 429  *
 430  * Return the button state that triggered this event.
 431  * For pointer events that are not of type LIBINPUT_EVENT_POINTER_BUTTON,
 432  * this function returns 0.
 433  *
 434  * @note It is an application bug to call this function for events other than
 435  * LIBINPUT_EVENT_POINTER_BUTTON.
 436  *
 437  * @return the button state triggering this event
 438  */
 439 enum libinput_pointer_button_state
 440 libinput_event_pointer_get_button_state(
 441         struct libinput_event_pointer *event);
 442
 443 /**
 444  * @ingroup event_pointer
 445  *
 446  * Return the axis that triggered this event.
 447  * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
 448  * this function returns 0.
 449  *
 450  * @note It is an application bug to call this function for events other than
 451  * LIBINPUT_EVENT_POINTER_AXIS.
 452  *
 453  * @return the axis triggering this event
 454  */
 455 enum libinput_pointer_axis
 456 libinput_event_pointer_get_axis(
 457         struct libinput_event_pointer *event);
 458
 459 /**
 460  * @ingroup event_pointer
 461  *
 462  * Return the axis value of the given axis. The interpretation of the value
 463  * is dependent on the axis. For the two scrolling axes
 464  * LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL and
 465  * LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL, the value of the event is in
 466  * relative scroll units, with the positive direction being down or right,
 467  * respectively. The dimension of a scroll unit is equal to one unit of
 468  * motion in the respective axis, where applicable (e.g. touchpad two-finger
 469  * scrolling).
 470  *
 471  * For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS,
 472  * this function returns 0.
 473  *
 474  * @note It is an application bug to call this function for events other than
 475  * LIBINPUT_EVENT_POINTER_AXIS.
 476  *
 477  * @return the axis value of this event
 478  */
 479 li_fixed_t
 480 libinput_event_pointer_get_axis_value(
 481         struct libinput_event_pointer *event);
 482
 483 /**
 484  * @defgroup event_touch Touch events
 485  *
 486  * Events from absolute touch devices.
 487  */
 488
 489 /**
 490  * @ingroup event_touch
 491  *
 492  * @return The event time for this event
 493  */
 494 uint32_t
 495 libinput_event_touch_get_time(
 496         struct libinput_event_touch *event);
 497
 498 /**
 499  * @ingroup event_touch
 500  *
 501  * Get the currently active slot on this device. See the kernel's multitouch
 502  * protocol B documentation for more information.
 503  *
 504  * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
 505  *
 506  * @return The currently active slot on this multitouch device
 507  */
 508 uint32_t
 509 libinput_event_touch_get_slot(
 510         struct libinput_event_touch *event);
 511
 512 /**
 513  * @ingroup event_touch
 514  *
 515  * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
 516  *
 517  * @return the absolute X coordinate on this touch device, scaled to screen coordinates.
 518  */
 519 li_fixed_t
 520 libinput_event_touch_get_x(
 521         struct libinput_event_touch *event);
 522
 523 /**
 524  * @ingroup event_touch
 525  *
 526  * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
 527  *
 528  * @return the absolute X coordinate on this touch device, scaled to screen coordinates.
 529  */
 530 li_fixed_t
 531 libinput_event_touch_get_y(
 532         struct libinput_event_touch *event);
 533
 534 /**
 535  * @ingroup event_touch
 536  *
 537  * @note this function should not be called for LIBINPUT_EVENT_TOUCH_FRAME.
 538  *
 539  * @return the type of touch that occured on the device
 540  */
 541 enum libinput_touch_type
 542 libinput_event_touch_get_touch_type(
 543         struct libinput_event_touch *event);
 544
 545 /**
 546  * @defgroup base Initialization and manipulation of libinput contexts
 547  */
 548
 549 struct libinput_interface {
 550         /**
 551          * Open the device at the given path with the flags provided and
 552          * return the fd.
 553          *
 554          * @param path The device path to open
 555          * @param flags Flags as defined by open(2)
 556          * @param user_data The user_data provided in
 557          * libinput_create_from_udev()
 558          *
 559          * @return the file descriptor, or a negative errno on failure.
 560          */
 561         int (*open_restricted)(const char *path, int flags, void *user_data);
 562         /**
 563          * Close the file descriptor.
 564          *
 565          * @param fd The file descriptor to close
 566          * @param user_data The user_data provided in
 567          * libinput_create_from_udev()
 568          */
 569         void (*close_restricted)(int fd, void *user_data);
 570
 571         void (*get_current_screen_dimensions)(struct libinput_device *device,
 572                                               int *width,
 573                                               int *height,
 574                                               void *user_data);
 575 };
 576
 577 /**
 578  * @ingroup base
 579  *
 580  * Create a new libinput context from udev, for input devices matching
 581  * the given seat ID. New devices or devices removed will appear as events
 582  * during libinput_dispatch.
 583  *
 584  * @param interface The callback interface
 585  * @param user_data Caller-specific data passed to the various callback
 586  * interfaces.
 587  * @param udev An already initialized udev context
 588  * @param seat_id A seat identifier. This string must not be NULL.
 589  *
 590  * @return An initialized libinput context, ready to handle events or NULL on
 591  * error.
 592  */
 593 struct libinput *
 594 libinput_create_from_udev(const struct libinput_interface *interface,
 595                           void *user_data,
 596                           struct udev *udev,
 597                           const char *seat_id);
 598 /**
 599  * @ingroup base
 600  *
 601  * Create a new libinput context from the given path. This context
 602  * represents one single device only, it will not respond to new devices
 603  * being added and reading from the device after it was removed will fail.
 604  *
 605  * @param interface The callback interface
 606  * @param user_data Caller-specific data passed to the various callback
 607  * interfaces.
 608  * @param path Path to an input device
 609  *
 610  * @return An initialized libinput context, ready to handle events or NULL on
 611  * error.
 612  */
 613 struct libinput *
 614 libinput_create_from_path(const struct libinput_interface *interface,
 615                           void *user_data,
 616                           const char *path);
 617
 618 /**
 619  * @ingroup base
 620  *
 621  * libinput keeps a single file descriptor for all events. Call into
 622  * libinput_dispatch() if any events become available on this fd.
 623  *
 624  * @return the file descriptor used to notify of pending events.
 625  */
 626 int
 627 libinput_get_fd(struct libinput *libinput);
 628
 629 /**
 630  * @ingroup base
 631  *
 632  * Main event dispatchment function. Reads events of the file descriptors
 633  * and processes them internally. Use libinput_get_event() to retrieve the
 634  * events.
 635  *
 636  * Dispatching does not necessarily queue libinput events.
 637  *
 638  * @param libinput A previously initialized libinput context
 639  *
 640  * @return 0 on success, or a negative errno on failure
 641  */
 642 int
 643 libinput_dispatch(struct libinput *libinput);
 644
 645 /**
 646  * @ingroup base
 647  *
 648  * Retrieve the next event from libinput's internal event queue.
 649  *
 650  * After handling the retrieved event, the caller must destroy it using
 651  * libinput_event_destroy().
 652  *
 653  * @param libinput A previously initialized libinput context
 654  * @return The next available event, or NULL if no event is available.
 655  */
 656 struct libinput_event *
 657 libinput_get_event(struct libinput *libinput);
 658
 659 /**
 660  * @ingroup base
 661  *
 662  * Return the type of the next event in the internal queue. This function
 663  * does not pop the event off the queue and the next call to
 664  * libinput_get_event() returns that event.
 665  *
 666  * @param libinput A previously initialized libinput context
 667  * @return The event type of the next available event or LIBINPUT_EVENT_NONE
 668  * if no event is availble.
 669  */
 670 enum libinput_event_type
 671 libinput_next_event_type(struct libinput *libinput);
 672
 673 /**
 674  * @ingroup base
 675  *
 676  * @param libinput A previously initialized libinput context
 677  * @return the caller-specific data previously assigned in
 678  * libinput_create_udev().
 679  */
 680 void *
 681 libinput_get_user_data(struct libinput *libinput);
 682
 683 /**
 684  * @ingroup base
 685  *
 686  * Resume a suspended libinput context. This re-enables device
 687  * monitoring and adds existing devices.
 688  *
 689  * @param libinput A previously initialized libinput context
 690  * @see libinput_suspend
 691  *
 692  * @return 0 on success or -1 on failure
 693  */
 694 int
 695 libinput_resume(struct libinput *libinput);
 696
 697 /**
 698  * @ingroup base
 699  *
 700  * Suspend monitoring for new devices and close existing devices.
 701  * This all but terminates libinput but does keep the context
 702  * valid to be resumed with libinput_resume().
 703  *
 704  * @param libinput A previously initialized libinput context
 705  */
 706 void
 707 libinput_suspend(struct libinput *libinput);
 708
 709 /**
 710  * @ingroup base
 711  *
 712  * Destroy the libinput context. After this, object references associated with
 713  * the destroyed context are invalid and may not be interacted with.
 714  *
 715  * @param libinput A previously initialized libinput context
 716  */
 717 void
 718 libinput_destroy(struct libinput *libinput);
 719
 720 /**
 721  * @defgroup seat Initialization and manipulation of seats
 722  *
 723  * A seat has two identifiers, the physical name and the logical name. The
 724  * physical name is summarized as the list of devices a process on the same
 725  * physical seat has access to.
 726  *
 727  * The logical seat name is the seat name for a logical group of devices. A
 728  * compositor may use that to create additonal seats as independent device
 729  * sets. Alternatively, a compositor may limit itself to a single logical
 730  * seat, leaving a second compositor to manage devices on the other logical
 731  * seats.
 732  *
 733  * @code
 734  * +---+--------+------------+------------------------+------------+
 735  * |   | event0 |            |                        | log seat A |
 736  * | K +--------+            |                        +------------+
 737  * | e | event1 | phys seat0 |    libinput context 1  |            |
 738  * | r +--------+            |                        | log seat B |
 739  * | n | event2 |            |                        |            |
 740  * | e +--------+------------+------------------------+------------+
 741  * | l | event3 | phys seat1 |    libinput context 2  | log seat C |
 742  * +---+--------+------------+------------------------+------------+
 743  * @endcode
 744  */
 745
 746 /**
 747  * @ingroup seat
 748  *
 749  * Increase the refcount of the seat. A seat will be freed whenever the
 750  * refcount reaches 0. This may happen during dispatch if the
 751  * seat was removed from the system. A caller must ensure to reference
 752  * the seat correctly to avoid dangling pointers.
 753  *
 754  * @param seat A previously obtained seat
 755  */
 756 void
 757 libinput_seat_ref(struct libinput_seat *seat);
 758
 759 /**
 760  * @ingroup seat
 761  *
 762  * Decrease the refcount of the seat. A seat will be freed whenever the
 763  * refcount reaches 0. This may happen during dispatch if the
 764  * seat was removed from the system. A caller must ensure to reference
 765  * the seat correctly to avoid dangling pointers.
 766  *
 767  * @param seat A previously obtained seat
 768  */
 769 void
 770 libinput_seat_unref(struct libinput_seat *seat);
 771
 772 /**
 773  * @ingroup seat
 774  *
 775  * Set caller-specific data associated with this seat. libinput does
 776  * not manage, look at, or modify this data. The caller must ensure the
 777  * data is valid.
 778  *
 779  * @param seat A previously obtained seat
 780  * @param user_data Caller-specific data pointer
 781  * @see libinput_seat_get_user_data
 782  */
 783 void
 784 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
 785
 786 /**
 787  * @ingroup seat
 788  *
 789  * Get the caller-specific data associated with this seat, if any.
 790  *
 791  * @param seat A previously obtained seat
 792  * @return Caller-specific data pointer or NULL if none was set
 793  * @see libinput_seat_set_user_data
 794  */
 795 void *
 796 libinput_seat_get_user_data(struct libinput_seat *seat);
 797
 798 /**
 799  * @ingroup seat
 800  *
 801  * Return the physical name of the seat. For libinput contexts created from
 802  * udev, this is always the same value as passed into
 803  * libinput_create_from_udev() and all seats from that context will have the
 804  * same physical name.
 805  *
 806  * The physical name of the seat is one that is usually set by the system or
 807  * lower levels of the stack. In most cases, this is the base filter for
 808  * devices - devices assigned to seats outside the current seat will not
 809  * be available to the caller.
 810  *
 811  * @param seat A previously obtained seat
 812  * @return the physical name of this seat
 813  */
 814 const char *
 815 libinput_seat_get_physical_name(struct libinput_seat *seat);
 816
 817 /**
 818  * @ingroup seat
 819  *
 820  * Return the logical name of the seat. This is an identifier to group sets
 821  * of devices within the compositor.
 822  *
 823  * @param seat A previously obtained seat
 824  * @return the logical name of this seat
 825  */
 826 const char *
 827 libinput_seat_get_logical_name(struct libinput_seat *seat);
 828
 829 /**
 830  * @defgroup device Initialization and manipulation of input devices
 831  */
 832
 833 /**
 834  * @ingroup device
 835  *
 836  * Increase the refcount of the input device. An input device will be freed
 837  * whenever the refcount reaches 0. This may happen during dispatch if the
 838  * device was removed from the system. A caller must ensure to reference
 839  * the device correctly to avoid dangling pointers.
 840  *
 841  * @param device A previously obtained device
 842  */
 843 void
 844 libinput_device_ref(struct libinput_device *device);
 845
 846 /**
 847  * @ingroup device
 848  *
 849  * Decrease the refcount of the input device. An input device will be freed
 850  * whenever the refcount reaches 0. This may happen during dispatch if the
 851  * device was removed from the system. A caller must ensure to reference
 852  * the device correctly to avoid dangling pointers.
 853  *
 854  * @param device A previously obtained device
 855  */
 856 void
 857 libinput_device_unref(struct libinput_device *device);
 858
 859 /**
 860  * @ingroup device
 861  *
 862  * Set caller-specific data associated with this input device. libinput does
 863  * not manage, look at, or modify this data. The caller must ensure the
 864  * data is valid.
 865  *
 866  * @param device A previously obtained device
 867  * @param user_data Caller-specific data pointer
 868  * @see libinput_device_get_user_data
 869  */
 870 void
 871 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
 872
 873 /**
 874  * @ingroup device
 875  *
 876  * Get the caller-specific data associated with this input device, if any.
 877  *
 878  * @param device A previously obtained device
 879  * @return Caller-specific data pointer or NULL if none was set
 880  * @see libinput_device_set_user_data
 881  */
 882 void *
 883 libinput_device_get_user_data(struct libinput_device *device);
 884
 885 /**
 886  * @ingroup device
 887  *
 888  * Get the system name of the device.
 889  *
 890  * @param device A previously obtained device
 891  * @return System name of the device
 892  */
 893 const char *
 894 libinput_device_get_sysname(struct libinput_device *device);
 895
 896 /**
 897  * @ingroup device
 898  *
 899  * A device may be mapped to a single output, or all available outputs. If a
 900  * device is mapped to a single output only, a relative device may not move
 901  * beyond the boundaries of this output. An absolute device has its input
 902  * coordinates mapped to the extents of this output.
 903  *
 904  * @return the name of the output this device is mapped to, or NULL if no
 905  * output is set
 906  */
 907 const char *
 908 libinput_device_get_output_name(struct libinput_device *device);
 909
 910 /**
 911  * @ingroup device
 912  *
 913  * Get the seat associated with this input device.
 914  *
 915  * @param device A previously obtained device
 916  * @return The seat this input device belongs to
 917  */
 918 struct libinput_seat *
 919 libinput_device_get_seat(struct libinput_device *device);
 920
 921 /**
 922  * @ingroup device
 923  *
 924  * Update the LEDs on the device, if any. If the device does not have
 925  * LEDs, or does not have one or more of the LEDs given in the mask, this
 926  * function does nothing.
 927  *
 928  * @param device A previously obtained device
 929  * @param leds A mask of the LEDs to set, or unset.
 930  */
 931 void
 932 libinput_device_led_update(struct libinput_device *device,
 933                            enum libinput_led leds);
 934
 935 /**
 936  * @ingroup device
 937  *
 938  * Set the bitmask in keys to the bitmask of the keys present on the device
 939  * (see linux/input.h), up to size characters.
 940  *
 941  * @param device A current input device
 942  * @param keys An array filled with the bitmask for the keys
 943  * @param size Size of the keys array
 944  */
 945 int
 946 libinput_device_get_keys(struct libinput_device *device,
 947                          char *keys, size_t size);
 948
 949 /**
 950  * @ingroup device
 951  *
 952  * Apply the 3x3 transformation matrix to absolute device coordinates. This
 953  * matrix has no effect on relative events.
 954  *
 955  * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
 956  * @code
 957  * [ a  b  c ]   [ x ]
 958  * [ d  e  f ] * [ y ]
 959  * [ 0  0  1 ]   [ 1 ]
 960  * @endcode
 961  */
 962 void
 963 libinput_device_calibrate(struct libinput_device *device,
 964                           float calibration[6]);
 965
 966 /**
 967  * @ingroup device
 968  *
 969  * Check if the given device has the specified capability
 970  *
 971  * @return 1 if the given device has the capability or 0 if not
 972  */
 973 int
 974 libinput_device_has_capability(struct libinput_device *device,
 975                                enum libinput_device_capability capability);
 976
 977 #endif /* LIBINPUT_H */